jaggregate
Interface Sequence<E>

Type Parameters:

E - a restriction on the types of elements that may be included in the sequence

All Superinterfaces:

Collection<E>, ReadOnlySequence<E>

All Known Implementing Classes:

OrderedCollection

public interface Sequence<E>
extends ReadOnlySequence<E>

Provides protocol for writing to an ordered collection of objects whose elements can be accessed using external integer keys.

Version:

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

Author:

Paul Holser

Method Summary

<R> Sequence<R>	collect(UnaryFunctor<? super E,? extends R> transformer) 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.
Sequence<E>	concat(ReadOnlySequence<? extends E> otherSequence) Answers a new sequence containing all of this sequence's elements in their original order followed by all of the elements of the given sequence, in their original order.
Sequence<E>	copyRange(int start, int stop) Answers a new sequence containing the specified range of elements of this sequence in their original order.
Sequence<E>	copyWith(E newElement) Answers a new sequence with size one greater than the size of this sequence, containing the elements of this sequence and a given new element placed at the end.
Sequence<E>	copyWithout(E oldElement) Answers a new sequence with all of the elements of this sequence that are not equivalent to the given element, in their original order.
E	putAt(int index, E newElement) Replaces the element in this sequence at a given index with a new element.
void	putAtAll(Collection<? extends Integer> indices, E newElement) Replaces the elements in this sequence specified by the given indices with a new element.
void	putAtAll(E newElement) Replaces all the elements in this sequence with a new element.
void	putAtAll(int[] indices, E newElement)
void	putAtAll(Integer[] indices, E newElement)
void	putAtAll(Iterable<? extends Integer> indices, E newElement)
Sequence<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 false.
void	replace(int start, int stop, E replacement) Replaces the elements of this sequence between two positions, inclusive, with a given element.
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.
void	replaceRange(int start, int stop, ReadOnlySequence<? extends E> replacements, int replacementStart) 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.
Sequence<E>	reverse() Answers a sequence with the elements of this sequence arranged in reverse order.
Sequence<E>	select(UnaryCondition<? super E> discriminator) Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer true.

Methods inherited from interface jaggregate.ReadOnlySequence

after, at, before, doWithIndex, doWithOthers, findFirst, findLast, first, forEachDo, forEachInRangeDo, forEachInRangeDoWithIndex, forEachInReverseDo, indexOf, indexOf, last

Methods inherited from interface jaggregate.Collection

allSatisfy, anySatisfy, detect, includes, inject, isEmpty, occurrencesOf, rehash, size, toArray, toArray, toBag, toIdentityBag, toIdentitySet, toOrderedCollection, toSet, toSortedCollection, toSortedCollection

Method Detail

collect

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

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.

The elements are traversed in the order specified by forEachDo for this collection.

Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection.

Specified by:

collect in interface Collection<E>

Specified by:

collect in interface ReadOnlySequence<E>

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a sequence of transformations

reject

Sequence<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 false.

For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer false is included in the new collection.

The elements are traversed in the order specified by forEachDo for this collection.

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.

Specified by:

reject in interface Collection<E>

Specified by:

reject in interface ReadOnlySequence<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a sequence of rejects

select

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

Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer true.

For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer true is included in the new collection.

The elements are traversed in order specified by forEachDo for this collection.

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.

Specified by:

select in interface Collection<E>

Specified by:

select in interface ReadOnlySequence<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a sequence of selections

concat

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

Answers a new sequence containing all of this sequence's elements in their original order followed by all of the elements of the given sequence, in their original order. The size of the new sequence is equal to the sum of the sizes of this sequence and otherSequence.

Sequences that enforce an ordering on their elements are permitted to refine this message to reorder the result.

Specified by:

concat in interface ReadOnlySequence<E>

Parameters:

otherSequence - the sequence to concatenate

Returns:

the result of the concatenation

copyRange

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

Answers a new sequence containing the specified range of elements of this sequence in their original order. The element at index start in this sequence is at index 0 in the new sequence; the element at start + 1 is at index 1, etc. If stop < start, then the new sequence is empty. Otherwise, the size of the new sequence is max(0, stop - start).

The given indices must be non-negative.

Specified by:

copyRange in interface ReadOnlySequence<E>

Parameters:

start - the beginning index

stop - the ending index

Returns:

a new sequence containing the specified range of elements

copyWith

Sequence<E> copyWith(E newElement)

