+Show TOC
×Hide TOC

Grid

Kind of class:	public class
Package:	com.bourre.structures
Inherits from:	none
Implements:	Collection TypedContainer
Author:	Cédric Néhémie
Classpath:	com.bourre.structures.Grid
File last modified:	Monday, 24 November 2008, 11:36:47

► 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.structures 
{
    import com.bourre.collection.Collection;
    import com.bourre.collection.Iterator;
    import com.bourre.collection.TypedContainer;
    import com.bourre.collection.WeakCollection;
    import com.bourre.error.ClassCastException;
    import com.bourre.error.IllegalArgumentException;
    import com.bourre.error.IndexOutOfBoundsException;
    import com.bourre.error.NullPointerException;
    import com.bourre.error.UnsupportedOperationException;
    import com.bourre.log.PixlibDebug;
    import com.bourre.log.PixlibStringifier;
    
    import flash.geom.Point;    

    /** 
     * A <code>Grid</code> is basically a two dimensions data structure
     * based on the <code>Collection</code> interface.
     * <p>
     * By default a <code>Grid</code> object is an untyped collection that
     * allow duplicate and <code>null</code> elements. You can set your own
     * default value instead of <code>null</code> by passing it to the grid
     * constructor.
     * </p><p>
     * Its also possible to restrict the type of grid elements in the constructor
     * as defined by the <code>TypedContainer</code> interface.
     * </p><p>
     * The <code>Grid</code> class don't support all the methods of the <code>Collection</code>
     * interface. Here the list of the unsupported methods : 
     * <ul>
     *     <li><code>add</code></li>
     *     <li><code>addAll</code></li>
     *     <li><code>isEmpty</code></li>
     * </ul>
     * </p><p>
     * Instead of using the methods above there are several specific methods to insert data in the
     * grid : 
     * <ul>
     *     <li><code>setVal</code> : Use it to insert value in the grid at specified coordinates</li>
     *     <li><code>setContent</code> : Use it to set the grid with the passed-in array.</li>
     *     <li><code>fill</code> : Use it to fill the grid with the same value in all cells.</li>
     * </ul>
     * </p> 
     * @author    C√©dric N√©h√©mie
     * @see        com.bourre.collection.Collection
     * @see        com.bourre.collection.TypedContainer
     */
    public class Grid implements Collection, TypedContainer
    {
        private var _vSize : Dimension;
        private var _aContent : Array;
        private var _oDefaultValue : Object;
        private var _cType : Class;
        
        /**
         * Create a new grid of passed-in <code>size</code>.
         * <p>
         * If <code>a</code> is set, and if it have the same size that the grid, 
         * it's used to fill the collection at creation.
         * </p><p>
         * If <code>dV</code> is set, all <code>null</code> elements in the grid
         * will be replaced by <code>dV</code> value.
         * </p>
         * 
         * @param    size Size of the grid.
         * @param    a    An array to fill the grid with.
         * @param     dV     The default value for null elements.
         * @throws     <code>ArgumentError</code> ‚Äî Invalid size passed in Grid constructor.
         * @throws     <code>ClassCastException</code> ‚Äî If objects type contained in the
         *             passed-in array prevents them to be added into this grid
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in array length
         *             doesn't match this grid size
         */
        public function Grid ( size : Dimension, 
                               a : Array = null, 
                               dV : Object = null, 
                               t : Class = null )
        {
            if( size == null )
            {
                var msg : String = "Invalid size in Grid constructor : " + size;
                PixlibDebug.ERROR( msg );
                throw new ArgumentError ( msg );
            }
            
            _vSize = size;
            _oDefaultValue = dV;
            _cType = t;
            
            initContent();
             
            if( a != null )
            {
                setContent ( a );
            }
            else if( _oDefaultValue != null )
            {
                fill( _oDefaultValue );
            }
        }
        
        /**
         * Returns the <code>String</code> representation of
         * this object. 
         * <p>
         * The function return a string like
         * <code>com.bourre.structures::Grid&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 + " [" + _vSize.width + ", " + _vSize.height + "]";
        }
        
        /*
         * Collection interface API implementation
         */
        
        /**
         * Returns <code>true</code> if this grid contains at least
         * one occurence of the specified element. Moreformally,
         * returns <code>true</code> if and only if this grid contains
         * at least an element <code>e</code> such that <code>o === e</code>.
         *
         * @param    o    <code>Object</code> whose presence in this grid
         *                   is to be tested.
         * @return     <code>true</code> if this grid contains the specified
         *             element.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         */
        public function contains( o : Object ) : Boolean
        {
            isValidType( o );
            
            var i : Iterator = iterator();
            
            while( i.hasNext() )
            {
                if( i.next() === o )
                    return true;
            }
            return false;
        }
        
        /**
         * Returns an array containing all the elements in this grid.
         * Obeys the general contract of the <code>Collection.toArray</code>
         * method.
         *
         * @return  <code>Array</code> containing all of the elements
         *             in this grid.
         * @see        Collection#toArray() Collection.toArray()
         */
        public function toArray() : Array
        {
            var a : Array = [];
            var i : Iterator = iterator();
            
            while ( i.hasNext() ) a.push( i.next() );
            
            return a;
        }
        
        /**
         * A <code>Grid</code> object is considered as empty if and only if all its cells
         * contains <code>null</code> or the default value for the current <code>Grid</code>.
         * 
         * @return     <code>true</code> if the grid is empty, either <code>false</code>.
         */
        public function isEmpty() : Boolean
        {
            var b : Boolean = false;
            var i : Iterator = iterator();
            
            while ( i.hasNext() )
            {
                b = ( i.next() != _oDefaultValue ) || b;
            }
            return !b;
        }
        
        /**
         * Removes a single instance of the specified element from this
         * grid, if this grid contains one or more such elements.
         * Returns <code>true</code> if this grid 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 grid contains an
         * occurrence of the passed-in element. Typically, the construct to
         * remove all occurrences of an element should look like that :
         * <listing>
         * while( grid.contains( element ) ) grid.remove( element );
         * </listing>
         * </p><p>
         * If the current grid object is typed and if the passed-in object's  
         * type prevents it to be added (and then removed) in this grid,
         * the function throws a <code>ClassCastException</code>.
         * </p><p>
         * The <code>Grid</code> introduce a specific behavior for its default
         * value, if the passed-in element is the default value for this grid
         * the function return <code>null</code> and isnt't modified as result
         * of the call.
         * </p>
         * @param    o <code>object</code> to be removed from this grid,
         *               if present.
         * @return     <code>true</code> if the grid contained the 
         *             specified element.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         */
        public function remove( o : Object ) : Boolean
        {
            isValidType( o );
            
            if( o === _oDefaultValue ) 
                return false;
            
            var i : Iterator = iterator ();

            while( i.hasNext() )
            {
                var e : Object = i.next ();
                if( e === o )
                {
                    i.remove();
                    return true;
                }
            }
            return false;
        }
                
        /**
         * Removes all of the elements from this collection.
         * This collection will not be empty after this method.
         * <p>
         * If a default value have been defined for the grid
         * then all cells of the grid contains that value.
         * </p>
         */
        public function clear() : void
        {
            fill ( _oDefaultValue );
        }
        
        /**
         * Returns an iterator over the elements in this collection. Iterations
         * are performed in the following order : columns first, rows after. 
         * <p>
         * Result for a 2x2 grid : 
         * <ul>
         *     <li>Cell 0, 0</li>
         *  <li>Cell 1, 0</li>
         *     <li>Cell 0, 1</li>
         *     <li>Cell 1, 1</li>
         * </ul>
         * </p> 
         * @return     an <code>Iterator</code> over the elements in this collection.
         */
        public function iterator() : Iterator
        {
            return new GridIterator( this );
        }
        
        /** 
         * Removes from this grid 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><p>
         * The only values which cannot be removed by a call to <code>removeAll</code>
         * is the default value for this grid. It result that all cells which contained
         * a value also contained in the passed-in collection are filled with the grid's
         * default value.
         * </p><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 grid.
         * @return     <code>true</code> if this grid changed as a result
         *             of the call.
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.    
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         */
        public function removeAll( c : Collection ) : Boolean
        {
            isValidCollection( c );
            
            var b : Boolean = false;
            var i : Iterator = c.iterator();
            while( i.hasNext() )
            {
                var o : Object = i.next();
                if( o != _oDefaultValue )
                    while( contains( o ) ) b = remove( o ) || b;
            } 
            return b;
        }
        
        /**
         * Returns <code>true</code> if this grid contains
         * all of the elements of the specified collection. If the specified
         * collection is also a <code>Grid</code>, this method returns <code>true</code>
         * if it is a <i>subliset</i> of this queue.
         * <p>
         * If the passed-in <code>Collection</code> is null the method throw a
         * <code>NullPointerException</code> error.
         * </p><p>
         * If the passed-in <code>Collection</code> type is different than the current
         * one the function will throw an <code>IllegalArgumentException</code>.
         * However, if the type of this grid is <code>null</code>, 
         * the passed-in <code>Collection</code> can have any type. 
         * </p><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     collection to be checked for containment in this collection.
         * @return     <code>true</code> if this collection contains all of the elements
         *               in the specified collection
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.    
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         * @see       #contains(Object)
         */
        public function containsAll( c : Collection ) : Boolean
        {
            isValidCollection( c );
            
            var i : Iterator = c.iterator();
            while( i.hasNext() ) if( !contains( i.next() ) ) return false;
            return true;
        }
        
        /**
         * The <code>addAll</code> method is unsupported by the <code>Grid</code> class.
         * 
         * @throws     <code>UnsupportedOperationException</code> ‚Äî The addAll method of the Collection interface is unsupported by the Grid Class
         */
        public function addAll( c : Collection ) : Boolean
        {
            PixlibDebug.ERROR( this + ".addAll() method is unsupported." );
            throw new UnsupportedOperationException ( "The addAll method of the Collection interface is unsupported by the Grid class" );
            return false;
        }
        
        /**
         * Copy the content of the passed-in grid at the specified coordinates.
         * The passed-in grid is paste into this grid such the top-left coordinates
         * will start at the specified <code>Point</code> argument.
         * 
         * @param    p    coordinates at which copy the grid
         * @param    c    grid to copy in this grid object
         * @return    <code>true</code> if the passed-in grid have been successfully added
         *             at the specified coordinates in this grid
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.    
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî If the passed-in point
         *             is not valid coordinates for this grid.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî If the passed-in grid
         *             will overlap this grid when copying.        
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         */
        public function addAllAt( p : Point, c : Grid ) : Boolean
        {
            isValidCollection( c );
            isGridCoords( p );
            isGridCoords( p.add( new Point( _vSize.width-1, _vSize.height-1 ) ) );
            
            var i : GridIterator = c.iterator( ) as GridIterator;
            
            while ( i.hasNext() )
            {
                var val : * = i.next();
                setVal( i.add( p ) , val );
            }
            
            return true;
        }
        
        /**
         * Removes the content of the passed-in grid at the specified coordinates.
         * The passed-in grid is removed from this grid such the top-left coordinates
         * will start at the specified <code>Point</code> argument.
         * <p>
         * The content of the passed-in grid is only removed in the bounds of the grid
         * in this grid space coordinates. Values which are also stored in the passed-in 
         * grid but whose coordinates aren't in the bounds of the operation aren't remove.
         * </p>
         * @param    p    coordinates at which remove the grid
         * @param    c    grid to remove from this grid object
         * @return    <code>true</code> if the passed-in grid have been successfully removed
         *             at the specified coordinates in this grid
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.    
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî If the passed-in point
         *             is not valid coordinates for this grid.
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî If the passed-in grid
         *             will overlap this grid when removing.        
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         */
        public function removeAllAt( p : Point, c : Grid ) : Boolean
        {
            isValidCollection( c );
            isGridCoords( p );
            isGridCoords( p.add( new Point( _vSize.width-1, _vSize.height-1 ) ) );            
            
            var b : Boolean = false;
            var i : GridIterator = c.iterator( ) as GridIterator;
            
            while( i.hasNext() )
            {
                i.next();
                removeAt( i.add( p ) );
                
            } 
            return b;
        }
        
        /**
         * Retains only the elements in this queue that are contained
         * in the specified collection (optional operation). In other words,
         * removes from this queue all of its elements that are not
         * contained in the specified collection.
         * <p>
         * The only values which cannot be removed by a call to <code>retainAll</code>
         * is the default value for this grid. It result that all cells which contained
         * a value that are not contained in the passed-in collection are filled with
         * the grid's default value.
         * </p><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     elements to be retained in this collection.
         * @return     <code>true</code> if this collection changed as a result of the
         *             call
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in collection
         *             type is not the same that the current one.    
         * @see        #isValidCollection() See isValidCollection for description of the rules for 
         *             collaboration between typed and untyped collections.
         * @see     #remove(Object)
         * @see     #contains(Object)
         */
        public function retainAll( c : Collection ) : Boolean
        {
            isValidCollection( c );
            
            var b : Boolean = false;
            var i : Iterator = iterator();
            
            while( i.hasNext() )
            {
                var o : Object = i.next();    
                if ( o != _oDefaultValue && !(c.contains( o )) ) b = remove( o ) || b;
            }
            return b;
            
        }
        
        /**
         * The <code>add</code> method is unsupported by the <code>Grid</code> class.
         * 
         * @throws     <code>UnsupportedOperationException</code> ‚Äî The add method of the Collection interface is unsupported by the Grid Class
         */
        public function add( o : Object ) : Boolean
        {
            PixlibDebug.ERROR( this + ".add() method is unsupported." );
            throw new UnsupportedOperationException ( "The add method of the Collection interface is unsupported by the Grid class" );
            return false;
        }
        
        /**
         * Returns the number of elements this collection can contains.
         * 
         * @return the number of elements this collection can contains.
         */
        public function size() : uint
        {
            return _vSize.width * _vSize.height;
        }
        
        /*
         * Grid specific API
         */
        
        /**
         * Verify if the passed-in object can be inserted in the
         * current <code>Grid</code>.
         * 
         * @param    o    Object to verify
         * @return     <code>true</code> if the object can be inserted in
         * the <code>Grid</code>, either <code>false</code>.
         */
        public function matchType( o : * ) : Boolean
        {
            return ( o is _cType || o == null );
        }
        
        /**
         * Returns <code>true</code> if this grid perform a verification
         * of the type of elements.
         * 
         * @return  <code>true</code> if this grid perform a verification
         *             of the type of elements.
         */
        public function isTyped () : Boolean
        {
            return _cType != null;
        }
        
        /**
         * Return the current type allowed in the <code>Grid</code>
         * 
         * @return <code>Class</code> used to type checking.
         */
        public function getType () : Class
        {
            return _cType;
        }
        
        /**
         * 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 ) 
            {
                PixlibDebug.ERROR( "The passed-in collection is null in " + this );
                throw new NullPointerException( "The passed-in collection is null in " + this );
            }
            else if( getType() != null )
            {
                if( c is TypedContainer && ( c as TypedContainer ).getType() != getType() )
                {
                    PixlibDebug.ERROR( "The passed-in collection is not of the same type than " + this );
                    throw new IllegalArgumentException( "The passed-in collection is not of the same type than " + this );
                }
                else
                {
                    return true;
                }
            }
            else
            {
                return true;
            }
        }
        
        /**
         * Verify that the passed-in object type match the current 
         * <code>Grid</code> element's type. 
         * <p>
         * In the case that the grid 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 grid 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
         *             grid object, either <cod>false</code>
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         */
        public function isValidType ( o : Object ) : Boolean
        {
            if ( getType() != null)
            {
                if ( matchType( o ) )
                {
                    return true;
                }
                else
                {
                    PixlibDebug.ERROR( o + " has a wrong type for " + this );
                    throw new ClassCastException( o + " has a wrong type for " + this ) ;
                }
            }
            else
                return true ;
        }
        
        /**
         * Creates the internal two dimensional array used to store
         * data of the grid.
         */
        protected function initContent() : void 
        {
            _aContent  = new Array( _vSize.width );
            for ( var x : Number = 0; x < _vSize.width ; x++ ) 
                _aContent[ x ] = new Array( _vSize.height );
        }
        
        /**
         * Fill the current grid with the passed-in value.
         * <p>
         * If the passed-in value is a "real" object (not a primitive) then
         * all cells contains a reference to the same object.
         * </p>
         * @param    o    Value used to fill the grid
         */
        public function fill ( o : Object ) : void
        {
            isValidType( o );
            
            var i : Iterator = iterator ();
            
            while ( i.hasNext() )
            {
                i.next();
                
                setVal ( i as GridIterator, o );
            }
        }
        
        /**
         * Removes the value located at the passed-in coordinate.
         * <p>
         * If the grid changed after the call the function returns
         * <code>true</code>. If the passed-in <code>Point</code> isn't
         * a valid coordinate for this grid the function failed and return
         * <code>false</code>.
         * </p><p>
         * If a default value is set, the cell contains that value instead
         * of <code>null</code> after the call.
         * </p>
         * @param    p    <code>Point</code> position of the value to remove
         * @return     <code>true</code> if the grid changed as result of the call
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî the passed-in point
         *             is not a valid coordinates for this grid
         */
        public function removeAt ( p : Point ) : Boolean
        {            
            return setVal ( p, _oDefaultValue );            
        }
        
        /**
         * Check if a <code>Point</code> object is a valid coordinate
         * in the current grid.
         * 
         * @param    p    <code>Point</code> object to check
         * @return     <code>true</code> if passed-in <code>Point</code> is a valid
         *             coordinate for the current grid
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî the passed-in point
         *             is not a valid coordinates for this grid
         */
        public function isGridCoords ( p : Point ) : Boolean
        {
            if ( !( p.x >= 0 && 
                    p.x < _vSize.width &&
                    p.y >= 0 &&
                    p.y < _vSize.height ) )
                throw new IndexOutOfBoundsException ( p + " is not a valid grid coordinates for " + this );
                
            return true;
        }

        /**
         * Returns the size of the grid as <code>Dimension</code>.
         * <p>
         * The returned <code>Dimension</code> is a clone of the
         * internal one.
         * </p>
         * @return     the dimensions of the grid as <code>Dimension</code>
         */
        public function getSize () : Dimension
        {
            return _vSize.clone(); 
        }
        
        /**
         * Returns a <code>Point</code> witch is the corresponding
         * position of the passed-in value.
         * 
         * @param     id    <code>uint</code> to convert in a two dimension location
         * @return     <code>Point</code> corresponding location
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî the passed-in index
         *             is not a valid coordinates for this grid
         */
        public function getCoordinates ( id : uint ) : Point
        {
            var r : Number = id % _vSize.width;
            var nY : Number = (id - r) / _vSize.width;
            var p : Point = new Point( r, nY );
            
            isGridCoords( p );
            
            return p;
        }
        
        /**
         * Returns the current default value of this grid used
         * to replace value when removing an element.
         * 
         * @return    element used as default value for the grid's cells
         */
        public function getDefaulValue () : Object
        {
            return _oDefaultValue;
        }
        
        /**
         * Defines the default value for this grid's cells content. 
         * When changing the default value of a grid, the cells which
         * previously contains the old default value will contains the
         * new one at the end of the call.
         * 
         * @param    o    new default value for this grid's cells
         * @return    <code>true</code> if the grid have change as result
         *             of the call
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         */
        public function setDefaultValue ( o : Object ) : Boolean
        {
            isValidType( o );
            
            var oldDV : Object = _oDefaultValue;
            _oDefaultValue = o;
            
            return removeAll( new WeakCollection( [ oldDV ] ) );
        }

        /**
         * Returns the element stored at the passed-in coordinate of the
         * grid.
         * 
         * @param     p    Coordinates <code>Point</code> in the grid
         * @return  Value stored at the coorespoding location or <code>null</code>
         *             if the passed-in coordinates is not a valid coordinates
         *             for this grid
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî the passed-in point
         *             is not a valid coordinates for this grid
         */
        public function getVal ( p : Point ) : Object
        {
            isGridCoords ( p );
            
            return _aContent [ p.x ][ p.y ];
        }
            
        /**
         * Defines value of grid cell defining by passed-in <code>Point</code> 
          * coordinate.
          * <p>
          * The call return <code>true</code> only if the <code>Grid</code>
          * changed as results of the call.
          * </p> 
         * @param     p    <code>Point</code> position of the cell
         * @param     o    value to store in the grid
         * @return  <code>true</code> if the <code>Grid</code> changed as results of the call
         * @throws     <code>IndexOutOfBoundsException</code> ‚Äî the passed-in point
         *             is not a valid coordinates for this grid
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         */
        public function setVal ( p : Point, o : Object ) : Boolean
        {
            isValidType( o );
            isGridCoords ( p );
            
            if( o === _aContent [ p.x ][ p.y ])
            {
                return false;
            }
            
            if( o == null && _oDefaultValue != null ) 
                o = _oDefaultValue;
            
            
            _aContent [ p.x ][ p.y ] = o;
            return true;
        }
        
        /**
         * Fill the content with an array of witch length is equal to
         * the grid <code>size()</code>.
         * <p>
         * The call return <code>true</code> only if the <code>Grid</code>
          * changed as results of the call.
          * </p>
         * @param     a    <code>Array</code> to fill the <code>Grid</code>
         * @return     <code>true</code> if the <code>Grid</code> changed as results of the call
         * @throws     <code>ClassCastException</code> ‚Äî If the object's type
         *             prevents it to be added into this grid
         * @throws     <code>IllegalArgumentException</code> ‚Äî If the passed-in array length
         *             doesn't match this grid size
         */
        public function setContent ( a : Array ) : Boolean
        {
            if( a.length != size () )
            {
                var msg : String = "Passed-in array of length " + a.length +
                                   " doesn't match " + this + ".size() : " + size();
                                   
                PixlibDebug.ERROR( msg );
                throw new IllegalArgumentException ( msg );
                return false;
            }
            var l : Number = a.length;
            var b : Boolean = false;
            while (--l-(-1))
            {
                var p : Point = getCoordinates ( l );
                b = setVal ( p, a[ l ] ) || b;
            }
            
            return true;
        }
    }
}

