/// <summary>
/// Sets the value associated with the first occurrence of the specified key.</summary>
/// <param name="key">
/// The key whose value to set.</param>
/// <param name="value"><para>
/// The value to associate with the first occurrence of <paramref name="key"/>.
/// </para><para>
/// If <paramref name="key"/> is not found, <b>SetByKey</b> adds a new element with the
/// specified <paramref name="key"/> and <paramref name="value"/> to the end of the <see
/// cref="KeyValueList{TKey, TValue}"/>.</para></param>
/// <returns>
/// The <see cref="KeyValueList{TKey, TValue}"/> index of the element that was changed or
/// added.</returns>
/// <exception cref="ArgumentNullException">
/// <paramref name="key"/> is a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="value"/> is an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="IKeyedValue{TKey}.Key"/> differs from <paramref name="key"/>.</exception>
/// <exception cref="NotSupportedException">
/// The <see cref="KeyValueList{TKey, TValue}"/> is read-only.</exception>
/// <remarks>
/// <b>SetByKey</b> has the same effect as setting the key indexer, <see
/// cref="this[TKey]"/>.</remarks>
public int SetByKey(TKey key, TValue value)
{
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
if (value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(key, value);
}
else if (key == null)
{
ThrowHelper.ThrowArgumentNullException("key");
}
var pair = new KeyValuePair <TKey, TValue>(key, value);
int index = IndexOfKey(key);
if (index >= 0)
{
InnerList[index] = pair;
return(index);
}
else
{
InnerList.Add(pair);
return(InnerList.Count - 1);
}
}
/// <summary>
/// Initializes a new instance of the <see cref="KeyValueList{TKey, TValue}"/> class that
/// contains elements copied from the specified collection and has sufficient capacity to
/// accommodate the number of elements copied.</summary>
/// <param name="collection">
/// The <see cref="IEnumerable{T}"/> collection whose <see cref="KeyValuePair{TKey,
/// TValue}"/> elements are copied to the new collection.</param>
/// <exception cref="ArgumentNullException"><para>
/// <paramref name="collection"/> is a null reference.
/// </para><para>-or-</para><para>
/// <paramref name="collection"/> contains an element whose <see cref="KeyValuePair{TKey,
/// TValue}.Key"/> component is a null reference.</para></exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="collection"/> contains an element whose <see cref="KeyValuePair{TKey,
/// TValue}.Value"/> component is an <see cref="IKeyedValue{TKey}"/> instance, and whose
/// <see cref="KeyValuePair{TKey, TValue}.Key"/> component differs from that instance’s
/// <see cref="IKeyedValue{TKey}.Key"/>.</exception>
/// <remarks>
/// Please refer to <see cref="List{T}(IEnumerable{T})"/> for details.</remarks>
public KeyValueList(IEnumerable <KeyValuePair <TKey, TValue> > collection) :
base(collection)
{
foreach (KeyValuePair <TKey, TValue> pair in InnerList)
{
CollectionsUtility.ValidateKey(pair.Key, pair.Value);
}
}
/// <summary>
/// Determines whether the specified collection contains the same elements in the reverse
/// order as the current <see cref="StackEx{T}"/>.</summary>
/// <param name="collection">
/// The <see cref="ICollection"/> to compare with the current <see cref="StackEx{T}"/>.
/// </param>
/// <returns><para>
/// <c>true</c> under the following conditions, otherwise <c>false</c>:
/// </para><list type="bullet"><item>
/// <paramref name="collection"/> is not a null reference, contains the same number of
/// elements as this <see cref="StackEx{T}"/>, and all elements compare as equal when
/// retrieved in the original enumeration sequence for the <paramref name="collection"/>,
/// and in the reverse enumeration sequence for this <see cref="StackEx{T}"/>.
/// </item></list></returns>
/// <remarks><para>
/// <b>Equals</b> calls <see cref="CollectionsUtility.SequenceEqualUntyped"/> to test the
/// two collections for value equality.
/// </para><note type="implementnotes">
/// <para>The <see cref="StackEx{T}"/> is a last-in, first-out (LIFO) collection, which
/// means that its enumeration sequence is reversed compared to a first-in, first-out (FIFO)
/// collection that contains the same elements in the same original insertion order.
/// </para><para>
/// When comparing to a non-LIFO collection, you must first reverse its element order, or
/// that of the <see cref="StackEx{T}"/>, for a successful comparison. <b>EqualsReverse</b>
/// automatically performs this inversion. Use the alternative method <see cref="Equals"/>
/// when comparing to another LIFO collection.</para></note></remarks>
public bool EqualsReverse(ICollection collection)
{
// comparing against the StackEx itself fails since we reverse the order
if (collection == null || collection == this || collection.Count != Count)
{
return(false);
}
T[] array = ToArray();
Array.Reverse(array);
return(CollectionsUtility.SequenceEqualUntyped(array, collection));
}
/// <overloads>
/// Adds an element to the end of the <see cref="KeyValueList{TKey, TValue}"/>.</overloads>
/// <summary>
/// Adds an element with the specified key and value to the end of the <see
/// cref="KeyValueList{TKey, TValue}"/>.</summary>
/// <param name="key">
/// The key of the element to add.</param>
/// <param name="value">
/// The value of the element to add.</param>
/// <exception cref="ArgumentNullException">
/// <paramref name="key"/> is a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="value"/> is an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="IKeyedValue{TKey}.Key"/> differs from <paramref name="key"/>.</exception>
/// <exception cref="NotSupportedException"><para>
/// The <see cref="KeyValueList{TKey, TValue}"/> is read-only.
/// </para><para>-or-</para><para>
/// The <see cref="KeyValueList{TKey, TValue}"/> already contains the specified
/// key-and-value pair, and the <see cref="KeyValueList{TKey, TValue}"/> ensures that all
/// elements are unique.</para></exception>
/// <remarks>
/// Please refer to <see cref="SortedList{TKey, TValue}.Add(TKey, TValue)"/> for details.
/// </remarks>
public void Add(TKey key, TValue value)
{
if (value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(key, value);
}
else if (key == null)
{
ThrowHelper.ThrowArgumentNullException("key");
}
Add(new KeyValuePair <TKey, TValue>(key, value));
}
/// <overloads>
/// Adds the specified element to the <see cref="SortedDictionaryEx{TKey, TValue}"/>.
/// </overloads>
/// <summary>
/// Adds the specified key and value to the <see cref="SortedDictionaryEx{TKey, TValue}"/>.
/// </summary>
/// <param name="key">
/// The key of the element to add.</param>
/// <param name="value">
/// The value of the element to add.</param>
/// <exception cref="ArgumentException">
/// <paramref name="key"/> already exists in the <see cref="SortedDictionaryEx{TKey,
/// TValue}"/>.</exception>
/// <exception cref="ArgumentNullException">
/// <paramref name="key"/> is a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="value"/> is an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="IKeyedValue{TKey}.Key"/> differs from <paramref name="key"/>.</exception>
/// <exception cref="NotSupportedException">
/// The <see cref="SortedDictionaryEx{TKey, TValue}"/> is read-only.</exception>
/// <remarks>
/// Please refer to <see cref="SortedDictionary{TKey, TValue}.Add(TKey, TValue)"/> for
/// details.</remarks>
public void Add(TKey key, TValue value)
{
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
if (value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(key, value);
}
InnerDictionary.Add(key, value);
}
/// <summary>
/// Removes the specified key-and-value pair from the <see cref="SortedDictionaryEx{TKey,
/// TValue}"/>.</summary>
/// <param name="pair">
/// The <see cref="KeyValuePair{TKey, TValue}"/> element to remove.</param>
/// <returns>
/// <c>true</c> if <paramref name="pair"/> was found and removed; otherwise, <c>false</c>.
/// </returns>
/// <exception cref="ArgumentNullException">
/// The <see cref="KeyValuePair{TKey, TValue}.Key"/> component of <paramref name="pair"/> is
/// a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// The <see cref="KeyValuePair{TKey, TValue}.Value"/> component of <paramref name="pair"/>
/// is an <see cref="IKeyedValue{TKey}"/> instance whose <see cref="IKeyedValue{TKey}.Key"/>
/// differs from the associated <see cref="KeyValuePair{TKey, TValue}.Key"/> component.
/// </exception>
/// <exception cref="NotSupportedException">
/// The <see cref="SortedDictionaryEx{TKey, TValue}"/> is read-only.</exception>
/// <remarks>
/// Please refer to <see cref="ICollection{T}.Remove"/> for details.</remarks>
public bool Remove(KeyValuePair <TKey, TValue> pair)
{
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
if (pair.Value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(pair.Key, pair.Value);
}
return(((ICollection <KeyValuePair <TKey, TValue> >)InnerDictionary).Remove(pair));
}
/// <summary>
/// Initializes a new instance of the <see cref="SortedDictionaryEx{TKey, TValue}"/> class
/// that contains elements copied from the specified collection and uses the specified
/// comparer for <typeparamref name="TKey"/>.</summary>
/// <param name="dictionary">
/// The <see cref="IDictionary{TKey, TValue}"/> whose elements are copied to the new
/// collection.</param>
/// <param name="comparer">
/// The <see cref="IComparer{TKey}"/> to use when comparing keys, or a null reference to use
/// the default <see cref="System.Collections.Generic.Comparer{T}"/> for <typeparamref
/// name="TKey"/>.</param>
/// <exception cref="ArgumentException">
/// <paramref name="dictionary"/> contains one or more duplicate keys.</exception>
/// <exception cref="ArgumentNullException"><para>
/// <paramref name="dictionary"/> is a null reference.
/// </para><para>-or-</para><para>
/// <paramref name="dictionary"/> contains an element whose <see cref="KeyValuePair{TKey,
/// TValue}.Key"/> is a null reference. </para></exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="dictionary"/> contains an element whose <see cref="KeyValuePair{TKey,
/// TValue}.Value"/> is an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="IKeyedValue{TKey}.Key"/> differs from the associated <see cref="KeyValuePair{TKey,
/// TValue}.Key"/>.</exception>
/// <remarks>
/// Please refer to <see cref="SortedDictionary{TKey, TValue}(IDictionary{TKey, TValue},
/// IComparer{TKey})"/> for details.</remarks>
public SortedDictionaryEx(IDictionary <TKey, TValue> dictionary, IComparer <TKey> comparer)
{
if (dictionary == null)
{
ThrowHelper.ThrowArgumentNullException("dictionary");
}
foreach (KeyValuePair <TKey, TValue> pair in dictionary)
{
CollectionsUtility.ValidateKey(pair.Key, pair.Value);
}
InnerDictionary = new SortedDictionary <TKey, TValue>(dictionary, comparer);
}
/// <summary>
/// Sets the value at the specified index.</summary>
/// <param name="index">
/// The zero-based index of the value to set.</param>
/// <param name="value">
/// The value to store at the specified <paramref name="index"/> in the <see
/// cref="KeyValueList{TKey, TValue}"/>.</param>
/// <exception cref="ArgumentOutOfRangeException"><para>
/// <paramref name="index"/> is less than zero.
/// </para><para>-or-</para><para>
/// <paramref name="index"/> is equal to or greater than <see cref="ListEx{T}.Count"/>.
/// </para></exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="value"/> is an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="IKeyedValue{TKey}.Key"/> component differs from the key at the specified <paramref
/// name="index"/>.</exception>
/// <exception cref="NotSupportedException">
/// The <see cref="KeyValueList{TKey, TValue}"/> is read-only.</exception>
/// <remarks>
/// Please refer to <see cref="SortedList.SetByIndex"/> for details.</remarks>
public void SetByIndex(int index, TValue value)
{
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
TKey key = InnerList[index].Key;
if (value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(key, value);
}
InnerList[index] = new KeyValuePair <TKey, TValue>(key, value);
}
/// <summary>
/// Gets or sets the value associated with the specified key.</summary>
/// <param name="key">
/// The key whose value to get or set.</param>
/// <value><para>
/// The value associated with the specified <paramref name="key"/>.
/// </para><para>
/// If <paramref name="key"/> is not found, attempting to get it throws a <see
/// cref="KeyNotFoundException"/>, and attempting to set it adds a new element with the
/// specified key and value to the <see cref="SortedDictionaryEx{TKey, TValue}"/>.
/// </para></value>
/// <exception cref="ArgumentNullException">
/// <paramref name="key"/> is a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// The property is set to an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="KeyValuePair{TKey, TValue}.Key"/> differs from the specified <paramref
/// name="key"/>.</exception>
/// <exception cref="KeyNotFoundException">
/// The property is read, and <paramref name="key"/> does not exist in the <see
/// cref="SortedDictionaryEx{TKey, TValue}"/>.</exception>
/// <exception cref="NotSupportedException">
/// The property is set, and the <see cref="SortedDictionaryEx{TKey, TValue}"/> is
/// read-only.</exception>
/// <remarks>
/// Please refer to <see cref="SortedDictionary{TKey, TValue}.this"/> for details.</remarks>
public TValue this[TKey key] {
[DebuggerStepThrough]
get { return(InnerDictionary[key]); }
set {
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
if (value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(key, value);
}
InnerDictionary[key] = value;
}
}
/// <summary>
/// Checks that the specified key-and-value pair can be added to the <see
/// cref="KeyValueList{TKey, TValue}"/>.</summary>
/// <param name="pair">
/// The <see cref="KeyValuePair{TKey, TValue}"/> element to add.</param>
/// <exception cref="ArgumentNullException">
/// The <see cref="KeyValuePair{TKey, TValue}.Key"/> component of <paramref name="pair"/> is
/// a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// The <see cref="KeyValuePair{TKey, TValue}.Value"/> component of <paramref name="pair"/>
/// is an <see cref="IKeyedValue{TKey}"/> instance whose <see cref="IKeyedValue{TKey}.Key"/>
/// differs from the associated <see cref="KeyValuePair{TKey, TValue}.Key"/> component.
/// </exception>
/// <exception cref="NotSupportedException"><para>
/// The <see cref="KeyValueList{TKey, TValue}"/> is read-only.
/// </para><para>-or-</para><para>
/// The <see cref="KeyValueList{TKey, TValue}"/> already contains the <see
/// cref="KeyValuePair{TKey, TValue}.Key"/> component of <paramref name="pair"/>, and the
/// <see cref="MultiKeyedList{TKey, TValue}"/> ensures that all keys are unique.
/// </para></exception>
protected override void CheckWritable(KeyValuePair <TKey, TValue> pair)
{
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
if (pair.Value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(pair.Key, pair.Value);
}
if (UniqueFlag && IndexOfKey(pair.Key) >= 0)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionUnique);
}
}
/// <summary>
/// Checks that the specified key-and-value pair can be inserted into the <see
/// cref="MultiKeyedList{TKey, TValue}"/> at the specified index.</summary>
/// <param name="index">
/// The zero-based index at which to insert <paramref name="pair"/>.</param>
/// <param name="pair">
/// The <see cref="KeyValuePair{TKey, TValue}"/> element to add.</param>
/// <exception cref="ArgumentNullException">
/// The <see cref="KeyValuePair{TKey, TValue}.Key"/> component of <paramref name="pair"/> is
/// a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// The <see cref="KeyValuePair{TKey, TValue}.Value"/> component of <paramref name="pair"/>
/// is an <see cref="IKeyedValue{TKey}"/> instance whose <see cref="IKeyedValue{TKey}.Key"/>
/// differs from the associated <see cref="KeyValuePair{TKey, TValue}.Key"/> component.
/// </exception>
/// <exception cref="NotSupportedException"><para>
/// The <see cref="KeyValueList{TKey, TValue}"/> is read-only.
/// </para><para>-or-</para><para>
/// The <see cref="KeyValueList{TKey, TValue}"/> already contains the <see
/// cref="KeyValuePair{TKey, TValue}.Key"/> component of <paramref name="pair"/> at a
/// different index, and the <see cref="MultiKeyedList{TKey, TValue}"/> ensures that all
/// keys are unique.</para></exception>
/// <remarks>
/// <b>CheckWritable</b> does not test for duplicate keys if the specified <paramref
/// name="index"/> is less than zero, or equal to or greater than <see
/// cref="ListEx{T}.Count"/>.</remarks>
protected override void CheckWritable(int index, KeyValuePair <TKey, TValue> pair)
{
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
if (pair.Value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(pair.Key, pair.Value);
}
if (UniqueFlag && index >= 0 && index < Count)
{
int existing = IndexOfKey(pair.Key);
if (existing >= 0 && existing != index)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionUnique);
}
}
}
/// <summary>
/// Initializes a new instance of the <see cref="BraidedTreeNode{TKey, TValue}"/> class with
/// the specified tree structure, key and value.</summary>
/// <param name="tree">
/// The <see cref="BraidedTree{TKey, TValue}"/> that contains the <see
/// cref="BraidedTreeNode{TKey, TValue}"/>.</param>
/// <param name="key">
/// The key of the <see cref="BraidedTreeNode{TKey, TValue}"/>.</param>
/// <param name="value">
/// The value of the <see cref="BraidedTreeNode{TKey, TValue}"/>.</param>
/// <exception cref="ArgumentNullException">
/// <paramref name="tree"/> or <paramref name="key"/> is a null reference.</exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="value"/> is an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="KeyValuePair{TKey, TValue}.Key"/> differs from the specified <paramref
/// name="key"/>.</exception>
/// <remarks>
/// <see cref="Priority"/> is set to a random value in the open interval [0, 1).</remarks>
internal BraidedTreeNode(BraidedTree <TKey, TValue> tree, TKey key, TValue value)
{
if (tree == null)
{
ThrowHelper.ThrowArgumentNullException("tree");
}
if (value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(Key, value);
}
else if (key == null)
{
ThrowHelper.ThrowArgumentNullException("key");
}
_tree = tree;
_next = _previous = this;
_priority = tree.Random.NextDouble();
Key = key; _value = value;
}
/// <summary>
/// Adds the elements of the specified collection to the <see cref="SortedDictionaryEx{TKey,
/// TValue}"/>. </summary>
/// <param name="dictionary">
/// The <see cref="IDictionary{TKey, TValue}"/> whose elements to add.</param>
/// <exception cref="ArgumentNullException"><para>
/// <paramref name="dictionary"/> is a null reference.
/// </para><para>-or-</para><para>
/// <paramref name="dictionary"/> contains an element whose <see cref="KeyValuePair{TKey,
/// TValue}.Key"/> is a null reference. </para></exception>
/// <exception cref="KeyMismatchException">
/// <paramref name="dictionary"/> contains an element whose <see cref="KeyValuePair{TKey,
/// TValue}.Value"/> is an <see cref="IKeyedValue{TKey}"/> instance whose <see
/// cref="IKeyedValue{TKey}.Key"/> differs from the associated <see cref="KeyValuePair{TKey,
/// TValue}.Key"/>.</exception>
/// <exception cref="NotSupportedException"><para>
/// The <see cref="SortedDictionaryEx{TKey, TValue}"/> is read-only.
/// </para><para>-or-</para><para>
/// The <see cref="SortedDictionaryEx{TKey, TValue}"/> already contains one or more keys in
/// the specified <paramref name="dictionary"/>.
/// </para><para>-or-</para><para>
/// <paramref name="dictionary"/> contains one or more duplicate keys.</para></exception>
/// <remarks>
/// Please refer to <see cref="List{T}.AddRange"/> for details.</remarks>
public void AddRange(IDictionary <TKey, TValue> dictionary)
{
if (ReadOnlyFlag)
{
ThrowHelper.ThrowNotSupportedException(Strings.CollectionReadOnly);
}
if (dictionary == null)
{
ThrowHelper.ThrowArgumentNullException("dictionary");
}
foreach (KeyValuePair <TKey, TValue> pair in dictionary)
{
TKey key = pair.Key; TValue value = pair.Value;
if (value is IKeyedValue <TKey> )
{
CollectionsUtility.ValidateKey(key, value);
}
InnerDictionary.Add(key, value);
}
}
/// <summary>
/// Determines whether the specified collection contains the same elements in the same order
/// as the current <see cref="StackEx{T}"/>.</summary>
/// <param name="collection">
/// The <see cref="ICollection"/> to compare with the current <see cref="StackEx{T}"/>.
/// </param>
/// <returns><para>
/// <c>true</c> under the following conditions, otherwise <c>false</c>:
/// </para><list type="bullet"><item>
/// <paramref name="collection"/> is another reference to this <see cref="StackEx{T}"/>.
/// </item><item>
/// <paramref name="collection"/> is not a null reference, contains the same number of
/// elements as this <see cref="StackEx{T}"/>, and all elements compare as equal when
/// retrieved in the enumeration sequence for each collection.</item></list></returns>
/// <remarks><para>
/// <b>Equals</b> calls <see cref="CollectionsUtility.SequenceEqualUntyped"/> to test the
/// two collections for value equality.
/// </para><note type="implementnotes">
/// <para>The <see cref="StackEx{T}"/> is a last-in, first-out (LIFO) collection, which
/// means that its enumeration sequence is reversed compared to a first-in, first-out (FIFO)
/// collection that contains the same elements in the same original insertion order.
/// </para><para>
/// When comparing to a non-LIFO collection, you must first reverse its element order, or
/// that of the <see cref="StackEx{T}"/>, for a successful comparison. Use the alternative
/// method <see cref="EqualsReverse"/> to automatically perform this inversion.
/// </para></note></remarks>
public bool Equals(ICollection collection)
{
return(CollectionsUtility.SequenceEqualUntyped(this, collection));
}
