Loyc.Collections.MMap< K, V > Class Template Reference

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}.TryGetValue 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 an AddRange method.
• This class has some bonus features: MapOrMMap{K, V}.TryGetValue(K, V) returns a default value if the key is not present; AddIfNotPresent only adds a pair if the collection does not already contain the key; AddOrFind can retrieve the current value and change it to a new value at the same time; and GetAndRemove can get a value while it is being deleted.
• The persistent map operations Union, Intersect, Except and Xor combine two dictionaries to create a new dictionary, without modifying either of the original dictionaries. Equally interesting, 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 ICollection< K >	Keys [get]
new ICollection< 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.ICount
int	Count [get]
	Gets the number of items in the collection. More...
Properties inherited from Loyc.Collections.IIsEmpty
bool	IsEmpty [get]

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...
bool	AddIfNotPresent (K key, V value)
	Adds an item to the map if the key is not present. If the key is already present, this method has no effect. More...
bool	AddOrFind (ref KeyValuePair< K, V > pair, bool replaceIfPresent)
	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...
bool	GetAndRemove (K key, ref V valueRemoved)
	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.IAddRange< T >
void	AddRange (IEnumerable< T > e)
void	AddRange (IReadOnlyCollection< T > s)
Public Member Functions inherited from Loyc.Collections.ISetOperations< in T, in InSetT, out OutSetT >
OutSetT	With (T item)
OutSetT	Without (T item)
OutSetT	Union (InSetT other)
OutSetT	Intersect (InSetT other)
OutSetT	Except (InSetT other)
OutSetT	Xor (InSetT other)

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

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

inline

Creates an empty map with the specified key comparer.

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

inline

Creates a map with the specified elements.

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

bool Loyc.Collections.MMap< K, V >.AddIfNotPresent ( K  key, V  value  )

inline

Adds an item to the map if the key is not present. If the key is already present, this method has no effect.

Returns

True if the pair was added, false if not.

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

inline

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.

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.

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 items that were added.

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

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.

Implements Loyc.ICloneable< out T >.

bool Loyc.Collections.MMap< K, V >.GetAndRemove ( K  key, ref V  valueRemoved  )

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.
valueRemoved	The value that was removed. If the key is not found, the value of this parameter is left unchanged.

Returns

True if a pair was removed, false if not.

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.

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.

References Loyc.Collections.Remove.