+Show TOC
×Hide TOC

Stack

Kind of class:	public class
Package:	com.bourre.collection
Inherits from:	none
Implements:	List TypedContainer
Author:	Romain Flacher, Cédric Néhémie
Classpath:	com.bourre.collection.Stack
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 
{
    import com.bourre.error.ClassCastException;
    import com.bourre.error.IllegalArgumentException;
    import com.bourre.error.IndexOutOfBoundsException;
    import com.bourre.error.NullPointerException;
    import com.bourre.log.PixlibDebug;
    import com.bourre.log.PixlibStringifier;    

    /**
     * The Stack class represents a last-in-first-out (LIFO) stack
     * of objects. The usual <code>push</code> and <code>pop</code>
     * operations are provided, as well as a method to <code>peek</code>
     * at the top item on the stack, a method to test for whether the stack
     * is empty, and a method to <code>search</code> the stack for an item
     * and discover how far it is from the top.
     * <p>
     * When a stack is first created, it contains no items.
     * </p>
     * @author Romain Flacher
     * @author C√©dric N√©h√©mie
     * @see List
     * @example Using a <code>Stack</code>
     * <listing>
     * var stack : Stack = new Stack ( Number );
     * stack.push( 20 );
     * 
     * try
     * {
     *     stack.push("20"); // fail, as "20" isn't a Number
     * }
     * catch( e : ClassCastException )
     * {
     *     trace( e );
     * }
     * </listing>
     */
    public class Stack implements List, TypedContainer
    {
        protected var _aStack     : Array;
        protected var _oType     : Class;
        
        /**
         * Create an empty Stack.
         * <p>
         * You can pass the type for stack elements as argument
         * of the constructor. In that case the stack is considered
         * as typed
         * </p> 
         * @param    type A <code>Class</code> instance used as type for elements
         * @throws     <code>ClassCastException</code> ‚Äî if the class of the specified
         *                elements prevents it from being added to this list.
         */
        public function Stack ( type : Class = null, content : Array = null )
        {
            _aStack = new Array ();
            _oType = type;

            if ( content )
            {
                var l : Number = content.length;
                for( var i : uint; i < l ; i++ ) add ( content[ i ] );
            }
        }
        
        
        /**
         * Appends the specified element to the end of this stack.
         * 
         * @param    o     element to be appended to this Stack
         * @return     <code>true</code> if this stack has changed as result
         *             of the call (as per the general contract of Collection.add).
         * @see        #push() push()
         * @throws     <code>ClassCastException</code> ‚Äî if the class of the specified
         *                element prevents it from being added to this list.
         * @example Adding elements to an untyped stack
         * <listing>
         * var stack : Stack = new Stack();
         * 
         * stack.add( 50 );
         * stack.add( "foo" );
         * 
         * trace( stack.add( "foo" ) ); // true, because stack allow one or more entries
         *                                 // for an element
         * 
         * trace( stack.size() ); // 3
         * </listing>
         * 
         * Adding elements to a typed stack
         * <listing>
         * var stack : Stack = new Stack( String );
         * 
         * stack.add( "foo" );
         * 
         * trace( stack.add( "foo" ) ); // true, because stack allow one or more occurrences
         *                                 // for an element
         *                                 
         * try
         * {
         *     stack.add( 50 ); // fail, as 50 is not a string
         * }
         * catch( e : ClassCastException )
         * {
         *     trace ( e );
         * }
         * 
         * trace( stack.size() ); // 2
         * </listing>
         */
        public function add ( o : Object ) : Boolean
        {
            push( o );
            return true;
        }

        /**
         * Inserts the specified element at the specified position
         * in this stack. Shifts the element currently at that
         * position (if any) and any subsequent elements to the
         * right (adds one to their indices).
         * 
         * @param    index     <code>uint</code> index at which the specified
         *                     element is to be inserted.
         * @param    o         element to be inserted.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî index is out of range
         *                (index < 0 || index > size()).
         * @throws     <code>ClassCastException</code> ‚Äî if the class of the specified
         *                element prevents it from being added to this list.
         * @see        #add() add()
         */
        public function addAt ( index : uint, o : Object ) : void
        {
            isValidIndex ( index );
            _aStack.splice( index, 0, o );
        } 

        /**
         * Appends all of the elements in the specified Collection
         * to the end of this stack, in the order that
         * they are returned by the specified Collection's Iterator. 
         * The behavior of this operation is undefined if the
         * specified Collection is modified while the operation
         * is in progress. (This implies that the behavior of this
         * call is undefined if the specified Collection is this
         * stack, and this stack is nonempty.)
         * <p>
         * The rules which govern collaboration between typed and untyped
         * <code>Collection</code> are described in the <code>isValidCollection</code>
         * descrition, all rules described there are supported by the
         * <code>containsAll</code> method.
         * </p>
         * @param    c     elements to be inserted into this stack.
         * @return     <code>true</code> if this stack changed as a result of the call.
         * @throws     <code>ClassCastException</code> ‚Äî if the class of an element of the specified
         *            collection prevents it from being added to this collection.
         * @throws     <code>NullPointerException</code> ‚Äî if the passed in collection is null.
         * @see        #add() add()
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         */
        public function addAll ( c : Collection ) : Boolean
        {
            isValidCollection( c );
            var iter : Iterator = c.iterator();
            var modified : Boolean = false;
            while ( iter.hasNext() ) modified = add( iter.next() ) || modified;
            return modified;
        }

        /**
         * Inserts all of the elements in the specified Collection into
         * this stack at the specified position. Shifts the element
         * currently at that position (if any) and any subsequent
         * elements to the right (increases their indices). The new
         * elements will appear in the stack in the order that
         * they are returned by the specified Collection's iterator.
         * <p>
         * The rules which govern collaboration between typed and untyped
         * <code>Collection</code> are described in the <code>isValidCollection</code>
         * descrition, all rules described there are supported by the
         * <code>containsAll</code> method.
         * </p>
         * @param     index     <code>uint</code> index at which to insert
         *                     first element from the specified collection.
         * @param     c         elements to be inserted into this stack.
         * @return     <code>true</code> if this stack changed as a result of the call.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî index is out of range
         *                (index < 0 || index > size()).
         * @throws     <code>ClassCastException</code> ‚Äî if the class of an element of
         *             the specified collection prevents it from being added to this collection.
         * @throws     <code>NullPointerException</code> ‚Äî if the passed in collection is null.
         * @see        #add() add()
         * @see        #addAt() addAt()
         * @see        #addAll() addAll()
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         */
        public function addAllAt ( index : uint, c : Collection ) : Boolean
        {
            isValidIndex ( index );
            isValidCollection( c );
            var i : Iterator = c.iterator();
            while (i.hasNext()) addAt ( index++, i.next() );
            return true;
        }

        /**
         * Removes a single instance of the specified element from this
         * stack, if this stack contains one or more such elements.
         * Returns <code>true</code> if this stack contained the specified
         * element (or equivalently, if this collection changed as a result
         * of the call).
         * <p>
         * In order to remove all occurences of an element you have to call
         * the <code>remove</code> method as long as the stack contains an
         * occurrence of the passed-in element. Typically, the construct to
         * remove all occurrences of an element should look like that :
         * <listing>
         * while( stack.contains( element ) ) stack.remove( element );
         * </listing>
         * </p><p>
         * If the current stack object is typed and if the passed-in object's  
         * type prevents it to be added (and then removed) in this stack,
         * the function throws a <code>ClassCastException</code>.
         * </p> 
         * @param    o     <code>object</code> to be removed from this stack,
         *                   if present.
         * @return     <code>true</code> if the stack contained the 
         *             specified element.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this stack
         * @example Using the <code>Stack.remove()</code> method with an untyped stack : 
         * <listing>
         * var stack : Stack = new Stack();
         * stack.add ( "foo" );
         * stack.add ( "foo" );
         * 
         * trace( stack.size() ); // 1
         * trace( stack.remove( "foo" ) ); // true, the first occurence of 'foo' have
         *                                    // been removed from the stack
         * 
         * trace( stack.size() ); // 1
         * trace( stack.remove( "foo" ) ); // true, the passed-in value has always
         *                                    // an occurence contained in the stack
         * 
         * trace( stack.size() ); // 0
         * trace( stack.remove( "foo" ) ); // false, as there is no more occurence
         *                                    // in the stack
         * </listing>
         * 
         * Using the <code>Stack.remove()</code> method with a typed stack :
         * 
         * <listing>
         * var stack : Stack = new Stack( String );
         * stack.add ( "foo" );
         * 
         * trace( stack.size() ); // 1
         * trace( stack.remove( "foo" ) ); // true, the passed-in value have been removed
         * 
         * // the code below will produce an exception
         * try
         * {
         *     stack.remove( 45 ); // fail, as the passed-in value is not of type string
         * }
         * catch( e : ClassCastException )
         * {
         *     trace ( e );  
         * }
         * </listing>
         */
        public function remove ( o : Object ) : Boolean
        {
            if ( isValidType( o ) && contains( o ) )
            {
                _aStack.splice( _aStack.indexOf( o ), 1 );
                return true;
            }

            return false;
        }

        /**
         * Removes the element at the specified position in this stack.
         * Shifts any subsequent elements to the right (subtracts one from
         * their indices).
         * 
         * @copy    com.bourre.collection.Stack#remove()
         * @param    index     <code>uint</code> index at which to remove an element
         *                       from the specified <code>Collection</code>.
         * @return     <code>true</code> if the object have been removed, false otherwise.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî The passed-in
         *             index is not a valid index for this stack
         * @see        #remove() remove()
         * @example Using the <code>Stack.removeAt</code> method with an untyped stack
         * <listing>
         * var stack : Stack = new Stack();
         * stack.add( "foo1" );
         * stack.add( "foo2" );
         * stack.add( "foo3" );
         * 
         * trace ( stack.removeAt( 2 ) ); // return true, 'foo3' have been removed
         * trace ( stack.removeAt( 0 ) ); // return true, 'foo1' have been removed  
         *                                 // and 'foo2' is now at index 0
         * 
         * try
         * {
         *     stack.removeAt( 1 ); // fail, as stack have only one entry at index 0
         * }
         * catch( e : IndexOutOfBoundsException )
         * {
         *     trace( e );
         * }
         * </listing>
         */
        public function removeAt ( index : uint ) : Boolean
        {
            isValidIndex ( index );
            _aStack.splice( index, 1 );
            return true;            
        }

        /**
         * Removes from this stack all of its elements that are contained
         * in the specified collection (optional operation). At the end
         * of the call there's no occurences of any elements contained
         * in the passed-in collection.
         * <p>
         * The rules which govern collaboration between typed and untyped
         * <code>Collection</code> are described in the <code>isValidCollection</code>
         * descrition, all rules described there are supported by the
         * <code>removeAll</code> method.
         * </p>
         * @param    c     <code>Collection</code> that defines which elements will be
         *                   removed from this stack.
         * @return     <code>true</code> if this stack changed as a result
         *             of the call.
         * @throws     <code>NullPointerException</code> ‚Äî if the specified collection is
         *          <code>null</code>.
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.    
         * @see        #remove() remove()
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         * @example Using the <code>Stack.removeAll()</code> with untyped stacks
         * <listing>
         * var stack1 : Stack = new Stack();
         * var stack2 : Stack = new Stack();
         * 
         * stack1.add( 1 );
         * stack1.add( 2 );
         * stack1.add( 3 );
         * stack1.add( 4 );
         * stack1.add( "foo1" );
         * stack1.add( "foo2" );
         * stack1.add( "foo3" );
         * stack1.add( "foo4" );
         * 
         * stack2.add( 1 );
         * stack2.add( 3 );
         * stack2.add( "foo1" );
         * stack2.add( "foo3" );
         * 
         * trace ( stack1.removeAll ( stack2 ) ) ;// true
         * // stack1 now contains :
         * // 2, 4, 'foo2', 'foo4' 
         * </listing>
         */
        public function removeAll ( c : Collection ) : Boolean
        {
            if( isValidCollection( c ) )
            {    
                var iter : Iterator = c.iterator();
                var find : Boolean = false;
                
                while(iter.hasNext( ))
                {
                    var o : * = iter.next();
                    while( this.contains( o ) ) find = this.remove( o ) || find;
                }
        
                return find;
            }

            return false;
        }

        /**
         * Retains only the elements in this stack that are contained
         * in the specified collection (optional operation). In other words,
         * removes from this stack all of its elements that are not
         * contained in the specified collection.
         * <p>
         * The rules which govern collaboration between typed and untyped <code>Collection</code>
         * are described in the <code>isValidCollection</code> descrition, all rules described
         * there are supported by the <code>retainAll</code> method.
         * </p>
         * @param    c     <code>Collection</code> that defines which elements this
         *                   stack will retain.
         * @return     <code>true</code> if this collection changed as a result of the
         *             call.
         * @throws     <code>NullPointerException</code> ‚Äî if the specified collection is
         *          <code>null</code>.
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.
         * @see     #remove() remove()
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         * @example Using the <code>Stack.retainAll()</code> with untyped stacks
         * <listing>
         * var stack1 : Stack = new Stack();
         * var stack2 : Stack = new Stack();
         * 
         * stack1.add( 1 );
         * stack1.add( 2 );
         * stack1.add( 3 );
         * stack1.add( 4 );
         * stack1.add( "foo1" );
         * stack1.add( "foo2" );
         * stack1.add( "foo3" );
         * stack1.add( "foo4" );
         * 
         * stack2.add( 1 );
         * stack2.add( 3 );
         * stack2.add( "foo1" );
         * stack2.add( "foo3" );
         * 
         * trace ( stack1.retainAll ( stack2 ) ) ;// true
         * // stack1 now contains :
         * // 1, 3, 'foo1', 'foo3' 
         * </listing>
         */
        public function retainAll ( c : Collection ) : Boolean
        {
            if ( isValidCollection( c ) )
            {
                var modified : Boolean = false;
                var fin : int = _aStack.length;
                var id : int = 0;

                while( id < fin )
                {
                    var obj : * = _aStack[id];
                    if( !c.contains( obj ) )
                    {
                        var fromIndex : int = 0;
                        while( true )
                        {
                            fromIndex = _aStack.indexOf( obj, fromIndex );
                            if ( fromIndex == -1 ) break;
                            modified = true;
                            _aStack.splice( fromIndex, 1 );
                            --fin;
                        }

                    } else
                    {
                        ++id;
                    }
                }

                return modified;
            }

            return false;
        }

        /**
         * Returns <code>true</code> if this stack contains at least
         * one occurence of the specified element. Moreformally,
         * returns <code>true</code> if and only if this stack contains
         * at least an element <code>e</code> such that <code>o === e</code>.
         *
         * @param    o    <code>Object</code> whose presence in this stack
         *                   is to be tested.
         * @return     <code>true</code> if this stack contains the specified
         *             element.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this stack
         */
        public function contains ( o : Object ) : Boolean
        {
            return _aStack.indexOf( o ) != -1;
        }

        /**
         * Returns true if this <code>Stack</code> contains all of the elements
         * in the specified Collection.
         * 
         * @param    c     a collection whose elements will be tested for
         *          containment in this <code>Stack</code>
         * @return    <code>true</code> if this <code>Stack</code> contains all of the elements
         *             in the specified collection.
         * @throws     <code>NullPointerException</code> ‚Äî if the passed in collection is null.
         */
        public function containsAll ( c : Collection ) : Boolean
        {
            if ( isValidCollection( c ) )
            {
                var iter : Iterator = c.iterator( );
                
                //if one element is not in this collection return false
                //else if all elements is in return true
                while( iter.hasNext( ) )
                {
                    if( !contains( iter.next( ) ) )
                        return false;
                }

                return true;
            }

            return false;
        }

        /**
         * Searches for the first occurence of the given argument.
         * 
         * @param    o     an object to search in the stack
         * @return    the index of the first occurrence of the object argument
         *                in this stack, that is, the smallest value <code>k</code>
         *                such that <code>(elem === elementData[k]) && (k >= index)</code>
         *                is true; returns <code>-1</code> if the object is not found.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this stack
         */
        public function search ( o : Object ) : int
        {
            return _aStack.indexOf( o );
        }        

        /**
         * Searches for the first occurence of the given argument.
         * 
         * @param    o     an object
         * @return    the index of the first occurrence of the object argument
         *                in this stack, that is, the smallest value <code>k</code>
         *                such that <code>(elem === elementData[k]) && (k >= index)</code>
         *                is true; returns <code>-1</code> if the object is not found.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this stack
         */
        public function indexOf ( o : Object ) : int
        {
            isValidType( o );
            return _aStack.indexOf(o);
        }

        /**
         * Returns the index of the last occurrence of the specified
         * object in this <code>Stack</code>.
         * 
         * @param     o    the desired component.
         * @return    the index of the first occurrence of the object argument
         *                in this stack, that is, the largest value <code>k</code>
         *                such that <code>(elem === elementData[k])</code> is true;
         *                returns <code>-1</code> if the object is not found.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this stack    
         */
        public function lastIndexOf ( o : Object ) : int
        {
            isValidType( o );
            return _aStack.lastIndexOf( o );
        }

        /**
         * Removes all of the elements from this <code>Stack</code>. 
         * The <code>Stack</code> will be empty after this call returns
         * (unless it throws an exception).
         */
        public function clear () : void
        {
            _aStack = new Array();
        }

        /**
         * Returns an iterator over the elements in this list
         * in proper sequence. The elements are returned according
         * to the LIFO order of the stack.
         * <p>
         * This implementation returns a straightforward implementation
         * of the iterator interface.
         * </p>
         * @return an iterator over the elements in this list in proper sequence.
         */
        public function iterator () : Iterator
        {
            return new StackIterator( this );
        }

        /**
         * Returns a list iterator of the elements in this list
         * (in proper sequence), starting at the specified position
         * in the list. The specified index indicates the first
         * element that would be returned by an initial call to
         * the next method. An initial call to the previous method
         * would return the element with the specified index minus one.
         * <p>
         * This implementation returns a straightforward implementation
         * of the ListIterator interface that extends the implementation
         * of the Iterator interface returned by the iterator() method.
         * The ListIterator implementation relies on the backing list's
         * <code>get(int)</code>, <code>set(int, Object)</code>, 
         * <code>add(int, Object)</code> and <code>remove(int)</code>
         * methods.
         * </p>
         * @param    index     <code>uint</code> index of the first element
         *                     to be returned from    the list iterator (by
         *                     a call to the next method).
         * @return     a list iterator of the elements in this list (in proper sequence),
         *             starting at the specified position in the list.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî index is out of range
         *                (index < 0 || index > size()).
         */
        public function listIterator ( index : uint = 0 ) : ListIterator
        {
            isValidIndex ( index );
            return new StackIterator ( this, index );
        }

        /**
         * Returns the number of components in this <code>Stack</code>.
         * 
         * @return the number of components in this <code>Stack</code>.
         */
        public function size () : uint
        {
            return _aStack.length;
        }

        /**
         * Returns the <code>Object</code> stored at the passed-in
         * <code>index</code> in this stack object.
         * <p>
         * If the passed-in <code>index</code> is not a valid index
         * for this stack, the function throw an 
         * <code>IndexOutOfBoundsException</code> exception.
         * </p> 
         * @param    index     <code>uint</code> index of the entry to get.
         * @return    <code>Object</code> stored at the specified <code>index</code>
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî The passed-in
         *             index is not a valid index for this stack
         */
        public function get ( index : uint ) : Object
        {
            isValidIndex ( index );
            return _aStack[ index ];
        }

        /**
         * Insert the passed-in <code>Object</code> in this stack
         * at the specified <code>index</code>. The method returns
         * the object previously stored at this index.
         * <p>
         * If the passed-in <code>index</code> is not a valid index
         * for this stack, the function throw an 
         * <code>IndexOutOfBoundsException</code> exception.
         * </p><p>
         * If the passed-in object's type prevents it to be added
         * in this stack the function will throw a 
         * <code>ClassCastException</code>.
         * </p>
         * @param    index     <code>uint</code> index at which insert the
         *                     passed-in <code>Object</code>.
         * @param    o        <code>Object</code> to insert in this stack
         * @return    <code>Object</code> previously stored at the specified
         *             <code>index</code> or null if the insertion haven't been 
         *             done.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî The passed-in
         *             index is not a valid index for this stack
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this stack    
         */
        public function set ( index : uint, o : Object ) : Object
        {
            isValidIndex ( index );
            
            if( isValidType( o ) )
            {
                return _aStack.splice( index, 1, o )[0];

            } else 
            {
                return false;
            }
        }

        /**
         * Looks at the object at the top of this stack
         * without removing it from the stack.
         * 
         * @return the object at the top of this stack
         *            (the last item of the object).
         */
        public function peek () : Object
        {
            return _aStack[ size() - 1 ];
        }

        /**
         * Removes the object at the top of this stack and returns
         * that object as the value of this function.
         * 
         * @return The object at the top of this stack
         *            (the last item of the <code>Stack</code> object).
         */
        public function pop () : Object
        {
            return _aStack.pop();
        }

        /**
         * Pushes an item onto the top of this stack. 
         * This has exactly the same effect as:
         * 
          * <listing>add(item)</listing>
         * @param    item the item to be pushed onto this stack..
         * @return     the item argument.
         * @see        #add() add()
         */
        public function push ( item : Object ) : Object
        {
            if( isValidType( item ) ) _aStack.push( item );
            return item;
        }

        /**
         * Returns a view of the portion of this List between fromIndex,
         * inclusive, and toIndex, exclusive. (If fromIndex and ToIndex
         * are equal, the returned List is empty.) 
         * 
         * @param     fromIndex     low endpoint (inclusive) of the subList.
         * @param    toIndex     high endpoint (exclusive) of the subList.
         * @return     a view of the specified range within this List.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî fromIndex or toIndex are
         *                out of range (index < 0 || index > size()).
         */
        public function subList ( fromIndex:uint, toIndex:uint ) : List
        {
            isValidIndex( fromIndex );
            isValidIndex( toIndex );
            var l : List = new Stack( getType() );
            for ( var i : Number = fromIndex; i < toIndex; i++ ) l.add( _aStack[ i ] );
            return l;
        }

        /**
         * Verify that the passed-in <code>uint</code> index is a
         * valid index for this </code>Stack</code>. If not, an 
         * <code>IndexOutOfBoundsException</code> exception is
         * thrown.
         *  
         * @param    index     <code>uint<code> index to verify
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî The passed-in
         *             index is not a valid index for this stack
         */
        public function isValidIndex ( index : uint ) : void
        {
            if ( index >= size( ) )
            {
                var msg : String = index + " is not a valid index for " + this + " of size " + size();
                PixlibDebug.ERROR( msg );
                throw new IndexOutOfBoundsException( msg );
            }
        }
        
        /**
         * Returns <code>true</code> if this stack contains no elements.
         *
         * @return <code>true</code> if this stack contains no elements.
         */
        public function isEmpty () : Boolean
        {
            return size() == 0;
        }
        
        /**
         * Verify that the passed-in <code>Collection</code> is a valid
         * collection for use with the <code>addAll</code>, <code>addAllAt</code>,
         * <code>removeAll</code>, <code>retainAll</code> and
         * <code>containsAll</code> methods.
         * <p>
         * When dealing with typed and untyped collection, the following rules apply : 
         * <ul>
         * <li>Two typed collection, which have the same type, can collaborate each other.</li>
         * <li>Two untyped collection can collaborate each other.</li>
         * <li>An untyped collection can add, remove, retain or contains any typed collection
         * of any type without throwing errors.</li>
         * <li>A typed collection will always fail when attempting to add, remove, retain
         * or contains an untyped collection.</li>
         * </ul></p><p>
         * If the passed-in <code>Collection</code> is null the method throw a
         * <code>NullPointerException</code> error.
         * </p>
         * 
         * @param    c <code>Collection</code> to verify
         * @return     boolean <code>true</code> if the collection is valid, 
         *             either <code>false</code>             
         * @throws     <code>NullPointerException</code> ‚Äî If the passed-in collection
         *             is <code>null</code>
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.
         * @see        #addAll() addAll()
         * @see        #removeAll() removeAll()
         * @see        #retainAll() retainAll()
         * @see        #containsAll() containsAll()
         */
        public function isValidCollection ( c : Collection ) : Boolean
        {
            if ( c == null ) 
            {
                var msg0 : String = "The passed-in collection is null in " + this;
                PixlibDebug.ERROR ( msg0 );
                throw new NullPointerException ( msg0 );

            } else if ( getType() != null )
            {
                if( c is TypedContainer && ( c as TypedContainer ).getType() != getType() )
                {
                    var msg1 : String = "The passed-in collection " + c + " is not of the same type than " + this;
                    PixlibDebug.ERROR ( msg1 );
                    throw new IllegalArgumentException ( msg1 );

                } else
                {
                    return true;
                }

            } else
            {
                return true;
            }
        }
                
        /**
         * Verify that the passed-in object type match the current 
         * <code>Stack</code> element's type. 
         * <p>
         * In the case that the stack is untyped the function
         * will always returns <code>true</code>.
         * </p><p>
         * In the case that the object's type prevents it to be added
         * as element for this stack the method will throw
         * a <code>ClassCastException</code>.
         * </p> 
         * @param    o <code>Object</code> to verify
         * @return  <code>true</code> if the object is elligible for this
         *             stack object, either <cod>false</code>.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this stack
         */
        public function isValidType ( o : Object ) : Boolean
        {
            if ( getType() != null)
            {
                if ( matchType( o ) )
                {
                    return true;

                } else
                {
                    var msg : String = o + " has a wrong type for " + this;
                    PixlibDebug.ERROR ( msg );
                    throw new ClassCastException ( msg ) ;
                }

            } else
            {
                return true;
            }
        }

        /**
         * Verify if the passed-in object can be inserted in the
         * current <code>Stack</code>.
         * 
         * @param    o    Object to verify
         * @return     <code>true</code> if the object can be inserted in
         * the <code>Stack</code>, either <code>false</code>.
         */
        public function matchType ( o : * ) : Boolean
        {
            return o is _oType;
        }

        /**
         * Returns <code>true</code> if this stack perform a verification
         * of the type of elements.
         * 
         * @return  <code>true</code> if this stack perform a verification
         *             of the type of elements.
         */
        public function isTyped () : Boolean
        {
            return _oType != null;
        }

        /**
         * Return the current type allowed in the <code>Stack</code>
         * 
         * @return <code>Class</code> used to type checking.
         */
        public function getType () : Class
        {
            return _oType;
        }

        /**
         * Returns an array containing all the elements in this stack.
         * Obeys the general contract of the <code>Collection.toArray</code>
         * method.
         *
         * @return  <code>Array</code> containing all of the elements
         *             in this stack.
         * @see        Collection#toArray() Collection.toArray()
         */
        public function toArray () : Array
        {
            return _aStack.concat();
        }

        /**
         * Returns the <code>String</code> representation of
         * this object. 
         * <p>
         * The function return a string like
         * <code>com.bourre.collection::Stack&lt;String&gt;</code>
         * for a typed collection. The string between the &lt;
         * and &gt; is the name of the type of the collection's
         * elements. If the collection is an untyped collection
         * the function will simply return the result of the
         * <code>PixlibStringifier.stringify</code> call.
         * </p>
         * @return <code>String</code> representation of
         *            this object.
         */
        public function toString () : String
        {
            var hasType : Boolean = getType() != null;
            var parameter : String = "";

            if ( hasType )
            {
                parameter = getType().toString();
                parameter = "<" + parameter.substr( 7, parameter.length - 8 ) + ">";
            }

            return PixlibStringifier.stringify( this ) + parameter;
        }
    }
}

