Class OrderedMultiDictionary<TKey, TValue>

The OrderedMultiDictionary class that associates values with a key. Unlike an OrderedDictionary, each key can have multiple values associated with it. When indexing an OrderedMultidictionary, instead of a single value associated with a key, you retrieve an enumeration of values.

All of the key are stored in sorted order. Also, the values associated with a given key are kept in sorted order as well.

When constructed, you can chose to allow the same value to be associated with a key multiple times, or only one time.

Inheritance
System.Object
CollectionBase<System.Collections.Generic.KeyValuePair<TKey, System.Collections.Generic.ICollection<TValue>>>
MultiDictionaryBase<TKey, TValue>
OrderedMultiDictionary<TKey, TValue>
Implements
System.Collections.ICollection
System.Collections.Generic.IDictionary<TKey, System.Collections.Generic.ICollection<TValue>>
System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<TKey, System.Collections.Generic.ICollection<TValue>>>
System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey, System.Collections.Generic.ICollection<TValue>>>
System.Collections.IEnumerable
System.ICloneable
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: Wintellect.PowerCollections
Assembly: CADability.dll
Syntax
[Serializable]
public class OrderedMultiDictionary<TKey, TValue> : MultiDictionaryBase<TKey, TValue>, ICollection, IDictionary<TKey, ICollection<TValue>>, ICollection<KeyValuePair<TKey, ICollection<TValue>>>, IEnumerable<KeyValuePair<TKey, ICollection<TValue>>>, IEnumerable, ICloneable
Type Parameters
Name Description
TKey

The type of the keys.
TValue

The of values associated with the keys.

Constructors

| Improve this Doc View Source

OrderedMultiDictionary(Boolean)

Create a new OrderedMultiDictionary. The default ordering of keys and values are used. If duplicate values are allowed, multiple copies of the same value can be associated with the same key. For example, the key "foo" could have "a", "a", and "b" associated with it. If duplicate values are not allowed, only one copies of a given value can be associated with the same key, although different keys can have the same value. For example, the key "foo" could have "a" and "b" associated with it, which key "bar" has values "b" and "c" associated with it.

Declaration
public OrderedMultiDictionary(bool allowDuplicateValues)
Parameters
Type Name Description
System.Boolean allowDuplicateValues

Can the same value be associated with a key multiple times?
Remarks

The default ordering of keys and values will be used, as defined by TKey and TValue's implementation of IComparable<T> (or IComparable if IComparable<T> is not implemented). If a different ordering should be used, other constructors allow a custom Comparer or IComparer to be passed to changed the ordering.

Exceptions
Type Condition
System.InvalidOperationException

TKey or TValue does not implement either IComparable<T> or IComparable.
| Improve this Doc View Source

OrderedMultiDictionary(Boolean, IComparer<TKey>)

Create a new OrderedMultiDictionary. If duplicate values are allowed, multiple copies of the same value can be associated with the same key. For example, the key "foo" could have "a", "a", and "b" associated with it. If duplicate values are not allowed, only one copies of a given value can be associated with the same key, although different keys can have the same value. For example, the key "foo" could have "a" and "b" associated with it, which key "bar" has values "b" and "c" associated with it.

Declaration
public OrderedMultiDictionary(bool allowDuplicateValues, IComparer<TKey> keyComparer)
Parameters
Type Name Description
System.Boolean allowDuplicateValues

Can the same value be associated with a key multiple times?
System.Collections.Generic.IComparer<TKey> keyComparer

An IComparer<TKey> instance that will be used to compare keys.
Exceptions
Type Condition
System.InvalidOperationException

TValue does not implement either IComparable<TValue> or IComparable.
| Improve this Doc View Source

OrderedMultiDictionary(Boolean, IComparer<TKey>, IComparer<TValue>)

Create a new OrderedMultiDictionary. If duplicate values are allowed, multiple copies of the same value can be associated with the same key. For example, the key "foo" could have "a", "a", and "b" associated with it. If duplicate values are not allowed, only one copies of a given value can be associated with the same key, although different keys can have the same value. For example, the key "foo" could have "a" and "b" associated with it, which key "bar" has values "b" and "c" associated with it.

Declaration
public OrderedMultiDictionary(bool allowDuplicateValues, IComparer<TKey> keyComparer, IComparer<TValue> valueComparer)
Parameters
Type Name Description
System.Boolean allowDuplicateValues

Can the same value be associated with a key multiple times?
System.Collections.Generic.IComparer<TKey> keyComparer

An IComparer<TKey> instance that will be used to compare keys.
System.Collections.Generic.IComparer<TValue> valueComparer

An IComparer<TValue> instance that will be used to compare values.
| Improve this Doc View Source

OrderedMultiDictionary(Boolean, Comparison<TKey>)

