dk.rode.thesis.meta.model
Interface Sequence<E>

Type Parameters:

E - The type of values delivered by this sequence.

All Superinterfaces:

Copyable<Sequence<E>>, StrictCopyable<Sequence<E>>, Stringable<Sequence<E>>

All Known Subinterfaces:

AspectObservableSequence<O,A,E>, CompositeSequence<E>, MemorizableSequence<E>, ObservableSequence<O,A,E>, ReversibleSequence<E>, StateableSequence<E>, StepSequence, TypeVisitableSequence<E>, ValueVisitableSequence<E>

All Known Implementing Classes:

AbstractCompositeSequence, AbstractSequence, AbstractStateableSequence, AbstractVisitableSequence, AckermannSequence, AnnotatedObserversSequence, AnnotatedObserversSequenceDecorator, AppenderDecorator, ArraySequence, CharSequenceCompositeSequence, CountdownSequence, DanishAlphabetSequence, DateSequence, DateValuedVisitableSequence, DigitSequence, DuplexDecorator, EnglishAlphabetSequence, EvenSequence, FibonacciSequence, FileSequence, HexDigitSequence, ImmutableSequence, IntegerValuedVisitableSequence, IterableSequence, LongSequence, MemorizableEnglishAlphabetSequence, MemorizableSequenceAbstraction, MutatedSimpsonsFamilySequence, NegativeSequence, NonResettableSequence, NorwegianAlphabetSequence, OddSequence, PrimeSequence, ProcessableSequence, RandomSequence, RangeSequence, ReflectiveVisitableSequence, ReversiblePrimeSequence, Sentence, SequenceAbstraction, SequenceAdapter, SequenceDecorator, SequenceObserversSequence, SequenceObserversSequenceDecorator, SequenceTemplate, SimpsonsAndBouvierFamilySequence, SimpsonsFamilySequence, SmileySequence, StepSequenceImpl, StringValuedVisitableSequence, SymbolSequence, SynchronisedSequence, SynchronisedSequenceAbstraction, UnboundedRandomSequence, UppercaseDecorator, VisitableCompositeSequence, VisitableLongSequence, VisitableRandomSequence, VisitableReversiblePrimeSequence, Word, ZipSequence

public interface Sequence<E>
extends StrictCopyable<Sequence<E>>, Stringable<Sequence<E>>

Represents a sequence that will deliver the next, or current, value in the sequence on demand.

Sequences are more than mere iterators; they are value centric. Sequences always have a lower bound, i.e. the initial sequence value, and may be bounded, limiting the number of possible values it can deliver. If a sequence is bounded and deliver consistent values, it will restart when the upper bound is reached on an invocation of next(), i.e. the same values will be delivered again, in order. The sequence values of bounded, consistent sequences are thus deterministic: two instances of the same sequence type initialised identically will return the same sequence values if utilised in the same manner. Sequences may also deliver unique sequence values until reset or restarted.

Sequences can be reset explicitly, which will cause the sequence to restart if it is consistent.

Examples:

    Consistent, bounded, and unique number sequence:               [0, 1, 2, 3, 4, 5]
    
    Consistent, unbounded, and unique odd sequence:                [1, 3, 5, 7, 9, ..[
    
    Inconsistent, bounded, and not unique random sequence ([0,2]): [0, 2, 2, 1, 0, ..]
    
    Inconsistent, unbounded, and not unique odd*random sequence:   [1*0, 3*2, 5*2, 7*1, 9*0, 11*.., ..[

               consistent       consistent       inconsistent     inconsistent
               bounded          unbounded        bounded          unbounded
               unique           unique           not unique       not unique
    current(): 0 <- low bound    1 <- low bound  0 <- low bound   0*1  =  0 <- inconsistent low bound
    next():    1                 3               2                2*3  =  0 <- not unique
    next():    2                 5               2 <- not unique  2*5  = 10
    next():    3                 7               1                1*7  =  7
    current(): 3                 7               1                1*7  =  7
    next():    4                 9               0                0*9  =  0
    next():    5 <- high bound  11               2                2*11 = 22
    next():    1 <- restart     13               0                0*13 =  0
    next():    2                15               1                1*15 = 15
    next():    3                17               2                2*17 = 34
    reset():   1 <- restart      1 <- restart    1 <- no restart  1*1  =  1 <- restart of odd only!
    next():    2                 3               2                2*3  =  6
    ..
 

Notice that the initial current value is the lower sequence bound, and that the first invocation of next() will return the second sequence value because of the requirement that a sequence always have a current value.

Values from sequences are delivered on demand by calling next(), which may calculate the value. Hence, different invocations to next() may not perform the same amount of work. Once a call to next() completes, the value returned is considered the current value of the sequence and can be retrieved with current() until next() or reset() is invoked.

A sequence will never deliver a null element from the current() and next() methods; it always has a given non-null value, even if next() has not been invoked yet (the initial value which is the lower bound).

The current internal state of a sequence can be acquired via the state() method.

Unless otherwise stated, sequences are considered equal based on identity (==).

Author:

Gunni Rode / rode.dk

Nested Class Summary

static class

Sequence.State The possible internal states a Sequence can have.

Method Summary

boolean	bounded() Returns true if this sequence is bounded, i.e.
boolean	consistent() Returns true if this sequence is consistent, i.e. deliver the same values, in order, after restart or reset.
Sequence<E>	copy() Returns a copy of this sequence that will start at the same sequence index as this sequence.
E	current() Returns the current element from this sequence.
E	next() Returns the next element from this sequence.
void	reset() Resets this sequence to start over if it is consistent.
Sequence.State	state() Returns the internal state of this sequence.
boolean	unique() Returns true if this sequence deliver a given sequence value at most one time until reset or restarted.

Methods inherited from interface dk.rode.thesis.strategy.Stringable

getStringablePolicy, toString

Method Detail

bounded

boolean bounded()

Returns true if this sequence is bounded, i.e. deliver values between the initial sequence value and some upper bound.

The same type of sequence may represent both bounded and unbounded sequences and the behaviour is determined and fixed at construction time. Bounded sequences will restart if they deliver consistent values.

Returns:

True if bounded, false if not.

See Also:

unique()

consistent

boolean consistent()

Returns true if this sequence is consistent, i.e. deliver the same values, in order, after restart or reset.

Only bounded consistent sequences will restart. Consistent sequences need not deliver unique sequence values.

Instances of the same type of sequences are always consistent or inconsistent; it is determined at design time, not construction time.

Returns:

True if consistent, false if not.

copy

Sequence<E> copy()

Returns a copy of this sequence that will start at the same sequence index as this sequence.

Specified by:

copy in interface Copyable<Sequence<E>>

Returns:

A copy of this sequence; never null.

current

E current()

Returns the current element from this sequence.

This method can be invoked even if next() has not been invoked yet, thus delivering the initial value of this sequence.

Returns:

The current element; never null.

next

E next()

Returns the next element from this sequence.

Returns:

The next element; never null.

See Also:

current(), state()

reset

void reset()

Resets this sequence to start over if it is consistent.

If this sequence is consistent, the sequence will restart.

state

Sequence.State state()

Returns the internal state of this sequence.

Returns:

The internal state; never null.

unique

boolean unique()

Returns true if this sequence deliver a given sequence value at most one time until reset or restarted.

Unbounded sequences that are unique will never deliver the same sequence value more than once.

The same type of sequence may represent both unique and not unique sequences and the behaviour is determined and fixed at construction time.

Returns:

True if unique, false if not.

See Also:

consistent()