import com.bourre.collection.ListIterator;
import com.bourre.collection.Stack;
import com.bourre.error.IllegalStateException;
import com.bourre.error.NoSuchElementException;
import com.bourre.log.PixlibDebug;

internal class StackIterator 
    implements ListIterator
{
    private var _c             : Stack;
    private var _nIndex     : int;
    private var _nLastIndex : int;
    private var _a             : Array;
    private var _bRemoved     : Boolean;
    private var _bAdded     : Boolean;

    public function StackIterator ( c : Stack, index : uint = 0 )
    {
        _c                 = c;
        _nIndex         = index - 1;
        _a                 = c.toArray( );
        _nLastIndex     = _a.length - 1;
        _bRemoved         = false;
        _bAdded         = false;
    }

    public function hasNext () : Boolean
    {
        return _nIndex + 1 <= _nLastIndex;
    }

    public function next () : *
    {
        if ( !hasNext() )
        {
            var msg : String = this + " has no more elements at " + ( _nIndex + 1 );
            PixlibDebug.ERROR ( msg );
            throw new NoSuchElementException ( msg );
        }
            
        _bRemoved = false;
        _bAdded = false;
        return _a[ ++_nIndex ];
    }
    
    public function previous () : *
    {
        if ( !hasPrevious() )
        {
            var msg : String = this + " has no more elements at " + ( _nIndex );
            PixlibDebug.ERROR ( msg );
            throw new NoSuchElementException ( msg );
        }
            
        _bRemoved = false;
        _bAdded = false;
        return _a[ _nIndex-- ];
    }

    public function remove () : void
    {
        if ( !_bRemoved )
        {
            _c.remove( _a[_nIndex--] );
            _a = _c.toArray( );
            _nLastIndex--;
            _bRemoved = true;

        } else
        {
            var msg : String = this + ".remove() have been already called for this iteration";
            PixlibDebug.ERROR ( msg );
            throw new IllegalStateException ( msg );
        }
    }

    public function add ( o : Object ) : void
    {
        if( !_bAdded )
        {
            _c.add( o );
            _a = _c.toArray( );
            _nLastIndex++;
            _bAdded = true;

        } else
        {
            var msg : String = this + ".add() have been already called for this iteration";
            PixlibDebug.ERROR ( msg );
            throw new IllegalStateException ( msg );
        }
    }        

    public function hasPrevious () : Boolean
    {
        return _nIndex >= 0;
    }    

    public function nextIndex () : uint
    {
        return _nIndex + 1;
    }

    public function previousIndex () : uint
    {
        return _nIndex;
    }    

    public function set ( o : Object ) : void
    {
        if( !_bAdded && !_bRemoved )
        {
            _c.set( _nIndex, o );

        } else
        {
            var msg : String = this + ".set() can't be called after neither a remove() nor an add() call";
            PixlibDebug.ERROR ( msg );
            throw new IllegalStateException ( msg );
        }
    }
}

