Example #1
0
        /// <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);
            }
        }
Example #2
0
        /// <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);
            }
        }
Example #3
0
        /// <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));
        }
Example #4
0
        /// <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);
        }
Example #8
0
        /// <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;
            }
        }
Example #10
0
        /// <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);
            }
        }
Example #11
0
        /// <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);
                }
            }
        }
Example #12
0
        /// <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);
            }
        }
Example #14
0
        /// <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));
        }