C# 0 The Complete Reference

NotSupportedException

 if the collection is read-only. 

Because

ICollection

 inherits 

IEnumerable

 and 

IEnumerable

, it also includes both 

the generic and non-generic forms of the method 

GetEnumerator( )

.

Because

ICollection

 inherits 

IEnumerable

, it supports the extension methods 

defined by 

Enumerable

. Although the extension methods were designed mostly for LINQ, 

they are available for other uses, including collections.

The IList Interface

The

IList

 interface defines the behavior of a generic collection that allows elements to 

be accessed via a zero-based index. It inherits 

IEnumerable

,

IEnumerable

, and 

ICollection

and is the generic version of the non-generic 

IList

 interface. 

IList

defines the methods shown in Table 24-11. Two of these methods imply the modification of 

a collection. If the collection is read-only or of fixed size, then the 

Insert( ) 

and

RemoveAt( )

methods will throw a 

NotSupportedException

.

IList

defines the following indexer:

T this[int 

idx

] { get; set; }

This indexer sets or gets the value of the element at the index specified by 

idx.

Method

Description

int IndexOf(T 

obj

)

Returns the index of the first occurrence of 

obj

 if 

obj

 is 

contained within the invoking collection. If 

obj

 is not found, 

–1 is returned. 

void Inser t(int 

idx

, T 

obj

)

Inser ts 

obj

 at the index specified by 

idx.

void RemoveAt(int 

idx

)

Removes the object at the index specified by 

idx

 from the 

invoking collection. 

T

ABLE

 24-11 

The Methods Defi ned by 

IList

www.freepdf-books.com

---

PART II

C h a p t e r   2 4 :  

C o l l e c t i o n s ,   E n u m e r a t o r s ,   a n d   I t e r a t o r s    

777

The IDictionary Interface

The

IDictionary

 interface defines the behavior of a generic collection that 

maps unique keys to values. That is, it defines a collection that stores key/value pairs. 

IDictionary

 inherits 

IEnumerable

,

IEnumerable>

,

and

ICollection< KeyValuePair>

 and is the generic version of the non-generic 

IDictionary

. The methods declared by 

IDictionary

 are summarized in Table 24-12. 

All throw an 

ArgumentNullException

 if an attempt is made to specify a null key.

IDictionary

 defines the following properties:

Property

Description

ICollection Keys { get; }

Obtains a collection of the keys. 

ICollection Values { get; }

Obtains a collection of the values. 

Notice that the keys and values contained within the collection are available as separate lists 

through the 

Keys

 and 

Values

 properties.

IDictionary

 defines the following indexer:

TV this[TK 

key

] { get; set; }

You can use this indexer to get or set the value of an element. You can also use it to add a 

new element to the collection. Notice that the “index” is not actually an index, but rather the 

key of the item.

IEnumerable and IEnumerator

IEnumerable

and

 IEnumerator 

are the generic equivalents of the non-generic 

IEnumerable

 and 

IEnumerator

 interfaces described earlier. They declare the same methods 

and properties, and work in the same way. Of course, the generic versions operate on data 

of the type specified by the type argument.

IEnumerable

 declares the 

GetEnumerator( ) 

method as shown here:

IEnumerator GetEnumerator( )

It returns an enumerator of type 

T

 for the collection. Thus, it returns a type-safe enumerator.

Method

Description

void Add(TK 

k

, TV 

v

)

Adds the key/value pair specified by 

k

 and 

v

 to the invoking 

collection. An 

ArgumentException

 is thrown if 

k

 is already 

stored in the collection.

bool ContainsKey(TK 

k

)

Returns true if the invoking collection contains 

k

 as a key. 

Other wise, returns false.

bool Remove(TK 

k

)

Removes the entr y whose key equals 

k.

bool Tr yGetValue(TK 

k

, out TV 

v

)

Attempts to retrieve the value associated with 

k

, putting it 

into

v

. Returns true if successful and false other wise. If 

k

is not found, 

