Type: System.Collections.SortedList

System.Collections.SortedList Class

Assembly: Mscorlib.dll
Namespace: System.Collections

Summary: Represents a collection of key-and-value pairs that are sorted by the keys and are accessible by key and by index.

C# Syntax:

[Serializable]
public class SortedList : IDictionary, ICollection, IEnumerable, ICloneable

Thread Safety

Public static (non-instance) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

A SortedList can safely support multiple readers concurrently, as long as the collection is not modified. To guarantee the thread safety of the SortedList, all operations must be done through the wrapper returned by the SortedList.Synchronized method.

Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.

Remarks

A SortedList is a hybrid between a Hashtable and an Array. When an element is accessed by its key using the SortedList.Item indexer property, it behaves like a Hashtable. When an element is accessed by its index using SortedList.GetByIndex or SortedList.SetByIndex, it behaves like an Array.

A SortedList internally maintains two arrays to store the elements of the list; that is, one array for the keys and another array for the associated values. Each element is a key-and-value pair that can be accessed as a DictionaryEntry object.

The capacity of a SortedList is the number of elements that the list can hold. As elements are added to a SortedList, the capacity is automatically increased as required through reallocation. The capacity can be decreased by calling SortedList.TrimToSize or by setting the SortedList.Capacity property explicitly.

The elements of a SortedList are sorted by the keys either according to a specific IComparer implementation specified when the SortedList is created or according to the IComparable implementation provided by the keys themselves. In either case, a SortedList does not allow duplicate keys.

The index sequence is based on the sort sequence. When an element is added, it is inserted into SortedList in the correct sort order, and the indexing adjusts accordingly. When an element removed, the indexing also adjusts accordingly. Therefore, the index of a specific key-and-value pair might change as elements are added or removed from the SortedList.

Operations on a SortedList tend to be slower than operations on a Hashtable because of the sorting. However, the SortedList offers more flexibility by allowing access to the values either through the associated keys or through the indexes.

A key cannot be null, but a value can be null.

Indexes in this collection are zero-based.

The foreach statement of the C# language requires the type of each element in the collection. Since each element of the Hashtable is a key-and-value pair, the element type is not the type of the key or the type of the value. Instead, the element type is DictionaryEntry. For example: foreach (DictionaryEntry myEntry in myHashtable) {...}

Example

The following example shows how to create and initialize a SortedList and how to print out its keys and values.

 using System;
 using System.Collections;
 public class SamplesSortedList  {
 
    public static void Main()  {
 
       // Creates and initializes a new SortedList.
       SortedList mySL = new SortedList();
       mySL.Add("First", "Hello");
       mySL.Add("Second", "World");
       mySL.Add("Third", "!");
 
       // Displays the properties and values of the SortedList.
       Console.WriteLine( "mySL" );
       Console.WriteLine( "  Count:    {0}", mySL.Count );
       Console.WriteLine( "  Capacity: {0}", mySL.Capacity );
       Console.WriteLine( "  Keys and Values:" );
       PrintKeysAndValues( mySL );
    }
 
 
    public static void PrintKeysAndValues( SortedList myList )  {
       Console.WriteLine( "\t-KEY-\t-VALUE-" );
       for ( int i = 0; i < myList.Count; i++ )  {
          Console.WriteLine( "\t{0}:\t{1}", myList.GetKey(i), myList.GetByIndex(i) );
       }
       Console.WriteLine();
    }
 }
 /* 
 This code produces the following output.
 
 mySL
   Count:    3
   Capacity: 16
   Keys and Values:
     -KEY-    -VALUE-
     First:    Hello
     Second:    World
     Third:    !
 */

System.Collections.SortedList Member List:

Public Constructors

