Home > Articles > Programming > C#

.NET Reference Guide

Hosted by

Toggle Open Guide Table of ContentsGuide Contents

Close Table of ContentsGuide Contents

Close Table of Contents

ArrayList

Last updated Mar 14, 2003.

Think of an ArrayList as a resizable one-dimensional array of objects. In addition to automatic resizing, ArrayList has a few other advantages over Array. ArrayList has methods that will add, insert, and remove a range of elements, and it's very easy to create a thread-safe ArrayList using the Synchronized method.

ArrayList isn't without its disadvantages, the primary one being that ArrayList is restricted to a single dimension with a lower bound of zero. Also, because ArrayList is limited to storing only Objects, a one-dimensional Array of a specific type will perform better than an ArrayList, especially if the items you're storing are value types that have to be boxed and unboxed.

You'll find ArrayList very convenient to use, and it performs well enough for all but the most performance-sensitive applications. Unless you must have multiple dimensions, you're probably better off using an ArrayList in the initial development of your program. If you then determine that ArrayList is causing performance problems, it's a relatively simple matter to modify the code to replace the ArrayList with an Array.

The Capacity property tells you how many items the list can hold before it is resized. You can set the Capacity explicitly if you know how many items you need to add to the list. This will increase performance by eliminating the need to resize the list incrementally as items are added.

Count is a read-only property that tells you how many items are currently in the list. Count will always be less than or equal to Capacity. If Count exceeds Capacity when you're adding an item to the list, the list is resized. If you try to set Capacity to a value that's less than Count, ArrayList will throw an ArgumentOutOfRangeException. The TrimToSize method will set Capacity equal to Count, resizing the list and minimizing memory use.

Using an ArrayList

ArrayList has three constructors. The default, parameterless, constructor creates an empty ArrayList that has a default initial capacity of 16 items. There also is a constructor that allows you to specify the list's initial capacity. The final constructor takes an ICollection interface reference, and copies all the items from the collection into the new ArrayList. The Count and Capacity properties of the new list are set to reflect the number of items copied. Here are some examples:

C#

static void DoArrayList()
{
  // create an ArrayList and set its Capacity to 100
  ArrayList al1 = new ArrayList();
  al1.Capacity = 100;

  // create an ArrayList with the initial Capacity of 100
  ArrayList al2 = new ArrayList(100);

  // create an ArrayList from the passed Array
  int[] a = new int[] {0,1,2,3,4,5,6,7,8,9};
  ArrayList al3 = new ArrayList(a);

  foreach (object o in al3)
  {
    Console.WriteLine(o.ToString());
  }
}

Visual Basic

Sub DoArrayList()
  ' create an ArrayList and set its Capacity to 100
  Dim al1 As ArrayList = New ArrayList
  al1.Capacity = 100

  ' create an ArrayList with an initial Capacity of 100
  Dim al2 As ArrayList = New ArrayList(100)

  ' create an Arraylist from the passed Array
  Dim a() As Integer = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}
  Dim al3 As ArrayList = New ArrayList(a)

  Dim o As Object
  For Each o In al3
    Console.WriteLine(o.ToString())
  Next
End Sub

The Add method adds an item to the end of the ArrayList. Insert will insert an item into the list at the specified index, moving all items beyond it "down" one place in the list. AddRange and InsertRange will add or insert multiple items from an ICollection into the list.

Two methods can remove a single item from an ArrayList. Remove removes the first object in the list (searched in sequential order) that is equal to the object passed. Equality is determined by calling Object.Equals. RemoveAt removes the item at the specified index in the list. In both cases, the item is removed from the list and all subsequent items are moved up one place in the list.

The RemoveRange method removes a range of items from the list, starting at the supplied index and removing the specified count of items. All subsequent items in the list are moved up count places in the list.

I suspect an example will help clarify things. The code below shows how to manipulate the ArrayList using the Add, Insert, and Remove methods and some variants.

C#

static void OutputList(ArrayList al)
{
  Console.WriteLine("-----");
  foreach (Object o in al)
    Console.WriteLine(o.ToString());
}

static void DoArrayList()
{
  // create an ArrayList
  ArrayList al = new ArrayList();

  // add a couple of items
  al.Add (1);
  al.Add (2);

  // insert an item between the two
  al.Insert(1, 191);

  OutputList(al);

  // insert a range of items into the list
  int[] a = new int[] {-1, -2, -3, -4, -5, -6};
  al.InsertRange(2, a);

  OutputList(al);

  // remove an item from the list
  al.Remove(-4);

  // remove an item from a specific place in the list
  al.RemoveAt(5);

  // remove items 2, 3, and 4 (start at index 2 and delete 3 items)
  al.RemoveRange(2, 3);

  OutputList(al);
}

Visual Basic

Sub DoArrayList()
  ' create an ArrayList
  Dim al As ArrayList = New ArrayList

  ' Add some items
  al.Add(1)
  al.Add(2)

  ' insert an item between the two
  al.Insert(1, 191)

  OutputList(al)

  ' insert a range of items into the list
  Dim a() As Integer = {-1, -2, -3, -4, -5, -6}
  al.InsertRange(2, a)

  OutputList(al)

  ' remove an item from the list
  al.Remove(-4)

  ' remove an item from a specific place in the list
  al.RemoveAt(5)

  ' remove items 2, 3, and 4 (start at index 2 and delete 3 items)
  al.RemoveRange(2, 3)

  OutputList(al)
End Sub

You access individual items in the ArrayList through the Item property. For example:

C#

Object o = al.Item[3];

Visual Basic

Dim o as Object = al.Item(3)

Item is the indexer for the ArrayList class, so in C# and Visual Basic (and any other .NET language that supports indexers), you can access items in the ArrayList using array-like syntax. For example, the code below sets the fourth item in the list:

C#

al[3] = new Object();

Visual Basic

al(3) = new Object()

Like Array, ArrayList implements a number of interfaces that are common to all collection types, allowing you to in many circumstances treat an ArrayList like a generic list or collection. The interfaces that ArrayList implements are IList, ICollection, ICloneable, and IEnumerable. Check the online reference for each of those interfaces for more information on their capabilities.

Array and ArrayList are the workhorses of .NET collections. Most of the advanced collection types (HashTable, SortedList, Queue, etc.) use one or the other of these base collection types as their underlying data structure. Understanding how Array and ArrayList work will get you a long way towards understanding all of the .NET collection types.