+Show TOC
×Hide TOC

ListIterator

Kind of class:	public interface
Package:	com.bourre.collection
Inherits from:	Iterator
Implemented by:	ArrayIterator SetIterator StackIterator StringIterator
Author:	Cédric Néhémie
Classpath:	com.bourre.collection.ListIterator
File last modified:	Monday, 24 November 2008, 11:36:49

► View source

▼ Hide source

/*
 * Copyright the original author or authors.
 * 
 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.mozilla.org/MPL/MPL-1.1.html
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.bourre.collection
{
    
    /**
     * An iterator for lists that allows the programmer
     * to traverse the list in either direction, modify
     * the list during iteration, and obtain the iterator's
     * current position in the list. A <code>ListIterator</code
     * has no current element; its cursor position always lies
     * between the element that would be returned by a call
     * to <code>previous()</code> and the element that would
     * be returned by a call to <code>next()</code>. In a list
     * of length <code>n</code>, there are <code>n+1</code> valid
     * index values, from <code>0</code> to <code>n</code>, inclusive. 
     * <p>
     * Note that the <code>remove()</code> and <code>set(Object)</code>
     * methods are not defined in terms of the cursor position; they
     * are defined to operate on the last element returned by a call
     * to <code>next()</code> or <code>previous()</code>.
     * </p>
     * @author     C√©dric N√©h√©mie
     * @see        Iterator
     */
    public interface ListIterator 
        extends Iterator
    {
        /**
         * Inserts the specified element into the list (optional operation).
         * The element is inserted immediately before the next element that
         * would be returned by next, if any, and after the next element
         * that would be returned by previous, if any. (If the list contains
         * no elements, the new element becomes the sole element on the list.)
         * The new element is inserted before the implicit cursor: a subsequent
         * call to next would be unaffected, and a subsequent call to previous
         * would return the new element. (This call increases by one the value
         * that would be returned by a call to nextIndex  or previousIndex.)
         * 
         * @param    o    the element to insert.
         * @throws     <code>UnsupportedOperationException</code> ‚Äî if the set operation
         *             is not supported by this list iterator.
         * @throws     <code>ClassCastException</code> ‚Äî if the class of the specified
         *             element prevents it from being added to this list.
         * @throws     <code>IllegalArgumentException</code> ‚Äî if some aspect of the
         *             specified element prevents it from being added to this list.
         * @throws     <code>IllegalStateException</code> ‚Äî if neither next nor previous have
         *             been called, or remove or add have been called after
         *             the last call to next or previous.
         */
        function add ( o : Object ) : void;
        
        /**
         * Returns true if this list iterator has more elements when
         * traversing the list in the reverse direction. (In other words,
         * returns <code>true</code> if previous would return an element
         * rather than throwing an exception.)
         * 
         * @return     <code>true</code> if the list iterator has more elements when
         *             traversing the list in the reverse direction.
         */
        function hasPrevious () : Boolean;
        
        /**
         * Returns the index of the element that would be returned
         * by a subsequent call to next. (Returns list size if the
         * list iterator is at the end of the list.)
         * 
         * @return     the index of the element that would be returned
         *             by a subsequent call to next, or list size if list
         *             iterator is at end of list. 
         */
        function nextIndex () : uint;
        
        /**
         * Returns the previous element in the list. This method
         * may be called repeatedly to iterate through the list
         * backwards, or intermixed with calls to next to go back
         * and forth. (Note that alternating calls to next and
         * previous will return the same element repeatedly.)
         * 
         * @return     the previous element in the list.
         * @throws     <code>NoSuchElementException</code> ‚Äî if the iteration has no previous element.
         */
        function previous () : *;
        
        /**
         * Returns the index of the element that would be returned
         * by a subsequent call to previous. (Returns <code>-1</code>
         * if the list iterator is at the beginning of the list.)
         * 
         * @return    the index of the element that would be returned
         *             by a subsequent call to previous, or <code>-1</code>
         *             if list iterator is at beginning of list.
         */
        function previousIndex () : uint;
        
        /**
         * Replaces the last element returned by next or previous
         * with the specified element (optional operation).
         * This call can be made only if neither <code>ListIterator.remove</code>
         * nor <code>ListIterator.add</code> have been called after the last 
         * call to next or previous.
         * 
         * @param    o    the element with which to replace the last
         *                 element returned by next or previous.
         * @throws     <code>UnsupportedOperationException</code> ‚Äî if the set operation
         *             is not supported by this list iterator.
         * @throws     <code>ClassCastException</code> ‚Äî if the class of the specified
         *             element prevents it from being added to this list.
         * @throws     <code>IllegalArgumentException</code> ‚Äî if some aspect of the
         *             specified element prevents it from being added to this list.
         * @throws     <code>IllegalStateException</code> ‚Äî if neither next nor previous have
         *             been called, or remove or add have been called after
         *             the last call to next or previous.
         */
        function set ( o : Object ) : void;
    }
}