ctor #1	Overloaded: `.ctor()`Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the SortedList class that is empty, has the default initial capacity and is sorted according to the IComparable interface implemented by each key added to the SortedList.
ctor #2	Overloaded: `.ctor(IComparer comparer)` Initializes a new instance of the SortedList class that is empty, has the default initial capacity and is sorted according to the specified IComparer interface.
ctor #3	Overloaded: `.ctor(IDictionary d)` Initializes a new instance of the SortedList class that contains elements copied from the specified dictionary, has the same initial capacity as the number of elements copied and is sorted according to the IComparable interface implemented by each key.
ctor #4	Overloaded: `.ctor(int initialCapacity)` Initializes a new instance of the SortedList class that is empty, has the specified initial capacity and is sorted according to the IComparable interface implemented by each key added to the SortedList.
ctor #5	Overloaded: `.ctor(IComparer comparer, int capacity)` Initializes a new instance of the SortedList class that is empty, has the specified initial capacity and is sorted according to the specified IComparer interface.
ctor #6	Overloaded: `.ctor(IDictionary d, IComparer comparer)` Initializes a new instance of the SortedList class that contains elements copied from the specified dictionary, has the same initial capacity as the number of elements copied and is sorted according to the specified IComparer interface.

Public Properties

Capacity	Read-write Gets or sets the capacity of the SortedList.
Count	Read-only Gets the number of elements contained in the SortedList.
IsFixedSize	Read-only Gets a value indicating whether the SortedList has a fixed size.
IsReadOnly	Read-only Gets a value indicating whether the SortedList is read-only.
IsSynchronized	Read-only Gets a value indicating whether access to the SortedList is synchronized (thread-safe).
Item	Read-write Gets and sets the value associated with a specific key in the SortedList.
Keys	Read-only Gets the keys in the SortedList.
SyncRoot	Read-only Gets an object that can be used to synchronize access to the SortedList.
Values	Read-only Gets the values in the SortedList.

Public Methods

Add	Adds an element with the specified key and value to the SortedList.
Clear	Removes all elements from the SortedList.
Clone	Creates a shallow copy of the SortedList.
Contains	Determines whether the SortedList contains a specific key.
ContainsKey	Determines whether the SortedList contains a specific key.
ContainsValue	Determines whether the SortedList contains a specific value.
CopyTo	Copies the SortedList elements to a one-dimensional Array instance at the specified index.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetByIndex	Gets the value at the specified index of the SortedList.
GetEnumerator	Returns an IDictionaryEnumerator that can iterate through the SortedList.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetKey	Gets the key at the specified index of the SortedList.
GetKeyList	Gets the keys in the SortedList.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
GetValueList	Gets the values in the SortedList.
IndexOfKey	Returns the zero-based index of the specified key in the SortedList.
IndexOfValue	Returns the zero-based index of the first occurrence of the specified value in the SortedList.
Remove	Removes the element with the specified key from SortedList.
RemoveAt	Removes the element at the specified index of SortedList.
SetByIndex	Replaces the value at a specific index in the SortedList.
Synchronized	Returns a synchronized (thread-safe) wrapper for the SortedList.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
TrimToSize	Sets the capacity to the actual number of elements in the SortedList.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Explicit Interface Implementations

IEnumerable.GetEnumerator

Returns an IEnumerator that can iterate through the SortedList.

Hierarchy:

System.Object

System.Collections.SortedList

System.Collections.SortedList Member Details

Overloaded ctor #1

Summary: Initializes a new instance of the SortedList class that is empty, has the default initial capacity and is sorted according to the IComparable interface implemented by each key added to the SortedList.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:


            public SortedList();

Remarks

The initial capacity is the starting capacity of the new SortedList. The default initial capacity for a SortedList is 16.

If the number of elements added to the list reaches the current capacity, the capacity is automatically doubled.

Each key must implement the IComparable interface to be capable of comparisons with every other key in the SortedList. The elements are sorted according to the IComparable implementation of each key added to the SortedList.

Exception Type	Condition
ArgumentNullException	d is null.
InvalidCastException	One or more elements in d do not implement the IComparable interface.

Exception Type	Condition
ArgumentNullException	key is null.
ArgumentException	An element with the specified key already exists in the SortedList. -or- The SortedList is set to use the IComparable interface, and key does not implement the IComparable interface.
NotSupportedException	The SortedList is read-only. -or- The SortedList has a fixed size.
InvalidOperationException	The comparer throws an exception.

Exception Type	Condition
ArgumentNullException	array is null.
ArgumentOutOfRangeException	arrayIndex is less than zero.
ArgumentException	array is multidimensional. -or- arrayIndex is equal to or greater than the length of array. -or- The number of elements in the source SortedList is greater than the available space from arrayIndex to the end of the destination array.
InvalidCastException	The type of the source SortedList cannot be cast automatically to the type of the destination array.