import com.bourre.collection.Iterator;
import com.bourre.error.IllegalStateException;
import com.bourre.error.NoSuchElementException;
import com.bourre.structures.Grid;

import flash.geom.Point;

internal class GridIterator extends Point implements Iterator
{
    
    private var _nIndex : Number;
    private var _nLength : Number;
    private var _oGrid : Grid;    
    private var _bRemoved : Boolean;

    public function GridIterator ( g : Grid )
    {
        _oGrid = g;
        _nIndex = -1;
        _nLength = _oGrid.size();
        _bRemoved = false;
    }
    
    public function hasNext() : Boolean
    {
        return ( _nIndex + 1 ) < _nLength;
    }
     public function next() : *
     {
         if( !hasNext() )
            throw new NoSuchElementException ( this + " has no more elements at " + ( _nIndex ) );
         
         var p : Point = _oGrid.getCoordinates( ++_nIndex );
         x = p.x;
         y = p.y;
         _bRemoved = false;
        return _oGrid.getVal( this );
     }
    public function remove() : void
    {
        if( !_bRemoved )
        {
            _oGrid.removeAt( this );
            _bRemoved = true;
        }
        else
        {
            throw new IllegalStateException ( this + ".remove() have been already called for this iteration" );
        }
    }
}

A Grid is basically a two dimensions data structure
based on the Collection interface.

