You declare a C# array with the following syntax:

type[] array-name;

For example:

int[] myIntArray;

The square brackets ([]) tell the C# compiler that you are declaring an array, and the type specifies the type of the elements it will contain. In the previous example, myIntArray is an array of integers.

You instantiate an array by using the new keyword. For example:

myIntArray = new int[5];

This declaration creates and initializes an array of five integers, all of which are initialized to the value 0.

string myArray[10];

It is important to distinguish between the array (which is a collection of elements) and the elements of the array. myIntArray is the array (or, more accurately, the variable that holds the reference to the array); its elements are the five integers it holds.

C# arrays are reference types, created on the heap. Thus, the array to which myIntArray refers is allocated on the heap. The elements of an array are allocated based on their own type. Because integers are value types, the elements in myIntArray will be value types, not boxed integers, and thus all the elements will be created inside the block of memory allocated for the array.

The block of memory allocated to an array of reference types will contain references to the actual elements, which are themselves created on the heap in memory separate from that allocated for the array.

When you create an array of value types, each element initially contains the default value for the type stored in the array (refer back to Table 4-2 in Chapter 4). The statement:

myIntArray = new int[5];

creates an array of five integers, each whose value is set to 0, which is the default value for integer types.

Unlike with arrays of value types, the reference types in an array aren’t initialized to their default value. Instead, the references held in the array are initialized to null. If you attempt to access an element in an array of reference types before you have specifically initialized the elements, you will generate an exception.

Assume that you have created a Button class. You would declare an array of Button objects with the following statement:

Button[] myButtonArray;

and instantiate the actual array like this:

myButtonArray = new Button[3];

You can shorten this to:

Button[] myButtonArray = new Button[3];

This statement doesn’t create an array with references to three Button objects. Instead, this creates the array myButtonArray with three null references. To use this array, you must first construct and assign the Button objects for each reference in the array. You can construct the objects in a loop that adds them one by one to the array.

You access the elements of an array using the index operator ([]). Arrays are zero-based, which means that the index of the first element is always 0—in this case, myArray[0].

As explained previously, arrays are objects and thus have properties. One of the more useful of these is Length, which tells you how many objects are in an array. Array objects can be indexed from 0 to Length−1. That is, if there are five elements in an array, their indexes are 0, 1, 2, 3, 4.

Example 9-1 illustrates the array concepts covered so far. In this example, a class named Tester creates an array of Employees and an array of integers, populates the Employee array, and then prints the values of both.

namespace Programming_CSharp
{
    // a simple class to store in the array
    public class Employee
    {
        public Employee(int empID)
        {
            this.empID = empID;
        }
        public override string ToString(  )
        {
            return empID.ToString(  );
        }
        private int empID;
    }
    public class Tester
    {
        static void Main(  )
        {
            int[] intArray;
            Employee[] empArray;
            intArray = new int[5];
            empArray = new Employee[3];

            // populate the array
            for (int i = 0; i < empArray.Length; i++)
            {
                empArray[i] = new Employee(i + 5);
            }

            for (int i = 0; i < intArray.Length; i++)
            {
                Console.WriteLine(intArray[i].ToString(  ));
            }

            for (int i = 0; i < empArray.Length; i++)
            {
                Console.WriteLine(empArray[i].ToString(  ));
            }
        }
    }
}


Output:
0
0
0
0
0
5
6
7

The example starts with the definition of an Employee class that implements a constructor that takes a single integer parameter. The ToString( ) method inherited from Object is overridden to print the value of the Employee object’s employee ID.

The test method declares and then instantiates a pair of arrays. The integer array is automatically filled with integers whose values are set to 0. The Employee array contents must be constructed by hand.

Finally, the contents of the arrays are printed to ensure that they are filled as intended. The five integers print their value first, followed by the three Employee objects.

It is possible to initialize the contents of an array at the time it is instantiated by providing a list of values delimited by curly brackets ({}). C# provides a longer and a shorter syntax:

int[] myIntArray = new int[5] { 2, 4, 6, 8, 10 }
int[] myIntArray = { 2, 4, 6, 8, 10 }

There is no practical difference between these two statements, and most programmers will use the shorter syntax, but see the note on syntaxes.

You can create a method that displays any number of integers to the console by passing in an array of integers and then iterating over the array with a foreach loop.^[11] The params keyword allows you to pass in a variable number of parameters without necessarily explicitly creating the array.

In the next example, you create a method, DisplayVals( ), that takes a variable number of integer arguments:

public void DisplayVals(params int[] intVals)

The method itself can treat the array as though an integer array were explicitly created and passed in as a parameter. You are free to iterate over the array as you would over any other array of integers:

foreach (int i in intVals)
{
  Console.WriteLine("DisplayVals {0}",i);
}

The calling method, however, need not explicitly create an array: it can simply pass in integers, and the compiler will assemble the parameters into an array for the DisplayVals( ) method:

t.DisplayVals(5,6,7,8);