The Stack class represents a last-in-first-out (LIFO) stack
of objects. The usual push and popoperations are provided, as well as a method to peekat the top item on the stack, a method to test for whether the stack
is empty, and a method to search the stack for an item
and discover how far it is from the top.

When a stack is first created, it contains no items.

See also:

List

Example:

Using a Stack
var stack : Stack = new Stack ( Number );
stack.push( 20 );

try
{
stack.push("20"); // fail, as "20" isn't a Number
}
catch( e : ClassCastException )
{
trace( e );
}

Summary

Constructor

Stack (type:Class = null, content:Array = null)
- Create an empty Stack.

Instance methods

add (o:Object) : Boolean
- Appends the specified element to the end of this stack.
addAt (index:uint, o:Object) : void
- Inserts the specified element at the specified position
addAll (c:Collection) : Boolean
- Appends all of the elements in the specified Collection
addAllAt (index:uint, c:Collection) : Boolean
- Inserts all of the elements in the specified Collection into
remove (o:Object) : Boolean
- Removes a single instance of the specified element from this
removeAt (index:uint) : Boolean
- Removes the element at the specified position in this stack.
removeAll (c:Collection) : Boolean
- Removes from this stack all of its elements that are contained
retainAll (c:Collection) : Boolean
- Retains only the elements in this stack that are contained
contains (o:Object) : Boolean
- Returns true if this stack contains at least
containsAll (c:Collection) : Boolean
- Returns true if this Stack contains all of the elements
search (o:Object) : int
- Searches for the first occurence of the given argument.
indexOf (o:Object) : int
- Searches for the first occurence of the given argument.
lastIndexOf (o:Object) : int
- Returns the index of the last occurrence of the specified
clear : void
- Removes all of the elements from this Stack.
iterator : Iterator
- Returns an iterator over the elements in this list
listIterator (index:uint = 0) : ListIterator
- Returns a list iterator of the elements in this list
size : uint
- Returns the number of components in this Stack.
get (index:uint) : Object
- Returns the Object stored at the passed-in
set (index:uint, o:Object) : Object
- Insert the passed-in Object in this stack
peek : Object
- Looks at the object at the top of this stack
pop : Object
- Removes the object at the top of this stack and returns
push (item:Object) : Object
- Pushes an item onto the top of this stack.
subList (fromIndex:uint, toIndex:uint) : List
- Returns a view of the portion of this List between fromIndex,
isValidIndex (index:uint) : void
- Verify that the passed-in uint index is a
isEmpty : Boolean
- Returns true if this stack contains no elements.
isValidCollection (c:Collection) : Boolean
- Verify that the passed-in Collection is a valid
isValidType (o:Object) : Boolean
- Verify that the passed-in object type match the current
matchType (o:*) : Boolean
- Verify if the passed-in object can be inserted in the
isTyped : Boolean
- Returns true if this stack perform a verification
getType : Class
- Return the current type allowed in the Stack
toArray : Array
- Returns an array containing all the elements in this stack.
toString : String
- Returns the String representation of