Create a new OrderedMultiDictionary. If duplicate values are allowed, multiple copies of the same value can be associated with the same key. For example, the key "foo" could have "a", "a", and "b" associated with it. If duplicate values are not allowed, only one copies of a given value can be associated with the same key, although different keys can have the same value. For example, the key "foo" could have "a" and "b" associated with it, which key "bar" has values "b" and "c" associated with it.

Declaration
public OrderedMultiDictionary(bool allowDuplicateValues, Comparison<TKey> keyComparison)
Parameters
Type Name Description
System.Boolean allowDuplicateValues

Can the same value be associated with a key multiple times?
System.Comparison<TKey> keyComparison

A delegate to a method that will be used to compare keys.
Exceptions
Type Condition
System.InvalidOperationException

TValue does not implement either IComparable<TValue> or IComparable.
| Improve this Doc View Source

OrderedMultiDictionary(Boolean, Comparison<TKey>, Comparison<TValue>)

Create a new OrderedMultiDictionary. If duplicate values are allowed, multiple copies of the same value can be associated with the same key. For example, the key "foo" could have "a", "a", and "b" associated with it. If duplicate values are not allowed, only one copies of a given value can be associated with the same key, although different keys can have the same value. For example, the key "foo" could have "a" and "b" associated with it, which key "bar" has values "b" and "c" associated with it.

Declaration
public OrderedMultiDictionary(bool allowDuplicateValues, Comparison<TKey> keyComparison, Comparison<TValue> valueComparison)
Parameters
Type Name Description
System.Boolean allowDuplicateValues

Can the same value be associated with a key multiple times?
System.Comparison<TKey> keyComparison

A delegate to a method that will be used to compare keys.
System.Comparison<TValue> valueComparison

A delegate to a method that will be used to compare values.

Properties

| Improve this Doc View Source

Count

Gets the number of key-value pairs in the dictionary. Each value associated with a given key is counted. If duplicate values are permitted, each duplicate value is included in the count.

Declaration
public override sealed int Count { get; }
Property Value
Type Description
System.Int32

The number of key-value pairs in the dictionary.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.Count
| Improve this Doc View Source

KeyComparer

Returns the IComparer<T> used to compare keys in this dictionary.

Declaration
public IComparer<TKey> KeyComparer { get; }
Property Value
Type Description
System.Collections.Generic.IComparer<TKey>

If the dictionary was created using a comparer, that comparer is returned. If the dictionary was created using a comparison delegate, then a comparer equivalent to that delegate is returned. Otherwise the default comparer for TKey (Comparer<TKey>.Default) is returned.
| Improve this Doc View Source

KeyValuePairs

Gets a read-only collection of all key-value pairs in the dictionary. If a key has multiple values associated with it, then a key-value pair is present for each value associated with the key.

Declaration
public override sealed ICollection<KeyValuePair<TKey, TValue>> KeyValuePairs { get; }
Property Value
Type Description
System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<TKey, TValue>>
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.KeyValuePairs
| Improve this Doc View Source

ValueComparer

Returns the IComparer<T> used to compare values in this dictionary.

Declaration
public IComparer<TValue> ValueComparer { get; }
Property Value
Type Description
System.Collections.Generic.IComparer<TValue>

If the dictionary was created using a comparer, that comparer is returned. If the dictionary was created using a comparison delegate, then a comparer equivalent to that delegate is returned. Otherwise the default comparer for TValue (Comparer<TValue>.Default) is returned.

Methods

| Improve this Doc View Source

Add(TKey, TValue)

Adds a new value to be associated with a key. If duplicate values are permitted, this method always adds a new key-value pair to the dictionary.

If duplicate values are not permitted, and key already has a value equal to value associated with it, then that value is replaced with value, and the number of values associate with key is unchanged.

Declaration
public override sealed void Add(TKey key, TValue value)
Parameters
Type Name Description
TKey key

The key to associate with.
TValue value

The value to associated with key.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.Add(TKey, TValue)
| Improve this Doc View Source

Clear()

Removes all keys and values from the dictionary.

Declaration
public override sealed void Clear()
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.Clear()
| Improve this Doc View Source

Clone()

Makes a shallow clone of this dictionary; i.e., if keys or values of the dictionary are reference types, then they are not cloned. If TKey or TValue is a value type, then each element is copied as if by simple assignment.

Declaration
public OrderedMultiDictionary<TKey, TValue> Clone()
Returns
Type Description
OrderedMultiDictionary<TKey, TValue>

The cloned dictionary.
Remarks

Cloning the dictionary takes time O(N), where N is the number of key-value pairs in the dictionary.

| Improve this Doc View Source

CloneContents()

Makes a deep clone of this dictionary. A new dictionary is created with a clone of each entry of this dictionary, by calling ICloneable.Clone on each element. If TKey or TValue is a value type, then each element is copied as if by simple assignment.