You are free to pass in an array if you prefer:

int [] explicitArray = new int[5] {1,2,3,4,5};
t.DisplayVals(explicitArray);

Example 9-3 provides the complete source code illustrating the params keyword.

using System;
using System.Collections.Generic;
using System.Text;

namespace UsingParams
{
    public class Tester
    {
        static void Main(  )
        {
            Tester t = new Tester(  );
            t.DisplayVals(5, 6, 7, 8);
            int[] explicitArray = new int[5] { 1, 2, 3, 4, 5 };
            t.DisplayVals(explicitArray);
        }

        public void DisplayVals(params int[] intVals)
        {
            foreach (int i in intVals)
            {
                Console.WriteLine("DisplayVals {0}", i);
            }
        }
    }
}
Output:
DisplayVals 5
DisplayVals 6
DisplayVals 7
DisplayVals 8
DisplayVals 1
DisplayVals 2
DisplayVals 3
DisplayVals 4
DisplayVals 5

You can think of an array as a long row of slots into which you can place values. Once you have a picture of a row of slots, imagine 10 rows, one on top of another. This is the classic two-dimensional array of rows and columns. The rows run across the array and the columns run up and down the array.

A third dimension is possible, but somewhat harder to imagine. Make your arrays three-dimensional, with new rows stacked atop the old two-dimensional array. OK, now imagine four dimensions. Now imagine 10.

Those of you who aren’t string-theory physicists have probably given up, as have we. Multidimensional arrays are useful, however, even if you can’t quite picture what they would look like.

C# supports two types of multidimensional arrays: rectangular and jagged. In a rectangular array, every row is the same length. A jagged array, however, is an array of arrays, each of which can be a different length.

type [,] array-name

int [,] myRectangularArray = new int[2,3];

using System;
using System.Collections.Generic;
using System.Text;

namespace RectangularArray
{
    public class Tester
    {
        static void Main(  )
        {
            const int rows = 4;
            const int columns = 3;

            // declare a 4x3 integer array
            int[,] rectangularArray = new int[rows, columns];

            // populate the array
            for (int i = 0; i < rows; i++)
            {
                for (int j = 0; j < columns; j++)
                {
                    rectangularArray[i, j] = i + j;
                }
            }

            // report the contents of the array
            for (int i = 0; i < rows; i++)
            {
                for (int j = 0; j < columns; j++)
                {
                    Console.WriteLine("rectangularArray[{0},{1}] = {2}",
                        i, j, rectangularArray[i, j]);
                }
            }
        }
    }
}


Output:
rectangularArray[0,0] = 0
rectangularArray[0,1] = 1
rectangularArray[0,2] = 2
rectangularArray[1,0] = 1
rectangularArray[1,1] = 2
rectangularArray[1,2] = 3
rectangularArray[2,0] = 2
rectangularArray[2,1] = 3
rectangularArray[2,2] = 4
rectangularArray[3,0] = 3
rectangularArray[3,1] = 4
rectangularArray[3,2] = 5

const int rows = 4;
const int columns = 3;

int[,] rectangularArray = new int[rows, columns];

using System;
using System.Collections.Generic;
using System.Text;

namespace InitializingMultiDimensionalArray
{
    public class Tester
    {
        static void Main(  )
        {
            const int rows = 4;
            const int columns = 3;

            // imply a 4x3 array
            int[,] rectangularArray =
                 {
                    {0,1,2}, {3,4,5}, {6,7,8}, {9,10,11}
                 };

            for (int i = 0; i < rows; i++)
            {
                for (int j = 0; j < columns; j++)
                {
                    Console.WriteLine("rectangularArray[{0},{1}] = {2}",
                        i, j, rectangularArray[i, j]);
                }
            }
        }
    }
}


Output:
rectangularArrayrectangularArray[0,0] = 0
rectangularArrayrectangularArray[0,1] = 1
rectangularArrayrectangularArray[0,2] = 2
rectangularArrayrectangularArray[1,0] = 3
rectangularArrayrectangularArray[1,1] = 4
rectangularArrayrectangularArray[1,2] = 5
rectangularArrayrectangularArray[2,0] = 6
rectangularArrayrectangularArray[2,1] = 7
rectangularArrayrectangularArray[2,2] = 8
rectangularArrayrectangularArray[3,0] = 9
rectangularArrayrectangularArray[3,1] = 10
rectangularArrayrectangularArray[3,2] = 11

int[,] rectangularArrayrectangularArray =
{
 {0,1,2}, {3,4,5}, {6,7,8}, {9,10,11}
};

int[,] rectangularArrayrectangularArray =
{
 {0,1,2,3}, {4,5,6,7}, {8,9,10,11}
};

Exception occurred: System.IndexOutOfRangeException:
Index was outside the bounds of the array.
at Programming_CSharp.Tester.Main(  ) in
csharp/programming csharp/listing0703.cs:line 23

type [] []...

int [] [] myJaggedArray;