Constructor

Stack

public function Stack (

type:Class = null, content:Array = null)

Create an empty Stack.

You can pass the type for stack elements as argument
of the constructor. In that case the stack is considered
as typed

Parameters:

type:

A Class instance used as type for elements

Throws:

{VISDOC_LINK_0}ClassCastException — if the class of the specified
elements prevents it from being added to this list.

Instance methods

add

public function add (

o:Object) : Boolean

Appends the specified element to the end of this stack.

Parameters:

element to be appended to this Stack

Returns:

true if this stack has changed as result
of the call (as per the general contract of Collection.add).

See also:

push()

Throws:

{VISDOC_LINK_0}ClassCastException — if the class of the specified
element prevents it from being added to this list.

Example:

Adding elements to an untyped stack

var stack : Stack = new Stack();

stack.add( 50 );
stack.add( "foo" );

trace( stack.add( "foo" ) );

trace( stack.size() );

Adding elements to a typed stack

var stack : Stack = new Stack( String );

stack.add( "foo" );

trace( stack.add( "foo" ) );

try
{
stack.add( 50 );
}
catch( e : ClassCastException )
{
trace ( e );
}

trace( stack.size() );

Specified by:

Collection.add

addAll

public function addAll (

c:Collection) : Boolean

Appends all of the elements in the specified Collection
to the end of this stack, in the order that
they are returned by the specified Collection's Iterator.
The behavior of this operation is undefined if the
specified Collection is modified while the operation
is in progress. (This implies that the behavior of this
call is undefined if the specified Collection is this
stack, and this stack is nonempty.)

