Arrays and Index Positions in Java

An ArrayList is a dynamic array. An object of type ArrayList<T> has the instance methods you would expect from a dynamic array implementation, and four of them do most of the everyday work: size reports how many items the list holds, add puts a new item at the end, get reads the item at a given position, and set replaces the item at a given position. If you understand what each of these does to the list and which positions it accepts, you can read and write most ArrayList code with confidence.

Most ArrayList bugs come from using a position that does not exist. Before you learn the methods, test your intuition with a small question about a list that has three items.

A call to the default constructor, new ArrayList<T>(), creates a list with size zero. The list holds no items yet, so it has no valid positions. Adding an item is the only thing that gives the list its first position. Follow the list step by step as the calls below run in order.

Notice that you never chose a position when you called add. The new item simply became the last item, at the position that was list.size() before the call. After the call, that position is list.size()-1.

The call list.size() returns the current size of the list, meaning the number of items in the list at that moment. The size changes as items are added or removed, so calling size later may give a different answer. The size can be zero, as in a brand-new list.

The size tells you where the valid positions end. The only valid positions are the whole numbers from 0 up to list.size()-1. Positions in an ArrayList start at 0, not 1. The first item is at position 0, the second is at position 1, and the last is at position list.size()-1. Because size() tells you exactly where the range ends, it is the standard way to check a position before you use it.

The diagram shows a list with three items. Its size is 3, so the valid positions are 0, 1, and 2. Position 3 does not exist, even though a list of size 3 seems to have room for it. Keeping this in mind prevents the most common off-by-one errors.

The call list.add(obj) appends the object obj to the end of the list and increases the size by 1. The parameter obj can be of type T or it can be null. Because add always appends, you do not choose a position when you call it.

The call list.get(N) returns the value stored at position N, and its return type is T. The integer N must lie in the range 0 to list.size()-1. Calling get is similar to reading A[N] from an array A, with one important difference: you can read with list.get(N), but you cannot use list.get(N) on the left side of an assignment statement.

The call list.set(N, obj) assigns obj to position N, replacing the item that was previously stored there. The parameter obj must be of type T, and N must be in the range 0 to list.size()-1. A call to set is equivalent to the array command A[N] = obj. Because set replaces an item instead of adding one, it does not change the size.

The source example starts with a three-item list holding apple, banana, and cherry. A call to set at position 1 with the value blueberry replaces banana. Nothing else in the list changes, and the size remains 3. Only the item at position 1 is changed; the other two items keep their positions and values.

When get or set receives an index outside 0 to list.size()-1, an IndexOutOfBoundsException error occurs. You can check the outcome by comparing the index with the size before the call. The valid range depends on the current size, so a position that was valid earlier may be invalid after items are removed, and calling size again later may give a different range.

Now trace a full sequence. Start with an empty list, then run add, add, set, and get in order. After each step, state the size and the contents before reading the next line. The diagram shows the state after each call.