using System;
using System.Collections.Generic;
using System.Text;

namespace JaggedArray
{
    public class Tester
    {
        static void Main(  )
        {
            const int rows = 4;

            // declare the jagged array as 4 rows high
            int[][] jaggedArray = new int[rows][];

            // the first row has 5 elements
            jaggedArray[0] = new int[5];

            // a row with 2 elements
            jaggedArray[1] = new int[2];

            // a row with 3 elements
            jaggedArray[2] = new int[3];

            // the last row has 5 elements
            jaggedArray[3] = new int[5];

            // Fill some (but not all) elements of the rows
            jaggedArray[0][3] = 15;
            jaggedArray[1][1] = 12;
            jaggedArray[2][1] = 9;
            jaggedArray[2][2] = 99;
            jaggedArray[3][0] = 10;
            jaggedArray[3][1] = 11;
            jaggedArray[3][2] = 12;
            jaggedArray[3][3] = 13;
            jaggedArray[3][4] = 14;

            for (int i = 0; i < 5; i++)
            {
                Console.WriteLine("jaggedArray[0][{0}] = {1}",
                    i, jaggedArray[0][i]);
            }

            for (int i = 0; i < 2; i++)
            {
                Console.WriteLine("jaggedArray[1][{0}] = {1}",
                    i, jaggedArray[1][i]);
            }

            for (int i = 0; i < 3; i++)
            {
                Console.WriteLine("jaggedArray[2][{0}] = {1}",
                    i, jaggedArray[2][i]);
            }
            for (int i = 0; i < 5; i++)
            {
                Console.WriteLine("jaggedArray[3][{0}] = {1}",
                    i, jaggedArray[3][i]);
            }
        }
    }
}


Output:
jaggedArray[0][0] = 0
jaggedArray[0][1] = 0
jaggedArray[0][2] = 0
jaggedArray[0][3] = 15
jaggedArray[0][4] = 0
jaggedArray[1][0] = 0
jaggedArray[1][1] = 12
jaggedArray[2][0] = 0
jaggedArray[2][1] = 9
jaggedArray[2][2] = 99
jaggedArray[3][0] = 10
jaggedArray[3][1] = 11
jaggedArray[3][2] = 12
jaggedArray[3][3] = 13
jaggedArray[3][4] = 14

int[][] jaggedArray = new int[rows][];

// the first row has 5 elements
jaggedArray[0] = new int[5];

// a row with 2 elements
jaggedArray[1] = new int[2];

// a row with 3 elements
jaggedArray[2] = new int[3];

// the last row has 5 elements
jaggedArray[3] = new int[5];

rectangularArrayrectangularArray[i,j]

jaggedArray[3][i]

The Array class can also be created by using the overloaded CreateInstance method. One of the overloads allows you to specify the lower bounds (starting index) of each dimension in a multidimensional array. This is a fairly obscure capability, not often used.

Briefly, here is how you do it: you call the static method CreateInstance, which returns an Array and which takes three parameters: an object of type Type (indicating the type of object to hold in the array), an array of integers indicating the length of each dimension in the array, and a second array of integers indicating the lower bound for each dimension. Note that the two arrays of integers must have the same number of elements; that is, you must specify a lower bound for each dimension:

using System;
using System.Collections.Generic;
using System.Text;

namespace SettingArrayBounds
{
    public class SettingArrayBounds
    {
        public static void CreateArrayWithBounds(  )
        {
            // Creates and initializes a multidimensional
            // Array of type String.
            int[] lengthsArray = new int[2] { 3, 5 };
            int[] boundsArray = new int[2] { 2, 3 };
            Array multiDimensionalArray = Array.CreateInstance(
                typeof(String), lengthsArray, boundsArray);

            // Displays the lower bounds and the
            // upper bounds of each dimension.
            Console.WriteLine("Bounds:/tLower/tUpper");
            for (int i = 0; i < multiDimensionalArray.Rank; i++)
                Console.WriteLine("{0}:/t{1}/t{2}", i,
                    multiDimensionalArray.GetLowerBound(i),
                    multiDimensionalArray.GetUpperBound(i));
        }
        static void Main(  )
        {
            SettingArrayBounds.CreateArrayWithBounds(  );
        }
    }
}

You can convert one array into another, if the dimensions of the two arrays are equal, and if a conversion is possible between the reference element types. An implicit conversion can occur if the elements can be implicitly converted; otherwise, an explicit conversion is required.

You can also convert an array of derived objects to an array of base objects. Example 9-7 illustrates the conversion of an array of user-defined Employee types to an array of objects.

using System;
using System.Collections.Generic;
using System.Text;

namespace ConvertingArrays
{
    // create an object we can
    // store in the array
    public class Employee
    {
        // a simple class to store in the array
        public Employee(int empID)
        {
            this.empID = empID;
        }
        public override string ToString(  )
        {
            return empID.ToString(  );
        }
        private int empID;
    }

