it.unimi.dsi.fastutil
Class Iterators

java.lang.Object
  extended byit.unimi.dsi.fastutil.Iterators

public class Iterators
extends Object

A class providing static methods that do useful things with type-specific iterators.

See Also:
Iterator

Constructor Summary
Iterators()
           
 
Method Summary
static BooleanIterator asBooleanIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static ByteIterator asByteIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static CharIterator asCharIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static DoubleIterator asDoubleIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static FloatIterator asFloatIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static IntIterator asIntIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static LongIterator asLongIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static ObjectIterator asObjectIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static ShortIterator asShortIterator(Iterator i)
          Wraps a standard iterator into a type-specific iterator.
static BooleanIterator concat(BooleanIterator[] a)
          Concatenates all iterators contained in an array.
static BooleanIterator concat(BooleanIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static ByteIterator concat(ByteIterator[] a)
          Concatenates all iterators contained in an array.
static ByteIterator concat(ByteIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static CharIterator concat(CharIterator[] a)
          Concatenates all iterators contained in an array.
static CharIterator concat(CharIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static DoubleIterator concat(DoubleIterator[] a)
          Concatenates all iterators contained in an array.
static DoubleIterator concat(DoubleIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static FloatIterator concat(FloatIterator[] a)
          Concatenates all iterators contained in an array.
static FloatIterator concat(FloatIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static IntIterator concat(IntIterator[] a)
          Concatenates all iterators contained in an array.
static IntIterator concat(IntIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static LongIterator concat(LongIterator[] a)
          Concatenates all iterators contained in an array.
static LongIterator concat(LongIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static ObjectIterator concat(ObjectIterator[] a)
          Concatenates all iterators contained in an array.
static ObjectIterator concat(ObjectIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static ShortIterator concat(ShortIterator[] a)
          Concatenates all iterators contained in an array.
static ShortIterator concat(ShortIterator[] a, int offset, int length)
          Concatenates a sequence of iterators contained in an array.
static BooleanListIterator emptyBooleanIterator()
          Returns an empty type-specific list iterator.
static ByteListIterator emptyByteIterator()
          Returns an empty type-specific list iterator.
static CharListIterator emptyCharIterator()
          Returns an empty type-specific list iterator.
static DoubleListIterator emptyDoubleIterator()
          Returns an empty type-specific list iterator.
static FloatListIterator emptyFloatIterator()
          Returns an empty type-specific list iterator.
static IntListIterator emptyIntIterator()
          Returns an empty type-specific list iterator.
static LongListIterator emptyLongIterator()
          Returns an empty type-specific list iterator.
static ObjectListIterator emptyObjectIterator()
          Returns an empty type-specific list iterator.
static ShortListIterator emptyShortIterator()
          Returns an empty type-specific list iterator.
static ByteBidirectionalIterator fromTo(byte from, byte to)
          Creates a type-specific bidirectional iterator over an interval.
static CharBidirectionalIterator fromTo(char from, char to)
          Creates a type-specific bidirectional iterator over an interval.
static IntBidirectionalIterator fromTo(int from, int to)
          Creates a type-specific bidirectional iterator over an interval.
static LongBidirectionalIterator fromTo(long from, long to)
          Creates a type-specific bidirectional iterator over an interval.
static ByteSet pour(ByteIterator i)
          Pours an iterator, returning a type-specific set.
static int pour(ByteIterator i, ByteSet s)
          Pours an iterator into a type-specific set.
static int pour(ByteIterator i, ByteSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static ByteSet pour(ByteIterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static CharSet pour(CharIterator i)
          Pours an iterator, returning a type-specific set.
static int pour(CharIterator i, CharSet s)
          Pours an iterator into a type-specific set.
static int pour(CharIterator i, CharSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static CharSet pour(CharIterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static DoubleSet pour(DoubleIterator i)
          Pours an iterator, returning a type-specific set.
static int pour(DoubleIterator i, DoubleSet s)
          Pours an iterator into a type-specific set.
static int pour(DoubleIterator i, DoubleSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static DoubleSet pour(DoubleIterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static FloatSet pour(FloatIterator i)
          Pours an iterator, returning a type-specific set.
static int pour(FloatIterator i, FloatSet s)
          Pours an iterator into a type-specific set.
static int pour(FloatIterator i, FloatSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static FloatSet pour(FloatIterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static IntSet pour(IntIterator i)
          Pours an iterator, returning a type-specific set.
static IntSet pour(IntIterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static int pour(IntIterator i, IntSet s)
          Pours an iterator into a type-specific set.
static int pour(IntIterator i, IntSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static ObjectSet pour(Iterator i)
          Pours an iterator, returning a type-specific set.
static ObjectSet pour(Iterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static int pour(Iterator i, ObjectSet s)
          Pours an iterator into a type-specific set.
static int pour(Iterator i, ObjectSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static LongSet pour(LongIterator i)
          Pours an iterator, returning a type-specific set.
static LongSet pour(LongIterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static int pour(LongIterator i, LongSet s)
          Pours an iterator into a type-specific set.
static int pour(LongIterator i, LongSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static ShortSet pour(ShortIterator i)
          Pours an iterator, returning a type-specific set.
static ShortSet pour(ShortIterator i, int max)
          Pours an iterator, returning a type-specific set, with a limit on the number of elements.
static int pour(ShortIterator i, ShortSet s)
          Pours an iterator into a type-specific set.
static int pour(ShortIterator i, ShortSet s, int max)
          Pours an iterator into a type-specific set, with a limit on the number of elements.
static boolean[] unwrap(BooleanIterator i)
          Unwraps an iterator, returning an array.
static int unwrap(BooleanIterator i, boolean[] array)
          Unwraps an iterator into an array.
static int unwrap(BooleanIterator i, boolean[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(BooleanIterator i, BooleanCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(BooleanIterator i, BooleanCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static boolean[] unwrap(BooleanIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static byte[] unwrap(ByteIterator i)
          Unwraps an iterator, returning an array.
static int unwrap(ByteIterator i, byte[] array)
          Unwraps an iterator into an array.
static int unwrap(ByteIterator i, byte[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(ByteIterator i, ByteCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(ByteIterator i, ByteCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static byte[] unwrap(ByteIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static char[] unwrap(CharIterator i)
          Unwraps an iterator, returning an array.
static int unwrap(CharIterator i, char[] array)
          Unwraps an iterator into an array.
static int unwrap(CharIterator i, char[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(CharIterator i, CharCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(CharIterator i, CharCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static char[] unwrap(CharIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static double[] unwrap(DoubleIterator i)
          Unwraps an iterator, returning an array.
static int unwrap(DoubleIterator i, double[] array)
          Unwraps an iterator into an array.
static int unwrap(DoubleIterator i, double[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(DoubleIterator i, DoubleCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(DoubleIterator i, DoubleCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static double[] unwrap(DoubleIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static float[] unwrap(FloatIterator i)
          Unwraps an iterator, returning an array.
static int unwrap(FloatIterator i, float[] array)
          Unwraps an iterator into an array.
static int unwrap(FloatIterator i, float[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(FloatIterator i, FloatCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(FloatIterator i, FloatCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static float[] unwrap(FloatIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static int[] unwrap(IntIterator i)
          Unwraps an iterator, returning an array.
static int[] unwrap(IntIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static int unwrap(IntIterator i, int[] array)
          Unwraps an iterator into an array.
static int unwrap(IntIterator i, int[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(IntIterator i, IntCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(IntIterator i, IntCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static Object[] unwrap(Iterator i)
          Unwraps an iterator, returning an array.
static Object[] unwrap(Iterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static int unwrap(Iterator i, Object[] array)
          Unwraps an iterator into an array.
static int unwrap(Iterator i, Object[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(Iterator i, ObjectCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(Iterator i, ObjectCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static long[] unwrap(LongIterator i)
          Unwraps an iterator, returning an array.
static long[] unwrap(LongIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static int unwrap(LongIterator i, long[] array)
          Unwraps an iterator into an array.
static int unwrap(LongIterator i, long[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(LongIterator i, LongCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(LongIterator i, LongCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static short[] unwrap(ShortIterator i)
          Unwraps an iterator, returning an array.
static short[] unwrap(ShortIterator i, int max)
          Unwraps an iterator, returning an array, with a limit on the number of elements.
static int unwrap(ShortIterator i, short[] array)
          Unwraps an iterator into an array.
static int unwrap(ShortIterator i, short[] array, int offset, int max)
          Unwraps an iterator into an array starting at a given offset for a given number of elements.
static long unwrap(ShortIterator i, ShortCollection c)
          Unwraps an iterator into a type-specific collection.
static int unwrap(ShortIterator i, ShortCollection c, int max)
          Unwraps an iterator into a type-specific collection, with a limit on the number of elements.
static BooleanListIterator wrap(boolean[] array)
          Wraps the given array into a type-specific list iterator.
static BooleanListIterator wrap(boolean[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static ByteListIterator wrap(byte[] array)
          Wraps the given array into a type-specific list iterator.
static ByteListIterator wrap(byte[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static CharListIterator wrap(char[] array)
          Wraps the given array into a type-specific list iterator.
static CharListIterator wrap(char[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static DoubleListIterator wrap(double[] array)
          Wraps the given array into a type-specific list iterator.
static DoubleListIterator wrap(double[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static FloatListIterator wrap(float[] array)
          Wraps the given array into a type-specific list iterator.
static FloatListIterator wrap(float[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static IntListIterator wrap(int[] array)
          Wraps the given array into a type-specific list iterator.
static IntListIterator wrap(int[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static LongListIterator wrap(long[] array)
          Wraps the given array into a type-specific list iterator.
static LongListIterator wrap(long[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static ObjectListIterator wrap(Object[] array)
          Wraps the given array into a type-specific list iterator.
static ObjectListIterator wrap(Object[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
static ShortListIterator wrap(short[] array)
          Wraps the given array into a type-specific list iterator.
static ShortListIterator wrap(short[] array, int offset, int length)
          Wraps the given part of an array into a type-specific list iterator.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Iterators

public Iterators()
Method Detail

emptyBooleanIterator

public static BooleanListIterator emptyBooleanIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static BooleanListIterator wrap(boolean[] array,
                                       int offset,
                                       int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static BooleanListIterator wrap(boolean[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(BooleanIterator i,
                         boolean[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(BooleanIterator i,
                         boolean[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static boolean[] unwrap(BooleanIterator i,
                               int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static boolean[] unwrap(BooleanIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(BooleanIterator i,
                         BooleanCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(BooleanIterator i,
                          BooleanCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

asBooleanIterator

public static BooleanIterator asBooleanIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

concat

public static BooleanIterator concat(BooleanIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static BooleanIterator concat(BooleanIterator[] a,
                                     int offset,
                                     int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyByteIterator

public static ByteListIterator emptyByteIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static ByteListIterator wrap(byte[] array,
                                    int offset,
                                    int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static ByteListIterator wrap(byte[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(ByteIterator i,
                         byte[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(ByteIterator i,
                         byte[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static byte[] unwrap(ByteIterator i,
                            int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static byte[] unwrap(ByteIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(ByteIterator i,
                         ByteCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(ByteIterator i,
                          ByteCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(ByteIterator i,
                       ByteSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(ByteIterator i,
                       ByteSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static ByteSet pour(ByteIterator i,
                           int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static ByteSet pour(ByteIterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asByteIterator

public static ByteIterator asByteIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

fromTo

public static ByteBidirectionalIterator fromTo(byte from,
                                               byte to)
Creates a type-specific bidirectional iterator over an interval.

The type-specific bidirectional iterator returned by this method will return the elements from, from+1,…, to-1.

Parameters:
from - the starting element (inclusive).
to - the ending element (exclusive).
Returns:
a type-specific bidirectional iterator enumerating the elements from from to to.

concat

public static ByteIterator concat(ByteIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static ByteIterator concat(ByteIterator[] a,
                                  int offset,
                                  int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyShortIterator

public static ShortListIterator emptyShortIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static ShortListIterator wrap(short[] array,
                                     int offset,
                                     int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static ShortListIterator wrap(short[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(ShortIterator i,
                         short[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(ShortIterator i,
                         short[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static short[] unwrap(ShortIterator i,
                             int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static short[] unwrap(ShortIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(ShortIterator i,
                         ShortCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(ShortIterator i,
                          ShortCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(ShortIterator i,
                       ShortSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(ShortIterator i,
                       ShortSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static ShortSet pour(ShortIterator i,
                            int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static ShortSet pour(ShortIterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asShortIterator

public static ShortIterator asShortIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

concat

public static ShortIterator concat(ShortIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static ShortIterator concat(ShortIterator[] a,
                                   int offset,
                                   int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyIntIterator

public static IntListIterator emptyIntIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static IntListIterator wrap(int[] array,
                                   int offset,
                                   int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static IntListIterator wrap(int[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(IntIterator i,
                         int[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(IntIterator i,
                         int[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static int[] unwrap(IntIterator i,
                           int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static int[] unwrap(IntIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(IntIterator i,
                         IntCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(IntIterator i,
                          IntCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(IntIterator i,
                       IntSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(IntIterator i,
                       IntSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static IntSet pour(IntIterator i,
                          int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static IntSet pour(IntIterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asIntIterator

public static IntIterator asIntIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

fromTo

public static IntBidirectionalIterator fromTo(int from,
                                              int to)
Creates a type-specific bidirectional iterator over an interval.

The type-specific bidirectional iterator returned by this method will return the elements from, from+1,…, to-1.

Parameters:
from - the starting element (inclusive).
to - the ending element (exclusive).
Returns:
a type-specific bidirectional iterator enumerating the elements from from to to.

concat

public static IntIterator concat(IntIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static IntIterator concat(IntIterator[] a,
                                 int offset,
                                 int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyLongIterator

public static LongListIterator emptyLongIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static LongListIterator wrap(long[] array,
                                    int offset,
                                    int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static LongListIterator wrap(long[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(LongIterator i,
                         long[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(LongIterator i,
                         long[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static long[] unwrap(LongIterator i,
                            int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static long[] unwrap(LongIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(LongIterator i,
                         LongCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(LongIterator i,
                          LongCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(LongIterator i,
                       LongSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(LongIterator i,
                       LongSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static LongSet pour(LongIterator i,
                           int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static LongSet pour(LongIterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asLongIterator

public static LongIterator asLongIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

fromTo

public static LongBidirectionalIterator fromTo(long from,
                                               long to)
Creates a type-specific bidirectional iterator over an interval.

The type-specific bidirectional iterator returned by this method will return the elements from, from+1,…, to-1.

Parameters:
from - the starting element (inclusive).
to - the ending element (exclusive).
Returns:
a type-specific bidirectional iterator enumerating the elements from from to to.

concat

public static LongIterator concat(LongIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static LongIterator concat(LongIterator[] a,
                                  int offset,
                                  int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyCharIterator

public static CharListIterator emptyCharIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static CharListIterator wrap(char[] array,
                                    int offset,
                                    int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static CharListIterator wrap(char[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(CharIterator i,
                         char[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(CharIterator i,
                         char[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static char[] unwrap(CharIterator i,
                            int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static char[] unwrap(CharIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(CharIterator i,
                         CharCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(CharIterator i,
                          CharCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(CharIterator i,
                       CharSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(CharIterator i,
                       CharSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static CharSet pour(CharIterator i,
                           int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static CharSet pour(CharIterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asCharIterator

public static CharIterator asCharIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

fromTo

public static CharBidirectionalIterator fromTo(char from,
                                               char to)
Creates a type-specific bidirectional iterator over an interval.

The type-specific bidirectional iterator returned by this method will return the elements from, from+1,…, to-1.

Parameters:
from - the starting element (inclusive).
to - the ending element (exclusive).
Returns:
a type-specific bidirectional iterator enumerating the elements from from to to.

concat

public static CharIterator concat(CharIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static CharIterator concat(CharIterator[] a,
                                  int offset,
                                  int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyFloatIterator

public static FloatListIterator emptyFloatIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static FloatListIterator wrap(float[] array,
                                     int offset,
                                     int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static FloatListIterator wrap(float[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(FloatIterator i,
                         float[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(FloatIterator i,
                         float[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static float[] unwrap(FloatIterator i,
                             int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static float[] unwrap(FloatIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(FloatIterator i,
                         FloatCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(FloatIterator i,
                          FloatCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(FloatIterator i,
                       FloatSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(FloatIterator i,
                       FloatSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static FloatSet pour(FloatIterator i,
                            int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static FloatSet pour(FloatIterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asFloatIterator

public static FloatIterator asFloatIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

concat

public static FloatIterator concat(FloatIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static FloatIterator concat(FloatIterator[] a,
                                   int offset,
                                   int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyDoubleIterator

public static DoubleListIterator emptyDoubleIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static DoubleListIterator wrap(double[] array,
                                      int offset,
                                      int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static DoubleListIterator wrap(double[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(DoubleIterator i,
                         double[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(DoubleIterator i,
                         double[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static double[] unwrap(DoubleIterator i,
                              int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static double[] unwrap(DoubleIterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(DoubleIterator i,
                         DoubleCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(DoubleIterator i,
                          DoubleCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(DoubleIterator i,
                       DoubleSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(DoubleIterator i,
                       DoubleSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static DoubleSet pour(DoubleIterator i,
                             int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static DoubleSet pour(DoubleIterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asDoubleIterator

public static DoubleIterator asDoubleIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

concat

public static DoubleIterator concat(DoubleIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static DoubleIterator concat(DoubleIterator[] a,
                                    int offset,
                                    int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.

emptyObjectIterator

public static ObjectListIterator emptyObjectIterator()
Returns an empty type-specific list iterator.

The iterator provided by this method returns no elements. The implementation uses the singleton pattern (i.e., it will always return the same instance), so it is very efficient.

Returns:
an empty type-specific list iterator.

wrap

public static ObjectListIterator wrap(Object[] array,
                                      int offset,
                                      int length)
Wraps the given part of an array into a type-specific list iterator.

The type-specific list iterator returned by this method will iterate length times, returning consecutive elements of the given array starting from the one with index offset.

Parameters:
array - an array to wrap into a type-specific list iterator.
offset - the first element of the array to be returned.
length - the number of elements to return.

wrap

public static ObjectListIterator wrap(Object[] array)
Wraps the given array into a type-specific list iterator.

The type-specific list iterator returned by this method will return all elements of the given array.

Parameters:
array - an array to wrap into a type-specific list iterator.

unwrap

public static int unwrap(Iterator i,
                         Object[] array,
                         int offset,
                         int max)
Unwraps an iterator into an array starting at a given offset for a given number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of length, in the given array starting at offset. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
offset - the first element of the array to be returned.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped.

unwrap

public static int unwrap(Iterator i,
                         Object[] array)
Unwraps an iterator into an array.

This method iterates over the given type-specific iterator and stores the elements returned in the given array. The iteration will stop when the iterator has no more elements or when the end of the array has been reached.

Parameters:
i - a type-specific iterator.
array - an array to contain the output of the iterator.
Returns:
the number of elements unwrapped.

unwrap

public static Object[] unwrap(Iterator i,
                              int max)
Unwraps an iterator, returning an array, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator. At most max elements will be returned.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be unwrapped.
Returns:
an array containing the elements returned by the iterator (at most max).

unwrap

public static Object[] unwrap(Iterator i)
Unwraps an iterator, returning an array.

This method iterates over the given type-specific iterator and returns an array containing the elements returned by the iterator.

Parameters:
i - a type-specific iterator.
Returns:
an array containing the elements returned by the iterator.

unwrap

public static int unwrap(Iterator i,
                         ObjectCollection c,
                         int max)
Unwraps an iterator into a type-specific collection, with a limit on the number of elements.

This method iterates over the given type-specific iterator and stores the elements returned, up to a maximum of max, in the given type-specific collection. The number of actually unwrapped elements is returned (it may be less than max if the iterator emits less than max elements).

Parameters:
i - a type-specific iterator.
c - a type-specific collection array to contain the output of the iterator.
max - the maximum number of elements to unwrap.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

unwrap

public static long unwrap(Iterator i,
                          ObjectCollection c)
Unwraps an iterator into a type-specific collection.

This method iterates over the given type-specific iterator and stores the elements returned in the given type-specific collection. The returned count on the number unwrapped elements is a long, so that it will work also with very large collections.

Parameters:
i - a type-specific iterator.
c - a type-specific collection to contain the output of the iterator.
Returns:
the number of elements unwrapped. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the collection (because of duplicates).

pour

public static int pour(Iterator i,
                       ObjectSet s,
                       int max)
Pours an iterator into a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and adds the returned elements to the given set (up to max).

Parameters:
i - a type-specific iterator.
s - a type-specific set.
max - the maximum number of elements to be poured.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static int pour(Iterator i,
                       ObjectSet s)
Pours an iterator into a type-specific set.

This method iterates over the given type-specific iterator and adds the returned elements to the given set.

Parameters:
i - a type-specific iterator.
s - a type-specific set.
Returns:
the number of elements poured. Note that this is the number of elements returned by the iterator, which is not necessarily the number of elements that have been added to the set (because of duplicates).

pour

public static ObjectSet pour(Iterator i,
                             int max)
Pours an iterator, returning a type-specific set, with a limit on the number of elements.

This method iterates over the given type-specific iterator and returns a type-specific set containing the returned elements (up to max). Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
max - the maximum number of elements to be poured.
Returns:
a type-specific set containing the returned elements, up to max.

pour

public static ObjectSet pour(Iterator i)
Pours an iterator, returning a type-specific set.

This method iterates over the given type-specific iterator and returns a set containing the returned elements. Iteration on the returned set is guaranteed to produce the elements in the same order in which they appeared first in the iterator.

Parameters:
i - a type-specific iterator.
Returns:
a type-specific set containing the returned elements.

asObjectIterator

public static ObjectIterator asObjectIterator(Iterator i)
Wraps a standard iterator into a type-specific iterator.

This method wraps a standard iterator into a type-specific one which will handle the type conversions for you. Of course, any attempt to wrap an iterator returning the instances of the wrong class will generate a ClassCastException.

If i is already type-specific, it will returned and no new object will be generated.

Parameters:
i - an iterator.
Returns:
a type-specific iterator returning the same element as i.

concat

public static ObjectIterator concat(ObjectIterator[] a)
Concatenates all iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by all iterators contained in the given array.

Parameters:
a - an array of iterators.
Returns:
an iterator obtained by concatenation.

concat

public static ObjectIterator concat(ObjectIterator[] a,
                                    int offset,
                                    int length)
Concatenates a sequence of iterators contained in an array.

This method returns an iterator that will enumerate in order the elements returned by a[ offset ], then those returned by a[ offset + 1 ], and so on up to a[ offset + length - 1 ].

Parameters:
a - an array of iterators.
offset - the index of the first iterator to concatenate.
length - the number of iterators to concatenate.
Returns:
an iterator obtained by concatenation of length elements of a starting at offset.