dk.rode.thesis.iterator
Class SequenceIterator<E>

java.lang.Object
  dk.rode.thesis.iterator.SequenceIterator<E>

Type Parameters:

E - The type of values delivered by this iterator.

All Implemented Interfaces:

Stringable<Sequence<E>>, Iterator<E>

@ParticipantUsage(value="Iterator",
                  type=java.util.Iterator.class)
@Participant(value="ConcreteIterator")
public class SequenceIterator<E>
extends Object
implements Iterator<E>, Stringable<Sequence<E>>

A sequence iterator is an external iterator that can iterate over bounded sequences.

The next() method returns the result of Sequence.next() for the sequence represented by the iterator. The hasNext() method will return false as long as the bound has not been reached. The functionality offered by a sequence iterator to traverse the sequence values is roughly equivalent to the following idiom:

   Sequence sequence = ..; 
   while (sequence.state() != Sequence.State.RESTART) {
     // do something meaningful with returned value...
     sequence.next();
   }
 

The state of the sequence represented by the iterator may or may be affected if the sequence is accessed concurrently, depending on the means of creation.

A sequence iterator is not thread-safe.

Author:

Gunni Rode / rode.dk

See Also:

SequenceIterator(Sequence), SequenceIterator(SequenceIterator), iterator(Sequence), IterableSequence, ProcessableSequence

Field Summary

(package private) Sequence<E>

sequence The sequence to iterate over.

Constructor Summary

SequenceIterator(Sequence<E> sequence)
Constructor.

SequenceIterator(SequenceIterator<E> iterator)
Copy constructor.

Method Summary

StringablePolicy<? super Sequence<E>>	getStringablePolicy(StringablePolicy<? super Sequence<E>> policy) Always return a non-null policy: policy is not null: policy is returned.
boolean	hasNext()
static <V> Iterator<V>	iterator(Sequence<V> sequence) Creates a new iterator based on sequence.
E	next()
void	remove()
String	toString()
CharSequence	toString(StringablePolicy<? super Sequence<E>> policy) Returns a char sequence representation of this stringable object using the format determined by policy or the default policy in case policy is null.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

sequence

final Sequence<E> sequence

The sequence to iterate over.

Never null.

Constructor Detail

SequenceIterator

public SequenceIterator(Sequence<E> sequence)

Constructor.

Modifications to sequence will affect this iterator!

Parameters:

sequence - The sequence to iterate over; cannot be null.

Throws:

NullPointerException - If sequence is null.

SequenceIterator

public SequenceIterator(SequenceIterator<E> iterator)

Copy constructor.

Modifications to iterator will not affect this iterator!

Parameters:

iterator - The iterator to copy; cannot be null.

Throws:

NullPointerException - If iterator is null.

Method Detail

getStringablePolicy

public StringablePolicy<? super Sequence<E>> getStringablePolicy(StringablePolicy<? super Sequence<E>> policy)

Description copied from interface: Stringable

Always return a non-null policy:

1. policy is not null: policy is returned.

2. policy is null: a default, non-null policy is returned.

Specified by:

getStringablePolicy in interface Stringable<Sequence<E>>

Parameters:

policy - The supplied policy; can be null.

Returns:

The policy to use; never null.

See Also:

Stringable.toString(StringablePolicy)

hasNext

public boolean hasNext()

Specified by:

hasNext in interface Iterator<E>

iterator

public static final <V> Iterator<V> iterator(Sequence<V> sequence)

Creates a new iterator based on sequence.

Modification to sequence will not affect the returned iterator as sequence is copied before use.

Type Parameters:

V - The type of values delivered by sequence.

Parameters:

sequence - The sequence; cannot be null.

Returns:

The created iterator; never null.

Throws:

NullPointerException - If sequence is null.

next

public E next()

Specified by:

next in interface Iterator<E>

remove

public void remove()

Specified by:

remove in interface Iterator<E>

Throws:

UnsupportedOperationException - Always thrown.

toString

public String toString()

Overrides:

toString in class Object

toString

public CharSequence toString(StringablePolicy<? super Sequence<E>> policy)

Description copied from interface: Stringable

Returns a char sequence representation of this stringable object using the format determined by policy or the default policy in case policy is null.

In Foo, a typical implementation of this method could be:

    public CharSequence toString(StringablePolicy<? super Foo> policy) {
      return this.getStringablePolicy(policy).toString(this);
    }
 

There are two approaches to formatting this stringable object into a char sequence representation:

1. Let policy decide the entire format, as in the Foo example above; or

2. Use policy to format part of the overall representation, for example letting this method append certain text regardless of the policy used.

Bullet 1) is not always applicable because a given policy implementation may not have access to all required information in its StringablePolicy.toString(Object) method, for example in case multiple stringable objects should be formatted into an overall representation.

In case an implementation uses the approach from bullet 2), care must be take to respect the policy hints so the overall format remains meaningful.

Specified by:

toString in interface Stringable<Sequence<E>>

Parameters:

policy - The policy to dictate the formatting; can be null, in which case the result of toString method is returned.

Returns:

The char sequence representation; never null.

See Also:

StringablePolicy.Type