The rules which govern collaboration between typed and untyped

Collection are described in the isValidCollectiondescrition, all rules described there are supported by the

containsAll method.

Parameters:

elements to be inserted into this stack.

Returns:

true if this stack changed as a result of the call.

Throws:

{VISDOC_LINK_0}ClassCastException — if the class of an element of the specified
collection prevents it from being added to this collection.
{VISDOC_LINK_1}NullPointerException — if the passed in collection is null.

See also:

Specified by:

Collection.addAll

addAllAt

public function addAllAt (

index:uint, c:Collection) : Boolean

Inserts all of the elements in the specified Collection into
this stack at the specified position. Shifts the element
currently at that position (if any) and any subsequent
elements to the right (increases their indices). The new
elements will appear in the stack in the order that
they are returned by the specified Collection's iterator.

The rules which govern collaboration between typed and untyped

Collection are described in the isValidCollectiondescrition, all rules described there are supported by the

containsAll method.

Parameters:

index:

uint index at which to insert
first element from the specified collection.

c :

elements to be inserted into this stack.

Returns:

true if this stack changed as a result of the call.

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — index is out of range
(index < 0 || index > size()).
{VISDOC_LINK_1}ClassCastException — if the class of an element of
the specified collection prevents it from being added to this collection.
{VISDOC_LINK_2}NullPointerException — if the passed in collection is null.

