/*

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

  Licensed under the Academic Free License version 3.0

  */

 package jaggregate;

 /**

  * Provides protocol for writing to an ordered collection of objects whose

  * <dfn>elements</dfn> can be accessed using external integer <dfn>keys</dfn>.

  *

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

  * sequence

  *

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

  * @version $Id: Sequence.java,v 1.4 2008/05/07 06:00:48 pholser Exp $

  */

 public interface Sequence<E> extends ReadOnlySequence<E> {

     /**

      * {@inheritDoc}

      *

      * @return a sequence of transformations

      */

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

     /**

      * {@inheritDoc}

      *

      * @return a sequence of rejects

      */

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

     /**

      * {@inheritDoc}

      *

      * @return a sequence of selections

      */

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

     /**

      * {@inheritDoc}

      */

     Sequence<E> concat( ReadOnlySequence<? extends E> otherSequence );

     /**

      * {@inheritDoc}

      */

     Sequence<E> copyRange( int start, int stop );

     /**

      * {@inheritDoc}

      */

     Sequence<E> copyWith( E newElement );

     /**

      * {@inheritDoc}

      */

     Sequence<E> copyWithout( E oldElement );

     /**

      * {@inheritDoc}

      */

     Sequence<E> reverse();

     /**

      * Replaces the element in this sequence at a given index with a new element.

      *

      * @param index the index at which to replace the element

      * @param newElement the element to place at {@code index}

      * @return the previous element at {@code index}, or {@code null} if there is

      * no such element

      * @throws IndexOutOfBoundsException if {@code index < 0} or {@code index >=} this

      * sequence's {@linkplain #size() size}

      */

     E putAt( int index, E newElement );

     /**

      * Replaces the elements in this sequence specified by the given indices with a new

      * element.

      * <p/>

      * This message is equivalent to storing {@code newElement} in this sequence at

      * each index specified by {@code indices} using {@link #putAt(int,Object) putAt}.

      *

      * @param indices the indices at which to replace elements

      * @param newElement the element to place at each of the {@code indices}

      * @throws NullPointerException if {@code indices} or any of its elements is

      * {@code null}

      * @throws IndexOutOfBoundsException if any element of {@code indices} is

      * {@code < 0} or {@code >=} this sequence's {@linkplain #size() size}

      */

     void putAtAll( Collection<? extends Integer> indices, E newElement );

     /**

      * @see #putAtAll(Collection,Object)

      * @param indices the indices at which to replace elements

      * @param newElement the element to place at each of the {@code indices}

      * @throws NullPointerException if {@code indices} or any of its elements is

      * {@code null}

      * @throws IndexOutOfBoundsException if any element of {@code indices} is

      * {@code < 0} or {@code >=} this sequence's {@linkplain #size() size}

      */

     void putAtAll( int[] indices, E newElement );

     /**

      * @param indices the indices at which to replace elements

      * @param newElement the element to place at each of the {@code indices}

      * @throws NullPointerException if {@code indices} or any of its elements is

      * {@code null}

      * @throws IndexOutOfBoundsException if any element of {@code indices} is

      * {@code < 0} or {@code >=} this sequence's {@linkplain #size() size}

      * @see #putAtAll(Collection,Object)

      */

     void putAtAll( Integer[] indices, E newElement );

     /**

      * @see #putAtAll(Collection,Object)

      * @param indices the indices at which to replace elements

      * @param newElement the element to place at each of the {@code indices}

      * @throws NullPointerException if {@code indices} or any of its elements is

      * {@code null}

      * @throws IndexOutOfBoundsException if any element of {@code indices} is

      * {@code < 0} or {@code >=} this sequence's {@linkplain #size() size}

      */

     void putAtAll( Iterable<? extends Integer> indices, E newElement );

     /**

      * Replaces all the elements in this sequence with a new element.

      * <p/>

      * This message is equivalent to storing {@code newElement} in this sequence at each

      * index from {@code 0} to this sequence's {@linkplain #size() size} minus 1 using

      * {@link #putAt(int,Object) putAt}.

      *

      * @param newElement the element to place at each index

      */

     void putAtAll( E newElement );

     /**

      * Replaces the elements of this sequence between two positions, inclusive, with a

      * given element.

      *

      * @param start beginning index

      * @param stop ending index

      * @param replacement element with which to replace the elements between

      * {@code start} and {@code stop}, inclusive

      * @throws IndexOutOfBoundsException if either {@code start} or {@code stop} is

      * {@code < 0} or {@code >=} this sequence's {@linkplain #size() size}

      */

     void replace( int start, int stop, E replacement );

     /**

      * Replaces the elements of this sequence between two positions, inclusive, with a

      * given replacement sequence in their original order.

      * <p/>

      * The first element of {@code replacements} is stored in this sequence at position

      * {@code start}, the second at position {@code start + 1}, etc.  Any previously

      * stored elements at these positions are replaced.

      * <p/>

      * @param start beginning index

      * @param stop ending index

      * @param replacements elements to replace in between {@code start} and

      * {@code stop}, inclusive

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

      * @throws IndexOutOfBoundsException if either {@code start} or {@code stop} is

      * {@code < 0} or {@code >=} this sequence's {@linkplain #size() size}

      * @throws IllegalArgumentException if the {@linkplain #size() size} of

      * {@code replacements} is not equal to {@code stop - start + 1}

      */

     void replaceRange( int start, int stop, ReadOnlySequence<? extends E> replacements );

     /**

      * Replaces the elements of this sequence between two positions, inclusive, with a

      * given replacement sequence, in their original order, starting at a given

      * position in the replacement sequence.

      * <p/>

      * The element at position {@code replacementStart} in {@code replacements}

      * is stored in this sequence at position {@code start}; the element at

      * {@code replacementStart + 1} is stored at position {@code start + 1}; etc.

      * Any previously stored elements at these positions are replaced.

      *

      * @param start beginning index

      * @param stop ending index

      * @param replacements elements to replace in between {@code start} and

      * {@code stop}, inclusive

      * @param replacementStart index to start at in {@code replacements}

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

      * @throws IndexOutOfBoundsException if either {@code start} or {@code stop} is

      * {@code < 0} or {@code >=} this sequence's {@linkplain #size() size}, or if

      * {@code replacementStart} is {@code < 0} or {@code >=} {@code replacements}'s

      * {@linkplain #size() size}

      * @throws IllegalArgumentException if the {@linkplain #size() size} of

      * {@code replacements} is not equal to {@code replacementStart + stop - start}

      */

     void replaceRange( int start, int stop, ReadOnlySequence<? extends E> replacements,

         int replacementStart );

 }