Lists in Java: Sample Code

Here are some simple code examples of using some basic List abilities as described in The List in Java.

Comments about what the code is up to are included below.

This code is written to simply demonstrate a few things, as a reference. I chose to write it a bit "dirty" for the sake of keeping what it does demonstrate as clear as possible. For example it makes some assumptions about the nature of the data it is working with. In a real program, this may not be the right thing to do.

The code will generate a warning you can ignore: Note: Lister.java uses unchecked or unsafe operations.

This is a result of not doing complete checking to make sure that the Object types passed to System.out.println() are compatible, i.e., have a toString() method. It's one of the things I'm not worrying about for the sake of this short demo.

/* Playing around with Lists, in basic ways.
  We use the ArrayList class as an implementation of List,
  since at this point we're just using a List's features,
  rather than learning about building our own List-based
  class.

  -Mark Graybill, Apr. 2010
*/

import java.util.*; // include the package with List in it.

public class Lister{
  public static void main(String arg[]){

  // Create some Lists to play with.
    ArrayList lister = new ArrayList();
    ArrayList dave = new ArrayList();
    ArrayList kryten = new ArrayList();

  // Put some things in the lister List, manually.
    lister.add("The End");
    lister.add("Future Echoes");
    lister.add("Confidence and Paranoia");
    lister.add("Thanks for the Memories");

  // Print the current lister list.
    System.out.print(lister);
    System.out.println();

  /* Get a sublist from lister.
    This will get items at indices 1 and 2. Stops
    short of item 3. I.e., gets sublist from element
    1 up to, but not including, 3. */
    dave.addAll(lister.subList(1,3));

    System.out.print("Sublist elements 1 and 2: ");
    System.out.print(dave);
    System.out.println();

  // Put something in the kryten list.
    kryten.add("The Rimmer Experience");
    kryten.add("Ace");

  // See if kryten is in the lister list.
    if (lister.containsAll(kryten)){
      System.out.println("All of kryten is in lister.");
    }
    else {
      System.out.println("Items in kryten aren't in lister.");
    }

  // Do the same thing with the dave list.
    if (lister.containsAll(dave)){
      System.out.println("Items in dave are all in lister.");
    }
    else {
      System.out.println("Items in dave aren't in lister.");
    }

  // Step through the list with a for-each
    System.out.println(); // Get a blank line.
    System.out.println("Items in Lister:"); // Title the list.
    for (Object epname: lister){ // Print the list.
      System.out.println(epname);
    }

  /* Note: the above code is a little bit "dirty", in that we're counting on
    the objects we get from lister to be printable. Since we've had tight
    control over what goes in, we can get away with this. If you make a List
    that lets anything in, make sure they've all got toString() methods, or
    otherwise take care of object types. Generics are a partial solution to
    this problem (though they're less than perfect.)
  */

  // Get an iterator and use it.
    ListIterator iter = lister.listIterator();

  // Iterator starts out with the first element in List as its "next()"
    System.out.println();
    System.out.println(iter.next());

  // Doing next() has advaned our iterator in the list,
  // so if we do it again:
    System.out.println(iter.next());
  // We see we have advanced. And we advance again.

  // We can it to go through the list, use hasNext() to watch for the end.
    System.out.println("\nGoing forward:");
    while (iter.hasNext()){
      System.out.println(iter.next());
  }

  // And we can go backward:
    System.out.println("\nGoing backward:");
    while (iter.hasPrevious()){
      System.out.println(iter.previous());
    }

  // Print the element in front of "Thanks for the Memories".
    System.out.println("\nItem before \"Thanks for the Memories\" is:");
    while (iter.hasNext()){
      if ( iter.next().toString().contentEquals("Thanks for the Memories") ){
        iter.previous(); //we found it, now move back to it.
        System.out.println(iter.previous());       // Two steps to get back.
        break; // We've done it, now get out of the loop.
      }
    }

  } // end of main()
} // end of Lister


Since I'm not using generics in this code, some of the information about what's stored in the list gets lost--everything becomes an "Object". Not using generics limits the usability of a Collection quite a lot, so it's usually best to use generics as it beats writing all the code to work around the lack of known class types for data.

