Using the ArrayList Class

Overview

Some people love to collect things. My wife collects lots of things: Salt and pepper shakers, nutcrackers, bears, shot glasses, and tin signs to name but a few.

If I were writing a program to keep track of one of her collections, an array would be a poor choice for storing the data. That's because on any given day, she may come home with a new item she found at an estate sale or an auction. So if she had 87 tin signs before, and I had created an array big enough to hold all 87 signs, I'd have to change the array declaration to hold 88 signs.

Java's collection classes are designed to simplify the programming for applications that have to keep track of groups of objects. These classes are very powerful and surprisingly easy to use-at least the basics, anyway. The more advanced features of collection classes take some serious programming to get right, but for most applications, a few simple methods are all you need to use collection classes.

Unfortunately, Java's collection classes are organized according to a pretty complicated inheritance hierarchy that can be very confusing for beginners. Most of the Java books I have on my shelf start by explaining this inheritance scheme and showing how each of the various collection classes fits into this scheme, and why.

I'm not going to do that-I think it's very confusing for a newcomer to collections to have to wade through a class hierarchy that doesn't make sense until you know some of the details of how the basic classes work. So (instead), I just show you how to use two of the best of these classes. In this chapter, you find out how to use the ArrayList class. Then, in the next chapter, you find out how to use its first cousin, the LinkedList. Once you know how to use these two classes, you shouldn't have any trouble learning how to use the other collection classes from the API documentation.

The ArrayList Class

An array list is the most basic type of Java collection. You can think of an array list as an array on steroids. It's similar to an array, but avoids many of the most common problems of working with arrays. Specifically:

• An array list automatically resizes itself whenever necessary. If you create an array with 100 elements, then fill it up and need to add a 101st element, you're out of luck. The best you can do is create a new array with 101 elements, copy the 100 elements from the old array to the new one, and then put the new data in the 101st element. With an array list, there's never a limit to how many elements you can create. You can keep adding elements as long as you want.
• An array list lets you insert elements into the middle of the collection. With an array, inserting elements is pretty hard to do. Suppose you have an array that can hold 100 elements, but only the first 50 have data. If you need to insert a new element after the 25th item, you must first make a copy of elements 26 through 50 to make room for the new element. With an array list, you just tell the array list you want to insert the new element after the 25th item-and the array list takes care of shuffling things around.
• An array list lets you delete items. If you delete an item from an array, the deleted element becomes null, but the empty slot that was occupied by the item stays in the array. When you delete an item from an array list, any subsequent items in the array are automatically moved forward one position to fill in the spot that was occupied by the deleted item.

• TECHNICAL STAUFF

  The ArrayList class actually uses an array internally to store the data you add to the array list. The ArrayList class takes care of managing the size of this array. When you add an item to the array list and the underlying array is full, the ArrayList class automatically creates a new array with a larger capacity and copies the existing items to the new array before it adds the new item.

The ArrayList class has several constructors and a ton of methods. For your reference, Table 3-1 lists the constructors and methods of the ArrayList class.

Table 3-1: The ArrayList Class

Open table as spreadsheet

Open table as spreadsheet

The rest of this chapter shows you how to use these constructors and methods to work with ArrayList objects.

Creating an ArrayList Object

To create an array list, you first declare an ArrayList variable, and then call the ArrayList constructor to instantiate an array list object and assign it to the variable. You can do this on separate lines:

ArrayList signs; signs = new ArrayList();

or, you can do it on a single line:

ArrayList signs = new ArrayList();

Here are a few things to note about creating array lists:

• Tip

  The ArrayList class is in the java.util package, so your program must import either java.util.ArrayList or java.util.*.

• Unlike an array, an array list doesn't make you specify a capacity-though you can if you want. Here's a statement that creates an array list with an initial capacity of 100:

  ArrayList signs = new ArrayList(100);

  If you don't specify a capacity for the array list, the initial capacity is set to 10. Providing at least a rough estimate of how many elements each array list can hold when you create it is a good idea.

• REMEMBER

  The capacity of an array list is not a fixed limit. The ArrayList class automatically increases the list's capacity whenever necessary.