By default a Grid object is an untyped collection that
allow duplicate and null elements. You can set your own
default value instead of null by passing it to the grid
constructor.

Its also possible to restrict the type of grid elements in the constructor
as defined by the TypedContainer interface.

The Grid class don't support all the methods of the Collectioninterface. Here the list of the unsupported methods :

add
addAll
isEmpty

Instead of using the methods above there are several specific methods to insert data in the
grid :

setVal : Use it to insert value in the grid at specified coordinates
setContent : Use it to set the grid with the passed-in array.
fill : Use it to fill the grid with the same value in all cells.

See also:

com.bourre.collection.Collection
com.bourre.collection.TypedContainer

Summary

Constructor

Grid (size:Dimension, a:Array = null, dV:Object = null, t:Class = null)
- Create a new grid of passed-in size.

Instance methods

toString : String
- Returns the String representation of
contains (o:Object) : Boolean
- Returns true if this grid contains at least
toArray : Array
- Returns an array containing all the elements in this grid.
isEmpty : Boolean
- A Grid object is considered as empty if and only if all its cells
remove (o:Object) : Boolean
- Removes a single instance of the specified element from this
clear : void
- Removes all of the elements from this collection.
iterator : Iterator
- Returns an iterator over the elements in this collection.
removeAll (c:Collection) : Boolean
- Removes from this grid all of its elements that are contained
containsAll (c:Collection) : Boolean
- Returns true if this grid contains
addAll (c:Collection) : Boolean
- The addAll method is unsupported by the Grid class.
addAllAt (p:Point, c:Grid) : Boolean
- Copy the content of the passed-in grid at the specified coordinates.
removeAllAt (p:Point, c:Grid) : Boolean
- Removes the content of the passed-in grid at the specified coordinates.
retainAll (c:Collection) : Boolean
- Retains only the elements in this queue that are contained
add (o:Object) : Boolean
- The add method is unsupported by the Grid class.
size : uint
- Returns the number of elements this collection can contains.
matchType (o:*) : Boolean
- Verify if the passed-in object can be inserted in the
isTyped : Boolean
- Returns true if this grid perform a verification
getType : Class
- Return the current type allowed in the Grid
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
fill (o:Object) : void
- Fill the current grid with the passed-in value.
removeAt (p:Point) : Boolean
- Removes the value located at the passed-in coordinate.
isGridCoords (p:Point) : Boolean
- Check if a Point object is a valid coordinate
getSize : Dimension
- Returns the size of the grid as Dimension.
getCoordinates (id:uint) : Point
- Returns a Point witch is the corresponding
getDefaulValue : Object
- Returns the current default value of this grid used
setDefaultValue (o:Object) : Boolean
- Defines the default value for this grid's cells content.
getVal (p:Point) : Object
- Returns the element stored at the passed-in coordinate of the
setVal (p:Point, o:Object) : Boolean
- Defines value of grid cell defining by passed-in Point
setContent (a:Array) : Boolean
- Fill the content with an array of witch length is equal to

