Array Length Property

The most commonly used Array property is the Length property. It's of type int and represents the total number of elements in an array across all of its dimensions. The following snippet shows the Length property in use for a one-dimensional array:

int[] x = new int[20];

// details of array content initialization omitted ...

// Step through the array.
// Stop BEFORE i equals x.Length!!!!
for (int i = 0; i < x.Length; i++) {
  Console.WriteLine(x[i]);
}

Because arrays are zero-based, we always need to stop just one short of the length when using it as an upper bound in a for loop, as the preceding example illustrates.

Note that the length of an array doesn't reflect how many elements have been explicitly assigned values because, technically speaking, even if nothing is stored explicitly in an array, its elements will be automatically filled with zero-equivalent values suitable for the array's type, as was discussed in Chapter 6. Rather, the length of an array simply represents the total capacity of the array in terms of the total number of items that it can hold; the capacity is fixed when an array is first declared, and can't be changed thereafter.

Array Methods

The Array class declares a variety of useful static and instance methods that can be used to examine or manipulate arrays; we'll discuss a few of the more commonly used methods here. A complete description of all of the Array class methods can be found in the FCL Reference on the MSDN web site.

The first three methods are static methods, meaning that they must be invoked on the Array class as a whole, passing in the array instance to be affected as an argument:

• public static void Clear(Array array, int startIndex, int length): Resets the contents of all or part of an array to zero-equivalent values. The arguments include the array to be cleared, the starting index (counting from 0), and the number of elements to clear.

          int[] x = new int[5];
  
          // Clear the entire array.
          Array.Clear(x, 0, x.Length);
  

• public static void Reverse(Array array): Reverses the order of the elements of a one-dimensional array.

          int[] x = {1, 2, 3};
          Array.Reverse(x);
          // x now contains the values: {3, 2, 1}
  

  There is also an overloaded version of this method in which the starting index and number of elements to reverse can be specified:

        public static void Reverse(Array array, int startIndex, int length)
  

• public static void Sort(Array array): Sorts the elements of a one-dimensional array. The default sorting criterion is alphabetically, for string elements; or smallest-to-largest, for numerical elements.

              string[] names = {"Vijay", "Tiger", "Phil"};
              Array.Sort(names);
              // the order of the elements is now "Phil", "Tiger", "Vijay"
  

  There is also an overloaded version of this method in which the starting index and number of elements to sort can be specified:

        public static void Sort(Array array, int startIndex, int length)
  

The next three methods are instance methods, meaning that they can be invoked on an individual array instance directly:

• public object GetValue(int index): Returns the element at the specified index of a one-dimensional array as a generic object. If we happen to know what the specific type of that object is, we can cast it:

        String[] names = {"Chris", "Sandi", "Brennan"};
        // Cast the returned object as a string.
  
        string name = (string) names.GetValue(0);
  

  or:

        int[] numbers = {11, 17, 85};
        // Cast the returned object as an int.
        string number = (int) numbers.GetValue(0);
  

  There are also overloaded versions of this method for returning an element of a 2- or 3-dimensional array:

        public object GetValue(int index1, int index2)
        public object GetValue(int index1, int index2, int index3)
  

• public void SetValue(object value, int index): Changes the element at the specified index of a one-dimensional array.

  There are also overloaded versions for changing an element of a two- or three-dimensional array:

        public void SetValue(object value, int index1, int index2)
        public void SetValue(object value, int index1, int index2, int index3)
  

  Note?/td>

  Even though GetValue and SetValue methods are provided by the Array class, the indexer notation is easier and more convenient to use. The syntax string name = names[0]; is easier to write and understand than the equivalent syntax string name = (string) names.GetValue(0);

• public int GetLength(int dimension): Returns the length of the specified dimension in an array of any number of dimensions. For example, to obtain the length of the first dimension of a two-dimensional array, we would use GetLength(0). (For a one-dimensional array, we may simply use the Length property to determine the length of the array.)

Creating an ArrayList

An ArrayList object can be instantiated by using one of three constructors provided by the ArrayList class.

• The simplest form of constructor is the parameterless constructor:

        ArrayList coursesTaken = new ArrayList();
  

  This constructor will create an empty ArrayList with an initial default capacity of 16. When the number of elements in the ArrayList reaches the current capacity of the ArrayList, its capacity is automatically doubled.

• The second form of ArrayList constructor takes an integer argument representing the initial capacity of the ArrayList; e.g.,

        ArrayList students = new ArrayList(400);
  

  We might use this form of constructor if we knew that we would be adding a large number of object references to the ArrayList. Starting with a capacity greater than the default of 16 can increase performance by reducing the number of times the ArrayList would need to resize itself as it grows.