• Tip

  If you're using Java 1.5 or later, you can also specify the type of elements the array list is allowed to contain. For example, this statement creates an array list that holds String objects: ArrayList signs = new ArrayList();

  The advantage of specifying a type when you declare an array list is that the compiler complains if you then try to add an object of the wrong type to the list. (This feature is called generics because it lets the Java API designers create generic collection classes that can be used to store any type of object. For more information, refer to Book IV, Chapter 5.)

• The ArrayList class also has a constructor that lets you specify another collection object (typically another array list) whose items are copied into the new array list. This provides an easy way to make a copy of an array list, but you can also use it to convert any other type of collection to an array list.

Adding Elements

After you create an array list, you can use the add method to add objects to the array list. For example, here's code that adds strings to an array list:

signs.add("Drink Pepsi"); signs.add("No minors allowed"); signs.add("Say Pepsi, Please"); signs.add("7-Up: You Like It, It Likes You"); signs.add("Dr. Pepper 10, 2, 4");

If you specified a type when you created the array list, the objects you add via the add method must be of the correct type.

You can insert an object at a specific position in the list by listing the position in the add method. For example, consider these statements:

ArrayList nums = new ArrayList(); nums.add("One"); nums.add("Two"); nums.add("Three"); nums.add("Four"); nums.add(2, "Two and a half");

After these statements execute, the nums array list contains the following strings:

One Two Two and a half Three Four

Here are some important points to keep in mind when you add elements to array lists:

• Tip

  If an array list is already at its capacity when you add an element, the array list automatically expands its capacity. Although this capacity is flexible, it's also inefficient. So, whenever possible, you should anticipate how many elements you're adding to an array list and set the list's initial capacity accordingly. (You can also change the capacity at any time by calling the ensureCapacity method.)

• Like arrays, array lists are indexed starting with zero. Keep this in mind when you use the version of the add method that accepts an index number.

• Warning

  The add method that inserts elements at a specific index position throws the unchecked exception IndexOutOfBoundsException if an object isn't already at the index position you specify.

Accessing Elements

To access a specific element in an array list, you can use the get method. It specifies the index value of the element you want to retrieve. For example, here's a for loop that prints all the strings in an array list:

for (int i = 0; i < nums.size(); i++) System.out.println(nums.get(i));

Here the size method is used to set the limit of the for loop's index variable.

The easiest way to access all the elements in an array list is by using an enhanced for statement. It lets you retrieve the elements without bothering with indexes or the get method. For example:

for (String s : nums) System.out.println(s);

Here, each String element in the nums array list is printed to the console.

If you need to know the index number of a particular object in an array list and you have a reference to the object, you can use the indexOf method. For example, here's an enhanced for loop that prints the index number of each string along with the string:

for (String s : nums) { int i = nums.indexOf(s); System.out.println("Item " + i + ": " + s); }

Depending on the contents of the array list, the output from this loop looks something like this:

Item 0: One Item 1: Two Item 2: Three Item 3: Four

Printing an ArrayList

The toString method of the ArrayList class (as well as other collection classes) is designed to make it easy to quickly print out the contents of the list. It returns the contents of the array list enclosed in a set of brackets, with each element value separated by commas. The toString method of each element is called to obtain the element value.

For example, consider these statements:

ArrayList nums = new ArrayList(); nums.add("One"); nums.add("Two"); nums.add("Three"); nums.add("Four"); System.out.println(nums);

When you run these statements, the following is displayed on the console:

[One, Two, Three, Four]

Although this output isn't very useful for actual applications, it's convenient for testing purposes or for debugging problems in programs that use array lists.

Using an Iterator

Another way to access all the elements in an array list (or any other collection type) is to use an iterator. An iterator is a special type of object whose sole purpose in life is to let you step through the elements of a collection.

An iterator object implements the Iterator interface, which is defined as part of the java.util package. As a result, to use an iterator, you must import either java.util.Iterator or java.util.*. The Iterator interface defines just three methods, as listed in Table 3-2. These methods are all you need to access each element of a collection. (Actually, you only need the hasNext and next methods. The remove method is gravy.)