    public class Tester
    {
        // This method takes an array of objects.
        // We'll pass in an array of Employees
        // and then an array of strings.
        // The conversion is implicit since both Employee
        // and string derive (ultimately) from object.
        public static void PrintArray(object[] theArray)
        {
            Console.WriteLine("Contents of the Array {0}",
            theArray.ToString(  ));

            // walk through the array and print
            // the values.
            foreach (object obj in theArray)
            {
                Console.WriteLine("Value: {0}", obj);
            }
        }

        static void Main(  )
        {
            // make an array of Employee objects
            Employee[] myEmployeeArray = new Employee[3];

            // initialize each Employee's value
            for (int i = 0; i < 3; i++)
            {
                myEmployeeArray[i] = new Employee(i + 5);
            }

            // display the values
            PrintArray(myEmployeeArray);

            // create an array of two strings
            string[] array = {"hello", "world"};

            // print the value of the strings
            PrintArray(array);
        }
    }
}


Output:
Contents of the Array Programming_CSharp.Employee[]
Value: 5
Value: 6
Value: 7
Contents of the Array System.String[]
Value: hello
Value: world

Example 9-7 begins by creating a simple Employee class, as seen earlier in the chapter. The Tester class now contains a new static method, PrintArray( ), that takes as a parameter a one-dimensional array of Objects:

public static void PrintArray(object[] theArray)

Object is the implicit base class of every object in the .NET Framework, and so is the base class of both String and Employee.

The PrintArray( ) method takes two actions. First, it calls the ToString( ) method on the array itself:

Console.WriteLine("Contents of the Array {0}",
 theArray.ToString(  ));

System.Array overrides the ToString( ) method to your advantage, printing an identifying name of the array:

Contents of the Array Programming_CSharp. Employee []
Contents of the Array System.String[]

PrintArray( ) then goes on to call ToString( ) on each element in the array it receives as a parameter. Because ToString( ) is a virtual method in the base class Object, it is guaranteed to be available in every derived class. You have overridden this method appropriately in Employee so that the code works properly. Calling ToString( ) on a String object might not be necessary, but it is harmless, and it allows you to treat these objects polymorphically.

Two useful static methods of Array are Sort( ) and Reverse( ). These are fully supported for arrays of the built-in C# types such as string. Making them work with your own classes is a bit trickier, as you must implement the IComparable interface (see the section "Implementing IComparable,” later in this chapter). Example 9-8 demonstrates the use of these two methods to manipulate String objects.

using System;
using System.Collections.Generic;
using System.Text;

namespace ArraySortAndReverse
{
    public class Tester
    {
        public static void PrintMyArray(object[] theArray)
        {
            foreach (object obj in theArray)
            {
                Console.WriteLine("Value: {0}", obj);
            }
            Console.WriteLine("
");
        }

        static void Main(  )
        {
            String[] myArray = {"Who", "is", "Douglas", "Adams"};

            PrintMyArray(myArray);
            Array.Reverse(myArray);
            PrintMyArray(myArray);

            String[] myOtherArray =
                     {
                         "We", "Hold", "These", "Truths",
                         "To", "Be", "Self","Evident",
                     };

            PrintMyArray(myOtherArray);
            Array.Sort(myOtherArray);
            PrintMyArray(myOtherArray);
        }
    }
}

Output:
Value: Who
Value: is
Value: Douglas
Value: Adams

Value: Adams
Value: Douglas
Value: is
Value: Who

Value: We
Value: Hold
Value: These
Value: Truths
Value: To
Value: Be
Value: Self
Value: Evident

Value: Be
Value: Evident
Value: Hold
Value: Self
Value: These
Value: To
Value: Truths
Value: We

The example begins by creating myArray, an array of strings with the words:

"Who", "is", "Douglas", "Adams"

This array is printed, and then is passed to the Array.Reverse( ) method, where it is printed again to see that the array itself has been reversed:

Value: Adams
Value: Douglas
Value: is
Value: Who

Similarly, the example creates a second array, myOtherArray, containing the words:

"We", "Hold", "These", "Truths",
"To", "Be", "Self", "Evident",

This is passed to the Array.Sort( ) method. Then Array.Sort( ) happily sorts them alphabetically:

Value: Be
Value: Evident
Value: Hold
Value: Self
Value: These
Value: To
Value: Truths
Value: We

In Example 9-9, you can’t assign to an index that doesn’t have a value. So, if you write:

lbt[10] = "wow!";

you will trigger the error handler in the set( ) method, which will note that the index you’ve passed in (10) is larger than the counter (6).

Of course, you can use the set( ) method for assignment; you simply have to handle the indexes you receive. To do so, you might change the set( ) method to check the Length of the buffer rather than the current value of counter. If a value was entered for an index that did not yet have a value, you would update ctr:

set
{
  // add only through the add method
  if (index >= strings.Length )
  {
    // handle error
  }
  else
  {
    strings[index] = value;
    if (ctr < index+1)
      ctr = index+1;
  }
}

This allows you to create a “sparse” array in which you can assign to offset 10 without ever having assigned to offset 9. Thus, if you now write:

lbt[10] = "wow!";

the output will be:

lbt[0]: Hello
lbt[1]: Universe
lbt[2]: Who
lbt[3]: Is
lbt[4]: Douglas
lbt[5]: Adams
lbt[6]:
lbt[7]:
lbt[8]:
lbt[9]:
lbt[10]: wow!

In Main( ), you create an instance of the ListBoxTest class named lbt and pass in two strings as parameters:

ListBoxTest lbt = new ListBoxTest("Hello", "World");

Then, call Add( ) to add four more strings:

// add a few strings
lbt.Add("Who");
lbt.Add("Is");
lbt.Add("Douglas");
lbt.Add("Adams");

Before examining the values, modify the second value (at index 1):

string subst = "Universe";
lbt[1] = subst;

Finally, display each value in a loop:

for (int i = 0;i<lbt.GetNumEntries(  );i++)
{
 Console.WriteLine("lbt[{0}]: {1}",i,lbt[i]);
}

C# doesn’t require that you always use an integer value as the index to a collection. When you create a custom collection class and create your indexer, you are free to create indexers that index on strings and other types. In fact, the index value can be overloaded so that a given collection can be indexed, for example, by an integer value or by a string value, depending on the needs of the client.

In the case of your listbox, you might want to be able to index into the listbox based on a string. Example 9-10 illustrates a string index. The indexer calls findString( ), which is a helper method that returns a record based on the value of the string provided. Notice that the overloaded indexer and the indexer from Example 9-9 are able to coexist.

using System;
using System.Collections.Generic;
using System.Text;

namespace OverloadedIndexer
{
    // a simplified ListBox control
    public class ListBoxTest
    {
        private string[] strings;
        private int ctr = 0;