See also:

Specified by:

List.addAllAt

addAt

public function addAt (

index:uint, o:Object) : void

Inserts the specified element at the specified position
in this stack. Shifts the element currently at that
position (if any) and any subsequent elements to the
right (adds one to their indices).

Parameters:

index:

uint index at which the specified
element is to be inserted.

o :

element to be inserted.

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — index is out of range
(index < 0 || index > size()).
{VISDOC_LINK_1}ClassCastException — if the class of the specified
element prevents it from being added to this list.

See also:

add()

Specified by:

List.addAt

clear

public function clear (

) : void

Removes all of the elements from this Stack.
The Stack will be empty after this call returns
(unless it throws an exception).

Throws:

{VISDOC_LINK_0}NullPointerException — if the null method is
not supported by this collection.
#

Specified by:

Collection.clear

contains

public function contains (

o:Object) : Boolean

Returns true if this stack contains at least
one occurence of the specified element. Moreformally,
returns true if and only if this stack contains
at least an element e such that o === e.

Parameters:

Object whose presence in this stack
is to be tested.

Returns:

true if this stack contains the specified
element.

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this stack

Specified by:

Collection.contains

containsAll

public function containsAll (

c:Collection) : Boolean

Returns true if this Stack contains all of the elements
in the specified Collection.

