// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.core.util;

import java.util.*;

/**
 * An Iterator Helper class.  Optimally, SUN/Java would have provided a
 * seamless mechanism to add behavior/functionality to a class while
 * preserving the syntactic cleanliness of the usage.<p>
 * <p/>
 * An example from this file would be:<p>
 * <pre>
 *          IteratorHelper.toString( iterator , label ) ;
 *      could have been replaced with:
 *          iterator.toString( label ) ;
 * </pre><p>
 *
 * Instead, we are left to create this class (with its clumsy usage).
 * Each method's first parameter is the <i>Iterator</i> that would have
 * been automatically passed in as <i>this</i>.
 * Note: As these would all be <i>instance</i> methods, the first
 * parameter may NOT be <i>null</i>.<p>
 *
 * When the first parameter can be null, by convention, I place these
 * methods in a aaaUtil class.<p>
 *
 * See <a href="IteratorUtil.html">IteratorUtil</a><p>
 *
 * This class is non-instantiable.<p>
 *
 * @author George Smith
 * @version 1.0 7/28/01
 */

public class IteratorHelper
{
    private IteratorHelper()
    {
    }

    /**
     * Returns a debug/human friendly <i>label</i>ed String that represents
     * the <i>iterator</i>.<p>
     *
     * @param pIterator the Iterator to dump (!null).
     * @param pLabel    the label for the Iterator (null OK).<p>
     *
     * @return A <i>label</i>ed String that represents <i>iterator</i>.
     */
    public static String toString( Iterator pIterator, String pLabel )
            throws NullPointerException
    {
        StringBuilder sbElements = new StringBuilder();
        int elements = 0;
        if ( pIterator.hasNext() )
        {
            sbElements.append( '\n' );
            while ( pIterator.hasNext() )
            {
                elements++;
                Object entry = pIterator.next();
                sbElements.append( "    [" );
                sbElements.append( (entry == null) ? "?null?" : entry.toString() );
                sbElements.append( "]\n" );
            }
        }
        StringBuilder sb = new StringBuilder();
        if ( pLabel != null )
        {
            sb.append( pLabel );
            sb.append( ": " );
        }
        sb.append( elements );
        sb.append( " elements" );
        sb.append( sbElements.toString() );
        return sb.toString();
    }
}