To use an iterator, you first call the array list's iterator method to get the iterator. Then you use the iterator's hasNext and next methods to retrieve each item in the collection. The normal way to do that is with a while loop; here's an example:

ArrayList nums = new ArrayList(); nums.add("One"); nums.add("Two"); nums.add("Three"); nums.add("Four"); String s; Iterator e = nums.iterator(); while (e.hasNext()) { s = (String)e.next(); System.out.println(s); }

Here the first five statements create an array list and add four strings to it. Next, the iterator method is called to get an iterator for the nums array list. The hasNext method is called in the while statement, and the next method is called to get the element to be printed.

Updating Elements

You can use the set method to replace an existing object with another object. Consider this example:

ArrayList nums = new ArrayList(); nums.clear(); nums.add("One"); nums.add("Two"); nums.add("Three"); System.out.println(nums); nums.set(0, "Uno"); nums.set(1, "Dos"); nums.set(2, "Tres"); System.out.println(nums);

Here an array list is created with three strings, and the contents of the array list are printed to the console. Then each of the three strings is replaced by another string, and the contents print to the console again. When you run this code, the following is what you see printed on the console:

[One, Two, Three] [Uno, Dos, Tres]

For example:

ArrayList emps = new ArrayList(); // add employees to array list emps.add(new Employee("Addams", "Gomez")); emps.add(new Employee("Taylor", "Andy")); emps.add(new Employee("Kirk", "James")); // print array list System.out.println(emps); // change one of the employee's names Employee e = emps.get(1); e.changeName("Petrie", "Robert"); // print the array list again System.out.println(emps);

It uses the Employee class whose constructor accepts an employee's last name and first name to create a new employee object, as well as a changeName method that also accepts a last name and a first name. In addition, the Employee class overrides the toString method to return the employee's first name and last name.

The main method begins by creating an ArrayList object and adding three employees. Then it prints out the contents of the array list. Next, it retrieves the employee with index number 1 and changes that employee's name. Finally, it prints the contents of the array list again.

Here's what this code produces on the console:

[Gomez Addams, Andy Taylor, James Kirk] [Gomez Addams, Robert Petrie, James Kirk]

Notice that the second employee's name was changed, even though the program doesn't use the set method to replace the changed Employee object in the collection. That's because the array list merely stores references to the Employee objects.

Deleting Elements

The ArrayList class provides several methods that let you remove elements from the collection. To remove all the elements, use the clear method, like this:

emps.clear();

To remove a specific element, use the remove method. It lets you remove an element based on the index number, like this:

emps.remove(0);

Here the first element in the array list is removed.

Alternatively, you can pass the actual object you want removed. This is useful if you don't know the index of the object you want to remove, but you happen to have a reference to the actual object as in this example:

ArrayList emps = new ArrayList(); // create employee objects Employee emp1 = new Employee("Addams", "Gomez"); Employee emp2 = new Employee("Taylor", "Andy"); Employee emp3 = new Employee("Kirk", "James"); // add employee objects to array list emps.add(emp1); emps.add(emp2); emps.add(emp3); // print the array list System.out.println(emps); // remove one of the employees emps.remove(emp2); // print the array list again System.out.println(emps);

Here's what this code produces on the console:

[Gomez Addams, Andy Taylor, James Kirk] [Gomez Addams, James Kirk]

As you can see, Andy Taylor was removed from the list without knowing his index position.

Here are a few important details to keep in mind:

• The clear and remove methods don't actually delete objects. They simply remove the references to the objects from the array list. Like any other object, the objects in a collection are deleted automatically by the garbage collector-and then only if the objects are no longer being referenced by the program.
• You can remove more than one element at once by using the removeRange method. On it, you specify the starting and ending index numbers. (Note that this method removes all elements between the elements you specify, but the elements you specify aren't themselves removed. For example, removeRange(5, 8) removes elements 6 and 7. Elements 5 and 8 aren't removed.)

• Warning

  You can also use the removeAll method to remove all the objects in one collection from another collection. And a similar method, retainAll, removes all the objects that are not in another collection.