Parameters:

a collection whose elements will be tested for
containment in this Stack

Returns:

true if this Stack contains all of the elements
in the specified collection.

Throws:

{VISDOC_LINK_0}NullPointerException — if the passed in collection is null.

Specified by:

Collection.containsAll

get

public function get (

index:uint) : Object

Returns the Object stored at the passed-in

index in this stack object.

If the passed-in index is not a valid index
for this stack, the function throw an

IndexOutOfBoundsException exception.

Parameters:

index:

uint index of the entry to get.

Returns:

Object stored at the specified index

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — The passed-in
index is not a valid index for this stack

Specified by:

List.get

getType

public function getType (

) : Class

Return the current type allowed in the Stack

Returns:

Class used to type checking.

Specified by:

TypedContainer.getType

indexOf

public function indexOf (

o:Object) : int

Searches for the first occurence of the given argument.

Parameters:

an object

Returns:

the index of the first occurrence of the object argument
in this stack, that is, the smallest value k such that (elem === elementData[k]) && (k >= index) is true; returns -1 if the object is not found.

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this stack

Specified by:

List.indexOf

isEmpty

public function isEmpty (

) : Boolean

Returns true if this stack contains no elements.

Returns:

true if this stack contains no elements.

Specified by:

Collection.isEmpty

isTyped

public function isTyped (

) : Boolean

Returns true if this stack perform a verification
of the type of elements.

Returns:

true if this stack perform a verification
of the type of elements.

Specified by:

TypedContainer.isTyped

isValidCollection

public function isValidCollection (

c:Collection) : Boolean

Verify that the passed-in Collection is a valid
collection for use with the addAll, addAllAt,

removeAll, retainAll and

containsAll methods.

When dealing with typed and untyped collection, the following rules apply :

Two typed collection, which have the same type, can collaborate each other.
Two untyped collection can collaborate each other.
An untyped collection can add, remove, retain or contains any typed collection
of any type without throwing errors.
A typed collection will always fail when attempting to add, remove, retain
or contains an untyped collection.

If the passed-in Collection is null the method throw a

NullPointerException error.

Parameters:

Collection to verify

Returns:

boolean true if the collection is valid,
either false

Throws:

{VISDOC_LINK_0}NullPointerException — If the passed-in collection
is null
{VISDOC_LINK_1}IllegalArgumentException — If the passed-in collection
type is not the same that the current one.

See also:

isValidIndex

public function isValidIndex (

index:uint) : void

Verify that the passed-in uint index is a
valid index for this Stack. If not, an

IndexOutOfBoundsException exception is
thrown.

Parameters:

index:

uint<code> index to verify

@throws 	<code>IndexOutOfBoundsException

— The passed-in
index is not a valid index for this stack

isValidType

public function isValidType (

o:Object) : Boolean

Verify that the passed-in object type match the current

Stack element's type.

In the case that the stack is untyped the function
will always returns true.

In the case that the object's type prevents it to be added
as element for this stack the method will throw
a ClassCastException.

Parameters:

Object to verify

Returns:

true if the object is elligible for this
stack object, either false.

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this stack

iterator

public function iterator (

) : Iterator

Returns an iterator over the elements in this list
in proper sequence. The elements are returned according
to the LIFO order of the stack.

This implementation returns a straightforward implementation
of the iterator interface.

Returns:

an iterator over the elements in this list in proper sequence.

Specified by:

Iterable.iterator

lastIndexOf

public function lastIndexOf (

o:Object) : int

Returns the index of the last occurrence of the specified
object in this Stack.

Parameters:

the desired component.

Returns:

the index of the first occurrence of the object argument
in this stack, that is, the largest value k such that (elem === elementData[k]) is true;
returns -1 if the object is not found.

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this stack

Specified by:

List.lastIndexOf

listIterator

public function listIterator (

index:uint = 0) : ListIterator

Returns a list iterator of the elements in this list
(in proper sequence), starting at the specified position
in the list. The specified index indicates the first
element that would be returned by an initial call to
the next method. An initial call to the previous method
would return the element with the specified index minus one.

This implementation returns a straightforward implementation
of the ListIterator interface that extends the implementation
of the Iterator interface returned by the iterator() method.
The ListIterator implementation relies on the backing list's

get(int), set(int, Object),

add(int, Object) and remove(int)methods.

Parameters:

index:

uint index of the first element
to be returned from the list iterator (by
a call to the next method).

Returns:

a list iterator of the elements in this list (in proper sequence),
starting at the specified position in the list.

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — index is out of range
(index < 0 || index > size()).

Specified by:

List.listIterator

matchType

public function matchType (

o:*) : Boolean

Verify if the passed-in object can be inserted in the
current Stack.

Parameters:

Object to verify

Returns:

true if the object can be inserted in
the Stack, either false.

Specified by:

TypedContainer.matchType

peek

public function peek (

) : Object

Looks at the object at the top of this stack
without removing it from the stack.

Returns:

the object at the top of this stack
(the last item of the object).

pop

public function pop (

) : Object

Removes the object at the top of this stack and returns
that object as the value of this function.

Returns:

The object at the top of this stack
(the last item of the Stack object).

push

public function push (

item:Object) : Object

Pushes an item onto the top of this stack.
This has exactly the same effect as:

add(item)

Parameters:

item:

the item to be pushed onto this stack..

Returns:

the item argument.

See also:

add()

remove

public function remove (

o:Object) : Boolean

Removes a single instance of the specified element from this
stack, if this stack contains one or more such elements.
Returns true if this stack contained the specified
element (or equivalently, if this collection changed as a result
of the call).

In order to remove all occurences of an element you have to call
the remove method as long as the stack contains an
occurrence of the passed-in element. Typically, the construct to
remove all occurrences of an element should look like that :

while( stack.contains( element ) ) stack.remove( element );

If the current stack object is typed and if the passed-in object's
type prevents it to be added (and then removed) in this stack,
the function throws a ClassCastException.

Parameters:

object to be removed from this stack,
if present.