Constructor

Grid

public function Grid (

size:Dimension, a:Array = null, dV:Object = null, t:Class = null)

Create a new grid of passed-in size.

If a is set, and if it have the same size that the grid,
it's used to fill the collection at creation.

If dV is set, all null elements in the grid
will be replaced by dV value.

Parameters:

size:

Size of the grid.

a :

An array to fill the grid with.

dV :

The default value for null elements.

Throws:

{VISDOC_LINK_0}ArgumentError — Invalid size passed in Grid constructor.
{VISDOC_LINK_1}ClassCastException — If objects type contained in the
passed-in array prevents them to be added into this grid
{VISDOC_LINK_2}IllegalArgumentException — If the passed-in array length
doesn't match this grid size

Instance methods

add

public function add (

o:Object) : Boolean

The add method is unsupported by the Grid class.

Parameters:

element whose presence in this collection is to be ensured.

Throws:

{VISDOC_LINK_0}UnsupportedOperationException — The add method of the Collection interface is unsupported by the Grid Class

Returns:

a if this collection changed as a result of the
call
#

Specified by:

Collection.add

addAll

public function addAll (

c:Collection) : Boolean

The addAll method is unsupported by the Grid class.

Parameters:

elements to be inserted into this collection.

Throws:

{VISDOC_LINK_0}UnsupportedOperationException — The addAll method of the Collection interface is unsupported by the Grid Class

