/*

 Wotonomy: OpenStep design patterns for pure Java applications.

 Copyright (C) 2000 Blacksmith, Inc.

 This library is free software; you can redistribute it and/or

 modify it under the terms of the GNU Lesser General Public

 License as published by the Free Software Foundation; either

 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,

 but WITHOUT ANY WARRANTY; without even the implied warranty of

 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public

 License along with this library; if not, see http://www.gnu.org

 */

 package net.wotonomy.foundation;

 import java.io.Serializable;

 import java.util.ArrayList;

 import java.util.Collection;

 import java.util.Collections;

 import java.util.Enumeration;

 import java.util.Iterator;

 import java.util.LinkedList;

 import java.util.List;

 import java.util.ListIterator;

 /**

 * NSArray is an unmodifiable List.  

 * Calling the mutator methods of the List interface (add, addAll, 

 * set, etc.) on an instance of NSArray will throw an Unsupported

 * Operation exception: use a NSMutableArray instead.  This is to

 * simulate Objective-C's pattern of exposing mutator methods only

 * on mutable subinterface, which is wonderful for communicating

 * via interface the contract on returned collections (whether you

 * may modify return values) as well as implementing array faults.

 *

 * @author michael@mpowers.net

 * @author $Author: cgruber $

 * @version $Revision: 929 $

 */

 public class NSArray implements List, Serializable

 {

     /**

     * Actual list that backs this instance.

     */

     List list;

         /**

         * Return value when array index is not found.

         */

     public static final int NotFound = -1;

         /**

         * A constant representing an empty array.

         */

     public static final NSArray EmptyArray = new NSArray();

     /**

     * Returns an NSArray backed by the specified List.

     * This is useful to "protect" an internal representation

     * that is returned by a method of return type NSArray.

     */

     public static NSArray arrayBackedByList( List aList )

     {

         return new NSArray( aList, null );

     }

     /**

      * A constructor that uses the provided list as the backing 

      * list object.  This is unlike ArrayList and other 

      * java.util.Collection types insofar as that API requires

      * that the provided Collection be copied into the newly constructed

      * Collection.

      * 

      * TODO: See if this signature can be reasonably changed, as having a no-op parameter is a little counter-intuitive.

      * @param aList A list that the caller wishes to become the backing list for the NSArray.

      * @param ignored This parameter is entirely ignored, and is only there to distinguish the API.

      */

     NSArray( List aList, Object ignored ) // differentiates

     {

         list = aList;

     }

     /**

     * Constructor with a size hint, used by NSMutableArray.

     */

     NSArray( int aSize )

     {

         list = new ArrayList( aSize );

     }

         /**

         * Default constructor returns an empty array.

         */

     public NSArray ()

     {

             list = new ArrayList();

     }        

         /**

         * Produces an array containing only the specified object.

         */

     public NSArray (Object anObject)

     {

             this();

             list.add( anObject );

     }

         /**

         * Produces an array containing the specified objects.

         */

     public NSArray (Object[] anArray)

     {

             this();

             for ( int i = 0; i < anArray.length; i++ )

             {

                     list.add( anArray[i] );

             }

     }

         /**

         * Produces an array containing the objects in the specified collection.

         */

     public NSArray (Collection aCollection)

     {

         this();

             Iterator i = aCollection.iterator();

         while ( i.hasNext() ) list.add( i.next() );

     }

         /**

         * Returns the number of items in this array.

         */

     public int count ()

     {

             return list.size();

     }

         /**

         * Returns an array containing all objects in this array 

         * plus the specified object.

         */

     public NSArray arrayByAddingObject (Object anObject)

     {

             NSArray result = new NSArray( this );

             result.protectedAdd( anObject );

             return result;

     }

         /**

         * Returns an array containing all objects in this array

         * plus all objects in the specified list.

         */

     public NSArray arrayByAddingObjectsFromArray (Collection aCollection)

     {

             NSArray result = new NSArray( this );

             result.protectedAddAll( aCollection );

             return result;

     }

         /**

         * Returns a string containing the string representations of

         * each element in this array, with each element separated from

         * each neighboring element by the specified string.

         */

     public String componentsJoinedByString (String separator)

     {

             StringBuffer buf = new StringBuffer();

             Iterator it = list.iterator();

             if ( it.hasNext() )

             {

                     buf.append( it.next().toString() );

             }

             while ( it.hasNext() )

             {

                     buf.append( separator );

                     buf.append( String.valueOf(it.next()) );

             }

             return buf.toString();

     }

         /**

         * Returns whether an equivalent object is contained in this array.

         */

     public boolean containsObject (Object anObject)

     {

             return list.contains( anObject );

     }

         /**

         * Returns the first object in this array that is equivalent to

         * an object in the specified list, or null if no objects are

         * in common.

         */

     public Object firstObjectCommonWithArray (Collection aCollection)

     {

             if ( aCollection == null ) return null;

             Object o;

             Iterator it = list.iterator();

             while ( it.hasNext() )

             {

                     o = it.next();

                     if ( aCollection.contains( o ) ) return o;

             }

             return null;

     }

         /**

         * Returns whether the specified list contains elements equivalent

         * to those in this array in the same order.

         */

     public boolean isEqualToArray (List aList)

     {

             return list.equals( aList );

     }

         /**

         * Returns the last object in this array, or null if the array is empty.

         */

     public Object lastObject ()

     {

             int i;

             if ( (i = list.size()) == 0 ) return null;

             return list.get( i - 1 );

     }

         /**

         * 

         */

 /*

     public NSArray sortedArrayUsingSelector (NSSelector);

 */

         /**

         * Returns an array comprised of only those elements whose

         * indices fall within the specified range.

         */

     public NSArray subarrayWithRange (NSRange aRange)

     {

             //TODO: Test this logic.

             NSArray result = new NSArray();

             if ( aRange == null ) return result;

             int loc = aRange.location();

             int max = aRange.maxRange();

         int count = count();

             for ( int i = loc; i <= max && i < count; i++ )

             {

                     result.protectedAdd( list.get( i ) );

             }

             return result;

     }

         /**

         * Returns an enumeration over the the elements of the array.

         */

     public Enumeration objectEnumerator ()

     {

             //TODO: Test this logic.

             return new Enumeration()

                 {

                     Iterator it = NSArray.this.iterator(); 

                     public boolean hasMoreElements()

                     {

                                 return it.hasNext();

                     }

                     public Object nextElement()

                     {

                             return it.next();

                     }

             };

         }

         /**

         * Returns an enumeration over the elements of the array in reverse order.

         */

     public java.util.Enumeration reverseObjectEnumerator ()

     {

             return new java.util.Enumeration()

             {

                     ListIterator it = null;

                     public ListIterator getIterator()

                     {

                             if ( it == null )

                             {

                     it = NSArray.this.listIterator();

                     // zoom to end

                     while ( it.hasNext() ) it.next();

                                 }

                                 return it;

                     }

                     public boolean hasMoreElements()

                     {

                                 return getIterator().hasPrevious();

                     }

                     public Object nextElement()

                     {

                             return getIterator().previous();

                     }

             };

         }

         /**

         * Copies the elements of this array into the specified object array

         * as the array's capacity permits.

         */

     public void getObjects (Object[] anArray)

     {

             getObjects(anArray,null);

     }

         /**

         * Copies the elements of this array that fall within the specified range

         * into the specified object array as the array's capacity permits. This

         * method must not overflow, even in the face of a null range, an over or

         * under-sized array, or a bad range.  It may underflow and fail to 

         * entirely populate the array, if the array is larger than the data to 

         * be copied.

         * 

         * TODO: Check whether in WebObjects the range supposed to be measured against the parameter or the NSArray itself??? -ceg

         * 

         * @param anArray An object array to be filled by this method.

         * @param range An NSRange object representing the range of data in the NSArray to be copied.

         */

     public void getObjects (Object[] array, NSRange range)

     {

             if ( array == null ) return;

             if ( range == null) range = new NSRange(0,array.length);

             int limit = Math.min(Math.min(array.length,range.length()),(count()-range.location()));

             for ( int i = 0; i < limit ; i++ ) {

                     //anArray[ i-aRange.location() ] = objectAtIndex( i );

                     array[ i ] = objectAtIndex( range.location() + i );

             }

     }

         /**

         * Returns the index of the first object in the array equivalent

         * to the specified object.  Returns NotFound if the item is not found.

         */

     public int indexOfObject (Object anObject)

     {

             int result = list.indexOf( anObject );

             if ( result == -1 ) return NotFound; // in case this changes

             return result;

     }

         /**

         * Returns the index of the first object in the array 

         * within the specified range equivalent to the specified object.

         * Returns NotFound if the item is not found.

         */

     public int indexOfObject (Object anObject, NSRange aRange)

     {

             if ( ( anObject == null ) || ( aRange == null ) ) return NotFound;

             int loc = aRange.location();

             int max = aRange.maxRange();

             for ( int i = loc; i < max; i++ )

             {

                     if ( anObject.equals( list.get(i) ) )

                     {

                             return i;

                     }

             }

             return NotFound;

     }

         /**

         * Returns the index of the specified object if it exists

         * in the array, comparing by reference.

         * Returns NotFound if the item is not found.

         */

     public int indexOfIdenticalObject (Object anObject)

     {

         int size = list.size();

             for ( int i = 0; i < size; i++ )

             {

                     if ( anObject == list.get(i) )

                     {

                             return i;

                     }

             }

             return NotFound;

     }

         /**

         * Returns the index of the first object in the array 

         * within the specified range equivalent to the specified object.

         */

     public int indexOfIdenticalObject (Object anObject, NSRange aRange)

     {

             if ( aRange == null ) return NotFound;

             int loc = aRange.location();

             int max = aRange.maxRange();

             for ( int i = loc; i < max; i++ )

             {

                     if ( anObject == list.get(i) )

                     {

                             return i;

                     }

             }

             return NotFound;

     }

         /**

         * Returns the object at the specified index.  Throws an

         * IndexOutOfRange exception if the index is out of range.

         */

     public Object objectAtIndex (int anIndex)

     {

             return list.get( anIndex );

     }

         /**

         * Returns an array consisting of strings within the specified string

         * as delimited by the specified separator characters. 

         */

     public static NSArray componentsSeparatedByString 

             (String aString, String aSeparator)

     {

             NSArray result = new NSArray();

             if ( aString == null ) return result;

             if ( aSeparator == null ) return new NSArray( aString );

         //FIXME: The spec probably considers the whole

         // string as a separator, unlike string tokenizer.

             java.util.StringTokenizer tokens = 

                     new java.util.StringTokenizer( aString, aSeparator );

             while ( tokens.hasMoreTokens() )

             {

                     result.protectedAdd( tokens.nextToken() );

             }

             return result;

     }

     public Object clone()

     {

         return new NSArray( list );

     }

     public NSArray immutableClone()

     {

         return this;

     }

     public NSMutableArray mutableClone()

     {

         return new NSMutableArray( this );

     }

     public String toString() {

         StringBuffer buf = new StringBuffer();

         buf.append(NSPropertyListSerialization.TOKEN_BEGIN[NSPropertyListSerialization.PLIST_ARRAY]);

         for (int i = 0; i < count(); i++) {

             Object x = objectAtIndex(i);

             buf.append(NSPropertyListSerialization.stringForPropertyList(x));

             if (i < count() - 1)

                 buf.append(", ");

         }

         buf.append(NSPropertyListSerialization.TOKEN_END[NSPropertyListSerialization.PLIST_ARRAY]);

         return buf.toString();

     }

     // interface List: accessors

     public boolean contains(Object o) { return list.contains(o); }

     public boolean containsAll(Collection c) { return list.containsAll(c); }

     public boolean equals(Object o) { return list.equals(o); }

     public Object get(int index) { return list.get(index); }

     public int hashCode() { 

             int code = 19;

             code *= getClass().hashCode();

             code *= list.hashCode();

             return code;

     }

     public int indexOf(Object o) { return list.indexOf(o); }

     public boolean isEmpty() { return list.isEmpty(); }

     public int lastIndexOf(Object o) { return list.lastIndexOf(o); }

         public int size() { return list.size(); }

     public Object[] toArray() { return list.toArray(); }

     public Object[] toArray(Object[] a) { return list.toArray(a); }

     // interface List: mutators

         public void add(int index, Object element) 

     {

                 this.list.add(index,element);

     }

         public boolean add(Object o)

     {

                 return this.list.add(o);

     }

         public boolean addAll(Collection coll) 

     {

             return this.list.addAll(coll);

     }

         public boolean addAll(int index, Collection c) 

     {

                 return this.list.addAll(index,c);

     }

         public void clear() 

     {

                 this.list.clear();

     }

         public Iterator iterator() 

     {

         // make a copy to avoid ConcurrentModificationExceptions

         final Iterator i = new LinkedList( list ).iterator();

             return new Iterator() 

         {

             public boolean hasNext() {return i.hasNext();}

             public Object next()          {return i.next();}

             public void remove() { throw new UnsupportedOperationException(); }

         };

     }

         public ListIterator listIterator() { return listIterator(0); }

         public ListIterator listIterator(final int index) 

     {

         // make a copy to avoid ConcurrentModificationExceptions

         final ListIterator i = new LinkedList( list ).listIterator(index);

             return new ListIterator() 

         {

             public boolean hasNext()     {return i.hasNext();}

             public Object next()         {return i.next();}

             public boolean hasPrevious() {return i.hasPrevious();}

             public Object previous()     {return i.previous();}

             public int nextIndex()       {return i.nextIndex();}

             public int previousIndex()   {return i.previousIndex();}

             public void remove() { throw new UnsupportedOperationException(); }

             public void set(Object o) { throw new UnsupportedOperationException(); }

             public void add(Object o) { throw new UnsupportedOperationException(); }

             };

         }

         public Object remove(int index) 

     {

                 return this.list.remove(index);

     }

         public boolean remove(Object o) 

     {

                 return this.list.remove(o);

     }

         public boolean removeAll(Collection coll) 

     {

                 return this.list.removeAll(coll);

     }

         public boolean retainAll(Collection coll) 

     {

                 return this.list.retainAll(coll);

     }

     public Object set(int index, Object element) 

     {

             return this.list.set(index,element);

     }

     public List subList(int fromIndex, int toIndex) 

     {

         return Collections.unmodifiableList(list.subList(fromIndex, toIndex));

     }

     /**

     * Provided for the use of subclasses like ArrayFault.

     */

     protected boolean protectedAdd( Object o )

     {

         return list.add( o );

     }

     /**

     * Provided for the use of subclasses like ArrayFault.

     */

     protected boolean protectedAddAll( Collection coll )

     {

         return list.addAll( coll );

     }

 }

 /*

  * $Log$

  * Revision 1.2  2006/03/10 00:52:27  cgruber

  * Add tests for NSArray and fix some problems that became obvious as a result.

  *

  * Revision 1.1  2006/02/16 12:47:16  cgruber

  * Check in all sources in eclipse-friendly maven-enabled packages.

  *

  * Revision 1.16  2005/07/13 14:12:44  cgruber

  * Add mutableClone() and immutableClone()  per. WebObjects 5.3 conformance.

  *

  * Revision 1.15  2003/08/06 23:07:52  chochos

  * general code cleanup (mostly, removing unused imports)

  *

  * Revision 1.14  2003/08/05 00:48:56  chochos

  * use NSPropertyListSerialization to get the opening and closing tokens for the string representation

  *

  * Revision 1.13  2003/08/04 20:26:10  chochos

  * use NSPropertyListSerialization inside toString()

  *

  * Revision 1.12  2003/08/04 18:18:43  chochos

  * toString() yields strings in the same format as Apple's NSArray

  *

  * Revision 1.11  2003/01/28 19:44:20  mpowers

  * Fixed reverse enumerator.

  *

  * Revision 1.10  2003/01/18 23:49:55  mpowers

  * Added mutableClone().

  *

  * Revision 1.9  2003/01/18 23:30:42  mpowers

  * WODisplayGroup now compiles.

  *

  * Revision 1.8  2003/01/16 22:47:30  mpowers

  * Compatibility changes to support compiling woextensions source.

  * (34 out of 56 classes compile!)

  *

  * Revision 1.7  2003/01/10 19:16:40  mpowers

  * Implemented support for page caching.

  *

  * Revision 1.6  2002/10/24 21:15:36  mpowers

  * New implementations of NSArray and subclasses.

  *

  * Revision 1.5  2002/10/24 18:16:30  mpowers

  * Now enforcing NSArray's immutable nature.

  *

  * Revision 1.4  2002/03/08 19:02:54  mpowers

  * Long-overdue speed optimization of indexOfIdenticalObject.

  *

  * Revision 1.3  2002/02/13 22:02:56  mpowers

  * Fixed: bug in componentsSeparatedByString when separator is null

  * (thanks to Cedrik LIME).

  *

  * Revision 1.2  2001/01/11 20:34:26  mpowers

  * Implemented EOSortOrdering and added support in framework.

  * Added header-click to sort table columns.

  *

  * Revision 1.1.1.1  2000/12/21 15:47:26  mpowers

  * Contributing wotonomy.

  *

  * Revision 1.3  2000/12/20 16:25:37  michael

  * Added log to all files.

  *

  *

  */