Declaration
public OrderedMultiDictionary<TKey, TValue> CloneContents()
Returns
Type Description
OrderedMultiDictionary<TKey, TValue>

The cloned dictionary.
Remarks

If TKey or TValue is a reference type, it must implement ICloneable. Otherwise, an InvalidOperationException is thrown.

Cloning the dictionary takes time O(N log N), where N is the number of key-value pairs in the dictionary.

Exceptions
Type Condition
System.InvalidOperationException

TKey or TValue is a reference type that does not implement ICloneable.
| Improve this Doc View Source

Contains(TKey, TValue)

Checks to see if value is associated with key in the dictionary.

Declaration
public override sealed bool Contains(TKey key, TValue value)
Parameters
Type Name Description
TKey key

The key to check.
TValue value

The value to check.
Returns
Type Description
System.Boolean

True if value is associated with key.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.Contains(TKey, TValue)
| Improve this Doc View Source

ContainsKey(TKey)

Checks to see if the key is present in the dictionary and has at least one value associated with it.

Declaration
public override sealed bool ContainsKey(TKey key)
Parameters
Type Name Description
TKey key

The key to check.
Returns
Type Description
System.Boolean

True if key is present and has at least one value associated with it. Returns false otherwise.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.ContainsKey(TKey)
| Improve this Doc View Source

CountAllValues()

Gets a total count of values in the collection.

Declaration
protected override sealed int CountAllValues()
Returns
Type Description
System.Int32

The total number of values associated with all keys in the dictionary.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.CountAllValues()
| Improve this Doc View Source

CountValues(TKey)

Gets the number of values associated with a given key.

Declaration
protected override sealed int CountValues(TKey key)
Parameters
Type Name Description
TKey key

The key to count values of.
Returns
Type Description
System.Int32

The number of values associated with key. If key is not present in the dictionary, zero is returned.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.CountValues(TKey)
| Improve this Doc View Source

EnumerateKeys()

Enumerate all of the keys in the dictionary.

Declaration
protected override sealed IEnumerator<TKey> EnumerateKeys()
Returns
Type Description
System.Collections.Generic.IEnumerator<TKey>

An IEnumerator<TKey> of all of the keys in the dictionary.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.EnumerateKeys()
| Improve this Doc View Source

EqualValues(TValue, TValue)

Determine if two values are equal.

Declaration
protected override sealed bool EqualValues(TValue value1, TValue value2)
Parameters
Type Name Description
TValue value1

First value to compare.
TValue value2

Second value to compare.
Returns
Type Description
System.Boolean

True if the values are equal.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.EqualValues(TValue, TValue)
| Improve this Doc View Source

Item(TKey)

Declaration
public TValue Item(TKey key)
Parameters
Type Name Description
TKey key
Returns
Type Description
TValue
| Improve this Doc View Source

Range(TKey, Boolean, TKey, Boolean)

Returns a collection that can be used for enumerating some of the keys and values in the collection. Only keys that are greater than from and less than to are included. The keys are enumerated in sorted order. Keys equal to the end points of the range can be included or excluded depending on the fromInclusive and toInclusive parameters.

Declaration
public OrderedMultiDictionary<TKey, TValue>.View Range(TKey from, bool fromInclusive, TKey to, bool toInclusive)
Parameters
Type Name Description
TKey from

The lower bound of the range.
System.Boolean fromInclusive

If true, the lower bound is inclusive--keys equal to the lower bound will be included in the range. If false, the lower bound is exclusive--keys equal to the lower bound will not be included in the range.
TKey to

The upper bound of the range.
System.Boolean toInclusive

If true, the upper bound is inclusive--keys equal to the upper bound will be included in the range. If false, the upper bound is exclusive--keys equal to the upper bound will not be included in the range.
Returns
Type Description
OrderedMultiDictionary.View<>

An OrderedMultiDictionary.View of key-value pairs in the given range.
Remarks

If from is greater than or equal to to, the returned collection is empty.

The sorted order of the keys is determined by the comparison instance or delegate used to create the dictionary.

Typically, this property is used in conjunction with a foreach statement. For example:

 foreach(KeyValuePair<TKey, TValue> pair in dictionary.Range(from, true, to, false)) {
    // process pair
 }

Calling Range does not copy the data in the dictionary, and the operation takes constant time.

| Improve this Doc View Source

RangeFrom(TKey, Boolean)

Returns a collection that can be used for enumerating some of the keys and values in the collection. Only keys that are greater than (and optionally, equal to) from are included. The keys are enumerated in sorted order. Keys equal to from can be included or excluded depending on the fromInclusive parameter.

Declaration
public OrderedMultiDictionary<TKey, TValue>.View RangeFrom(TKey from, bool fromInclusive)
Parameters
Type Name Description
TKey from

The lower bound of the range.
System.Boolean fromInclusive