Returns:

ClassCastException if this collection changed as a result of the
call
#

Specified by:

Collection.addAll

addAllAt

public function addAllAt (

p:Point, c:Grid) : Boolean

Copy the content of the passed-in grid at the specified coordinates.
The passed-in grid is paste into this grid such the top-left coordinates
will start at the specified Point argument.

Parameters:

coordinates at which copy the grid

grid to copy in this grid object

Returns:

true if the passed-in grid have been successfully added
at the specified coordinates in this grid

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this grid
{VISDOC_LINK_1}IllegalArgumentException — If the passed-in collection
type is not the same that the current one.
{VISDOC_LINK_2}IndexOutOfBoundsException — If the passed-in point
is not valid coordinates for this grid.
{VISDOC_LINK_3}IndexOutOfBoundsException — If the passed-in grid
will overlap this grid when copying.

See also:

See isValidCollection for description of the rules for
collaboration between typed and untyped collections.

clear

public function clear (

) : void

Removes all of the elements from this collection.
This collection will not be empty after this method.

If a default value have been defined for the grid
then all cells of the grid contains that value.

Throws:

{VISDOC_LINK_0}Collection — 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 grid contains at least
one occurence of the specified element. Moreformally,
returns true if and only if this grid contains
at least an element e such that o === e.

