A dictionary class built on top of InternalSet<KeyValuePair<K,V>>. More...

Source file:

/Core/Loyc.Collections/Sets/MMap.cs

Inheritance diagram for Loyc.Collections.MMap< K, V >:

Remarks

A dictionary class built on top of InternalSet<KeyValuePair<K,V>>.

Template Parameters

K
V

Benchmarks show that this class is not as fast as the standard Dictionary<K,V> in most cases. however, it does have some advantages:

MMap allows null as a key (assuming it is based on the second version of Impl.InternalSet<T>).
MapOrMMap<K, V>.TryGet and MapOrMMap<K, V>.ContainsKey do not throw an incredibly annoying exception if you have the audacity to ask whether there is a null key in the collection.
This class supports fast cloning in O(1) time.
You can convert a mutable MMap<K,V> into an immutable Map<K,V>, a read-only dictionary that does not change when you change the original MMap.
This class has bonus methods defined by IDictionaryEx<K, V>.
The persistent map operations Union, Intersect, Except and Xor combine two dictionaries to create a new dictionary, without modifying either of the original dictionaries.
The methods With and Without create a new dictionary with a single item added or removed.

The documentation of InternalSet<T> describes how the data structure works.

Properties
new KeyCollection< K, V >	Keys `[get]`

new ValueCollection< K, V >	Values `[get]`

new V	this[K key] `[get, set]`

bool	IsReadOnly `[get]`

Properties inherited from Loyc.Collections.MapOrMMap< K, V >
bool	IsEmpty `[get]`

IEqualityComparer< K >	KeyComparer `[get]`

InternalSet< KeyValuePair< K, V > >	FrozenInternalSet `[get]`

V	this[K key] `[get]`

V	this[K key, V defaultValue] `[get]`
	Retrieves the value associated with the specified key, or returns `defaultValue` if the key is not found. More...

int	Count `[get]`

IEnumerable< K >	Keys `[get]`

IEnumerable< V >	Values `[get]`

Properties inherited from Loyc.Collections.IIndexed< K, V >
V	this[K key] `[get]`
	Gets the value associated with the specified key. More...

Properties inherited from Loyc.Collections.IDictionaryEx< K, V >
new V	this[K key] `[get, set]`

new ICollection< K >	Keys `[get]`

new ICollection< V >	Values `[get]`

Properties inherited from Loyc.Collections.IDictionarySink< K, V >
V	this[K key] `[set]`

Public Member Functions
	MMap (IEqualityComparer< K > comparer)
	Creates an empty map with the specified key comparer. More...

	MMap (IEnumerable< KeyValuePair< K, V >> copy)
	Creates a map with the specified elements. More...

	MMap (IEnumerable< KeyValuePair< K, V >> copy, IEqualityComparer< K > comparer)
	Creates a map with the specified elements and key comparer. More...

void	Add (K key, V value)

bool	Remove (K key)

void	Add (KeyValuePair< K, V > item)

void	Clear ()

bool	Remove (KeyValuePair< K, V > item)
	Removes a pair from the map. More...

virtual MMap< K, V >	Clone ()
	Creates a copy of this map in O(1) time, by marking the current root node as frozen. More...

int	AddRange (MMap< K, V > data, bool replaceIfPresent=true)
	Merges the contents of the specified map into this map. More...

int	AddRange (IEnumerable< KeyValuePair< K, V >> data, bool replaceIfPresent=true)
	Merges the contents of the specified sequence into this map. More...

int	AddRange (IEnumerable< KeyValuePair< K, V >> data, DictEditMode mode)
	Merges the contents of the specified sequence into this map. More...

bool	GetAndEdit (ref K key, ref V value, DictEditMode mode)
	Combines a get and change operation into a single method call. You rarely need to call this method directly; the following extension methods are based on it: DictionaryExt.SwapIfPresent, DictionaryExt.AddIfNotPresent, DictionaryExt.AddOrGetExisting, DictionaryExt.ReplaceIfPresent, DictionaryExt.SetAndGet.

