Loyc.Collections.IDictionaryEx< K, V > Interface Template Reference

Combines IDictionary, IReadOnlyDictionary, and IDictonarySink with a few additional methods. More...

---

Source file:

• /Core/Loyc.Interfaces/Collections/IDictionaryEx.cs

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

Remarks

Combines IDictionary, IReadOnlyDictionary, and IDictonarySink with a few additional methods.

This interface also derives from ICloneable for the sake of implementations such as MMap<K,V> that support fast cloning. RemoveRange() is only provided as an extension method because it is rare that a dictionary can accelerate bulk removal of an arbitrary sequence.

Look in LCInterfaces for default implementations of the extra methods. And, as always, KeyCollection<K,V>, ValueCollection<K,V> and Impl.DictionaryBase<K,V>will help you implement dictionary types.

Properties
new V	this[K key] [get, set]
new ICollection< K >	Keys [get]
new ICollection< 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.IDictionarySink< K, V >
V	this[K key] [set]

Public Member Functions
new bool	ContainsKey (K key)
new bool	TryGetValue (K key, out V value)
new void	Add (K key, V value)
new bool	Remove (K key)
new void	Clear ()
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	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. More...
int	AddRange (IEnumerable< KeyValuePair< K, V >> data, DictEditMode mode)
	Merges the contents of the specified sequence into this map. More...
Public Member Functions inherited from Loyc.Collections.IDictionarySink< K, V >
void	Add (K key, V value)
bool	Remove (K key)
void	Clear ()
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...

Member Function Documentation

AddRange()

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

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>>)

Implemented in Loyc.Collections.BDictionary< K, V >, and Loyc.Collections.MMap< K, V >.

GetAndEdit()

bool Loyc.Collections.IDictionaryEx< K, V >.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.

Parameters

key	Specifies the key that you want to search for in the map. Some implementations will update the key with the version of it found in the dictionary (although the new key is "equal" to the old key, it may be a different object); otherwise the key is left unchanged.
value	If the key is found, the old value is saved in this parameter. Otherwise, it is left unchanged.
mode	The specific behavior of this method depends on this. See DictEditMode to understand its effect.

Returns

True if the pair's key ALREADY existed, false if not.

This method exists because some collections can optimize certain combinations of operations, avoiding the two traversals through the data structure that would be required by the IDictionary interface.

This method shall not throw when the key is null, unless the AddIfNotPresent bit is set in mode and the dictionary does not support a null key.

See also

DictionaryExt.AddIfNotPresent

Implemented in Loyc.Collections.BDictionary< K, V >, and Loyc.Collections.MMap< K, V >.

Referenced by Loyc.Collections.LCInterfaces.AddIfNotPresent< K, V >(), Loyc.Collections.LCInterfaces.AddOrGetExisting< K, V >(), Loyc.Collections.LCInterfaces.GetAndSet< K, V >(), Loyc.Collections.LCInterfaces.GetOrAdd< K, V >(), Loyc.Collections.LCInterfaces.ReplaceIfPresent< K, V >(), and Loyc.Collections.LCInterfaces.SwapIfPresent< K, V >().

GetAndRemove()

Maybe<V> Loyc.Collections.IDictionaryEx< K, V >.GetAndRemove

(

K

key

)

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.

Implemented in Loyc.Collections.BDictionary< K, V >, and Loyc.Collections.MMap< K, V >.