• The third constructor takes as its argument any proper C# collection object—that is, any object belonging to one of the classes that implements the ICollection interface, which as we mentioned earlier includes all of the System.Collections classes along with the System.Array class— and copies the contents of the passed-in collection to populate the newly constructed ArrayList:

        // Create an array of Course objects ...
        Course[] courses = new Course[3];
        courses[0] = new Course("Math 101");
        courses[1] = new Course("Physics 250");
        courses[2] = new Course("Management 283");
  
        // Intervening details omitted.
        // ... and, later in the program, use it to initialize
        // an ArrayList.
        ArrayList coursesTaken = new ArrayList(courses);
  

In the previous code snippet, we initialized an ArrayList with the contents of a Course array; note that both collections are now referencing the same objects, as illustrated conceptually in Figure 13-12.

Figure 13-12: An ArrayList can be initialized with the contents of another collection.

ArrayList Properties

The ArrayList class declares a number of properties that return information about the ArrayList.

• The Capacity property is used to get or set the capacity of the ArrayList. (If we programmatically attempt to resize an ArrayList to be smaller than the number of items it holds at any given time, an ArgumentOutOfRangeException is thrown.)

• The Count property returns the current number of elements actually contained in the ArrayList.

• To access an element stored inside an ArrayList, the ArrayList class defines a special indexer property that allows us to get or set an element of an ArrayList just as we would access an element of a standard array—with an integer expression representing the desired index, surrounded by brackets. When the indexer returns an ArrayList element, it's returned as a generic object, and the element is then typically cast to its original type.

Here is an example illustrating all of these properties:

Course c1 = new Course("Math 101");
Course c2 = new Course("Physics 250");
Course c3 = new Course("Management 283");

// Using the ArrayList indexer property. (Note that it looks as
// if we are accessing an Array!)
coursesTaken[0] = c1;
coursesTaken[1] = c2;
coursesTaken[2] = c3;

// Access the Capacity and Count properties.
Console.WriteLine("capacity = " + coursesTaken.Capacity);
Console.WriteLine("no. of elements = " + coursesTaken.Count);

// Let's now pull the ArrayList elements back out, again
// using the indexer.
for (int i = 0; i < coursesTaken.Count; i++) {
  // Use the indexer to retrieve each element of the ArrayList.
  // Cast a generic object reference back into a Course reference.
  Course c = (Course) coursesTaken[i];
  // We now can invoke the methods of a Course on c.
  Console.WriteLine(c.Name);
}

The previous example highlights why it can be dangerous to mix and match types in an ArrayList. The ArrayList elements are accessed one-by-one and cast into a Course object. The Name property is then invoked on each Course object. This process works fine if all of the ArrayList elements are Course objects (or objects that derive from Course). If there happened to be an element of a disparate type— say, a double—mixed in with the Course objects, the cast wouldn't work—an InvalidCastException would be thrown because there is no way to cast a double into a Course. We'll see a more complete example of how mixing types can be a problem in the "Collections and Casting" section later in the chapter.

ArrayList Methods

Some of the more commonly used ArrayList class methods are as follows:

• public virtual int Add(object value): Adds an object reference to the end of the ArrayList by default, automatically expanding the ArrayList if need be to accommodate the reference. The provision of the virtual keyword allows derived classes to override this method as desired. The return value of the method is an int representing the index position in the ArrayList at which the argument was placed.

• public void Add(ICollection c): Appends the contents of the specified collection to the end of the ArrayList.

• public void SetRange(int startIndex, ICollection c): Replaces the current elements of an ArrayList with the contents of a different ICollection object, beginning at the specified starting index in the target ArrayList. If "c" contains more elements than the segment of the ArrayList that it is replacing, the ArrayList automatically gets extended in size as needed.

• public IEnumerator GetEnumerator(): Retrieves an instance of a special type of object called an IEnumerator that can be used to iterate through the elements of an ArrayList. We'll discuss IEnumerators later in this chapter.

• public int IndexOf(object obj): Hunts for the existence of a specific object reference and, if found, returns an integer indicating the (first) index location at which this reference was found (counting from 0). If the specified object isn't found, the value –1 is returned.

• public bool Contains(object obj): Hunts for existence of the object reference in question and, if found, returns the value true, otherwise false.

• public void RemoveAt(int index): Takes out the element at the specified index and "closes up"/"collapses" the resultant "hole." The value of the Count property decreases by one, but the Capacity remains the same. An ArgumentOutOfRangeException is thrown if the specified index exceeds the Count or is less than zero.

