/*

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

  Licensed under the Academic Free License version 3.0

  */

 package jaggregate;

 /**

  * Provides protocol for removing <dfn>elements</dfn> from an ordered collection of

  * objects, whose elements can be accessed using external <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: ContractibleSequence.java,v 1.4 2008/05/07 06:00:49 pholser Exp $

  */

 public interface ContractibleSequence<E> extends Collection<E> {

     /**

      * {@inheritDoc}

      *

      * @return a contractible sequence of the transformations

      */

     <R> ContractibleSequence<R> collect(

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

     /**

      * {@inheritDoc}

      *

      * @return a contractible sequence of the rejected elements of this sequence

      */

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

     /**

      * {@inheritDoc}

      *

      * @return a contractible sequence of the selected elements of this sequence

      */

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

     /**

      * Removes and answers the element at a given position in this sequence.

      *

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

      * @return the removed element

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

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

      */

     E removeAt( int index );

     /**

      * Removes and answers the first element of this sequence.

      *

      * @return the removed element

      * @throws java.util.NoSuchElementException if this sequence is

      * {@linkplain #isEmpty() empty}

      */

     E removeFirst();

     /**

      * Removes and answers the last element of this sequence.

      *

      * @return the removed element

      * @throws java.util.NoSuchElementException if this sequence is

      * {@linkplain #isEmpty() empty}

      */

     E removeLast();

 }