The document provides an overview of the List interface in Java, describing it as an ordered collection that allows for duplicate elements and various operations like positional access, searching, and iteration. It includes details on common implementations such as ArrayList and LinkedList, as well as examples of specific operations like add, remove, and sublist. Additionally, it covers algorithms that can be applied to lists, such as sorting and shuffling.
![8/30/2016 The List Interface (The Java™ Tutorials > Collections > Interfaces)
https://docs.oracle.com/javase/tutorial/collections/interfaces/list.html 2/6
a.set(j, tmp);
}
Of course, there's one big difference. This is a polymorphic algorithm: It swaps two elements in any List, regardless of its implementation type.
Here's another polymorphic algorithm that uses the preceding swap method.
public static void shuffle(List<?> list, Random rnd) {
for (int i = list.size(); i > 1; i‐‐)
swap(list, i ‐ 1, rnd.nextInt(i));
}
This algorithm, which is included in the Java platform's Collections class, randomly permutes the specified list using the specified source of
randomness. It's a bit subtle: It runs up the list from the bottom, repeatedly swapping a randomly selected element into the current position. Unlike
most naive attempts at shuffling, it's fair (all permutations occur with equal likelihood, assuming an unbiased source of randomness) and fast (requiring
exactly list.size()1 swaps). The following program uses this algorithm to print the words in its argument list in random order.
import java.util.*;
public class Shuffle {
public static void main(String[] args) {
List<String> list = new ArrayList<String>();
for (String a : args)
list.add(a);
Collections.shuffle(list, new Random());
System.out.println(list);
}
}
In fact, this program can be made even shorter and faster. The Arrays class has a static factory method called asList, which allows an array to be
viewed as a List. This method does not copy the array. Changes in the List write through to the array and vice versa. The resulting List is not a
generalpurpose List implementation, because it doesn't implement the (optional) add and remove operations: Arrays are not resizable. Taking
advantage of Arrays.asList and calling the library version of shuffle, which uses a default source of randomness, you get the following tiny
program whose behavior is identical to the previous program.
import java.util.*;
public class Shuffle {
public static void main(String[] args) {
List<String> list = Arrays.asList(args);
Collections.shuffle(list);
System.out.println(list);
}
}
Iterators
As you'd expect, the Iterator returned by List's iterator operation returns the elements of the list in proper sequence. List also provides a
richer iterator, called a ListIterator, which allows you to traverse the list in either direction, modify the list during iteration, and obtain the current
position of the iterator.
The three methods that ListIterator inherits from Iterator (hasNext, next, and remove) do exactly the same thing in both interfaces. The
hasPrevious and the previous operations are exact analogues of hasNext and next. The former operations refer to the element before the
(implicit) cursor, whereas the latter refer to the element after the cursor. The previous operation moves the cursor backward, whereas next moves
it forward.
Here's the standard idiom for iterating backward through a list.
for (ListIterator<Type> it = list.listIterator(list.size()); it.hasPrevious(); ) {
Type t = it.previous();
...
}
Note the argument to listIterator in the preceding idiom. The List interface has two forms of the listIterator method. The form with no
arguments returns a ListIterator positioned at the beginning of the list; the form with an int argument returns a ListIterator positioned at
the specified index. The index refers to the element that would be returned by an initial call to next. An initial call to previous would return the
element whose index was index1. In a list of length n, there are n+1 valid values for index, from 0 to n, inclusive.](https://image.slidesharecdn.com/thelistinterfacethejavatutorialscollectionsinterfaces-161008062601/85/The-list-interface-the-java-tutorials-collections-interfaces-2-320.jpg)
![8/30/2016 The List Interface (The Java™ Tutorials > Collections > Interfaces)
https://docs.oracle.com/javase/tutorial/collections/interfaces/list.html 4/6
The rangeview operation, subList(int fromIndex, int toIndex), returns a List view of the portion of this list whose indices range
from fromIndex, inclusive, to toIndex, exclusive. This halfopen range mirrors the typical for loop.
for (int i = fromIndex; i < toIndex; i++) {
...
}
As the term view implies, the returned List is backed up by the List on which subList was called, so changes in the former are reflected in the
latter.
This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a List can be
used as a range operation by passing a subList view instead of a whole List. For example, the following idiom removes a range of elements from
a List.
list.subList(fromIndex, toIndex).clear();
Similar idioms can be constructed to search for an element in a range.
int i = list.subList(fromIndex, toIndex).indexOf(o);
int j = list.subList(fromIndex, toIndex).lastIndexOf(o);
Note that the preceding idioms return the index of the found element in the subList, not the index in the backing List.
Any polymorphic algorithm that operates on a List, such as the replace and shuffle examples, works with the List returned by subList.
Here's a polymorphic algorithm whose implementation uses subList to deal a hand from a deck. That is, it returns a new List (the "hand")
containing the specified number of elements taken from the end of the specified List (the "deck"). The elements returned in the hand are removed
from the deck.
public static <E> List<E> dealHand(List<E> deck, int n) {
int deckSize = deck.size();
List<E> handView = deck.subList(deckSize ‐ n, deckSize);
List<E> hand = new ArrayList<E>(handView);
handView.clear();
return hand;
}
Note that this algorithm removes the hand from the end of the deck. For many common List implementations, such as ArrayList, the
performance of removing elements from the end of the list is substantially better than that of removing elements from the beginning.
The following is a program that uses the dealHand method in combination with Collections.shuffle to generate hands from a normal 52
card deck. The program takes two commandline arguments: (1) the number of hands to deal and (2) the number of cards in each hand.
import java.util.*;
public class Deal {
public static void main(String[] args) {
if (args.length < 2) {
System.out.println("Usage: Deal hands cards");
return;
}
int numHands = Integer.parseInt(args[0]);
int cardsPerHand = Integer.parseInt(args[1]);
// Make a normal 52‐card deck.
String[] suit = new String[] {
"spades", "hearts",
"diamonds", "clubs"
};
String[] rank = new String[] {
"ace", "2", "3", "4",
"5", "6", "7", "8", "9", "10",
"jack", "queen", "king"
};
List<String> deck = new ArrayList<String>();
for (int i = 0; i < suit.length; i++)
for (int j = 0; j < rank.length; j++)
deck.add(rank[j] + " of " + suit[i]);](https://image.slidesharecdn.com/thelistinterfacethejavatutorialscollectionsinterfaces-161008062601/85/The-list-interface-the-java-tutorials-collections-interfaces-4-320.jpg)
![8/30/2016 The List Interface (The Java™ Tutorials > Collections > Interfaces)
https://docs.oracle.com/javase/tutorial/collections/interfaces/list.html 5/6
// Shuffle the deck.
Collections.shuffle(deck);
if (numHands * cardsPerHand > deck.size()) {
System.out.println("Not enough cards.");
return;
}
for (int i = 0; i < numHands; i++)
System.out.println(dealHand(deck, cardsPerHand));
}
public static <E> List<E> dealHand(List<E> deck, int n) {
int deckSize = deck.size();
List<E> handView = deck.subList(deckSize ‐ n, deckSize);
List<E> hand = new ArrayList<E>(handView);
handView.clear();
return hand;
}
}
Running the program produces output like the following.
% java Deal 4 5
[8 of hearts, jack of spades, 3 of spades, 4 of spades,
king of diamonds]
[4 of diamonds, ace of clubs, 6 of clubs, jack of hearts,
queen of hearts]
[7 of spades, 5 of spades, 2 of diamonds, queen of diamonds,
9 of clubs]
[8 of spades, 6 of diamonds, ace of spades, 3 of hearts,
ace of hearts]
Although the subList operation is extremely powerful, some care must be exercised when using it. The semantics of the List returned by
subList become undefined if elements are added to or removed from the backing List in any way other than via the returned List. Thus, it's
highly recommended that you use the List returned by subList only as a transient object — to perform one or a sequence of range operations on
the backing List. The longer you use the subList instance, the greater the probability that you'll compromise it by modifying the backing List
directly or through another subList object. Note that it is legal to modify a sublist of a sublist and to continue using the original sublist (though not
concurrently).
List Algorithms
Most polymorphic algorithms in the Collections class apply specifically to List. Having all these algorithms at your disposal makes it very easy to
manipulate lists. Here's a summary of these algorithms, which are described in more detail in the Algorithms section.
sort — sorts a List using a merge sort algorithm, which provides a fast, stable sort. (A stable sort is one that does not reorder equal
elements.)
shuffle — randomly permutes the elements in a List.
reverse — reverses the order of the elements in a List.
rotate — rotates all the elements in a List by a specified distance.
swap — swaps the elements at specified positions in a List.
replaceAll — replaces all occurrences of one specified value with another.
fill — overwrites every element in a List with the specified value.
copy — copies the source List into the destination List.
binarySearch — searches for an element in an ordered List using the binary search algorithm.
indexOfSubList — returns the index of the first sublist of one List that is equal to another.
lastIndexOfSubList — returns the index of the last sublist of one List that is equal to another.
Your use of this page and all the material on pages under "The Java Tutorials" banner is subject to these legal
notices.
Copyright © 1995, 2015 Oracle and/or its affiliates. All rights reserved.
Problems with the examples? Try Compiling and Running the Examples:
FAQs.
Complaints? Compliments? Suggestions? Give us your feedback.](https://image.slidesharecdn.com/thelistinterfacethejavatutorialscollectionsinterfaces-161008062601/85/The-list-interface-the-java-tutorials-collections-interfaces-5-320.jpg)