For example, using Java's Generics, I can declare a type for items in the list that Java will enforce:
ArrayList<String> lister = new ArrayList<String>();

In this way, I can now treat items that come out of lister as a String, too:
if (iter.next().contentEquals("Thanks for the Memories")){ ...

Watch for more about Generics in another article.

The List in Java

A Java List is a way for keeping track of things in the order you put them in. They are part of the Collections framework in Java, in other words, they are a kind on Collection. Collections all share some abilities, and can easily be converted from one kind of Collection to another.

List is an Interface, which means that it is not a Class, but a standard that you can make a class adhere to. By making a class a List, and implementing at least the required methods of a List, you have the abilities of a List, as if it were a class.

Make sure you have the right List when you look it up.
This is the one you want. The List class from the java.awt package is something different.

Lists are used to keep a list of objects. This seems obvious, but there are lots of ways of collecting up a number of objects in Java, including sets, arrays, different types of lists like linked lists, and maps. Each has its own characteristics. A List is good for sets of objects where you don't know how many objects there might be, where you want the objects kept in the order you put them in, and where you want to be able add objects to the list or remove them. Objects can be added to or removed from Lists en masse. Lists can also be tested against other collections to see if they include all the objects in that list, or none of them.

• Lists start at zero and go up to the number of objects in them, minus one.


• You can determine if a List is empty (true or false) using isEmpty()


• You can get the size of a List using size()


• You can access an item in a List by its index using get().


• Items can be added to the end of a List with add(), or


• You can insert an object into a particular place in a List, moving the rest "down" with add(index, element).


• You can put one object repeatedly in a List (unlike a Set).


• You can find the first instance of an object in a List (getting its index) with indexOf(), or


• You can get the last instance of an object (getting its index) with lastIndexOf()


• You can delete an object from a List with remove().


• You can append all the members of some other Collection to a List at once with addAll().


• You can delete all members of some other Collection from a List all at once with removeAll().


• You can delete all members that are not in another Collection with retainAll()


• You can see if all members of a Collection are present in a List with containsAll().


• You can clear the list out with clear()


• or keep a section of it with subList().

Some things you can do with a List.

See Lists in Java: Sample Code for examples of using a List.

Many programmers first encounter the List when they run into a method for something they're working with that returns a List. If you're not used to using Collections, this will seem to add an extra layer of complexity. However, it lets the method deal with giving you a group of objects as its return value, without it having to know how many things it might be returning in advance, or what the classes of those objects will be.

For example, the Greenfoot framework for Java makes copious use of the List. If you have a World in Greenfoot that contains a bunch of Robot objects, like this:

A World That Contains a Bunch of Robots

You can do something to all the Robots by calling a World method that returns a List of the Robots.

Using the List

Once you've got the List, you can then do something to all the Robots by iterating through the list and calling the appropriate method for each Robot. To do this, we use the List's ability to provide us with an iterator to move between its elements one by one once we get the List. In this case, it's done automatically by Java's for-each loop:

List<robot> robots = getWorld().getObjects(Robot.class); // get a List of Robots

for (Robot thisRobot : robots) {
    thisRobot.turnLeft();
}

This goes through and calls the turnLeft() method of each robot returned in the list.

To explicitly get an iterator from a List, we can use the listIterator() method of the List:

ListIterator robotIterator = robots.listIterator();

This gives us a list iterator that starts at zero and progresses through the list as we call the iterator's next() method, after checking to see that there is a next item using hasNext(), of course. See ListIterator to see what you can do with the iterator.

We can also get an iterator that starts at a particular position in the list. For example, let's say we want to skip our way past the first 100 elements:

ListIterator robotIterator = robots.listIterator(100);

The normal use of a List is as a simple list of objects to iterate through, as shown. The use of the additional features of the List make it a far more powerful construct, however. In general, it's very useful to learn as much about Collections in Java as possible, as they are the most generally useful data structures for dealing with groups of objects.

See Lists in Java: Sample Code for examples of using a List.