v

 is given its default value.

T

ABLE

 24-12 

The Methods Defi ned by 

IDictionary

www.freepdf-books.com

---

778

 

P a r t   I I :  

E x p l o r i n g   t h e   C #   L i b r a r y

IEnumerator

 has the same two methods as does the non-generic 

IEnumerator

:

MoveNext( )

 and 

Reset( )

. It also declares a generic version of the 

Current

 property, as 

shown here:

T Current { get; }

It returns a 

T

 reference to the next object. Thus, the generic version of 

Current

 is type-safe.

There is one other difference between 

IEnumerator

 and 

IEnumerator

:

IEnumerator

inherits the 

IDisposable

 interface, but 

IEnumerator

 does not. 

IDisposable

 defines the 

Dispose( )

method, which is used to free unmanaged resources.

N

OTE

N

OTE

IEnumerable

 also implements the non-generic 

IEnumerable

 interface. Thus, it 

supports the non-generic version of 

GetEnumerator( )

.

IEnumerator

 also implements the 

non-generic

IEnumerator

 interface, thus supporting the non-generic versions of 

Current

.

IComparer

The

IComparer

 interface is the generic version of 

IComparer

 described earlier. The 

main difference between the two is that 

IComparer

 is type-safe, declaring the generic 

version of 

Compare( )

 shown here:

int Compare(T 

obj1

, T 

obj2

)

This method compares 

obj1

 with 

obj2

 and returns greater than zero if 

obj1

 is greater than 

obj2,

zero if the two objects are the same, and less than zero if 

obj1

 is less that 

obj2.

IEqualityComparer

The

IEqualityComparer

 interface is the equivalent of its non-generic relative 

IEqualityComparer

. It defines these two methods:

bool Equals(T 

obj1

, T 

obj2

)

int GetHashCode(T 

obj

)

Equals( )

 must return true if 

obj1

 and 

obj2

 are equal. 

GetHashCode( )

 must return the hash 

code for 

obj.

The KeyValuePair Structure

System.Collections.Generic

 defines a structure called 

KeyValuePair

, which is 

used to store a key and its value. It is used by the generic collection classes that store key/

value pairs, such as 

Dictionary

. This structure defines the following two 

properties:

public TK Key { get; };

public TV Value { get; };

These properties hold the key or value associated with an entry. You can construct a 

KeyValuePair

 object by using the following constructor:

public KeyValuePair(TK 

k

, TV 

v

)

Here, 

k

 is the key and 

v

 is the value.

www.freepdf-books.com

---

PART II

C h a p t e r   2 4 :  

C o l l e c t i o n s ,   E n u m e r a t o r s ,   a n d   I t e r a t o r s    

779

The Generic Collection Classes

As mentioned at the start of this section, the generic collection classes largely parallel their 

non-generic relatives, although in some cases the names have been changed. Also, some 

differences in organization and functionality exist. The generic collections are defined in 

System.Collections.Generic

. The ones described in this chapter are shown in Table 24-13. 

These classes form the core of the generic collections.

N

OTE

N

OTE

System.Collections.Generic

also includes the following classes: 

SynchronizedCollection

is a synchronized collection based on 

IList

.

SynchronizedReadOnlyCollection

 is a 

read-only synchronized collection based on 

IList

.

SynchronizedKeyCollection

 is 

an abstract class used as a base class by 

System.ServiceModel.UriSchemeKeyedCollection

.

KeyedByTypeCollection

 is a collection that uses types as keys.

The List Collection

The

List

 class implements a generic dynamic array and is conceptually similar to the 

non-generic

ArrayList

 class. 

List

 implements the 

ICollection

,

ICollection

,

IList

,

IList

,

 IEnumerable

, and 

IEnumerable

 interfaces. 

List

 has the constructors 

shown here:

public List( )

public List(IEnumerable 

c

)

public List(int 

capacity

)

The first constructor builds an empty 

List

 with a default initial capacity. The second 

constructor builds a 