Parameters:

Object whose presence in this grid
is to be tested.

Returns:

true if this grid contains the specified
element.

Throws:

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

Specified by:

Collection.contains

containsAll

public function containsAll (

c:Collection) : Boolean

Returns true if this grid contains
all of the elements of the specified collection. If the specified
collection is also a Grid, this method returns trueif it is a subliset of this queue.

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

NullPointerException error.

If the passed-in Collection type is different than the current
one the function will throw an IllegalArgumentException.
However, if the type of this grid is null,
the passed-in Collection can have any type.

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 collection.

Returns:

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

Throws:

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

See also:

Specified by:

Collection.containsAll

fill

public function fill (

o:Object) : void

Fill the current grid with the passed-in value.

If the passed-in value is a "real" object (not a primitive) then
all cells contains a reference to the same object.

Parameters:

Value used to fill the grid

getCoordinates

public function getCoordinates (

id:uint) : Point

Returns a Point witch is the corresponding
position of the passed-in value.

Parameters:

id:

uint to convert in a two dimension location

Returns:

Point corresponding location

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — the passed-in index
is not a valid coordinates for this grid

getDefaulValue

public function getDefaulValue (

) : Object

Returns the current default value of this grid used
to replace value when removing an element.

Returns:

element used as default value for the grid's cells