Answers a new sequence with size one greater than the size of this sequence, containing the elements of this sequence and a given new element placed at the end.

Unless specifically refined, this message is defined to answer an instance of the same class as this sequence.

Sequences that enforce an ordering on their elements are permitted to refine this message to reorder the result.

Specified by:

copyWith in interface ReadOnlySequence<E>

Parameters:

newElement - element to add to the copy

Returns:

copy of this sequence with newElement appended

copyWithout

Sequence<E> copyWithout(E oldElement)

Answers a new sequence with all of the elements of this sequence that are not equivalent to the given element, in their original order.

Specified by:

copyWithout in interface ReadOnlySequence<E>

Parameters:

oldElement - the element to strip from the copy of this sequence

Returns:

copy of this sequence with oldElement removed

reverse

Sequence<E> reverse()

Answers a sequence with the elements of this sequence arranged in reverse order.

This operation is equivalent to:

1. Create a new sequence which conforms to the same protocols as this sequence.
2. Traverse the elements of this sequence in the order specified by forEachInReverseDo message, adding each element of this sequence to the new sequence.
3. Answer the new sequence.

Specified by:

reverse in interface ReadOnlySequence<E>

Returns:

a new sequence with the elements of this sequence in reverse order

putAt

E putAt(int index,
        E newElement)

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

Parameters:

index - the index at which to replace the element

newElement - the element to place at index

Returns:

the previous element at index, or null if there is no such element

Throws:

IndexOutOfBoundsException - if index < 0 or index >= this sequence's size

putAtAll

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

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

This message is equivalent to storing newElement in this sequence at each index specified by indices using putAt.

Parameters:

indices - the indices at which to replace elements

newElement - the element to place at each of the indices

Throws:

NullPointerException - if indices or any of its elements is null

IndexOutOfBoundsException - if any element of indices is < 0 or >= this sequence's size

putAtAll

void putAtAll(int[] indices,
              E newElement)

Parameters:

indices - the indices at which to replace elements

newElement - the element to place at each of the indices

Throws:

NullPointerException - if indices or any of its elements is null

IndexOutOfBoundsException - if any element of indices is < 0 or >= this sequence's size

See Also:

putAtAll(Collection,Object)

putAtAll

void putAtAll(Integer[] indices,
              E newElement)

Parameters:

indices - the indices at which to replace elements

newElement - the element to place at each of the indices

Throws:

NullPointerException - if indices or any of its elements is null

IndexOutOfBoundsException - if any element of indices is < 0 or >= this sequence's size

See Also:

putAtAll(Collection,Object)

putAtAll

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

Parameters:

indices - the indices at which to replace elements

newElement - the element to place at each of the indices

Throws:

NullPointerException - if indices or any of its elements is null

IndexOutOfBoundsException - if any element of indices is < 0 or >= this sequence's size

See Also:

putAtAll(Collection,Object)

putAtAll

void putAtAll(E newElement)

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

This message is equivalent to storing newElement in this sequence at each index from 0 to this sequence's size minus 1 using putAt.

Parameters:

newElement - the element to place at each index

replace

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

Replaces the elements of this sequence between two positions, inclusive, with a given element.

Parameters:

start - beginning index

stop - ending index

replacement - element with which to replace the elements between start and stop, inclusive

Throws:

IndexOutOfBoundsException - if either start or stop is < 0 or >= this sequence's size

replaceRange

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.

The first element of replacements is stored in this sequence at position start, the second at position start + 1, etc. Any previously stored elements at these positions are replaced.

Parameters:

start - beginning index

stop - ending index

replacements - elements to replace in between start and stop, inclusive

Throws:

NullPointerException - if replacements is null

IndexOutOfBoundsException - if either start or stop is < 0 or >= this sequence's size

IllegalArgumentException - if the size of replacements is not equal to stop - start + 1

replaceRange

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

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.

The element at position replacementStart in replacements is stored in this sequence at position start; the element at replacementStart + 1 is stored at position start + 1; etc. Any previously stored elements at these positions are replaced.

Parameters:

start - beginning index

stop - ending index

replacements - elements to replace in between start and stop, inclusive

replacementStart - index to start at in replacements

Throws:

NullPointerException - if replacements is null

IndexOutOfBoundsException - if either start or stop is < 0 or >= this sequence's size, or if replacementStart is < 0 or >= replacements's size

IllegalArgumentException - if the size of replacements is not equal to replacementStart + stop - start