/*

  Copyright 2004-2008 Paul R. Holser, Jr.  All rights reserved.

  Licensed under the Academic Free License version 3.0

  */

 package jaggregate;

 import java.util.Iterator;

 import java.util.NoSuchElementException;

 import static jaggregate.internal.ArgumentChecks.*;

 import static jaggregate.internal.UnaryConditions.*;

 /**

  * Functions that offer {@linkplain Collection}-like functionality for

  * {@linkplain Iterable}s.

  *

  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>

  * @version $Id: Iterables.java,v 1.8 2008/10/03 19:01:23 pholser Exp $

  */

 public class Iterables {

     /**

      * Discourages instantiation.

      *

      * @throws UnsupportedOperationException always

      */

     protected Iterables() {

         throw new UnsupportedOperationException();

     }

     /**

      * Answers {@code true} if the given discriminator answers {@code true} for every

      * element yielded by the given iterable, or if the iterable yields no elements;

      * otherwise answers {@code false}.

      * <p/>

      * It is unspecified whether {@code discriminator} will be evaluated with every

      * element that the iterable yields.

      *

      * @param <E> type of the items to iterate over

      * @param items the items to iterate over

      * @param discriminator the discriminator to evaluate

      * @return whether {@code discriminator} is {@code true} for every element

      * @throws NullPointerException if {@code items} or {@code discriminator}

      * is {@code null}

      * @see Collection#allSatisfy(UnaryCondition)

      */

     public static <E> boolean allSatisfy( Iterable<? extends E> items,

         UnaryCondition<? super E> discriminator ) {

         ensureNotNull( discriminator, DISCRIMINATOR );

         for ( E each : items ) {

             if ( !discriminator.matches( each ) )

                 return false;

         }

         return true;

     }

     /**

      * Answers {@code true} if the given discriminator answers {@code true} for any

      * element yielded by the given iterable; answers {@code false} otherwise, or if the

      * iterable yields no elements.

      * <p/>

      * It is unspecified whether {@code discriminator} will be evaluated with every

      * element that the iterable yields.

      *

      * @param <E> type of the items to iterate over

      * @param items the items to iterate over

      * @param discriminator the discriminator to evaluate

      * @return whether {@code discriminator} is {@code true} for any element

      * @throws NullPointerException if {@code items} or {@code discriminator}

      * is {@code null}

      * @see Collection#anySatisfy(UnaryCondition)

      */

     public static <E> boolean anySatisfy( Iterable<? extends E> items,

         UnaryCondition<? super E> discriminator ) {

         ensureNotNull( discriminator, DISCRIMINATOR );

         for ( E each : items ) {

             if ( discriminator.matches( each ) )

                 return true;

         }

         return false;

     }

     /**

      * Wraps the given iterable with another iterable whose iterator will transform

      * items using the given functor.

      *

      * @param <E> type of the items to iterate over

      * @param <R> type of the transformed iterated items

      * @param items the iterable to wrap

      * @param transformer functor used to transform elements

      * @return the wrapping, transforming iterable

      * @throws NullPointerException if {@code items} or {@code transformer} is

      * {@code null}

      * @see Collection#collect(UnaryFunctor)

      */

     public static <E, R> Iterable<R> collect( final Iterable<? extends E> items,

         final UnaryFunctor<? super E, ? extends R> transformer ) {

         ensureNotNull( items, ITERABLE );

         ensureNotNull( transformer, TRANSFORMER );

         return new Iterable<R>() {

             public Iterator<R> iterator() {

                 return new TransformingIterator<E, R>( items.iterator(), transformer );

             }

         };

     }

     /**

      * Answers the first element yielded by the given iterable for which the given

      * discriminator answers {@code true} when given that element as an argument.

      * <p/>

      * {@code discriminator} will only be evaluated until such an object is found or

      * until the iterable yields no elements to use as arguments.  That is, there may

      * be elements that the iterable yields that are never used as arguments to

      * {@code discriminator}.

      *

      * @param <E> type of the items to iterate over

      * @param items the items to iterate over

      * @param discriminator the discriminator to evaluate

      * @return the first item that satisfies {@code discriminator}

      * @throws java.util.NoSuchElementException if no item satisfies

      * {@code discriminator}

      * @throws NullPointerException if {@code items} or {@code discriminator} is

      * {@code null}

      */

     public static <E> E detect( Iterable<? extends E> items,

         UnaryCondition<? super E> discriminator ) {

         ensureNotNull( discriminator, DISCRIMINATOR );

         for ( E each : items ) {

             if ( discriminator.matches( each ) )

                 return each;

         }

         throw new NoSuchElementException();

     }

     /**

      * Answers the number of elements yielded by the given iterable which are equivalent

      * to the given target.

      *

      * @param <E> type of the items to iterate over

      * @param items the items to iterate over

      * @param target the object to compare against

      * @return the number of occurrences of equivalent objects yielded by the iterable

      * @throws NullPointerException if {@code items} is {@code null}

      */

     public static <E> int occurrencesOf( Iterable<? extends E> items, E target ) {

         int occurrences = 0;

         for ( E each : items ) {

             if ( Objects.areEqual( each, target ) )

                 ++occurrences;

         }

         return occurrences;

     }

     /**

      * Answers the final result of evaluating the given operation using each element of

      * the given iterable and the previous evaluation result as the parameters.

      * <p/>

      * The first evaluation of {@code operation} is performed with the given initial

      * value as the first parameter, and the first element of the iterable as the second

      * parameter.  Subsequent evaluations are done with the result of the previous

      * evaluation as the first parameter, and the next element as the second parameter.

      * The result of the last evaluation is answered.

      *

      * @param <E> type of the items to iterate over

      * @param <R> type of the initial value, intermediate results, and final result

      * @param items the items to iterate over

      * @param initialValue first parameter for the first evaluation

      * @param operation the operation to evaluate

      * @return the result of the last evaluation

      * @throws NullPointerException if {@code items} or {@code operation} is {@code null}

      * @see Collection#inject(Object, BinaryFunctor)

      */

     public static <E, R> R inject( Iterable<? extends E> items, R initialValue,

         BinaryFunctor<? super R, ? super E, ? extends R> operation ) {

         ensureNotNull( operation, OPERATION );

         R result = initialValue;

         for ( E each : items )

             result = operation.evaluate( result, each );

         return result;

     }

     /**

      * Removes items from the given iterable which match the given predicate.

      *

      * @param <E> type of the items to iterate over

      * @param items items to iterate over

      * @param discriminator tells which items should be removed

      * @return {@code true} if any removals occurred

      * @throws NullPointerException if {@code items} or {@code discriminator}

      * is {@code null}

      * @throws UnsupportedOperationException if {@code items}'s iterator does not

      * support removal

      * @see ExtensibleCollection#removeIf(UnaryCondition)

      */

     public static <E> boolean removeIf( Iterable<? extends E> items,

         UnaryCondition<? super E> discriminator ) {

         ensureNotNull( discriminator, DISCRIMINATOR );

         boolean removalsOccurred = false;

         for ( Iterator<? extends E> it = items.iterator(); it.hasNext(); ) {

             if ( discriminator.matches( it.next() ) ) {

                 it.remove();

                 removalsOccurred = true;

             }

         }

         return removalsOccurred;

     }

     /**

      * Removes items from the given iterable which do not match the given predicate.

      *

      * @param <E> type of the items to iterate over

      * @param items items to iterate over

      * @param discriminator tells which items should be retained

      * @return {@code true} if any removals occurred

      * @throws NullPointerException if {@code items} or {@code discriminator}

      * is {@code null}

      * @throws UnsupportedOperationException if {@code items}'s iterator does not

      * support removal

      * @see ExtensibleCollection#retainIf(UnaryCondition)

      */

     public static <E> boolean retainIf( Iterable<? extends E> items,

         UnaryCondition<? super E> discriminator ) {

         return removeIf( items, not( discriminator ) );

     }

     /**

      * Wraps the given iterable with another iterable whose iterator will filter

      * out items which do not match the given predicate.

      *

      * @param <E> type of the items to iterate over

      * @param items the iterable to wrap

      * @param discriminator predicate used to filter elements

      * @return the wrapping, filtering iterable

      * @throws NullPointerException if {@code items} or {@code discriminator} is

      * {@code null}

      * @see Collection#select(UnaryCondition)

      */

     public static <E> Iterable<E> select( final Iterable<? extends E> items,

         final UnaryCondition<? super E> discriminator ) {

         ensureNotNull( items, ITERABLE );

         ensureNotNull( discriminator, DISCRIMINATOR );

         return new Iterable<E>() {

             public Iterator<E> iterator() {

                 return new SelectingIterator<E>( items.iterator(), discriminator );

             }

         };

     }

     private static class SelectingIterator<E> implements Iterator<E> {

         private final Iterator<? extends E> wrapped;

         private final UnaryCondition<? super E> discriminator;

         private boolean askedHasNext;

         private boolean hasNext = true;

         private E current = null;

         SelectingIterator( Iterator<? extends E> wrapped,

             UnaryCondition<? super E> discriminator ) {

             this.wrapped = wrapped;

             this.discriminator = discriminator;

         }

         /**

          * {@inheritDoc}

          */

         public boolean hasNext() {

             askedHasNext = true;

             advance();

             return hasNext;

         }

         /**

          * {@inheritDoc}

          */

         public E next() {

             if ( !askedHasNext )

                 advance();

             if ( !hasNext )

                 throw new NoSuchElementException();

             return current;

         }

         /**

          * {@inheritDoc}

          */

         public void remove() {

             throw new UnsupportedOperationException();

         }

         private void advance() {

             while ( wrapped.hasNext() ) {

                 current = wrapped.next();

                 if ( discriminator.matches( current ) )

                     return;

             }

             hasNext = false;

         }

     }

     private static class TransformingIterator<E, R> implements Iterator<R> {

         private Iterator<? extends E> wrapped;

         private UnaryFunctor<? super E, ? extends R> transformer;

         TransformingIterator( Iterator<? extends E> wrapped,

             UnaryFunctor<? super E, ? extends R> transformer ) {

             this.wrapped = wrapped;

             this.transformer = transformer;

         }

         /**

          * {@inheritDoc}

          */

         public boolean hasNext() {

             return wrapped.hasNext();

         }

         /**

          * {@inheritDoc}

          */

         public R next() {

             return transformer.evaluate( wrapped.next() );

         }

         /**

          * {@inheritDoc}

          */

         public void remove() {

             throw new UnsupportedOperationException();

         }

     }

 }