If true, the lower bound is inclusive--keys equal to the lower bound will be included in the range. If false, the lower bound is exclusive--keys equal to the lower bound will not be included in the range.
Returns
Type Description
OrderedMultiDictionary.View<>

An OrderedMultiDictionary.View of key-value pairs in the given range.
Remarks

The sorted order of the keys is determined by the comparison instance or delegate used to create the dictionary.

Typically, this property is used in conjunction with a foreach statement. For example:

 foreach(KeyValuePair<TKey, TValue> pair in dictionary.RangeFrom(from, true)) {
    // process pair
 }

Calling RangeFrom does not copy of the data in the dictionary, and the operation takes constant time.

| Improve this Doc View Source

RangeTo(TKey, Boolean)

Returns a collection that can be used for enumerating some of the keys and values in the collection. Only items that are less than (and optionally, equal to) to are included. The items are enumerated in sorted order. Items equal to to can be included or excluded depending on the toInclusive parameter.

Declaration
public OrderedMultiDictionary<TKey, TValue>.View RangeTo(TKey to, bool toInclusive)
Parameters
Type Name Description
TKey to

The upper bound of the range.
System.Boolean toInclusive

If true, the upper bound is inclusive--keys equal to the upper bound will be included in the range. If false, the upper bound is exclusive--keys equal to the upper bound will not be included in the range.
Returns
Type Description
OrderedMultiDictionary.View<>

An OrderedMultiDictionary.View of key-value pairs in the given range.
Remarks

The sorted order of the keys is determined by the comparison instance or delegate used to create the dictionary.

Typically, this property is used in conjunction with a foreach statement. For example:

 foreach(KeyValuePair<TKey, TValue> pair in dictionary.RangeFrom(from, false)) {
    // process pair
 }

Calling RangeTo does not copy the data in the dictionary, and the operation takes constant time.

| Improve this Doc View Source

Remove(TKey)

Removes a key and all associated values from the dictionary. If the key is not present in the dictionary, it is unchanged and false is returned.

Declaration
public override sealed bool Remove(TKey key)
Parameters
Type Name Description
TKey key

The key to remove.
Returns
Type Description
System.Boolean

True if the key was present and was removed. Returns false if the key was not present.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.Remove(TKey)
| Improve this Doc View Source

Remove(TKey, TValue)

Removes a given value from the values associated with a key. If the last value is removed from a key, the key is removed also.

Declaration
public override sealed bool Remove(TKey key, TValue value)
Parameters
Type Name Description
TKey key

A key to remove a value from.
TValue value

The value to remove.
Returns
Type Description
System.Boolean

True if value was associated with key (and was therefore removed). False if value was not associated with key.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.Remove(TKey, TValue)
| Improve this Doc View Source

Reversed()

Returns a View collection that can be used for enumerating the keys and values in the collection in reversed order.

Declaration
public OrderedMultiDictionary<TKey, TValue>.View Reversed()
Returns
Type Description
OrderedMultiDictionary.View<>

An OrderedDictionary.View of key-value pairs in reverse order.
Remarks

Typically, this method is used in conjunction with a foreach statement. For example: 

 foreach(KeyValuePair<TKey, TValue> pair in dictionary.Reversed()) {
    // process pair
 }

If an entry is added to or deleted from the dictionary while the View is being enumerated, then the enumeration will end with an InvalidOperationException.

Calling Reverse does not copy the data in the dictionary, and the operation takes constant time.

| Improve this Doc View Source

TryEnumerateValuesForKey(TKey, out IEnumerator<TValue>)

Determines if this dictionary contains a key equal to key. If so, all the values associated with that key are returned through the values parameter.

Declaration
protected override sealed bool TryEnumerateValuesForKey(TKey key, out IEnumerator<TValue> values)
Parameters
Type Name Description
TKey key

The key to search for.
System.Collections.Generic.IEnumerator<TValue> values

Returns all values associated with key, if true was returned.
Returns
Type Description
System.Boolean

True if the dictionary contains key. False if the dictionary does not contain key.
Overrides
Wintellect.PowerCollections.MultiDictionaryBase<TKey, TValue>.TryEnumerateValuesForKey(TKey, System.Collections.Generic.IEnumerator<TValue>)

Explicit Interface Implementations

| Improve this Doc View Source

ICloneable.Clone()

Implements ICloneable.Clone. Makes a shallow clone of this dictionary; i.e., if keys or values are reference types, then they are not cloned.

Declaration
object ICloneable.Clone()
Returns
Type Description
System.Object

The cloned dictionary.

Implements

System.Collections.ICollection
System.Collections.Generic.IDictionary<TKey, TValue>
System.Collections.Generic.ICollection<T>
System.Collections.Generic.IEnumerable<T>
System.Collections.IEnumerable
System.ICloneable