List interface


           Provides methods  .add(index...),   .addAll(index...),   .get(...),   .indexOf(...),   .iterator( ),

             .lastIndexOf(...),   .set(...),   .subList(...)


ArrayList,  LinkedList,  Vector  and  Stack  can use each of these methods.


■ This interface extends Collection and adds its methods to those of Collection. See Collection interface for those other methods which Lists can use.



void  .add( index, Obj )  method


■ This method inserts the item into the list after the specific spot indicated..


■ The index starts at zero.  


■ Its opposite is .remove( index, Obj ). 


 i.e. The snippet inserts the word "little" into its appropriate place in "Mary had a lamb":


Mary had a lamb

Mary had a little lamb


import java.util.*;


Vector v = new Vector( );

v.add( "Mary" );

v.add( "had" );

v.add( "a" );

v.add( "lamb");

System.out.println( v );

v.add(  3, "little" );

System.out.println( v );


  The index you specify cannot exceed the length of the list, or you will get an IndexOutOfBoundsException.  


  Note that, unlike all the other .add(...) methods, this one doesn't return a boolean false if things go badly.  Instead of a boolean false you will receive one of a variety of exceptions.



boolean  .addAll( index, Coll )  method


■ This version of .addAll(...) inserts all the elements of an existing collection into an indexed starting point of the List, pushing down any pre-existing contents from that point on.   It returns a true if successful.  i.e. The snippet inserts the three elements of the automatically alphabetized TreeSet into the element 1 point in the Vector and thus prints:


foo AAA BBB CCC bar


import java.util.*;


Set s = new TreeSet(  );

s.add( "BBB" );

s.add( "CCC" );

s.add( "AAA" );

Vector v = new Vector( 2 );

v.add( "foo" );

v.add( "bar" );

v.addAll ( 1, s );                     // insert the other collection

System.out.println( v );



Object  .get( index )   method


■ Returns the list element from the designated index position, without removing it.  If you supply a bad index you will get an IndexOutOfBoundsException.  i.e. Assume Vector v from the example immediately above still exists after the .addAll(...).  This statement will print  foo bar  from Vector v's zero and fourth positions:


System.out.println( v.get( 0 ) + " " + v.get( 4) );


■ There is no parameter-less get( ) method where you can simply retrieve the list's top element.  The closest is Stack's .pop( ) method, but that works only for a Stack.



 int  .indexOf( Obj )   method


Finding things in Lists.  This method returns the index position of the first occurrence of a specified element.  It returns -1 if the element is not found at all.


i.e. The snippet shows how to remove the first occurrence of an element from a list without knowing its position, by using this .index(...)  method to supply the element's index. However the danger in this trick is that the .removeElementAt(...) method will not like a -1 returned and will generate an ArrayIndexOutOfBoundsException if the element you specify is not in the List.  Also, if there are multiple occurrences of the item, they will not all be removed.


import java.util.*;


Stack st = new Stack(  );

st.add( "TOM" );

st.add( "DICK" );

st.add( "HARRY" );

st.removeElementAt( st.indexOf( "DICK" ) );    // remove DICK wherever it is

System.out.println( st );



Iterator  .iterator( )  method


■ Returns an Iterator over the elements in the List.  see Iterators for explanations and examples



int  .lastIndexOf( Obj )  method


■ This method is the opposite of .indexOf(...) above.  It returns the index of the last occurrence of the specified element.


i.e. The snippet uses both .indexOf(...) and .lastIndexOf(...) to find multiple occurrences of items in a List.  It prints:


Duplicate of DAFFY at element 0

Duplicate of DONALD at element 1

Duplicate of DAFFY at element 2

Duplicate of DAFFY at element 4

Duplicate of DONALD at element 5


import java.util.*;


ArrayList al = new ArrayList(  );

al.add( "DAFFY" );

al.add( "DONALD" );

al.add( "DAFFY" );

al.add( "QUACKY" );

al.add( "DAFFY" );

al.add( "DONALD" );

for ( int x = 0; x < al.size( ); x++ ) {

    String s = (String) al.get( x );

    if ( al.indexOf( s )  != al.lastIndexOf( s ) ) {

        System.out.println( "Duplicate of " + s + " at element " + x );





.set( index, Obj )  method


■ This method replaces the element at the specified index with the Object supplied, also returning the replaced Object.  It throws exceptions if anything goes wrong -  meaning it doesn’t return booleans.


i.e. The snippet replaces all "DAFFY"elements in a List with a new "REPLACED" element and prints:




import java.util.*;


ArrayList al = new ArrayList(  );

al.add( "DAFFY" );

al.add( "DONALD" );

al.add( "DAFFY" );

al.add( "QUACKY" );

String s1 = "DAFFY";

String s2 = "REPLACED";

for (int x =0; x < al.size( ); x++ ) {

    if (al.get( x ).equals( s1 ) )  al.set ( x, s2 );


System.out.println( al );  


■ You cannot use this method to add anything to the list, at either end. Attempting to do so will generate an ArrayIndexOutOfBoundsException.



List  .subList( fromIndex, toIndex )  method


■ This method returns a view of part of a List, so you can perform operations like .clear( ) or .copyInto(...).


■ The range of the List includes the element represented by the first parameter, the fromIndex, but it does not include the element at the second parameter, the toIndex.  In other words, saying 0,1 gets you just one element, element 0. Saying 1,3 gets you elements 2 and 3.  Specifying the same number for both always gets you nothing. Specifying a toIndex beyond the last element gets you an IndexOutOfBoundsException.


■ Also, the sublist is backed by the original list, so you can't modify the size or structure of the original list while these operations are underway.


■ The snippet clears out the fourth element, which is the 333, and prints:


000 111 222


import java.util.*;


ArrayList al = new ArrayList(  );

al.add( "000" );

al.add( "111" );

al.add( "222" );

al.add( "333" );

al.subList( 3,4 ).clear( );                       // clear the range

System.out.println( al );  


■ Using ArrayList al from above again, the next statement creates and prints an array of just the two elements 222 and 333:


String[ ] a = ( String[ ] ) al.subList( 2,4 ).toArray( new String[ 4 - 2 ] );

System.out.println( Arrays.asList( a ));


■ Here's how to truncate a list to the end. Using ArrayList al again, this statement truncates everything in al after the second element.


 al.subList( 2, al.size( ) ).clear( );