getSize

public function getSize (

) : Dimension

Returns the size of the grid as Dimension.

The returned Dimension is a clone of the
internal one.

Returns:

the dimensions of the grid as Dimension

getType

public function getType (

) : Class

Return the current type allowed in the Grid

Returns:

Class used to type checking.

Specified by:

TypedContainer.getType

getVal

public function getVal (

p:Point) : Object

Returns the element stored at the passed-in coordinate of the
grid.

Parameters:

Coordinates Point in the grid

Returns:

Value stored at the coorespoding location or null if the passed-in coordinates is not a valid coordinates
for this grid

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — the passed-in point
is not a valid coordinates for this grid

isEmpty

public function isEmpty (

) : Boolean

A Grid object is considered as empty if and only if all its cells
contains null or the default value for the current Grid.

Returns:

true if the grid is empty, either false.

Specified by:

Collection.isEmpty

isGridCoords

public function isGridCoords (

p:Point) : Boolean

Check if a Point object is a valid coordinate
in the current grid.

Parameters:

Point object to check

Returns:

true if passed-in Point is a valid
coordinate for the current grid

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — the passed-in point
is not a valid coordinates for this grid

isTyped

public function isTyped (

) : Boolean

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

Returns:

true if this grid 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:

isValidType

public function isValidType (

o:Object) : Boolean

Verify that the passed-in object type match the current

Grid element's type.

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

Parameters:

Object to verify

Returns:

true if the object is elligible for this
grid object, either false

Throws:

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

iterator

public function iterator (

) : Iterator

Returns an iterator over the elements in this collection. Iterations
are performed in the following order : columns first, rows after.

