/*

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

  Licensed under the Academic Free License version 3.0

  */

 package jaggregate;

 import java.util.Comparator;

 /**

  * Provides protocol for manipulating and operating on a collection of objects, called

  * <dfn>elements</dfn>, either individually or as a whole.  A collection can be fixed or

  * variable-sized, ordered or unordered, and its elements may or may not be accessible

  * by external keys.

  * <p/>

  * Some implementations of collections may choose to use the {@linkplain Object#hashCode

  * hash} values of either the elements of the collection or the keys by which those

  * elements are accessed (if there are any).  If the hash values of such objects are

  * modified, the behavior of any message sent to such a collection is undefined until

  * the collection is {@linkplain #rehash() rehashed} in order to restore its

  * consistency.

  *

  * @param <E> a restriction on the types of elements that may be included in the

  * collection

  *

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

  * @version $Id: Collection.java,v 1.7 2008/05/12 23:49:07 pholser Exp $

  */

 public interface Collection<E> {

     /**

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

      * element of this collection, or if this collection is {@linkplain #isEmpty()

      * empty}; otherwise answers {@code false}.

      * <p/>

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

      * element of this collection.

      *

      * @param discriminator the discriminator to evaluate

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

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

      */

     boolean allSatisfy( UnaryCondition<? super E> discriminator );

     /**

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

      * element of this collection; answers {@code false} otherwise, or if this

      * collection is {@linkplain #isEmpty() empty}.

      * <p/>

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

      * element of this collection.

      *

      * @param discriminator the discriminator to evaluate

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

      * @throws NullPointerException if the {@code discriminator} is {@code null}

      */

     boolean anySatisfy( UnaryCondition<? super E> discriminator );

     /**

      * Answers an array with the same elements as this collection, with the same

      * {@linkplain #size() size} as this collection, and a component class of

      * {@link Object}.  This means that objects of any class may be inserted into

      * the result.

      * <p/>

      * If this collection maintains an ordering for its elements, the order of those

      * elements will be preserved in the result.

      *

      * @return an array of this collection's elements

      * @see #toArray(Class)

      * @see Collections#toArray(Collection,Class)

      */

     Object[] toArray();

     /**

      * Answers an array with the same elements as this collection, with the same

      * {@linkplain #size() size} as this collection, and a component type of the given

      * class.  This means that only elements of the given class or any of its

      * derivatives may be inserted into the result.

      * <p/>

      * Note that even though the given class will be the runtime component class of the

      * result array, the return type of this method is {@code Object[]}.  With Java

      * generics, it is not possible to express the return type as an array of the

      * component class without sacrificing the flexibility of providing a

      * {@code componentClass} that is a supertype of the generic parameter's actual

      * argument.  Therefore, the caller should downcast to the desired type, or risk

      * raising {@link ArrayStoreException} when inserting via a reference of type

      * {@code Object[]}.

      * <p/>

      * If this collection maintains an ordering for its elements, the order of those

      * elements will be preserved in the result.

      *

      * @param componentClass the desired type of the result array's components

      * @return an array of this collection's elements

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

      * @see Collections#toArray(Collection,Class)

      */

     Object[] toArray( Class<? super E> componentClass );

     /**

      * Answers a bag with the same elements as this collection.

      *

      * @return a bag of this collection's elements

      */

     Bag<E> toBag();

     /**

      * Answers an identity bag with the same elements as this collection.

      *

      * @return a bag of this collection's elements

      */

     IdentityBag<E> toIdentityBag();

     /**

      * Answers an identity set with the same elements as this collection.  Since sets

      * do not store duplicate elements, the result may have fewer elements than this

      * collection.

      *

      * @return a set of this collection's elements

      */

     IdentitySet<E> toIdentitySet();

     /**

      * Answers an ordered collection with the same elements as this collection.

      * The result has the same {@linkplain #size() size} as this collection.

      * <p/>

      * If this collection maintains an ordering for its elements, the order of those

      * elements will be preserved in the result.

      *

      * @return an ordered collection of this collection's elements

      */

     OrderedCollection<E> toOrderedCollection();

     /**

      * Answers a set with the same elements as this collection.  Since sets do not store

      * duplicate elements, the result may have fewer elements than this collection.

      *

      * @return a set of this collection's elements

      */

     Set<E> toSet();

     /**

      * Answers a sorted collection with the same elements as this collection.  If this

      * collection has established an ordering on its elements, then that ordering is used

      * in the answer.  Otherwise, order of the elements is arbitrary--in such a case,

      * one should probably use the {@linkplain #toSortedCollection(Comparator) overload

      * of this method that accepts a comparator}.

      *

      * @return a sorted collection of this collection's elements

      */

     SortedCollection<E> toSortedCollection();

     /**

      * Answers a sorted collection with the same elements as this collection, using the

      * given comparator to order the elements.

      *

      * @param comparator a comparator

      * @return a sorted collection of this collection's elements

      */

     SortedCollection<E> toSortedCollection( Comparator<? super E> comparator );

     /**

      * Evaluates the given transformer for each element of this collection, with the

      * element as the parameter, and answers a new collection containing the results

      * of these evaluations.

      * <p/>

      * The elements are traversed in the order specified by {@link

      * #forEachDo(UnaryFunctor) forEachDo} for this collection.

      * <p/>

      * Unless specifically refined, this message is defined to answer an object

      * conforming to the same protocol as this collection.

      *

      * @param <R> return type of the transformer

      * @param transformer the transformer to evaluate

      * @return a collection of the transformations

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

      */

     <R> Collection<R> collect( UnaryFunctor<? super E, ? extends R> transformer );

     /**

      * Answers the first element of this collection 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 all of the elements of the collection have been used as arguments.

      * That is, there may be elements of this collection that are never used as

      * arguments to {@code discriminator}.

      * <p/>

      * The elements are traversed in the order specified by {@link

      * #forEachDo(UnaryFunctor) forEachDo} for this collection.

      *

      * @param discriminator the discriminator to evaluate

      * @return the first element of this collection that satisfies {@code discriminator}

      * @throws java.util.NoSuchElementException if no element of this collection

      * satisfies {@code discriminator}

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

      */

     E detect( UnaryCondition<? super E> discriminator );

     /**

      * For each element of this collection, evaluates the given operation with the

      * element as the parameter.

      * <p/>

      * Unless specifically refined, the elements are not traversed in a particular order.

      * Each element is visited exactly once.  Conformant protocols may refine this

      * message to specify a particular ordering.

      *

      * @param operation the operation to perform

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

      */

     void forEachDo( UnaryFunctor<? super E, ?> operation );

     /**

      * Answers {@code true} if an element of this collection is equivalent to the

      * given one; answers {@code false} otherwise.

      *

      * @param target the object to compare against

      * @return whether an equivalent object is in the collection

      */

     boolean includes( E target );

     /**

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

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

      * <p/>

      * If this collection is {@linkplain #isEmpty() empty}, answers the initial value.

      * <p/>

      * The elements are traversed in the order specified by {@link

      * #forEachDo(UnaryFunctor) forEachDo} for this collection.

      *

      * @param <R> return type and type of first argument of the operation

      * @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 operation} is {@code null}

      */

     <R> R inject( R initialValue,

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

     /**

      * Answers {@code true} iff this collection's {@linkplain #size() size} is zero;

      * otherwise answers {@code false}.

      *

      * @return whether this collection contains any elements

      */

     boolean isEmpty();

     /**

      * Answers the number of elements of this collection which are equivalent to

      * the given target.

      *

      * @param target the object to compare against

      * @return the number of occurrences of equivalent objects in this collection

      */

     int occurrencesOf( E target );

     /**

      * Re-establishes any hash invariants of this collection.

      */

     void rehash();

     /**

      * Answers a new collection which contains only the elements in this collection

      * which cause the given discriminator to answer {@code false}.

      * <p/>

      * For each element of this collection, {@code discriminator} is evaluated with the

      * element as the parameter.  Each element which causes {@code discriminator} to

      * answer {@code false} is included in the new collection.

      * <p/>

      * The elements are traversed in the order specified by {@link

      * #forEachDo(UnaryFunctor) forEachDo} for this collection.

      * <p/>

      * Unless specifically refined, this message is defined to answer an object

      * conforming to the same protocol as this collection.  If both this collection

      * and the result maintain an ordering of their elements, the elements of the

      * result will be in the same relative order as the elements of this collection.

      *

      * @param discriminator the discriminator to evaluate

      * @return a collection of the rejected elements of this collection

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

      */

     Collection<E> reject( UnaryCondition<? super E> discriminator );

     /**

      * Answers a new collection which contains only the elements in this collection

      * which cause the given discriminator to answer {@code true}.

      * <p/>

      * For each element of this collection, {@code discriminator} is evaluated with the

      * element as the parameter.  Each element which causes {@code discriminator} to

      * answer {@code true} is included in the new collection.

      * <p/>

      * The elements are traversed in order specified by {@link

      * #forEachDo(UnaryFunctor) forEachDo} for this collection.

      * <p/>

      * Unless specifically refined, this message is defined to answer an object

      * conforming to the same protocol as this collection.  If both this collection

      * and the result maintain an ordering of their elements, the elements of the

      * result will be in the same relative order as the elements of this collection.

      *

      * @param discriminator the discriminator to evaluate

      * @return a collection of the selected elements of this collection

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

      */

     Collection<E> select( UnaryCondition<? super E> discriminator );

     /**

      * Answers the number of elements in this collection.

      *

      * @return the number of elements in this collection

      */

     int size();

 }