        // initialize the listbox with strings
        public ListBoxTest(params string[] initialStrings)
        {
            // allocate space for the strings
            strings = new String[256];

            // copy the strings passed in to the constructor
            foreach (string s in initialStrings)
            {
                strings[ctr++] = s;
            }
        }

        // add a single string to the end of the listbox
        public void Add(string theString)
        {
            strings[ctr] = theString;
            ctr++;
        }

        // allow array-like access
        public string this[int index]
        {
            get
            {
                if (index < 0 || index >= strings.Length)
                {
                    // handle bad index
                }
                return strings[index];
            }
            set
            {
                strings[index] = value;
            }
        }

        private int findString(string searchString)
        {
            for (int i = 0; i < strings.Length; i++)
            {
                if (strings[i].StartsWith(searchString))
                {
                    return i;
                }
            }
            return −1;
        }

        // index on string
        public string this[string index]
        {
            get
            {
                if (index.Length == 0)
                {
                    // handle bad index
                }

                return this[findString(index)];
            }
            set
            {
                strings[findString(index)] = value;
            }
        }

        // publish how many strings you hold
        public int GetNumEntries(  )
        {
            return ctr;
        }
    }

    public class Tester
    {
        static void Main(  )
        {
            // create a new listbox and initialize
            ListBoxTest lbt =
            new ListBoxTest("Hello", "World");

            // add a few strings
            lbt.Add("Who");
            lbt.Add("Is");
            lbt.Add("Douglas");
            lbt.Add("Adams");

            // test the access
            string subst = "Universe";
            lbt[1] = subst;
            lbt["Hel"] = "GoodBye";
            // lbt["xyz"] = "oops";

            // access all the strings
            for (int i = 0; i < lbt.GetNumEntries(  ); i++)
            {
                Console.WriteLine("lbt[{0}]: {1}", i, lbt[i]);
            } // end for
        } // end main
    } // end tester
}


Output:
lbt[0]: GoodBye
lbt[1]: Universe
lbt[2]: Who
lbt[3]: Is
lbt[4]: Douglas
lbt[5]: Adams

Example 9-10 is identical to Example 9-9 except for the addition of an overloaded indexer, which can match a string, and the method findString, created to support that index.

The findString method simply iterates through the strings held in myStrings until it finds a string that starts with the target string you use in the index. If found, it returns the index of that string; otherwise, it returns the value −1.

We see in Main( ) that the user passes in a string segment to the index, just as with an integer:

lbt["Hel"] = "GoodBye";

This calls the overloaded index, which does some rudimentary error-checking (in this case, making sure the string passed in has at least one letter), and then passes the value (Hel) to findString. It gets back an index and uses that index to index into myStrings:

return this[findString(index)];

The set value works in the same way:

myStrings[findString(index)] = value;

lbt["xyz"] = "oops";

You can support the foreach statement in ListBoxTest by implementing the IEnumerable<T> interface (see Example 9-11). IEnumerable<T> has only one method, GetEnumerator( ), whose job is to return an implementation of IEnumerator<T>. The C# language provides special help in creating the enumerator, using the new keyword yield.

using System;
using System.Collections;
using System.Collections.Generic;
using System.Text;

namespace Enumerable
{
    public class ListBoxTest : IEnumerable<string>
    {
        private string[] strings;
        private int ctr = 0;
        // Enumerable classes can return an enumerator
        public IEnumerator<string> GetEnumerator(  )
        {
            foreach (string s in strings)
            {
                yield return s;
            }
        }