List

 that is initialized with the elements of the collection specified by 

c

and with an initial capacity at least equal to the number of elements

.

 The third constructor 

builds an array list that has the specified initial 

capacity.

 The capacity is the size of the 

underlying array that is used to store the elements. The capacity grows automatically as 

elements are added to a 

List

. Each time the list must be enlarged, its capacity is increased.

Class

Description

Dictionar y

Stores key/value pairs. Provides functionality similar to that 

found in the non-generic 

Hashtable

 class. 

HashSet

Stores a set of unique values using a hash table. 

LinkedList

Stores elements in a doubly linked list.

List

A dynamic array. Provides functionality similar to that found in 

the non-generic 

ArrayList

 class. 

Queue

A first-in, first-out list. Provides functionality similar to that 

found in the non-generic 

Queue

 class.

Sor tedDictionar y

A sor ted list of key/value pairs. 

Sor tedList

A sor ted list of key/value pairs. Provides functionality similar 

to that found in the non-generic 

SortedList

 class.

Stack

A first-in, last-out list. Provides functionality similar to that 

found in the non-generic 

Stack

 class.

T

ABLE

 24-13 

The Core Generic Collection Classes

www.freepdf-books.com

---

780

 

P a r t   I I :  

E x p l o r i n g   t h e   C #   L i b r a r y

In addition to the methods defined by the interfaces that it implements, 

List

 defines 

several methods of its own. A sampling is shown in Table 24-14.

Method

Description

public void AddRange(IEnumerable 

c

)

Adds the elements in 

c

 to the end of the invoking list.

public vir tual int Binar ySearch(T 

v

)

Searches the invoking collection for the value passed 

in

v.

 The index of the matching element is returned. If 

the value is not found, a negative value is returned. The 

invoking list must be sor ted.

public int

     Binar ySearch(T 

v

, IComparer        

comp

)

Searches the invoking collection for the value passed in 

v

 using the comparison object specified by 

comp.

 The 

index of the matching element is returned. If the value 

is not found, a negative value is returned. The invoking 

list must be sor ted.

public int

     Binar ySearch(int 

star tIdx

, int 

count

,

         T 

v

, IComparer 

comp

)

Searches the invoking collection for the value passed in 

v

 using the comparison object specified by 

comp.

 The 

search begins at 

star tIdx

 and runs for 

count

 elements. 

The index of the matching element is returned. If the 

value is not found, a negative value is returned. The 

invoking list must be sor ted. 

public List

    GetRange(int 

idx

, int 

count

)

Returns a por tion of the invoking list. The range 

returned begins at 

idx

 and runs for 

count

 elements. 

The returned object refers to the same elements as the 

invoking object.

public int IndexOf(T 

v

)

Returns the index of the first occurrence of 

v

 in the 

invoking collection. Returns –1 if 

v

 is not found.

public void

    Inser tRange(int 

star tIdx

,

                      IEnumerable 

c

)

Inser ts the elements of 

c

 into the invoking collection, 

star ting at the index specified by 

star tIdx.

public int LastIndexOf(T 

v

)

Returns the index of the last occurrence of 

v

 in the 

invoking collection. Returns –1 if 

v

 is not found.

public void

    RemoveRange(int 

idx

, int 

count

)

Removes

count

 elements from the invoking collection, 

beginning at 

idx.

public void Reverse( )

Reverses the contents of the invoking collection.

public void

    Reverse(int 

star tIdx

, int 

count

)

Reverses

count

 elements of the invoking collection, 

beginning at 

star tIdx.

public void Sor t( )

Sor ts the collection into ascending order.

public void Sor t(IComparer 

comp

)

Sor ts the collection using the specified comparison 

object. If 

comp

 is null, the default comparer for each 

object is used.

public void Sor t(Comparison 

comp

)

Sor ts the collection using the specified comparison 

delegate.

T

ABLE

 24-14 

A Sampling of Methods Defi ned by 

List

www.freepdf-books.com

---