package org.litesoft.core.util;

import java.util.*;

// Copyright Status:
//
// All Software available from LiteSoft.org (including this file) is
// hereby released into the public domain.
//
// It is free!  As in, you may use it freely in both commercial and
// non-commercial applications, bundle it with your software
// distribution, include it on a CD-ROM, list the source code in a book,
// mirror the documentation at your own web site, or use it in any other
// way you see fit.
//
// NO Warranty!
//
// All software is provided "as is".
//
// There is ABSOLUTELY NO WARRANTY OF ANY KIND: not for the design, fitness
// (for a particular purpose), level of errors (or lack thereof), or
// applicability of this software.  The entire risk as to the quality
// and performance of this software is with you.  Should this software
// prove defective, you assume the cost of all necessary servicing, repair
// or correction.
//
// In no event unless required by applicable law or agreed to in writing
// will any party who created or may modify and/or redistribute this
// software, be liable to you for damages, including any general,
// special, incidental or consequential damages arising out of the use or
// inability to use this software (including but not limited to loss of
// data or data being rendered inaccurate or losses sustained by you or
// third parties or a failure of this software to operate with any
// other programs), even if such holder or other party has been advised
// of the possibility of such damages.
//
// NOTE: Should you discover a bug, have a recogmendation for a change, wish
// to submit modifications, or wish to add new classes/functionality,
// please email them to:
//
//        changes@litesoft.org
//

/**
 * An Iterator (Read-Only) of an Array.<p>
 * <p/>
 * While this same functionality is provided by
 * Arrays.asList(array).iterator(), the tendency would be to
 * return Arrays.asList(array).  While the returned List does
 * NOT allow adds or removes, it unfortunately DOES
 * support set().  This means that the underlying Array
 * CAN BE modified.  Besides, if you don't want the List
 * object, but just the Iterator, why create it.
 *
 * @author George Smith
 * @version 1.0 7/28/01
 */

public class ArrayIterator<T> extends AbstractReadOnlyIterator<T>
{
    /**
     * Construct an Iterator for an Array.<p>
     *
     * @param pArray the Array to Iterate thru (null OK).
     */
    public ArrayIterator( T[] pArray )
    {
        this( "ArrayIterator", pArray );
    }

    /**
     * Super class constructor for an Iterator for an Array.<p>
     *
     * @param pInteratorName the Name for this Iterator (for toString) (null questionable).
     * @param pArray         the Array to Iterate thru (null OK).
     */
    protected ArrayIterator( String pInteratorName, T[] pArray )
    {
        zInteratorName = pInteratorName;
        arrayLen = ((zArray = pArray) == null) ? 0 : pArray.length;
    }

    private String zInteratorName;
    private T[] zArray;
    private int arrayLen, index = 0;

    /**
     * Returns <tt>true</tt>/<tt>false</tt>, depending on IF there is a
     * <i>current</i> object that <i>next()</i> will return.<p>
     *
     * @return If there is an Object available via <i>next()</i>.<p>
     *
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html#hasNext()">java.util.Iterator#hasNext()</a>
     */
    public final boolean hasNext()
    {
        return (index < arrayLen);
    }

    /**
     * Return the <i>current</i> object and advance the <i>underlying</i>
     * pointer/index.  If there is no <i>current</i> object, then a
     * NoSuchElementException is thrown.<p>
     *
     * @throws NoSuchElementException if nothing to return.<p>
     * @see <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Util/Iterator.html#next()">java.util.Iterator#next()</a>
     */
    public final T next()
    {
        if ( hasNext() )
        {
            return zArray[index++];
        }
        throw new NoSuchElementException();
    }

    /**
     * Returns a debug/human friendly String that represents this.<p>
     *
     * @return A String representation of this.
     */
    public final String toString()
    {
        StringBuilder sb = new StringBuilder( zInteratorName );
        sb.append( ": " );
        if ( zArray == null )
        {
            sb.append( "null" );
        }
        else
        {
            sb.append( arrayLen );
            sb.append( " elements" );
            if ( !hasNext() )
            {
                sb.append( " AT END (NO MORE ELEMENTS)" );
            }
            if ( arrayLen != 0 )
            {
                sb.append( '\n' );
                for ( int i = 0; i < arrayLen; i++ )
                {
                    T entry = zArray[i];
                    sb.append( (i == index) ? " -> [" : "    [" );
                    sb.append( (entry == null) ? "?null?" : entry.toString() );
                    sb.append( "]\n" );
                }
            }
        }
        return sb.toString();
    }
}