edu.rice.cs.plt.iter
Interface SizedIterable<T>

All Superinterfaces:

Iterable<T>

All Known Subinterfaces:

FunctionalRelation<T1,T2>, InjectiveRelation<T1,T2>, Multiset<T>, OneToOneRelation<T1,T2>, PredicateSet<T>, Relation<T1,T2>, Relation3<T1,T2,T3>, Relation4<T1,T2,T3,T4>, RelationIndex<K,V>

All Known Implementing Classes:

AbstractFunctionalRelation, AbstractFunctionalRelation.InverseFunctionalRelation, AbstractInjectiveRelation, AbstractInjectiveRelation.InverseInjectiveRelation, AbstractKeyBasedMap.EntrySet, AbstractOneToOneRelation, AbstractOneToOneRelation.InverseOneToOneRelation, AbstractPredicateSet, AbstractRelation, AbstractRelation.InverseRelation, BinaryMappedIterable, CartesianIterable, CartesianRelation, CollapsedIterable, ComplementRelation, ComplementSet, ComposedIterable, ComposedRelation, ConcreteRelationIndex, ConsList, ConsList.Empty, ConsList.Nonempty, DelegatingCollection, DelegatingRelation, DelegatingSet, DiagonalCartesianIterable, EmptyCollection, EmptyIterable, EmptyRelation, EmptySet, EventSequence, ExternallySortedSet, FilteredRelation, FilteredSet, FiniteSequenceIterable, HashMultiset, ImmutableCollection, ImmutableIterable, ImmutableRelation, ImmutableSet, IndexedFunctionalRelation, IndexedInjectiveRelation, IndexedOneToOneRelation, IndexedRelation, IntersectionRelation, IntersectionSet, IterableCollection, IterableSet, LazyRelationIndex, MappedIterable, PermutationIterable, SequenceIterable, SingletonIterable, SingletonRelation, SingletonSet, SkipFirstIterable, SkipLastIterable, SnapshotIterable, TruncatedIterable, UnionRelation, UnionSet

public interface SizedIterable<T>
extends Iterable<T>

Allows size calculations on Iterables. Implementing classes must be able to calculate their size; ideally, this calculation should be done in constant time. IterUtil.sizeOf(java.lang.Iterable) uses this interface to optimize size calculations.

In an ideal design, java.util.Collection would implement a SizedIterable API class, and applications that required this behavior could be defined in terms of SizedIterables instead of Iterables. However, since the Java APIs can't be modified and are too valuable to abandon, the sizeOf method provides a workaround that, through casting, calculates the size appropriately. An alternative design would allow collections as components of SizedIterables such as ComposedIterable only by manually wrapping them in a bridge class (see IterUtil.asSizedIterable(java.util.Collection)).

Method Summary

boolean	hasFixedSize() true if this iterable is known to have a fixed size.
boolean	isEmpty() Whether the iterable does not contain any elements.
boolean	isInfinite() true if the iterable is known to have infinite size.
boolean	isStatic() true if this iterable is unchanging.
int	size() Compute the number of elements in the iterable.
int	size(int bound) Compute the number of elements in the iterable, up to the given bound.

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

isEmpty

boolean isEmpty()

Whether the iterable does not contain any elements.

size

int size()

Compute the number of elements in the iterable. If the size is infinite or too large to be represented as an int, Integer.MAX_VALUE should be returned. Otherwise, next() may be safely invoked on the iterator exactly this number of times.

size

int size(int bound)

Compute the number of elements in the iterable, up to the given bound. If the size is infinite or greater than bound, bound is returned.

Parameters:

bound - Maximum result. Assumed to be nonnegative.

isInfinite

boolean isInfinite()

true if the iterable is known to have infinite size. If true, an iterator over the iterable in its current state will never return false from hasNext().

hasFixedSize

boolean hasFixedSize()

true if this iterable is known to have a fixed size. This is the case if the iterable is immutable, or if changes can only replace values, not remove or add them. An infinite iterable may be fixed if it is guaranteed to never become finite.

isStatic

boolean isStatic()

true if this iterable is unchanging. This implies that hasFixedSize() is true, and that iterator() will always return the same (either == or equal() and immutable) elements in the same order. ("Immutable" here means that equals() invocations are consistent over time -- if two objects are equal, they will never become inequal, and vice versa.)