An iterator for lists that allows the programmer
to traverse the list in either direction, modify
the list during iteration, and obtain the iterator's
current position in the list. A

ListIterator</code

has no current element; its cursor position always lies

between the element that would be returned by a call

to <code>previous()

and the element that would
be returned by a call to next(). In a list
of length n, there are n+1 valid
index values, from 0 to n, inclusive.

Note that the remove() and set(Object)methods are not defined in terms of the cursor position; they
are defined to operate on the last element returned by a call
to next() or previous().

Summary

Instance methods

add (o:Object) : void
- Inserts the specified element into the list (optional operation).
hasPrevious : Boolean
- Returns true if this list iterator has more elements when
nextIndex : uint
- Returns the index of the element that would be returned
previous : *
- Returns the previous element in the list.
previousIndex : uint
- Returns the index of the element that would be returned
set (o:Object) : void
- Replaces the last element returned by next or previous

Instance methods inherited from Iterator

hasNext next remove

Instance methods

add

public function add (

o:Object) : void

Inserts the specified element into the list (optional operation).
The element is inserted immediately before the next element that
would be returned by next, if any, and after the next element
that would be returned by previous, if any. (If the list contains
no elements, the new element becomes the sole element on the list.)
The new element is inserted before the implicit cursor: a subsequent
call to next would be unaffected, and a subsequent call to previous
would return the new element. (This call increases by one the value
that would be returned by a call to nextIndex or previousIndex.)

Parameters:

the element to insert.

Throws:

{VISDOC_LINK_0}UnsupportedOperationException — if the set operation
is not supported by this list iterator.
{VISDOC_LINK_1}ClassCastException — if the class of the specified
element prevents it from being added to this list.
{VISDOC_LINK_2}IllegalArgumentException — if some aspect of the
specified element prevents it from being added to this list.
{VISDOC_LINK_3}IllegalStateException — if neither next nor previous have
been called, or remove or add have been called after
the last call to next or previous.

hasPrevious

public function hasPrevious (

) : Boolean

Returns true if this list iterator has more elements when
traversing the list in the reverse direction. (In other words,
returns true if previous would return an element
rather than throwing an exception.)

Returns:

true if the list iterator has more elements when
traversing the list in the reverse direction.

nextIndex

public function nextIndex (

) : uint

Returns the index of the element that would be returned
by a subsequent call to next. (Returns list size if the
list iterator is at the end of the list.)

Returns:

the index of the element that would be returned
by a subsequent call to next, or list size if list
iterator is at end of list.

public function previous (

) : *

Returns the previous element in the list. This method
may be called repeatedly to iterate through the list
backwards, or intermixed with calls to next to go back
and forth. (Note that alternating calls to next and
previous will return the same element repeatedly.)

Returns:

the previous element in the list.

Throws:

{VISDOC_LINK_0}NoSuchElementException — if the iteration has no previous element.

previousIndex

public function previousIndex (

) : uint

Returns the index of the element that would be returned
by a subsequent call to previous. (Returns -1if the list iterator is at the beginning of the list.)

Returns:

the index of the element that would be returned
by a subsequent call to previous, or -1 if list iterator is at beginning of list.

set

public function set (

o:Object) : void

Replaces the last element returned by next or previous
with the specified element (optional operation).
This call can be made only if neither ListIterator.removenor ListIterator.add have been called after the last
call to next or previous.

Parameters:

the element with which to replace the last
element returned by next or previous.

Throws:

{VISDOC_LINK_0}UnsupportedOperationException — if the set operation
is not supported by this list iterator.
{VISDOC_LINK_1}ClassCastException — if the class of the specified
element prevents it from being added to this list.
{VISDOC_LINK_2}IllegalArgumentException — if some aspect of the
specified element prevents it from being added to this list.
{VISDOC_LINK_3}IllegalStateException — if neither next nor previous have
been called, or remove or add have been called after
the last call to next or previous.