Result for a 2x2 grid :

Cell 0, 0
Cell 1, 0
Cell 0, 1
Cell 1, 1

Returns:

an Iterator over the elements in this collection.

Specified by:

Iterable.iterator

matchType

public function matchType (

o:*) : Boolean

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

Parameters:

Object to verify

Returns:

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

Specified by:

TypedContainer.matchType

remove

public function remove (

o:Object) : Boolean

Removes a single instance of the specified element from this
grid, if this grid contains one or more such elements.
Returns true if this grid 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 grid contains an
occurrence of the passed-in element. Typically, the construct to
remove all occurrences of an element should look like that :

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

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

The Grid introduce a specific behavior for its default
value, if the passed-in element is the default value for this grid
the function return null and isnt't modified as result
of the call.

Parameters:

object to be removed from this grid,
if present.

Returns:

true if the grid contained the
specified element.

Throws:

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

Specified by:

Collection.remove

removeAll

public function removeAll (

c:Collection) : Boolean

Removes from this grid 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 only values which cannot be removed by a call to removeAllis the default value for this grid. It result that all cells which contained
a value also contained in the passed-in collection are filled with the grid's
default value.

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 grid.

Returns:

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

Throws:

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

See also:

See isValidCollection for description of the rules for
collaboration between typed and untyped collections.

Specified by:

Collection.removeAll

removeAllAt

public function removeAllAt (

p:Point, c:Grid) : Boolean

Removes the content of the passed-in grid at the specified coordinates.
The passed-in grid is removed from this grid such the top-left coordinates
will start at the specified Point argument.

The content of the passed-in grid is only removed in the bounds of the grid
in this grid space coordinates. Values which are also stored in the passed-in
grid but whose coordinates aren't in the bounds of the operation aren't remove.

Parameters:

coordinates at which remove the grid

grid to remove from this grid object

Returns:

true if the passed-in grid have been successfully removed
at the specified coordinates in this grid

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this grid
{VISDOC_LINK_1}IllegalArgumentException — If the passed-in collection
type is not the same that the current one.
{VISDOC_LINK_2}IndexOutOfBoundsException — If the passed-in point
is not valid coordinates for this grid.
{VISDOC_LINK_3}IndexOutOfBoundsException — If the passed-in grid
will overlap this grid when removing.

See also:

See isValidCollection for description of the rules for
collaboration between typed and untyped collections.

removeAt

public function removeAt (

p:Point) : Boolean

Removes the value located at the passed-in coordinate.

If the grid changed after the call the function returns

true. If the passed-in Point isn't
a valid coordinate for this grid the function failed and return

false.

If a default value is set, the cell contains that value instead
of null after the call.

Parameters:

Point position of the value to remove

Returns:

true if the grid changed as result of the call

Throws:

{VISDOC_LINK_0}IndexOutOfBoundsException — the passed-in point
is not a valid coordinates for this grid

retainAll

public function retainAll (

c:Collection) : Boolean

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

The only values which cannot be removed by a call to retainAllis the default value for this grid. It result that all cells which contained
a value that are not contained in the passed-in collection are filled with
the grid's default value.

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:

elements to be retained in this collection.

Returns:

true if this collection changed as a result of the
call

Throws:

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

See also:

Specified by:

Collection.retainAll

setContent

public function setContent (

a:Array) : Boolean

Fill the content with an array of witch length is equal to
the grid size().

The call return true only if the Gridchanged as results of the call.

Parameters:

Array to fill the Grid

Returns:

true if the Grid changed as results of the call

Throws:

{VISDOC_LINK_0}ClassCastException — If the object's type
prevents it to be added into this grid
{VISDOC_LINK_1}IllegalArgumentException — If the passed-in array length
doesn't match this grid size

setDefaultValue

public function setDefaultValue (

o:Object) : Boolean

Defines the default value for this grid's cells content.
When changing the default value of a grid, the cells which
previously contains the old default value will contains the
new one at the end of the call.

Parameters:

new default value for this grid's cells

Returns:

true if the grid have change as result
of the call

Throws:

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

setVal

public function setVal (

p:Point, o:Object) : Boolean

Defines value of grid cell defining by passed-in Point
coordinate.

The call return true only if the Gridchanged as results of the call.

Parameters:

Point position of the cell

value to store in the grid

Returns:

true if the Grid changed as results of the call

Throws:

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

size

public function size (

) : uint

Returns the number of elements this collection can contains.

Returns:

the number of elements this collection can contains.

Specified by:

Collection.size

toArray

public function toArray (

) : Array

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

Returns:

Array containing all of the elements
in this grid.

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.structures::Grid<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.