bool	AddOrFind (ref KeyValuePair< K, V > pair, bool replaceIfPresent)
	For internal use. Adds a pair to the map if the key is not present, retrieves the existing key-value pair if the key is present, and optionally replaces the existing pair with a new pair. More...

Maybe< V >	GetAndRemove (K key)
	Gets the value associated with the specified key, then removes the pair with that key from the dictionary. More...

bool	GetAndRemove (ref KeyValuePair< K, V > pair)
	Gets the pair associated with `pair.Key`, then removes the pair with that key from the dictionary. More...

MMap< K, V >	With (K key, V value, bool replaceIfPresent=true)

MMap< K, V >	With (KeyValuePair< K, V > item)

MMap< K, V >	Without (K key)

MMap< K, V >	Union (MapOrMMap< K, V > other)

MMap< K, V >	Union (MapOrMMap< K, V > other, bool replaceWithValuesFromOther)

MMap< K, V >	Intersect (MapOrMMap< K, V > other)

MMap< K, V >	Except (MapOrMMap< K, V > other)

MMap< K, V >	Xor (MapOrMMap< K, V > other)

Map< K, V >	AsImmutable ()

Public Member Functions inherited from Loyc.Collections.MapOrMMap< K, V >
bool	ContainsKey (K key)

bool	TryGetValue (K key, out V value)

bool	Contains (KeyValuePair< K, V > item)

void	CopyTo (KeyValuePair< K, V >[] array, int arrayIndex)

InternalSet< KeyValuePair< K, V > >.Enumerator	GetEnumerator ()

V	TryGetValue (K key, V defaultValue)
	Synonym for this[key, defaultValue]. More...

virtual long	CountMemory (int sizeOfPair)
	Measures the total size of all objects allocated to this collection, in bytes, including the size of this object itself; see InternalSet<T>.CountMemory. More...

Public Member Functions inherited from Loyc.Collections.ITryGet< K, V >
V	TryGet (K key, out bool fail)
	Gets the item for the specified key or index, and does not throw an exception on failure. More...

Public Member Functions inherited from Loyc.Collections.IDictionaryEx< K, V >
new bool	ContainsKey (K key)

new bool	TryGetValue (K key, out V value)

Public Member Functions inherited from Loyc.Collections.IDictionarySink< K, V >
void	Add (K key, V value)

bool	Remove (K key)

void	Clear ()

Static Public Member Functions
static	operator Map< K, V > (MMap< K, V > copy)

Additional Inherited Members
Protected Member Functions inherited from Loyc.Collections.MapOrMMap< K, V >
	MapOrMMap (IEqualityComparer< K > comparer)

	MapOrMMap (IEnumerable< KeyValuePair< K, V >> list)

	MapOrMMap (IEnumerable< KeyValuePair< K, V >> list, IEqualityComparer< K > comparer)

Protected static fields inherited from Loyc.Collections.MapOrMMap< K, V >
static readonly EqualityComparer< V >	DefaultValueComparer = EqualityComparer<V>.Default

Constructor & Destructor Documentation

◆ MMap() [1/3]

Loyc.Collections.MMap< K, V >.MMap ( IEqualityComparer< K > comparer )

inline

Creates an empty map with the specified key comparer.

◆ MMap() [2/3]

Loyc.Collections.MMap< K, V >.MMap ( IEnumerable< KeyValuePair< K, V >> copy )

inline

Creates a map with the specified elements.

◆ MMap() [3/3]

Loyc.Collections.MMap< K, V >.MMap	(	IEnumerable< KeyValuePair< K, V >>	copy,
		IEqualityComparer< K >	comparer
	)

inline

Creates a map with the specified elements and key comparer.

Member Function Documentation

◆ AddOrFind()

bool Loyc.Collections.MMap< K, V >.AddOrFind	(	ref KeyValuePair< K, V >	pair,
		bool	replaceIfPresent
	)

inline

For internal use. Adds a pair to the map if the key is not present, retrieves the existing key-value pair if the key is present, and optionally replaces the existing pair with a new pair.

Parameters

