+Show TOC
×Hide TOC

Set

Kind of class:	public class
Package:	com.bourre.collection
Inherits from:	none
Implements:	List TypedContainer
Author:	Olympe Dignat, Cédric Néhémie
Classpath:	com.bourre.collection.Set
File last modified:	Monday, 24 November 2008, 11:36:50

► 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;    

    /**
     * A collection that contains no duplicate elements. More formally, sets
     * contain no pair of elements <code>e1</code> and <code>e2</code> such that
     * <code>e1 === e2</code>, and at most one null element. As implied by
     * its name, this interface models the mathematical <i>set</i> abstraction.
     * <p>
     * The <code>Set</code> class places additional stipulations, beyond those
     * inherited from the <code>Collection</code> interface, on the contracts of the
     * constructor and on the contracts of the <code>add</code> method. 
     * Declarations for other inherited methods are also included here for convenience.
     * (The specifications accompanying these declarations have been tailored to the
     * <code>Set</code> class, but they do not contain any additional stipulations.)
     * </p><p>
     * The additional stipulation on constructors is, not surprisingly,
     * that all constructors must create a set that contains no duplicate elements
     * (as defined above).
     * </p><p>
     * Some set implementations have restrictions on the elements that
     * they may contain.  For example, some implementations prohibit null elements,
     * and some have restrictions on the types of their elements.  Attempting to
     * add an ineligible element throws an unchecked exception, typically
     * <code>NullPointerException</code> or <code>ClassCastException</code>. 
     * Attempting to query the presence of an ineligible element may throw an exception,
     * or it may simply return false; some implementations will exhibit the former
     * behavior and some will exhibit the latter. More generally, attempting an
     * operation on an ineligible element whose completion would not result in
     * the insertion of an ineligible element into the set may throw an
     * exception or it may succeed, at the option of the implementation.
     * Such exceptions are marked as "optional" in the specification for this
     * class. 
     * </p>
     * @author  Olympe Dignat
     * @author     C√©dric N√©h√©mie
     * @see     Collection
     * @see        TypedContainer
     * @example Using an untyped <code>Set</code>
     * <listing>
     * var set : Set = new Set();
     * 
     * set.add( "foo" );
     * set.add( 25 );
     * 
     * trace ( set.add( 25 ) ) // false, as the object already exist in this set
     * 
     * set.add( false );
     * 
     * trace( set.size() ); // 3
     * </listing>
     * 
     * Using a typed <code>Set</code>
     * <listing>
     * var set : Set = new Set( String );
     * 
     * set.add( "foo" );
     * 
     * try
     * {
     *     set.add( 25 ); // throw an error, as 25 is not a String
     * }
     * catch( e : Error ) {}
     * 
     * trace ( set.add( "foo" ); ) // false, as the object already exist in this set
     * 
     * set.add( "hello" );
     * 
     * trace( set.size() ); // 2
     * </listing>
     */    
    public class Set 
        implements List, TypedContainer
    {
        protected var _aSet     : Array;
        protected var _oType     : Class;

        /**
         * Creates a new set object. If the <code>type</code>
         * argument is defined, the set is considered as typed, and then
         * the type of all elements inserted in this set is checked.
         * 
         * @param    type <code>Class</code> type for elements of this set
         */
        public function Set ( type : Class = null )
        {
            this._aSet = new Array( );
            _oType = type;
        }

        /**
         * Adds the specified element to this set if it is not already 
         * present (optional operation).  More formally, adds the specified
         * element, <code>o</code>, to this set if this set contains no
         * element <code>e</code> such that <code>o === e</code>. If this set
         * already contains the specified element, the call leaves this set
         * unchanged and returns <code>false</code>. In combination with the
         * restriction on constructors, this ensures that sets never contain
         * duplicate elements.
         * <p>
         * The stipulation above does not imply that sets must accept all
         * elements; sets may refuse to add any particular element, including
         * <code>null</code>, and throwing an exception, as described in the
         * specification for <code>Collection.add</code>. Individual set
         * implementations should clearly document any restrictions on the the
         * elements that they may contain.
         * </p>
         * @param    o    element to be added to this set.
         * @return     <code>true</code> if this set did not already contain the specified
         *             element.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this set
         * @example How to use the <code>Set.add</code> method
         * <listing>
         * var set : Set = new Set( String );
         * 
         * set.add( "foo" );
         * 
         * set.add( "foo" ); // return false, as 'foo' already exist in this set
         * 
         * set.add( 25 ); // throw a ClassCastException, as 25 is not a string 
         * </listing>
         * 
         * In comparison with Java, where object which have all of their properties
         * equals are considered as equals, AS3 doesn't allow that, except if objects
         * provides an <code>equals</code> method which is used instead of the 
         * <code>==</code> or <code>===</code> operators. Nevertheless, the <code>Set</code>
         * class use the native operator to perform comparison, thus two objects with
         * equals properties are considered as differents.
         * 
         * <listing>
         * var set : Set = new Set( Object );
         * var o : Object = { x : 50, y : 100 };
         * 
         * set.add( o ); 
         * set.add( o ); // return false, as o' already exist in this set
         * 
         * set.add( { x : 50, y : 100 } ); // return true, as the argument is not
         *                                    // the same object than o, even if all
         *                                    // their properties are equals
         * </listing>
         */
        public function add ( o : Object ) : Boolean
        {
            if( isValidObject( o ) )
            {
                _aSet.splice( _aSet.length, 0, o );
                return true ;

            } else
            {
                return false ;
            }                
        }

        /**
         * Inserts the specified element at the specified position
         * in this set. 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
        {
            isValidIndexForAdd( index );
            if( isValidObject( o ) ) _aSet.splice( index, 0, o );
        }

        /**
         * Adds all of the elements in the specified <code>Collection</code> 
         * to this set if they're not already present (optional operation).
         * If the specified collection is also a set, the <code>addAll</code>
         * operation effectively modifies this set so that its value is the 
         * <i>union</i> of the two sets. The behavior of this operation is
         * unspecified if the specified collection is modified while the
         * operation is in progress.
         * <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>addAll</code> method.
         * </p>
         * @param    c     <code>Collection</code> whose elements are to be added to this set.
         * @return     <code>true</code> if this set changed as a result of the call.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this set
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.    
         * @see     #add() add()
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         * @example    How the <code>Set.addAll</code> method works with types 
         * <p>
         * Let say that you have two typed sets <code>typedSet1</code>
         * and <code>typedSet1</code>.
         * </p> 
         * <listing>
         * var typedSet1 : Set = new Set( String );
         * var typedSet2 : Set = new Set( String );
         * 
         * typedSet1.add( "foo1" );
         * typedSet1.add( "foo2" );
         * typedSet1.add( "foo3" );
         * typedSet1.add( "foo4" );
         * 
         * typedSet2.add( "foo3" );
         * typedSet2.add( "foo4" );
         * typedSet2.add( "foo5" );
         * typedSet2.add( "foo6" );
         * </listing>
         * 
         * And two untyped sets <code>untypedSet1</code>
         * and <code>untypedSet1</code>. 
         * 
         * <listing>
         * var untypedSet1 : Set = new Set();
         * var untypedSet2 : Set = new Set();
         * 
         * untypedSet1.add( 1 );
         * untypedSet1.add( 2 );
         * untypedSet1.add( 3 );
         * untypedSet1.add( "foo1" );
         * 
         * untypedSet1.add( 3 );
         * untypedSet1.add( 4 );
         * untypedSet1.add( 5 );
         * untypedSet1.add( "foo1" );
         * </listing>
         * 
         * The two operations below will work as expected, 
         * realizing an union between <code>Set</code>s objects.
         * 
         * <listing>
         * 
         * typedSet1.addAll ( typedSet2 );
         * // will produce a set containing : 
         * // 'foo1'
         * // 'foo2'
         * // 'foo3'
         * // 'foo4'
         * // 'foo5'
         * // 'foo6'
         * 
         * untypedSet1.addAll ( untypedSet2 );
         * // will produce a set containing : 
         * // 'foo1'
         * // 1
         * // 2
         * // 3
         * // 4
         * // 5
         * </listing>
         * 
         * As an untyped set can contain any types of objects at the
         * same time, the code below is always valid.
         * 
         * <listing>
         * untypedSet1.addAll( typedSet2 );
         * // will produce a set containing : 
         * // 'foo1'
         * // 'foo3'
         * // 'foo4'
         * // 'foo5'
         * // 'foo6'
         * // 1
         * // 2
         * // 3
         * // 4
         * // 5
         * </listing>
         * 
         * But if you try to add an untyped collection to a typed one
         * the call will fail with an exception.
         * 
         * <listing>
         * try
         * {
         *     typedSet2.addAll( untypedSet2 );
         * }
         * catch( e : IllegalArgumentException )
         * {
         *     trace( e ); 
         *     // The passed-in collection with type 'null' has not the same type 
         *     // than com.bourre.collections::Set&lt;String&gt;
         * }
         * </listing>
         */
        public function addAll (c : Collection) : Boolean
        {
            var modified : Boolean = false;

            if ( isValidCollection( c ) )
            {
                var iter : Iterator = c.iterator( );
                while( iter.hasNext() ) modified = add( iter.next() ) || modified;
            }

            return modified;
        }
        
        /**
         * Inserts all of the elements in the specified Collection into
         * this set 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 set 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
        {
            isValidIndexForAdd( index );
            isValidCollection( c );
            
            var i : Iterator = c.iterator();
            while( i.hasNext() ) addAt( index++, i.next() );
            return true;
        }

        /**
         * Removes the specified element from this set
         * if it is present (optional operation). More formally,
         * removes an element <code>e</code> such that
         * <code>o === e</code>, if the set contains
         * such an element. Returns <code>true</code> if the set
         * contained the specified element (or equivalently, if the
         * set changed as a result of the call). 
         * (The set will not contain the specified element
         * once the call returns.)
         *
         * @param    o     <code>object</code> to be removed from this <code>Set</code>,
         *                 if present.
         * @return     <code>true</code> if the set contained the specified element.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this set
         * @example    Using the <code>Set.remove()</code> method of an untyped set : 
         * <listing>
         * var set : Set = new Set();
         * set.add ( "foo" );
         * 
         * trace( set.size() ); // 1
         * trace( set.remove( "foo" ) ); // true, the passed-in value have been removed
         * 
         * trace( set.size() ); // 0
         * trace( set.remove( "foo" ) ); // false, the passed-in value is no longer stored in this set
         * </listing>
         * 
         * Using the <code>Set.remove()</code> method of a typed set :
         * 
         * <listing>
         * var set : Set = new Set( String );
         * set.add ( "foo" );
         * 
         * trace( set.size() ); // 1
         * trace( set.remove( "foo" ) ); // true, the passed-in value have been removed
         * 
         * // the code below will produce an exception
         * try
         * {
         *     set.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
        {
            var find : Boolean = false;

            if ( isValidType( o ) && contains( o ) )
            {
                _aSet.splice( _aSet.indexOf( o ), 1 );
                find = true ;
            }

            return find;
        }

        /**
         * Removes the element at the specified position in this set.
         * Shifts any subsequent elements to the right (subtracts one from
         * their indices).
         * 
         * @copy    com.bourre.collection.Set#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 set
         * @see        #remove() remove()
         * @example Using the <code>Set.removeAt</code> method with an untyped set
         * <listing>
         * var set : Set = new Set();
         * set.add( "foo1" );
         * set.add( "foo2" );
         * set.add( "foo3" );
         * 
         * trace ( set.removeAt( 2 ) ); // return true, 'foo3' have been removed
         * trace ( set.removeAt( 0 ) ); // return true, 'foo1' have been removed  
         *                                 // and 'foo2' is now at index 0
         * 
         * try
         * {
         *     set.removeAt( 1 ); // fail, as set have only one entry at index 0
         * }
         * catch( e : IndexOutOfBoundsException )
         * {
         *     trace( e );
         * }
         * </listing>
         */
        public function removeAt ( index : uint ) : Boolean
        {
            isValidIndex( index );
            _aSet.splice( index, 1 );
            return true;            
        }

        /**
         * Removes from this set all of its elements that are contained
         * in the specified collection (optional operation). If the specified
         * <code>Collection</code> is also a <code>Set</code>, this operation
         * effectively modifies this set so that its value is the
         * <i>asymmetric set difference</i> of the two sets.
         * <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 set.
         * @return     <code>true</code> if this set 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>Set.removeAll()</code> with untyped sets
         * <listing>
         * var set1 : Set = new Set();
         * var set2 : Set = new Set();
         * 
         * set1.add( 1 );
         * set1.add( 2 );
         * set1.add( 3 );
         * set1.add( 4 );
         * set1.add( "foo1" );
         * set1.add( "foo2" );
         * set1.add( "foo3" );
         * set1.add( "foo4" );
         * 
         * set2.add( 1 );
         * set2.add( 3 );
         * set2.add( "foo1" );
         * set2.add( "foo3" );
         * 
         * trace ( set1.removeAll ( set2 ) ) ;// true
         * // set1 now contains :
         * // 2, 4, 'foo2', 'foo4' 
         * </listing>
         */
        public function removeAll ( c : Collection ) : Boolean
        {
            var find : Boolean = false;

            if ( isValidCollection( c ) )
            {
                var iter : Iterator = c.iterator( );
                while( iter.hasNext( ) ) find = remove( iter.next( ) ) || find;
            }

            return find;
        }

        /**
         * Retains only the elements in this set that are contained
         * in the specified collection (optional operation).  In other words,
         * removes from this set all of its elements that are not
         * contained in the specified collection.  If the specified collection
         * is also a <code>Set</code>, this operation effectively modifies this
         * set so that its value is the <i>intersection</i> of the
         * two sets.
         * <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
         *                   set 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>Set.retainAll()</code> with untyped sets
         * <listing>
         * var set1 : Set = new Set();
         * var set2 : Set = new Set();
         * 
         * set1.add( 1 );
         * set1.add( 2 );
         * set1.add( 3 );
         * set1.add( 4 );
         * set1.add( "foo1" );
         * set1.add( "foo2" );
         * set1.add( "foo3" );
         * set1.add( "foo4" );
         * 
         * set2.add( 1 );
         * set2.add( 3 );
         * set2.add( "foo1" );
         * set2.add( "foo3" );
         * 
         * trace ( set1.retainAll ( set2 ) ) ;// true
         * // set1 now contains :
         * // 1, 3, 'foo1', 'foo3' 
         * </listing>
         */
        public function retainAll (c : Collection) : Boolean
        {
            var b : Boolean = false;

            if ( isValidCollection( c ) )
            {
                var i : Iterator = iterator( );
                while( i.hasNext( ) )
                {
                    var o : Object = i.next( );    
                    if ( !( c.contains( o ) ) ) b = remove( o ) || b;
                }
            }

            return b;
        }

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

            } else
            {
                return false;
            }
        }

        /**
         * Returns <code>true</code> if this set contains
         * all of the elements of the specified collection. If the specified
         * collection is also a <code>Set</code>, this method returns <code>true</code>
         * if it is a <i>subset</i> of this set.
         * <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    <code>Collection</code> to be checked for containment in this set.
         * @return     <code>true</code> if this set contains all of the elements of the
         *                specified collection.
         * @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        #contains() contains()
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         */
        public function containsAll (c : Collection) : Boolean
        {
            var b : Boolean = true ;
            
            if ( isValidCollection( c ) )
            {
                var iter : Iterator = c.iterator( );
                while( iter.hasNext( ) )
                {
                    var ok : Boolean = contains( iter.next( ) ) ;
                    if( ok == false )  b = false;
                }

            } else
            {
                b = false ;
            }

            return b;
        }

        /**
         * Compares the specified object with this set for equality.
         * Returns <code>true</code> if the specified object is also a <code>Set</code>,
         * the two sets have the same size, and every member of the specified
         * <code>Set</code> is contained in this set (or equivalently,
         * every member of this set is contained in the specified
         * set). This definition ensures that the equals method works
         * properly across different implementations of the set class.
         *
         * @param    o     <code>Object</code> to be compared for equality with this
         *                   set.
         * @return     <code>true</code> if the specified Object is equal to this
         *             set.
         */
        public function equals ( o : Object ) : Boolean
        {
            if ( o is Set )
            {
                var _set : Set = o as Set;

                if ( _set.size( ) == size( ) )
                {
                    return containsAll( _set ) ;

                } else
                {
                    return false;
                }

            } else
            {
                return false;
            }
        }

        /**
         * Returns the index of the object in this set         
         * 
         * @param    o     the object to find
         * @return     <code>int</code> index of the passed object in this
         *             set, either if the object isn't contained
         *             in this set the function return <code>-1</code>
         * @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 _aSet.indexOf( o );
        }
        
        /**
         * Returns the index of the last occurrence of the specified
         * object in this <code>Set</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 _aSet.lastIndexOf( o );
        }

        /**
         * Removes all of the elements from this set
         * (optional operation). This set will be empty
         * after this call returns (unless it throws an exception).
         */
        public function clear () : void
        {
            _aSet = new Array( );
        }

        /**
         * Returns an iterator over the elements in this set. 
         * The elements are returned in no particular order (unless this
         * set is an instance of some class that provides
         * a guarantee).
         *
         * @return an iterator over the elements in this set.
         */
        public function iterator () : Iterator
        {
            return new SetIterator( 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 SetIterator ( this, index );
        }
        
         /**
         * 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( _aSet[ i ] );

            return l;
        }

        /**
         * Returns the number of elements in this set (its cardinality). 
         * 
         * @return <code>Number</code> of elements in this set (its cardinality).
         */
        public function size () : uint
        {
            return _aSet.length;
        }

        /**
         * Returns the <code>Object</code> stored at the passed-in
         * <code>index</code> in this set object.
         * <p>
         * If the passed-in <code>index</code> is not a valid index
         * for this set, 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 set
         */
        public function get ( index : uint ) : Object
        {
            isValidIndex( index );
            return _aSet[ index ];
        }

        /**
         * Insert the passed-in <code>Object</code> in this set
         * 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 set, the function throw an 
         * <code>IndexOutOfBoundsException</code> exception.
         * </p><p>
         * If the passed-in object's type prevents it to be added
         * in this set 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 set
         * @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 set
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this set    
         */
        public function set ( index : uint, o : Object ) : Object
        {
            isValidIndex( index );

            if ( isValidObject( o ) )
            {
                return _aSet.splice( index, 1, o )[0];

            } else
            {
                return null;
            }
        }

        /**
         * Verify that the passed-in <code>uint</code> index is a
         * valid index for this </code>Set</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 set
         */
        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 );
            }
        }
        /**
         * Verify that the passed-in <code>uint</code> index is a
         * valid index for an insertion in this </code>Set</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 set
         */
        public function isValidIndexForAdd ( index : uint ) : void
        {
            if ( index > size() )
            {
                var msg : String = index + " is not a valid index for insertion in " + this + " of size " + size();
                PixlibDebug.ERROR( msg );
                throw new IndexOutOfBoundsException( msg );
            }
        }

        /**
         * Verify that the passed-in <code>Collection</code> is a valid
         * collection for use with the <code>addAll</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 with type '" +  ( c as TypedContainer ).getType() + 
                                        "' has not the same type than" + this;
                    PixlibDebug.ERROR( msg1 );
                    throw new IllegalArgumentException( msg1 );

                } else
                {
                    return true;
                }

            } else
            {
                return true;
            }
        }

        /**
         * Verify that the passed-in object is valid for this <code>Set</code>
         * (well-typed, not already present in the set).
         * <p>
         * In the case that the object's type prevents it to be added
         * as element for this set the method will throw
         * a <code>ClassCastException</code>.
         * </p> 
         * @return     <code>true</code> if the object is valid
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this set
         */
        public function isValidObject (o : Object) : Boolean
        {
            if ( isValidType( o ) )
            {
                return ( !contains( o ) );

            } else
            {
                return false;
            }
        }

        /**
         * Verify that the passed-in object type match the current 
         * <code>Set</code> element's type. 
         * <p>
         * In the case that the set 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 set 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
         *             set object, either <cod>false</code>.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this set
         */
        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;
            }
        }

        /**
         * Returns <code>true</code> if this set contains no elements.
         *
         * @return <code>true</code> if this set contains no elements.
         */
        public function isEmpty () : Boolean
        {
            return size() == 0;
        }

        /**
         * Verify that the passed-in object type match the current 
         * set element's type. 
         * 
         * @return  <code>true</code> if the object is elligible for this
         *             set object, either <code>false</code>.
         */
        public function matchType ( o : * ) : Boolean
        {
            return o is _oType || o == null;
        }

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

        /**
         * Return the class type of element in this set object.
         * <p>
         * An untyped set returns <code>null</code>, as the
         * wildcard type (<code>*</code>) is not a <code>Class</code>
         * and <code>Object</code> class doesn't fit for primitive types.
         * </p>
         * @return <code>Class</code> type of the set's elements
         */
        public function getType () : Class
        {
            return _oType;
        }

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

        /**
        * Swap two objects stored in the passed-in index
        * <p>
        * If the passed-in <code>index</code> are not valid index
        * for this set, the function throw an 
        * <code>IndexOutOfBoundsException</code> exception.
        * </p><p>
        * </p>
        * @param index1 <code>uint</code> index of the first <code>Object</code>.
        * @param index2 <code>uint</code> index of the second <code>Object</code>.
        * @throws <code>IndexOutOfBoundsException</code> ‚Äî The passed-in
        * index are not valid index for this set
        */
        public function swap ( index1 : uint, index2 : uint ) : void
        {
            isValidIndex( index1 );
            isValidIndex( index2 );
            var save : Object = _aSet[ index1 ] ;
            _aSet[ index1 ] = _aSet[ index2 ] ;
            _aSet[ index2 ] = save ;
        }

        /**
         * Returns the <code>String</code> representation of
         * this object. 
         * <p>
         * The function return a string like
         * <code>com.bourre.collection::Set&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.Set;
import com.bourre.error.IllegalStateException;
import com.bourre.error.NoSuchElementException;
import com.bourre.log.PixlibDebug;

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

    public function SetIterator ( c : Set, 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 );
        }
    }
}

A collection that contains no duplicate elements. More formally, sets
contain no pair of elements e1 and e2 such that

e1 === e2, and at most one null element. As implied by
its name, this interface models the mathematical set abstraction.

The Set class places additional stipulations, beyond those
inherited from the Collection interface, on the contracts of the
constructor and on the contracts of the add method.
Declarations for other inherited methods are also included here for convenience.
(The specifications accompanying these declarations have been tailored to the

Set class, but they do not contain any additional stipulations.)

The additional stipulation on constructors is, not surprisingly,
that all constructors must create a set that contains no duplicate elements
(as defined above).

Some set implementations have restrictions on the elements that
they may contain. For example, some implementations prohibit null elements,
and some have restrictions on the types of their elements. Attempting to
add an ineligible element throws an unchecked exception, typically

NullPointerException or ClassCastException.
Attempting to query the presence of an ineligible element may throw an exception,
or it may simply return false; some implementations will exhibit the former
behavior and some will exhibit the latter. More generally, attempting an
operation on an ineligible element whose completion would not result in
the insertion of an ineligible element into the set may throw an
exception or it may succeed, at the option of the implementation.
Such exceptions are marked as "optional" in the specification for this
class.

See also:

Example:

Using an untyped Set
var set : Set = new Set();

set.add( "foo" );
set.add( 25 );

trace ( set.add( 25 ) ) // false, as the object already exist in this set

set.add( false );

trace( set.size() ); // 3

Using a typed Set
var set : Set = new Set( String );

set.add( "foo" );

try
{
set.add( 25 ); // throw an error, as 25 is not a String
}
catch( e : Error ) {}

trace ( set.add( "foo" ); ) // false, as the object already exist in this set

set.add( "hello" );

trace( set.size() ); // 2

Summary

Constructor

Set (type:Class = null)
- Creates a new set object.

Instance methods

add (o:Object) : Boolean
- Adds the specified element to this set if it is not already
addAt (index:uint, o:Object) : void
- Inserts the specified element at the specified position
addAll (c:Collection) : Boolean
- Adds 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 the specified element from this set
removeAt (index:uint) : Boolean
- Removes the element at the specified position in this set.
removeAll (c:Collection) : Boolean
- Removes from this set all of its elements that are contained
retainAll (c:Collection) : Boolean
- Retains only the elements in this set that are contained
contains (o:Object) : Boolean
- Returns true if this set contains the
containsAll (c:Collection) : Boolean
- Returns true if this set contains
equals (o:Object) : Boolean
- Compares the specified object with this set for equality.
indexOf (o:Object) : int
- Returns the index of the object in this set
lastIndexOf (o:Object) : int
- Returns the index of the last occurrence of the specified
clear : void
- Removes all of the elements from this set
iterator : Iterator
- Returns an iterator over the elements in this set.
listIterator (index:uint = 0) : ListIterator
- Returns a list iterator of the elements in this list
subList (fromIndex:uint, toIndex:uint) : List
- Returns a view of the portion of this List between fromIndex,
size : uint
- Returns the number of elements in this set (its cardinality).
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 set
isValidIndex (index:uint) : void
- Verify that the passed-in uint index is a
isValidIndexForAdd (index:uint) : void
- Verify that the passed-in uint index is a
isValidCollection (c:Collection) : Boolean
- Verify that the passed-in Collection is a valid
isValidObject (o:Object) : Boolean
- Verify that the passed-in object is valid for this Set(well-typed, not already present in the set).
isValidType (o:Object) : Boolean
- Verify that the passed-in object type match the current
isEmpty : Boolean
- Returns true if this set contains no elements.
matchType (o:*) : Boolean
- Verify that the passed-in object type match the current
isTyped : Boolean
- Returns true if this set perform a verification
getType : Class
- Return the class type of element in this set object.
toArray : Array
- Returns an array containing all the elements in this set.
swap (index1:uint, index2:uint) : void
- Swap two objects stored in the passed-in index
toString : String
- Returns the String representation of

Constructor

Set

public function Set (

type:Class = null)

Creates a new set object. If the typeargument is defined, the set is considered as typed, and then
the type of all elements inserted in this set is checked.

Parameters:

type:

Class type for elements of this set

Instance methods

add

public function add (

o:Object) : Boolean

Adds the specified element to this set if it is not already
present (optional operation). More formally, adds the specified
element, o, to this set if this set contains no
element e such that o === e. If this set
already contains the specified element, the call leaves this set
unchanged and returns false. In combination with the
restriction on constructors, this ensures that sets never contain
duplicate elements.

The stipulation above does not imply that sets must accept all
elements; sets may refuse to add any particular element, including

null, and throwing an exception, as described in the
specification for Collection.add. Individual set
implementations should clearly document any restrictions on the the
elements that they may contain.

Parameters:

element to be added to this set.

Returns:

true if this set did not already contain the specified
element.

Throws:

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

Example:

How to use the Set.add method

var set : Set = new Set( String );

set.add( "foo" );

set.add( "foo" );

set.add( 25 );

In comparison with Java, where object which have all of their properties
equals are considered as equals, AS3 doesn't allow that, except if objects
provides an equals method which is used instead of the

== or === operators. Nevertheless, the Setclass use the native operator to perform comparison, thus two objects with
equals properties are considered as differents.

var set : Set = new Set( Object );
var o : Object = { x : 50, y : 100 };

set.add( o );
set.add( o );

set.add( { x : 50, y : 100 } );

Specified by:

Collection.add

addAll

public function addAll (

c:Collection) : Boolean

Adds all of the elements in the specified Collection
to this set if they're not already present (optional operation).
If the specified collection is also a set, the addAlloperation effectively modifies this set so that its value is the
union of the two sets. The behavior of this operation is
unspecified if the specified collection is modified while the
operation is in progress.

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

Parameters:

Collection whose elements are to be added to this set.

Returns:

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

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this set
{VISDOC_LINK_1}IllegalArgumentException — If the passed-in collection
type is not the same that the current one.

See also:

Example:

How the Set.addAll method works with types
Let say that you have two typed sets typedSet1and typedSet1.

var typedSet1 : Set = new Set( String );
var typedSet2 : Set = new Set( String );

typedSet1.add( "foo1" );
typedSet1.add( "foo2" );
typedSet1.add( "foo3" );
typedSet1.add( "foo4" );

typedSet2.add( "foo3" );
typedSet2.add( "foo4" );
typedSet2.add( "foo5" );
typedSet2.add( "foo6" );

And two untyped sets untypedSet1and untypedSet1.

var untypedSet1 : Set = new Set();
var untypedSet2 : Set = new Set();

untypedSet1.add( 1 );
untypedSet1.add( 2 );
untypedSet1.add( 3 );
untypedSet1.add( "foo1" );

untypedSet1.add( 3 );
untypedSet1.add( 4 );
untypedSet1.add( 5 );
untypedSet1.add( "foo1" );

The two operations below will work as expected,
realizing an union between Sets objects.

typedSet1.addAll ( typedSet2 );

untypedSet1.addAll ( untypedSet2 );

As an untyped set can contain any types of objects at the
same time, the code below is always valid.

untypedSet1.addAll( typedSet2 );

But if you try to add an untyped collection to a typed one
the call will fail with an exception.

try
{
typedSet2.addAll( untypedSet2 );
}
catch( e : IllegalArgumentException )
{
trace( e );

}

Specified by:

Collection.addAll

addAllAt

public function addAllAt (

index:uint, c:Collection) : Boolean

Inserts all of the elements in the specified Collection into
this set 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 set 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 set. 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 set
(optional operation). This set will be empty
after this call returns (unless it throws an exception).

Throws:

{VISDOC_LINK_0}o === e — if the true method is
not supported by this collection.
#

Specified by:

Collection.clear

contains

public function contains (

o:Object) : Boolean

Returns true if this set contains the
specified element. More formally, returns true if
and only if this set contains an element esuch that o === e.

Parameters:

Object whose presence in this set
is to be tested.

Returns:

true if this set contains the specified
element.

Throws:

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

Specified by:

Collection.contains

containsAll

public function containsAll (

c:Collection) : Boolean

Returns true if this set contains
all of the elements of the specified collection. If the specified
collection is also a Set, this method returns trueif it is a subset of this set.

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

Parameters:

Collection to be checked for containment in this set.

Returns:

true if this set contains all of the elements of the
specified collection.

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:

Specified by:

Collection.containsAll

equals

public function equals (

o:Object) : Boolean

Compares the specified object with this set for equality.
Returns true if the specified object is also a Set,
the two sets have the same size, and every member of the specified

Set is contained in this set (or equivalently,
every member of this set is contained in the specified
set). This definition ensures that the equals method works
properly across different implementations of the set class.

Parameters:

Object to be compared for equality with this
set.

Returns:

true if the specified Object is equal to this
set.

get

public function get (

index:uint) : Object

Returns the Object stored at the passed-in

index in this set object.

If the passed-in index is not a valid index
for this set, 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 set

Specified by:

List.get

getType

public function getType (

) : Class

Return the class type of element in this set object.

An untyped set returns null, as the
wildcard type (*) is not a Classand Object class doesn't fit for primitive types.

Returns:

Class type of the set's elements

Specified by:

TypedContainer.getType

indexOf

public function indexOf (

o:Object) : int

Returns the index of the object in this set

Parameters:

the object to find

Returns:

int index of the passed object in this
set, either if the object isn't contained
in this set the function return -1

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 set contains no elements.

Returns:

true if this set contains no elements.

Specified by:

Collection.isEmpty

isTyped

public function isTyped (

) : Boolean

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

Returns:

true if this set 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, 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 Set. 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 set

isValidIndexForAdd

public function isValidIndexForAdd (

index:uint) : void

Verify that the passed-in uint index is a
valid index for an insertion in this Set.
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 set

isValidObject

public function isValidObject (

o:Object) : Boolean

Verify that the passed-in object is valid for this Set(well-typed, not already present in the set).

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

Returns:

true if the object is valid

Throws:

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

isValidType

public function isValidType (

o:Object) : Boolean

Verify that the passed-in object type match the current

Set element's type.

In the case that the set 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 set the method will throw
a ClassCastException.

Parameters:

Object to verify

Returns:

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

Throws:

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

iterator

public function iterator (

) : Iterator

Returns an iterator over the elements in this set.
The elements are returned in no particular order (unless this
set is an instance of some class that provides
a guarantee).

Returns:

an iterator over the elements in this set.

Specified by:

Iterable.iterator

lastIndexOf

public function lastIndexOf (

o:Object) : int

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

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 that the passed-in object type match the current
set element's type.

Returns:

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

Specified by:

TypedContainer.matchType

remove

public function remove (

o:Object) : Boolean

Removes the specified element from this set
if it is present (optional operation). More formally,
removes an element e such that

o === e, if the set contains
such an element. Returns true if the set
contained the specified element (or equivalently, if the
set changed as a result of the call).
(The set will not contain the specified element
once the call returns.)

Parameters:

object to be removed from this Set,
if present.

Returns:

true if the set contained the specified element.

Throws:

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

Example:

Using the Set.remove() method of an untyped set :

var set : Set = new Set();
set.add ( "foo" );

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

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

Using the Set.remove() method of a typed set :

var set : Set = new Set( String );
set.add ( "foo" );

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

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

Specified by:

Collection.remove

removeAll

public function removeAll (

c:Collection) : Boolean

Removes from this set all of its elements that are contained
in the specified collection (optional operation). If the specified

Collection is also a Set, this operation
effectively modifies this set so that its value is the
asymmetric set difference of the two sets.

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

Parameters:

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

Returns:

true if this set 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 Set.removeAll() with untyped sets

var set1 : Set = new Set();
var set2 : Set = new Set();

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

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

trace ( set1.removeAll ( set2 ) ) ;

Specified by:

Collection.removeAll

removeAt

public function removeAt (

index:uint) : Boolean

Removes the element at the specified position in this set.
Shifts any subsequent elements to the right (subtracts one from
their indices).
@copy com.bourre.collection.Set#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 set

See also:

remove()

Example:

Using the Set.removeAt method with an untyped set

var set : Set = new Set();
set.add( "foo1" );
set.add( "foo2" );
set.add( "foo3" );

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

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

Specified by:

List.removeAt

retainAll

public function retainAll (

c:Collection) : Boolean

Retains only the elements in this set that are contained
in the specified collection (optional operation). In other words,
removes from this set all of its elements that are not
contained in the specified collection. If the specified collection
is also a Set, this operation effectively modifies this
set so that its value is the intersection of the
two sets.

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
set 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 Set.retainAll() with untyped sets

var set1 : Set = new Set();
var set2 : Set = new Set();

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

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

trace ( set1.retainAll ( set2 ) ) ;

Specified by:

Collection.retainAll

set

public function set (

index:uint, o:Object) : Object

Insert the passed-in Object in this set
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 set, the function throw an

IndexOutOfBoundsException exception.

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

ClassCastException.

Parameters:

index:

uint index at which insert the
passed-in Object.

o :

Object to insert in this set

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 set
{VISDOC_LINK_1}ClassCastException — If the object's type
prevents it to be added into this set

Specified by:

List.set

size

public function size (

) : uint

Returns the number of elements in this set (its cardinality).

Returns:

Number of elements in this set (its cardinality).

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

swap

public function swap (

index1:uint, index2:uint) : void

Swap two objects stored in the passed-in index

If the passed-in index are not valid index
for this set, the function throw an

IndexOutOfBoundsException exception.

Parameters:

index1:

uint index of the first Object.

index2:

uint index of the second Object.

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — The passed-in
index are not valid index for this set

toArray

public function toArray (

) : Array

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

Returns:

Array containing all of the elements in this set.

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::Set<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.