• public void Remove(object obj): Hunts for existence of a specific object reference in question and, if found, removes the (first) occurrence of that reference from the ArrayList, again closing up the "hole." The Count decreases by one, but the Capacity remains the same. If the specified object isn't found, the ArrayList is unchanged. To remove all instances of obj, use a combination of the Contains and Remove methods in conjunction with a while loop:

        while (arraylist.Contains(x)) {
          arraylist.Remove(x)
        }
  

• public void Sort(): Sorts the elements of the ArrayList. The default is to sort string elements alphabetically and numerical elements smallest-to-largest.

  Note?/td>

  There is an overloaded version of this method that enables us to customize the sorting algorithm for arbitrary object types, but discussing user-defined sorting algorithms is beyond the scope of this book.

• public void Clear(): Empties out the ArrayList. The Count property is set to zero. The Capacity is unchanged.

• public object[] ToArray(): Creates an instance of an object array, and copies the elements of the ArrayList into the array.

and there are more! Please consult the FCL Reference on the MSDN web site for a complete description of all of the ArrayList methods.

Creating a Hashtable

A Hashtable object can be created using any one of the various constructors declared by the Hashtable class. The simplest way to instantiate a Hashtable is with the parameterless constructor, which creates an empty Hashtable. We then insert objects as desired using the Add method, whose header is as follows:

  public void Add(object key, object value)

Note that we must specify a key value for each item as we add it to the Hashtable, to be used to retrieve the item later on; we'll use simple string objects for the keys in this example—in particular, the students' social security numbers:

// Create a Hashtable instance (the "egg carton").
Hashtable students = new Hashtable();

// Create several Student objects ("eggs").
Student s1 = new Student("123-45-6789", "John Smith");
Student s2 = new Student("987-65-4321", "Mary Jones");
Student s3 = new Student("654-32-1987", "Jim Green");

// Store their handles in the Hashtable, using the value of the Ssn property
// (which happens to be declared as type string) as the key for each.
students.Add(s1.Ssn, s1);
students.Add(s2.Ssn, s2);
students.Add(s3.Ssn, s3);

The Hashtable class defines an indexer that can be used to get or set an element of the Hashtable. As with the ArrayList, the indexer is denoted by a pair of brackets; with Hashtables, however, the brackets surround the key value of the element to be accessed:

// Note that we have to recast the object when we retrieve it,
// just as we must do with ArrayLists.
Student s = (Student) students["123-45-6789"];  // retrieves the object
                                                // reference representing
                                                // Student John Smith
Console.WriteLine("name is " + s.Name);

or, by way of another example:

// Pseudocode.
string id = retrieve student ID number from a GUI;
Student s = (Student) students[id];

Note that we have to cast an object when we retrieve it from a Hashtable if we wish to manipulate it as an instance of its original type (in this case, a Student), just as we do when retrieving an object from an ArrayList.

Hashtable Properties

In addition to Count and indexer properties, which work the same for a Hashtable as they do for an ArrayList, the Hashtable class declares a number of other properties to return information about the Hashtable.

• The Keys property returns an ICollection object whose elements are the keys contained in the Hashtable.

• The Values property returns an ICollection object whose elements are the keys contained in the Hashtable.

and there are others. For a complete list of all Hashtable properties, consult the FCL reference on the MSDN web site.

Hashtable Methods

Some of the more commonly used methods from the Hashtable class are as follows:

• public void Add(object key, object value): As already discussed, this method inserts the second object reference (value) into the table with a retrieval key represented by the first object reference (key). This method will throw an ArgumentException if there already was a previously stored object at that key location, so it's important to first verify that the key we're about to use isn't already in use in the table, using the ContainsKey method discussed next.

• public bool ContainsKey(object key): Returns true if an entry with the designated key value is found in the Hashtable, otherwise returns false.

  Here's how we'd use the ContainsKey method in concert with the Add method to make sure we weren't trying to overwrite an existing entry in the Hashtable:

        Student s = new Student("111-11-1111", "Arnold Brown");
        if (students.ContainsKey(s.Ssn)) {
          // Whoops! This is a duplicate; we need to decide what to do!
          // details omitted ...
        }
        else {
          students.Add(s.Ssn, s); // OK, because no duplicate was detected.
        }
  

• public bool ContainsValue(object value): Looks for the designated value without the aid of its associated key, and returns true if the value is found, otherwise returns false.

• public void Remove(object key): Removes the reference to the object represented by the given key from the Hashtable; note that the object itself, as it exists outside of the Hashtable, is unaffected.

• public IDictionaryEnumerator GetEnumerator(): Returns an IDictionaryEnumerator object that can be used to examine the key-object pairs currently stored in the Hashtable. We'll talk about enumerators in the next section.

• public void Clear(): Empties out the Hashtable, as if it had just been newly instantiated. The Count property is set to zero.