        // Explicit interface implementation.
        IEnumerator IEnumerable.GetEnumerator(  )
        {
            return GetEnumerator(  );
        }

        // initialize the listbox with strings
        public ListBoxTest(params string[] initialStrings)
        {
            // allocate space for the strings
            strings = new String[8];

            // copy the strings passed in to the constructor
            foreach (string s in initialStrings)
            {
                strings[ctr++] = s;
            }
        }

        // add a single string to the end of the listbox
        public void Add(string theString)
        {
            strings[ctr] = theString;
            ctr++;
        }

        // allow array-like access
        public string this[int index]
        {
            get
            {
                if (index < 0 || index >= strings.Length)
                {
                    // handle bad index
                }
                return strings[index];
            }
            set
            {
                strings[index] = value;
            }
        }

        // publish how many strings you hold
        public int GetNumEntries(  )
        {
            return ctr;
        }
    }

    public class Tester
    {
        static void Main(  )
        {
            // create a new listbox and initialize
            ListBoxTest lbt =
            new ListBoxTest("Hello", "World");

            // add a few strings
            lbt.Add("Who");
            lbt.Add("Is");
            lbt.Add("Douglas");
            lbt.Add("Adams");

            // test the access
            string subst = "Universe";
            lbt[1] = subst;

            // access all the strings
            foreach (string s in lbt)
            {
                Console.WriteLine("Value: {0}", s);
            }
        }
    }
}


Output:
Value: Hello
Value: Universe
Value: Who
Value: Is
Value: Douglas
Value: Adams
Value:
Value:

The program begins in Main( ), creating a new ListBoxTest object and passing two strings to the constructor. When the object is created, an array of Strings is created with enough room for eight strings. Four more strings are added using the Add method, and the second string is updated, just as in the previous example.

The big change in this version of the program is that a foreach loop is called, retrieving each string in the listbox. The foreach loop automatically uses the IEnumerable<T> interface, invoking GetEnumerator( ).

The GetEnumerator method is declared to return an IEnumerator of string:

publicIEnumerator<string> GetEnumerator(  )

The implementation iterates through the array of strings, yielding each in turn:

foreach ( string s in strings )
{
  yield return s;
}

All the bookkeeping for keeping track of which element is next, resetting the iterator, and so forth is provided for you by the Framework.

Like all collections, the List implements the Sort( ) method, which allows you to sort any objects that implement IComparable. In the next example, you’ll modify the Employee object to implement IComparable:

public class Employee : IComparable<Employee>

To implement the IComparable<Employee> interface, the Employee object must provide a CompareTo( ) method:

public int CompareTo(Employee rhs)
{
    return this.empID.CompareTo(rhs.empID);
}

The CompareTo( ) method takes an Employee as a parameter. You know this is an Employee because this is a type-safe collection. The current Employee object must compare itself to the Employee passed in as a parameter and return −1 if it is smaller than the parameter, 1 if it is greater than the parameter, and 0 if it is equal to the parameter. It is up to Employee to determine what smaller than, greater than, and equal to mean. In this example, you delegate the comparison to the empId member. The empId member is an int and uses the default CompareTo( ) method for integer types, which will do an integer comparison of the two values.

You are now ready to sort the array list of employees, empList. To see whether the sort is working, you’ll need to add integers and Employee instances to their respective arrays with random values. To create the random values, you’ll instantiate an object of class Random; to generate the random values, you’ll call the Next( ) method on the Random object, which returns a pseudorandom number. The Next( ) method is overloaded; one version allows you to pass in an integer that represents the largest random number you want. In this case, you’ll pass in the value 10 to generate a random number between 0 and 10:

Random r = new Random(  );
r.Next(10);

Example 9-14 creates an integer array and an Employee array, populates them both with random numbers, and prints their values. It then sorts both arrays and prints the new values.

using System;
using System.Collections.Generic;
using System.Text;

namespace IComparable
{
    // a simple class to store in the array
    public class Employee : IComparable<Employee>
    {
        private int empID;

        public Employee(int empID)
        {
            this.empID = empID;
        }

        public override string ToString(  )
        {
            return empID.ToString(  );
        }

        public bool Equals(Employee other)
        {
            if (this.empID == other.empID)
            {
                return true;
            }
            else
            {
                return false;
            }
        }

        // Comparer delegates back to Employee
        // Employee uses the integer's default
        // CompareTo method

