//******************************************************************************************************//  DictionaryList.cs - Gbtc////  Copyright © 2012, Grid Protection Alliance.  All Rights Reserved.////  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See//  the NOTICE file distributed with this work for additional information regarding copyright ownership.//  The GPA licenses this file to you under the MIT License (MIT), the "License"; you may//  not use this file except in compliance with the License. You may obtain a copy of the License at:////      http://www.opensource.org/licenses/MIT////  Unless agreed to in writing, the subject software distributed under the License is distributed on an//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the//  License for the specific language governing permissions and limitations.////  Code Modification History://  ----------------------------------------------------------------------------------------------------//  01/07/2006 - J. Ritchie Carroll//       Generated original version of source code.//  09/10/2008 - J. Ritchie Carroll//       Converted to C#.//  02/19/2009 - Josh L. Patterson//       Edited Code Comments.//  08/05/2009 - Josh L. Patterson//       Edited Comments.//  09/14/2009 - Stephen C. Wills//       Added new header and license agreement.//  12/13/2012 - Starlynn Danyelle Gilliam//       Modified Header.////****************************************************************************************************** using System.Collections;using System.Collections.Generic; namespace GSF.Collections{    /// <summary>    /// Represents a sorted dictionary style list that supports <see cref="IList"/>.    /// </summary>    /// <remarks>    /// <para>    /// Have you ever needed the quick look-up feature on a Dictionary (e.g., Hashtable), but ended    /// up missing the indexed or sequential access like you have in a list? You may have wondered why    /// the .NET dictionary class doesn’t implement the IList interface which allows this. The reason    /// IDictionary implementations do not normally implement the IList interface is because of    /// ambiguity that is caused when implementing an integer key. For example, if you created a    /// dictionary style class with a key of type "Integer" that actually did implement IList(Of T),    /// you would not be able to access items in the IList interface by index without "casting" the    /// class as IList. This is because the Item property in both the IDictionary and IList would have    /// the same parameters. Note, however, that generics in .NET 2.0 gladly allow a class to implement    /// both IDictionary and IList (even specifying as Integer as the key) so long you as you are happy    /// knowing that the compiler will choose if you access your items by index or key. Given that    /// caveat, there are many times when you need a dictionary style collection but also desire an    /// IList implementation so the class can be used in other ways without conversion. As a result of    /// these needs, we’ve added a generic class to code library called a DictionaryList -- which is    /// essentially just a sorted dictionary style list (i.e., SortedList) that implements the    /// IList(Of T) interface (specifically as IList(Of KeyValuePair(Of TKey, TValue))). You will find    /// all of your convenient expected methods related to both dictionaries and lists; that is, you can    /// look-up items by key or by index. The class works perfectly for any non-Integer based key    /// (e.g., String, custom class, etc.) -- note that specifying an Integer as the key for the class    /// won’t cause an error, but it also will not be very useful. However, you can specify the key for    /// your DictionaryList as a "Long," which allows you to use long integers for keyed look-ups and    /// regular integers for indexed access--the best of both worlds! In summary, I would not change    /// your programming habits to start using this for "my collection for everything," as nothing comes    /// for free; however, if you have a need for a "hybrid" collection class, this fits the bill.    /// </para>    /// <para>    /// Important note about using an "Integer" as the key for this class: IDictionary implementations    /// do not normally implement the IList interface because of ambiguity that is caused when implementing    /// an integer key. For example, if you implement this class with a key of type "Integer" you will not    /// be able to access items in the queue by index without "casting" the class as IList. This is because    /// the Item property in both the IDictionary and IList would have the same parameters.    /// </para>    /// <para>    /// Note that prior to the addition of Generics in .NET, the class that performed a similar function    /// was the "NameObjectCollectionBase" in the System.Collections.Specialized namespace which    /// specifically allowed item access by either key or by index.  This class is similar in function    /// but instead is a generic class allowing use with any strongly typed key or value.     /// </para>    /// </remarks>    /// <typeparam name="TKey">Generic key type.</typeparam>    /// <typeparam name="TValue">Generic value type.</typeparam>    public class DictionaryList<TKey, TValue> : IList<KeyValuePair<TKey, TValue>>, IDictionary<TKey, TValue>    {        #region [ Members ]         // Fields        private readonly SortedList<TKey, TValue> m_list;         #endregion         #region [ Constructors ]         /// <summary>        /// Creates a new <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        public DictionaryList()        {            m_list = new SortedList<TKey, TValue>();        }         #endregion         #region [ Properties ]         // Generic IList(Of KeyValuePair(Of TKey, TValue)) Properties         /// <summary>        /// Gets the number of elements contained in the <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        public int Count        {            get            {                return m_list.Count;            }        }         /// <summary>        /// Gets a value indicating whether the <see cref="DictionaryList{TKey,TValue}"/> is read-only.        /// </summary>        public bool IsReadOnly        {            get            {                return false;            }        }         /// <summary>        /// Gets or sets the element at the specified index.        /// </summary>        /// <param name="index">The zero-based index of the element to get or set.</param>        /// <returns>The element at the specified index.</returns>        public KeyValuePair<TKey, TValue> this[int index]        {            get            {                return new KeyValuePair<TKey, TValue>(m_list.Keys[index], m_list.Values[index]);            }            set            {                m_list[value.Key] = value.Value;            }        }         // Generic IDictionary(Of TKey, TValue) Properties         /// <summary>        /// Gets or sets the element with the specified key.        /// </summary>        /// <param name="key">The key of the element to get or set.</param>        /// <returns>The element with the specified key.</returns>        public TValue this[TKey key]        {            get            {                return m_list[key];            }            set            {                m_list[key] = value;            }        }         /// <summary>        /// Gets an <see cref="ICollection{T}"/> containing the keys of the <see cref="IDictionary{TKey,TValue}"/>.        /// </summary>        public ICollection<TKey> Keys        {            get            {                return m_list.Keys;            }        }         /// <summary>        /// Gets an <see cref="ICollection{T}"/> containing the values in the <see cref="IDictionary{TKey,TValue}"/>.        /// </summary>        public ICollection<TValue> Values        {            get            {                return m_list.Values;            }        }         #endregion         #region [ Methods ]         // Generic IList(Of KeyValuePair(Of TKey, TValue)) Methods         /// <summary>        /// Adds an item to the <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        /// <param name="item">The key value pair item to add.</param>        public void Add(KeyValuePair<TKey, TValue> item)        {            m_list.Add(item.Key, item.Value);        }         /// <summary>        /// Removes all items from the <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        public void Clear()        {            m_list.Clear();        }         /// <summary>        /// Determines whether the <see cref="DictionaryList{TKey,TValue}"/> contains a specific value.        /// </summary>        /// <param name="item">The object to locate in the <see cref="DictionaryList{TKey,TValue}"/>.</param>        /// <returns>true if item is found in the <see cref="DictionaryList{TKey,TValue}"/>; otherwise, false</returns>        public bool Contains(KeyValuePair<TKey, TValue> item)        {            return m_list.ContainsKey(item.Key);        }         /// <summary>        /// Copies the elements of the <see cref="DictionaryList{TKey,TValue}"/> to an <see cref="System.Array"/>, starting at a particular index.        /// </summary>        /// <param name="array">        /// The one-dimensional <see cref="System.Array"/> that is the destination of the elements         /// copied from <see cref="DictionaryList{TKey,TValue}"/>. The array must         /// have zero-based indexing.        /// </param>        /// <param name="arrayIndex">The zero-based index in array at which copying begins.</param>        public void CopyTo(KeyValuePair<TKey, TValue>[] array, int arrayIndex)        {            for (int x = 0; x < m_list.Count; x++)            {                array[arrayIndex + x] = new KeyValuePair<TKey, TValue>(m_list.Keys[x], m_list.Values[x]);            }        }         /// <summary>        /// Removes the first occurrence of a specific object from the <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        /// <param name="item">The object to remove from the <see cref="DictionaryList{TKey,TValue}"/>.</param>        /// <returns>        /// true if item was successfully removed from the <see cref="DictionaryList{TKey,TValue}"/>;         /// otherwise, false. This method also returns false if item is not found in         /// the original <see cref="DictionaryList{TKey,TValue}"/>.        /// </returns>        public bool Remove(KeyValuePair<TKey, TValue> item)        {            return m_list.Remove(item.Key);        }         /// <summary>        /// Determines the index of a specific item in the <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        /// <param name="item">The object to locate in the <see cref="DictionaryList{TKey,TValue}"/>.</param>        /// <returns>The index of item if found in the list; otherwise, -1.</returns>        public int IndexOf(KeyValuePair<TKey, TValue> item)        {            return m_list.IndexOfKey(item.Key);        }         /// <summary>        /// Removes the <see cref="DictionaryList{TKey,TValue}"/> item at the specified index.        /// </summary>        /// <param name="index">The zero-based index of the item to remove.</param>        public void RemoveAt(int index)        {            m_list.RemoveAt(index);        }         /// <summary>        /// Inserts an item to the <see cref="DictionaryList{TKey,TValue}"/> at the specified index.        /// </summary>        /// <param name="index">The zero-based index at which item should be inserted.</param>        /// <param name="item">The object to insert into the <see cref="DictionaryList{TKey,TValue}"/>.</param>        public void Insert(int index, KeyValuePair<TKey, TValue> item)        {            // It does not matter where you try to insert the value, since it will be inserted into its sorted            // location, so we just add the value.            m_list.Add(item.Key, item.Value);        }         /// <summary>        /// Returns an enumerator that iterates through the collection.        /// </summary>        /// <returns>A <see cref="IEnumerator{T}"/> that can be used to iterate through the collection.</returns>        public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()        {            return m_list.GetEnumerator();        }         IEnumerator IEnumerable.GetEnumerator()        {            return ((IEnumerable)m_list).GetEnumerator();        }         // Generic IDictionary(Of TKey, TValue) Methods         /// <summary>        /// Adds an element with the provided key and value to the <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        /// <param name="key">The object to use as the key of the element to add.</param>        /// <param name="value">The object to use as the value of the element to add.</param>        public void Add(TKey key, TValue value)        {            m_list.Add(key, value);        }         /// <summary>        /// Determines whether the <see cref="DictionaryList{TKey,TValue}"/> contains an element with the specified key.        /// </summary>        /// <param name="key">The key to locate in the <see cref="DictionaryList{TKey,TValue}"/>.</param>        /// <returns>true if the <see cref="DictionaryList{TKey,TValue}"/> contains an element with the key; otherwise, false.</returns>        public bool ContainsKey(TKey key)        {            return m_list.ContainsKey(key);        }         /// <summary>        /// Determines whether the <see cref="DictionaryList{TKey,TValue}"/> contains a specific value.        /// </summary>        /// <param name="value">The value to locate in the <see cref="DictionaryList{TKey,TValue}"/>. The value can be null for reference types.</param>        /// <returns>true if the <see cref="DictionaryList{TKey,TValue}"/> contains an element with the specified value; otherwise, false.</returns>        public bool ContainsValue(TValue value)        {            return m_list.ContainsValue(value);        }         /// <summary>        /// Searches for the specified key and returns the zero-based index within the entire <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        /// <param name="key">The key to locate in the <see cref="DictionaryList{TKey,TValue}"/>.</param>        /// <returns>The zero-based index of key within the entire <see cref="DictionaryList{TKey,TValue}"/>, if found; otherwise, -1.</returns>        public int IndexOfKey(TKey key)        {            return m_list.IndexOfKey(key);        }         /// <summary>        /// Searches for the specified value and returns the zero-based index of the first occurrence within the entire <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        /// <param name="value">The value to locate in the <see cref="DictionaryList{TKey,TValue}"/>. The value can be null for reference types.</param>        /// <returns>The zero-based index of the first occurrence of value within the entire <see cref="DictionaryList{TKey,TValue}"/>, if found; otherwise, -1.</returns>        public int IndexOfValue(TValue value)        {            return m_list.IndexOfValue(value);        }         /// <summary>        /// Removes the element with the specified key from the <see cref="DictionaryList{TKey,TValue}"/>.        /// </summary>        /// <param name="key">The key of the element to remove.</param>        /// <returns>        /// true if the element is successfully removed; otherwise, false. This method also returns false if key        /// was not found in the original <see cref="DictionaryList{TKey,TValue}"/>.</returns>        public bool Remove(TKey key)        {            return m_list.Remove(key);        }         /// <summary>        /// Gets the value associated with the specified key.        /// </summary>        /// <param name="key">The key whose value to get.</param>        /// <param name="value">        /// When this method returns, the value associated with the specified key, if         /// the key is found; otherwise, the default value for the type of the value        /// parameter. This parameter is passed uninitialized.</param>        /// <returns>        /// true if the <see cref="DictionaryList{TKey,TValue}"/> contains an element with the specified key; otherwise, false.</returns>        public bool TryGetValue(TKey key, out TValue value)        {            return m_list.TryGetValue(key, out value);        }         #endregion    }}