The IEnumerator Interface

As mentioned previously, the ArrayList class (and some of the other System.Collections classes, as well) defines a GetEnumerator method with the following header:

public virtual IEnumerator GetEnumerator()

The return type of this method, IEnumerator, is an interface defined in the System.Collections namespace. An IEnumerator object represents a temporary copy of the ArrayList for which it has been acquired, and has the following methods:

• bool MoveNext(): Advances the enumerator to the next element in the collection. The method returns true if another element is successfully reached, or false if the end of the collection has been reached.

• void Reset(): Moves the enumerator back to its original position before the first item in the collection, such that the next call to MoveNext will advance the cursor to the first element in the collection.

The IEnumerator interface also declares a read-only property (i.e., one that has a get but not a set accessor) named Current that accesses the element currently being pointed to by the cursor as a generic object reference.

Here's a simple example to illustrate how to put all of this IEnumerator functionality to use. We'll use this simple version of the Course class:

public class Course
{
  // Field.
  private string name;

  // Constructor.
  public Course(string n) {
    name = n;
  }

  // Property.
  public string Name {
    // Accessor details omitted.
  }
}

This next program will serve as the driver:

using System.Collections;

public class EnumDemo
{
  static void Main() {
    ArrayList coursesTaken = new ArrayList();

    Course c1 = new Course("Math 101");
    Course c2 = new Course("Physics 250");
    Course c3 = new Course("Management 283");

    // Insert Course object references into the ArrayList.
    coursesTaken.Add(c1);
    coursesTaken.Add(c2);
    coursesTaken.Add(c3);

    // Obtain an enumerator for the ArrayList.
    IEnumerator enum = coursesTaken.GetEnumerator();

    // Iterate through the collection using the enumerator.
    while (enum.MoveNext()) {
      // Use the Current property to retrieve the current element;
      // cast a generic object reference back into a Course reference.
      Course c = (Course) enum.Current;
      // We now can manipulate c as a Course object.
      Console.WriteLine(c.Name);
    }
  }
}

This program, when run, produces the following output:

Math 101
Physics 250
Management 283

The IDictionaryEnumerator Interface

As we now know, a Hashtable is a collection that stores data in the form of key-value pairs. A specialized type of enumerator is used with Hashtables —specifically, an IDictionaryEnumerator. As mentioned previously, the Hashtable class declares the following method to retrieve an IDictionaryEnumerator for a given Hashtable:

public virtual IDictionaryEnumerator GetEnumerator()

The IDictionaryEnumerator interface derives from IEnumerator and inherits the MoveNext and Reset methods, which were previously discussed. The IDictionaryEnumerator interface declares several additional properties; of particular interest are Key and Value, which can be used to return the key and value of the current element of the enumeration, respectively.

Here is an example of using an IDictionaryEnumerator to iterate through the elements of a Hashtable. We'll start with a simplified version of the Student class:

public class Student
{
  private string name;
  private string ssn;

  // Constructor.
  public Student(string s, string n) {
    ssn = s;
    name = n;
  }

  // Properties.
  public string Name {
    // Accessor details omitted.
  }
  public string Ssn {
    // Accessor details omitted.
  }
}

Here is the driver code for our IDictionaryEnumerator example:

using System;
using System.Collections;

public class EnumDemo2
{
  static void Main() {
    // Create an instance of a Hashtable.
    Hashtable students = new Hashtable();

    // Instantiate several Student objects.
    Student s1 = new Student("123-45-6789", "Chris Williams");
    Student s2 = new Student("987-65-4321", "Yukio Koyari");
    Student s3 = new Student("654-32-1987", "Maria Lopez");

    // Store their handles in the Hashtable, using the Ssn value as the key.
    students.Add(s1.Ssn, s1);
    students.Add(s2.Ssn, s2);
    students.Add(s3.Ssn, s3);

    // Obtain an IDictionaryEnumerator for the Hashtable.
    IDictionaryEnumerator enum = students.GetEnumerator();

    // Iterate through the collection using the IDictionaryEnumerator.
    while (enum.MoveNext()) {
      // Obtain the next Student object from the collection as the VALUE in
      // a key-value pair.
      Student s = (Student) enum.Value;
      Console.WriteLine(s.Name + ": " + s.Ssn);
    }
  }
}

When this program is run, the following output is produced:

Maria Lopez: 654-32-1987
Yukio Koyari: 987-65-4321
Chris Williams: 123-45-6789

Note that the student information has been printed out in a different order from the order in which the students were originally added to the Hashtable. Entries in a Hashtable aren't retrieved in any particular order by an IDictionaryEnumerator; we're simply guaranteed that we'll have iterated through all the items.