        public int CompareTo(Employee rhs)
        {
            return this.empID.CompareTo(rhs.empID);
        }
    }
    public class Tester
    {
        static void Main(  )
        {
            List<Employee> empArray = new List<Employee>(  );
            List<Int32> intArray = new List<Int32>(  );

            // generate random numbers for
            // both the integers and the
            // employee IDs

            Random r = new Random(  );

            // populate the array
            for (int i = 0; i < 5; i++)
            {
                // add a random employee id
                empArray.Add(new Employee(r.Next(10) + 100));

                // add a random integer
                intArray.Add(r.Next(10));
            }

            // display all the contents of the int array
            for (int i = 0; i < intArray.Count; i++)
            {
                Console.Write("{0} ", intArray[i].ToString(  ));
            }
            Console.WriteLine("
");

            // display all the contents of the Employee array
            for (int i = 0; i < empArray.Count; i++)
            {
                Console.Write("{0} ", empArray[i].ToString(  ));
            }
            Console.WriteLine("
");

            // sort and display the int array
            intArray.Sort(  );
            for (int i = 0; i < intArray.Count; i++)
            {
                Console.Write("{0} ", intArray[i].ToString(  ));
            }
            Console.WriteLine("
");

            // sort and display the employee array
            empArray.Sort(  );

            // display all the contents of the Employee array
            for (int i = 0; i < empArray.Count; i++)
            {
                Console.Write("{0} ", empArray[i].ToString(  ));
            }
            Console.WriteLine("
");
        }
    }
}


Output:
4 5 6 5 7
108 100 101 103 103
4 5 5 6 7
100 101 103 103 108

The output shows that the integer array and Employee array were generated with random numbers. When sorted, the display shows the values have been ordered properly.

When you call Sort( ) on the List, the default implementation of IComparer is called, which uses QuickSort to call the IComparable implementation of CompareTo( ) on each element in the List.

You are free to create your own implementation of IComparer, which you might want to do if you need control over how the sort ordering is defined. In the next example, you will add a second field to Employee, yearsOfSvc. You want to be able to sort the Employee objects in the List on either field—empID or yearsOfSvc.

To accomplish this, create a custom implementation of IComparer that you pass to the Sort( ) method of the List. This IComparer class, EmployeeComparer, knows about Employee objects and knows how to sort them.

EmployeeComparer has the WhichComparison property, of type Employee.EmployeeComparer.ComparisonType:

public Employee.EmployeeComparer.ComparisonType
  WhichComparison
{
  get{return whichComparison;}
  set{whichComparison = value;}
}

ComparisonType is an enumeration with two values, empID and yearsOfSvc (indicating that you want to sort by employee ID or years of service, respectively):

public enum ComparisonType
{
  EmpID,
  YearsOfService
};

Before invoking Sort( ), create an instance of EmployeeComparer, and set its ComparisonType property:

Employee.EmployeeComparer c = Employee.GetComparer(  );
c.WhichComparison=Employee.EmployeeComparer.ComparisonType.EmpID;
empArray.Sort(c);

When you invoke Sort( ), the List calls the Compare method on the EmployeeComparer, which in turn delegates the comparison to the Employee.CompareTo( ) method, passing in its WhichComparison property:

public int Compare(Employee lhs, Employee rhs )
{
  return lhs.CompareTo( rhs, WhichComparison );
}

The Employee object must implement a custom version of CompareTo( ), which takes the comparison, and compares the objects accordingly:

public int CompareTo(
  Employee rhs,
  Employee.EmployeeComparer.ComparisonType which)
{
  switch (which)
  {
    case Employee.EmployeeComparer.ComparisonType.EmpID:
      return this.empID.CompareTo(rhs.empID);
    case Employee.EmployeeComparer.ComparisonType.Yrs:
      return this.yearsOfSvc.CompareTo(rhs.yearsOfSvc);
  }
  return 0;
}

Example 9-15 shows the complete source for this example. The integer array has been removed to simplify the example and the output of the employee’s ToString( ) method has been enhanced to enable you to see the effects of the sort.

using System;
using System.Collections.Generic;
using System.Text;

namespace IComparer
{
    public class Employee : IComparable<Employee>
    {
        private int empID;

        private int yearsOfSvc = 1;

        public Employee(int empID)
        {
            this.empID = empID;
        }

        public Employee(int empID, int yearsOfSvc)
        {
            this.empID = empID;
            this.yearsOfSvc = yearsOfSvc;
        }

        public override string ToString(  )
        {
            return "ID: " + empID.ToString(  ) +
            ". Years of Svc: " + yearsOfSvc.ToString(  );
        }

        public bool Equals(Employee other)
        {
            if (this.empID == other.empID)
            {
                return true;
            }
            else
            {
                return false;
            }
        }

        // static method to get a Comparer object
        public static EmployeeComparer GetComparer(  )
        {
            return new Employee.EmployeeComparer(  );
        }

        // Comparer delegates back to Employee
        // Employee uses the integer's default
        // CompareTo method
        public int CompareTo(Employee rhs)
        {
            return this.empID.CompareTo(rhs.empID);
        }

        // Special implementation to be called by custom comparer
        public int CompareTo(Employee rhs,
                Employee.EmployeeComparer.ComparisonType which)
        {
            switch (which)
            {
                case Employee.EmployeeComparer.ComparisonType.EmpID:
                    return this.empID.CompareTo(rhs.empID);
                case Employee.EmployeeComparer.ComparisonType.Yrs:
                    return this.yearsOfSvc.CompareTo(rhs.yearsOfSvc);
            }
            return 0;

        }

        // nested class which implements IComparer
        public class EmployeeComparer : IComparer<Employee>
        {
            // enumeration of comparison types
            public enum ComparisonType
            {
                EmpID,
                Yrs
            };

            public bool Equals(Employee lhs, Employee rhs)
            {
                return this.Compare(lhs, rhs) == 0;
            }

            public int GetHashCode(Employee e)
            {
                return e.GetHashCode(  );
            }

            // Tell the Employee objects to compare themselves
            public int Compare(Employee lhs, Employee rhs)
            {
                return lhs.CompareTo(rhs, WhichComparison);
            }

            public Employee.EmployeeComparer.ComparisonType
                WhichComparison {get; set;}
        }
    }
    public class Tester
    {
        static void Main(  )
        {
            List<Employee> empArray = new List<Employee>(  );

            // generate random numbers for
            // both the integers and the
            // employee IDs
            Random r = new Random(  );

            // populate the array
            for (int i = 0; i < 5; i++)
            {
                // add a random employee ID

                empArray.Add(
                new Employee(
                r.Next(10) + 100, r.Next(20)
                )
                );
            }

            // display all the contents of the Employee array
            for (int i = 0; i < empArray.Count; i++)
            {
                Console.Write("
{0} ", empArray[i].ToString(  ));
            }
            Console.WriteLine("
");

            // sort and display the employee array
            Employee.EmployeeComparer c = Employee.GetComparer(  );
            c.WhichComparison =
            Employee.EmployeeComparer.ComparisonType.EmpID;
            empArray.Sort(c);

            // display all the contents of the Employee array
            for (int i = 0; i < empArray.Count; i++)
            {
                Console.Write("
{0} ", empArray[i].ToString(  ));
            }
            Console.WriteLine("
");

            c.WhichComparison = Employee.EmployeeComparer.ComparisonType.Yrs;
            empArray.Sort(c);

            for (int i = 0; i < empArray.Count; i++)
            {
                Console.Write("
{0} ", empArray[i].ToString(  ));
            }
            Console.WriteLine("
");
        }
    }
}

Output:
ID: 103. Years of Svc: 11
ID: 101. Years of Svc: 15
ID: 107. Years of Svc: 14
ID: 108. Years of Svc: 5
ID: 102. Years of Svc: 0

ID: 101. Years of Svc: 15
ID: 102. Years of Svc: 0
ID: 103. Years of Svc: 11
ID: 107. Years of Svc: 14
ID: 108. Years of Svc: 15
ID: 108. Years of Svc: 5

ID: 102. Years of Svc: 0
ID: 108. Years of Svc: 5
ID: 103. Years of Svc: 11
ID: 107. Years of Svc: 14
ID: 101. Years of Svc: 15

The first block of output shows the Employee objects as they are added to the List. The employee ID values and the years of service are in random order. The second block shows the results of sorting by the employee ID, and the third block shows the results of sorting by years of service.

Dictionaries implement the IDictionary<K,V> interface (where K is the key type, and V is the value type). IDictionary provides a public property, Item. The Item property retrieves a value with the specified key. In C#, the declaration for the Item property is:

V[Kkey]
{get; set;}

The Item property is implemented in C# with the index operator ([]). Thus, you access items in any Dictionary object using the offset syntax, as you would with an array.

Example 9-18 demonstrates adding items to a Dictionary and then retrieving them with the Item property.

using System;
using System.Collections.Generic;

namespace Dictionary
{
    public class Tester
    {
        static void Main(  )
        {
            // Create and initialize a new Dictionary.
            Dictionary<string, string> Dictionary =
                new Dictionary<string, string>(  );
            Dictionary.Add("000440312", "Jesse Liberty");
            Dictionary.Add("000123933", "Stacey Liberty");
            Dictionary.Add("000145938", "Douglas Adams");
            Dictionary.Add("000773394", "Ayn Rand");

            // access a particular item
            Console.WriteLine("myDictionary["000145938"]: {0}",
            Dictionary["000145938"]);
        }
    }
}


Output:
Dictionary["000145938"]: Douglas Adams

Example 9-18 begins by instantiating a new Dictionary. The type of the key and of the value is declared to be string.

Add four key/value pairs. In this example, the Social Security number is tied to the person’s full name. (Note that the Social Security numbers here are intentionally bogus.)

Once the items are added, you access a specific entry in the dictionary using the Social Security number as the key.