pair	When calling this method, pair.Key specifies the key that you want to search for in the map. If the key is not found then the pair is added to the map; if the key is found, the pair is replaced with the existing pair that was found in the map.
replaceIfPresent	This parameter specifies what to do if the key is found in the map. If this parameter is true, the existing pair is replaced with the specified new pair (in fact the pair in the map is swapped with the `pair` parameter). If this parameter is false, the existing pair is left unmodified and a copy of it is stored in the `pair` parameter.

Returns: True if the pair's key did NOT exist and was added, false if the key already existed.

Referenced by Loyc.Collections.MMap< object, object >.GetAndEdit().

◆ AddRange() [1/3]

int Loyc.Collections.MMap< K, V >.AddRange	(	IEnumerable< KeyValuePair< K, V >>	data,
		bool	replaceIfPresent = `true`
	)

inline

Merges the contents of the specified sequence into this map.

Parameters

replaceIfPresent If true, values in the other collection replace values in this one. If false, the existing pairs in this map are not overwritten.

Returns: The number of new pairs added, whose keys didn't already exist.

Duplicates are allowed in the source data. If replaceIfPresent is true, later values take priority over earlier values, otherwise earlier values take priority.

◆ AddRange() [2/3]

int Loyc.Collections.MMap< K, V >.AddRange	(	IEnumerable< KeyValuePair< K, V >>	data,
		DictEditMode	mode
	)

inline

Merges the contents of the specified sequence into this map.

Parameters

data	Pairs to merge in. Duplicates are allowed; if the `ReplaceIfPresent` bit is set in `mode`, later values take priority over earlier values, otherwise earlier values take priority.
mode	Specifies how to combine the collections.

Returns: The number of pairs that did not already exist in the collection. if the AddIfNotPresent bit is set on mode, this is the number of new pairs added.

See also: DictionaryExt.AddRange<K, V>(IDictionary<K, V>, IEnumerable<KeyValuePair<K, V>>)

Implements Loyc.Collections.IDictionaryEx< K, V >.

◆ AddRange() [3/3]

int Loyc.Collections.MMap< K, V >.AddRange	(	MMap< K, V >	data,
		bool	replaceIfPresent = `true`
	)

inline

Merges the contents of the specified map into this map.

Parameters

replaceIfPresent If true, values in the other collection replace values in this one. If false, the existing pairs in this map are not overwritten.

Returns: The number of items that were added.

◆ Clone()

virtual MMap<K, V> Loyc.Collections.MMap< K, V >.Clone ( )

inlinevirtual

Creates a copy of this map in O(1) time, by marking the current root node as frozen.

◆ GetAndRemove() [1/2]

Maybe<V> Loyc.Collections.MMap< K, V >.GetAndRemove ( K key )

inline

Gets the value associated with the specified key, then removes the pair with that key from the dictionary.

Parameters

key	Key to search for.

Returns: The value that was removed. If the key is not found, the result has no value (Maybe<V>.HasValue is false).

This method shall not throw when the key is null.

Implements Loyc.Collections.IDictionaryEx< K, V >.

◆ GetAndRemove() [2/2]

bool Loyc.Collections.MMap< K, V >.GetAndRemove ( ref KeyValuePair< K, V > pair )

inline

Gets the pair associated with pair.Key, then removes the pair with that key from the dictionary.

Parameters

pair	Specifies the key to search for. On return, if the key was found, this holds both the key and value that used to be in the dictionary.

Returns: True if a pair was removed, false if not.

◆ Remove()

bool Loyc.Collections.MMap< K, V >.Remove ( KeyValuePair< K, V > item )

inline

Removes a pair from the map.

The removal occurs only if the value provided matches the value that is already associated with the key (value comparison is performed using object.Equals()).

Returns: True if the pair was removed, false if not.

Remarks

Properties

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ MMap() [1/3]

◆ MMap() [2/3]

◆ MMap() [3/3]

Member Function Documentation

◆ AddOrFind()

◆ AddRange() [1/3]

◆ AddRange() [2/3]

◆ AddRange() [3/3]

◆ Clone()

◆ GetAndRemove() [1/2]

◆ GetAndRemove() [2/2]

◆ Remove()