rcf.core.util.iterator
Interface ImmutableIterable<T>

Type Parameters:

T - The type of the elements which are stored at positions.

All Known Subinterfaces:

Iterable<T>

All Known Implementing Classes:

rcf.core.util.collection.AbstractCollection, rcf.core.util.collection.AbstractImmutableCollection, rcf.core.util.collection.vector.AbstractVector, ArrayEventSyndicate, rcf.core.util.collection.vector.ArrayVector, HashEventSyndicate, rcf.core.util.map.HashMap, rcf.core.util.collection.Hashtable, ImmutablePair.Iterable, ImmutableSingleton.Iterable, ImmutableTriple.Iterable, Pair.Iterable, Singleton.Iterable, Triple.Iterable

@Revision(value="$Revision: 1.5 $",
          date="$Date: 2006/11/09 02:10:05 $",
          tag="$Name:  $")
public interface ImmutableIterable<T>

TODO: Javadoc This interface includes all of the methods needed to check the size of, and handle positions. Please see rcf.core.util.iterator for a discussion of the fact that this interface contains no methods for starting an iteration.

Note that the return values from the summary methods isEmpty() and size() are only valid at the time of the method call, and they may change during the iteration.

TODO: Javadoc review, Seal/Finalize

Version:

$Revision: 1.5 $

Author:

Greg Gibeling

Method Summary

boolean	isCompatible(ImmutablePosition<T> p) TODO: Javadoc Determine if the specified position is compatible to, i.e.
boolean	isEmpty() TODO: Javadoc Return true if this iterable contains no elements.
boolean	isNative(ImmutablePosition<T> p) TODO: Javadoc Determine if the specified position is native to, i.e.
ImmutableIterator<T>	makeNative(ImmutablePosition<T> p) TODO: Javadoc Convert the specified position into an iterator native to this iterable.
int	size() TODO: Javadoc Return the number of elements which this iterable contains.

Method Detail

isCompatible

boolean isCompatible(ImmutablePosition<T> p)

TODO: Javadoc Determine if the specified position is compatible to, i.e. indicates a position in, this iterable object (should return true for pre- and post-sentinel positions). This method should never throw exceptions as it is a test to avoid them.

Note that this method will return true even for positions which did not original come from this iterable, for example in the case of an ImmutableFixedUniIterator over a ImmutableCollection.subCollection(rcf.core.util.collection.position.ImmutableFixedUniPosition, rcf.core.util.filter.Filter). To test if the specified position is native to this iterable, rather than just compatible with it, use the isNative(ImmutablePosition) method.

Parameters:

p - The position to determine if this iterable is compatible with.

Returns:

true indicates that the specified position is compatible with this iterable, and its iterators and methods.

isNative

boolean isNative(ImmutablePosition<T> p)

TODO: Javadoc Determine if the specified position is native to, i.e. indicates a position originally from this iterable object (should return true for pre- and post-sentinel positions). This method should never throw exceptions as it is a test to avoid them.

Note that this method will return false for positions which did not original come from this iterable, for example in the case of an ImmutableFixedUniIterator over a ImmutableCollection.subCollection(rcf.core.util.collection.position.ImmutableFixedUniPosition, rcf.core.util.filter.Filter). The positions may still be used as arguments to most methods both on this iterable and the ImmutableIterators it creates, but they are not native to it, and may behave differently under iteration. To test if the specified position is compatible with this iterable and its iterators, rather than native to it, use the isCompatible(ImmutablePosition) method.

Parameters:

p - The position to determine if this iterable is native to.

Returns:

true indicates that the specified position is native to this iterable.

isEmpty

boolean isEmpty()

TODO: Javadoc Return true if this iterable contains no elements.

Returns:

true if this iterable contains no elements.

makeNative

ImmutableIterator<T> makeNative(ImmutablePosition<T> p)

TODO: Javadoc Convert the specified position into an iterator native to this iterable. Note that if the specified position is already native to this iterable, it will be returned, not a copy of it. If it is not native, a ImmutableIterator.copy() will be returned.

Parameters:

p - The position to return a native version of.

Returns:

The position p if it is native to this iterable, or, if isCompatible(p) a position q such that q.equals(p) && isNative(q) && (q != p). Otherwise, if !isCompatible(p), this method will return null.

size

int size()

TODO: Javadoc Return the number of elements which this iterable contains. If there are more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. This method should always run in O(1), trivial time. Complex iterables must keep an up-to-date size count to ensure this method runs extremely quickly.

Returns:

The number of elements in this iterable.