4.8 ArrayList Methods

4.8 ArrayList Methods

An ArrayList is a resizable collection: unlike a fixed-length array, it can grow when new objects arrive and shrink when objects are removed. A tournament program, for example, can read competitor names, construct Competitor objects, store them in an ArrayList, and later create Match objects from those competitors.

Storing objects with add

The add method places an object at the end of an ArrayList. The list stores references to objects, so the type parameter should identify the class of object the list is intended to contain.

ArrayList<Competitor> competitorList = new ArrayList<Competitor>();

for (int i = 0; i < names.length; i++) {
    Competitor c = new Competitor(names[i], i + 1);
    competitorList.add(c);
}

The loop processes every element of names. On each pass, names[i] supplies the competitor's name, while i + 1 supplies a one-based position. The newly constructed object is then added to competitorList.

Statement	Effect
new Competitor(names[i], i + 1)	Constructs one Competitor object
competitorList.add(c)	Adds that object to the list
competitorList.size()	Reports how many competitors are currently stored
competitorList.get(i)	Retrieves the object at index i

Misconception check — adding an index is not adding an object. competitorList.add(i) attempts to add an integer, not the Competitor at position i. When the list is declared as ArrayList<Competitor>, the correct argument must be a Competitor, such as c or competitorList.get(i).

Methods that return an ArrayList

A method that constructs and returns a list must declare the complete return type. For matches, the signature is:

public ArrayList<Match> buildMatches()

Inside the method, declare and initialize the result before adding anything:

ArrayList<Match> matches = new ArrayList<Match>();

The method must return the list itself, not merely print it and not return competitor indices. Printing may display information, but returning an ArrayList<Match> gives the calling code a usable collection of Match objects.

return matches;

Syntactic precision matters. A statement such as matches; return is not a valid Java return statement. The expression after return must be the value being returned, followed by a semicolon.

Building pairings without duplicate or missing matches

Suppose competitors are paired from the outside inward: the first with the last, the second with the second-to-last, and so on. The loop must stop at the middle; continuing farther creates duplicate pairings or attempts to reuse competitors.

public ArrayList<Match> buildMatches() {
    ArrayList<Match> matches = new ArrayList<Match>();

    if (competitorList.size() % 2 == 0) {
        for (int i = 0; i < competitorList.size() / 2; i++) {
            matches.add(new Match(
                competitorList.get(i),
                competitorList.get(competitorList.size() - i - 1)
            ));
        }
    } else {
        for (int i = 1; i < competitorList.size() / 2 + 1; i++) {
            matches.add(new Match(
                competitorList.get(i),
                competitorList.get(competitorList.size() - i)
            ));
        }
    }

    return matches;
}

For an even number of competitors, index 0 must participate. With six competitors, the pairs are (0,5), (1,4), and (2,3). For an odd number, the first competitor receives the special unmatched position, so with five competitors the pairs are (1,4) and (2,3).

Misconception check — odd and even cases are not interchangeable. Always starting at index 0 for an odd-sized list incorrectly includes the first competitor. Always starting at index 1 incorrectly omits the first competitor when the list size is even.

Preserving order in returned lists

When a method builds a result from wordList, elements in the returned ArrayList must appear in the same order as their corresponding elements in wordList. If wordList contains ["catch", "bobcat", "catchacat", "cat", "at"], a method that removes the initial occurrence of a target must retain the relative order of every remaining string.

This is different from sorting. Removing or selecting elements may shorten the result, but it should not rearrange the survivors unless the method explicitly requires rearrangement.

Skills in action

This topic exercises Skill 2.A — Representing and contrasting data, because the program must identify whether an element is an object, an index, or a returned collection. It exercises Skill 2.B — Determine the required code, because the programmer must choose the correct ArrayList method and loop bounds. It also exercises Skill 2.C — Develop program code, especially constructing objects, adding them to a list, and returning the completed list.

Retrieval check: If competitorList.size() is $7$, which competitor index is intentionally left out of the pairing loop in the odd case, and why? What value should the method return: matches, an index, or the original competitorList?