Returns:

true if the stack contained the
specified element.

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this stack

Example:

Using the Stack.remove() method with an untyped stack :

var stack : Stack = new Stack();
stack.add ( "foo" );
stack.add ( "foo" );

trace( stack.size() );
trace( stack.remove( "foo" ) );

trace( stack.size() );
trace( stack.remove( "foo" ) );

trace( stack.size() );
trace( stack.remove( "foo" ) );

Using the Stack.remove() method with a typed stack :

var stack : Stack = new Stack( String );
stack.add ( "foo" );

trace( stack.size() );
trace( stack.remove( "foo" ) );

try
{
stack.remove( 45 );
}
catch( e : ClassCastException )
{
trace ( e );
}

Specified by:

Collection.remove

removeAll

public function removeAll (

c:Collection) : Boolean

Removes from this stack all of its elements that are contained
in the specified collection (optional operation). At the end
of the call there's no occurences of any elements contained
in the passed-in collection.

The rules which govern collaboration between typed and untyped

Collection are described in the isValidCollectiondescrition, all rules described there are supported by the

removeAll method.

Parameters:

Collection that defines which elements will be
removed from this stack.

Returns:

true if this stack changed as a result
of the call.

Throws:

{VISDOC_LINK_0}NullPointerException — if the specified collection is
null.
{VISDOC_LINK_1}IllegalArgumentException — If the passed-in collection
type is not the same that the current one.

See also:

Example:

Using the Stack.removeAll() with untyped stacks

var stack1 : Stack = new Stack();
var stack2 : Stack = new Stack();

stack1.add( 1 );
stack1.add( 2 );
stack1.add( 3 );
stack1.add( 4 );
stack1.add( "foo1" );
stack1.add( "foo2" );
stack1.add( "foo3" );
stack1.add( "foo4" );

stack2.add( 1 );
stack2.add( 3 );
stack2.add( "foo1" );
stack2.add( "foo3" );

trace ( stack1.removeAll ( stack2 ) ) ;

Specified by:

Collection.removeAll

removeAt

public function removeAt (

index:uint) : Boolean

Removes the element at the specified position in this stack.
Shifts any subsequent elements to the right (subtracts one from
their indices).
@copy com.bourre.collection.Stack#remove()

Parameters:

index:

uint index at which to remove an element
from the specified Collection.

Returns:

true if the object have been removed, false otherwise.

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — The passed-in
index is not a valid index for this stack

See also:

remove()

Example:

Using the Stack.removeAt method with an untyped stack

var stack : Stack = new Stack();
stack.add( "foo1" );
stack.add( "foo2" );
stack.add( "foo3" );

trace ( stack.removeAt( 2 ) );
trace ( stack.removeAt( 0 ) );

try
{
stack.removeAt( 1 );
}
catch( e : IndexOutOfBoundsException )
{
trace( e );
}

Specified by:

List.removeAt

retainAll

public function retainAll (

c:Collection) : Boolean

Retains only the elements in this stack that are contained
in the specified collection (optional operation). In other words,
removes from this stack all of its elements that are not
contained in the specified collection.

The rules which govern collaboration between typed and untyped Collectionare described in the isValidCollection descrition, all rules described
there are supported by the retainAll method.

Parameters:

Collection that defines which elements this
stack will retain.

Returns:

true if this collection changed as a result of the
call.

Throws:

{VISDOC_LINK_0}NullPointerException — if the specified collection is
null.
{VISDOC_LINK_1}IllegalArgumentException — If the passed-in collection
type is not the same that the current one.

See also:

Example:

Using the Stack.retainAll() with untyped stacks

var stack1 : Stack = new Stack();
var stack2 : Stack = new Stack();

stack1.add( 1 );
stack1.add( 2 );
stack1.add( 3 );
stack1.add( 4 );
stack1.add( "foo1" );
stack1.add( "foo2" );
stack1.add( "foo3" );
stack1.add( "foo4" );

stack2.add( 1 );
stack2.add( 3 );
stack2.add( "foo1" );
stack2.add( "foo3" );

trace ( stack1.retainAll ( stack2 ) ) ;

Specified by:

Collection.retainAll

search

public function search (

o:Object) : int

Searches for the first occurence of the given argument.

Parameters:

an object to search in the stack

Returns:

the index of the first occurrence of the object argument
in this stack, that is, the smallest value k such that (elem === elementData[k]) && (k >= index) is true; returns -1 if the object is not found.

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this stack

set

public function set (

index:uint, o:Object) : Object

Insert the passed-in Object in this stack
at the specified index. The method returns
the object previously stored at this index.

If the passed-in index is not a valid index
for this stack, the function throw an

IndexOutOfBoundsException exception.

If the passed-in object's type prevents it to be added
in this stack the function will throw a

ClassCastException.

Parameters:

index:

uint index at which insert the
passed-in Object.

o :

Object to insert in this stack

Returns:

Object previously stored at the specified
index or null if the insertion haven't been
done.

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — The passed-in
index is not a valid index for this stack
{VISDOC_LINK_1}ClassCastException — If the object's type
prevents it to be added into this stack

Specified by:

List.set

size

public function size (

) : uint

Returns the number of components in this Stack.

Returns:

the number of components in this Stack.

Specified by:

Collection.size

subList

public function subList (

fromIndex:uint, toIndex:uint) : List

Returns a view of the portion of this List between fromIndex,
inclusive, and toIndex, exclusive. (If fromIndex and ToIndex
are equal, the returned List is empty.)

Parameters:

fromIndex:

low endpoint (inclusive) of the subList.

toIndex :

high endpoint (exclusive) of the subList.

Returns:

a view of the specified range within this List.

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — fromIndex or toIndex are
out of range (index < 0 || index > size()).

Specified by:

List.subList

toArray

public function toArray (

) : Array

Returns an array containing all the elements in this stack.
Obeys the general contract of the Collection.toArraymethod.

Returns:

Array containing all of the elements
in this stack.

See also:

Collection.toArray()

Specified by:

Collection.toArray

toString

public function toString (

) : String

Returns the String representation of
this object.

The function return a string like

com.bourre.collection::Stack<String>for a typed collection. The string between the <
and > is the name of the type of the collection's
elements. If the collection is an untyped collection
the function will simply return the result of the

PixlibStringifier.stringify call.

Returns:

String representation of
this object.