Package org.apache.jackrabbit.oak.commons.collections

Class IteratorUtils

java.lang.Object

org.apache.jackrabbit.oak.commons.collections.IteratorUtils

public class IteratorUtils
extends Object

Utility methods for Iterator conversions.

Method Summary

Modifier and Type	Method	Description
static boolean	elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2)	Compares two iterators to determine if they contain the same elements in the same order.
static <T> T	get(Iterator<T> iterator, int index)	Returns the element at the specified position in the iterator.
static <T> T	getLast(Iterator<T> iterator)	Returns the last element in the given iterator.
static <T> Iterator<T>	mergeSorted(Iterable<? extends Iterator<? extends T>> itrs, Comparator<? super T> c)	Merges multiple sorted iterators into a single sorted iterator.
static int	size(Iterator<?> iterator)	Returns the number of elements in the given iterator.
static <T> @NotNull Iterable<T>	toIterable(@NotNull Iterator<T> iterator)	Convert an Iterator to an Iterable.

Methods inherited from class java.lang.Object

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

Method Detail

toIterable

@NotNull
public static <T> @NotNull Iterable<T> toIterable(@NotNull
                                                  @NotNull Iterator<T> iterator)

Convert an Iterator to an Iterable.

This method is not thread-safe

Parameters:

iterator - iterator to convert

Returns:

a single-use iterable for the iterator (representing the remaining elements in the iterator)

Throws:

IllegalStateException - when Iterable.iterator() is called more than once

mergeSorted

public static <T> Iterator<T> mergeSorted(Iterable<? extends Iterator<? extends T>> itrs,
                                          Comparator<? super T> c)

Merges multiple sorted iterators into a single sorted iterator. Equivalent entries will not be de-duplicated.

This method assumes that the input iterators are sorted in increasing order.

Type Parameters:

T - the type of elements returned by this iterator

Parameters:

itrs - the iterators to merge, must not be null

c - the comparator to determine the order of elements, must not be null

Returns:

an iterator that merges the input iterators in sorted order

Throws:

NullPointerException - if the iterators or comparator are null

elementsEqual

public static boolean elementsEqual(Iterator<?> iterator1,
                                    Iterator<?> iterator2)

Compares two iterators to determine if they contain the same elements in the same order.

This method iterates through both iterators and compares each corresponding pair of elements.

Note that this method consumes both iterators.

Parameters:

iterator1 - the first iterator to compare, may be null

iterator2 - the second iterator to compare, may be null

Returns:

true if both iterators contain the same number of elements and all corresponding elements are equal, false otherwise.

size

public static int size(Iterator<?> iterator)

Returns the number of elements in the given iterator.

This method consumes the iterator to count the elements. A null or empty iterator returns 0.

Parameters:

iterator - the iterator whose size is to be determined

Returns:

the number of elements in the iterator

get

public static <T> T get(Iterator<T> iterator,
                        int index)

Returns the element at the specified position in the iterator.

This method will consume the iterator up to the specified position.

Type Parameters:

T - the type of elements in the iterator

Parameters:

iterator - the iterator to get the element from, must not be null

index - the position of the element to return, zero-based

Returns:

the element at the specified position

Throws:

NullPointerException - if the iterator is null

IndexOutOfBoundsException - if the iterator is empty or index is negative or greater than the number of elements in the iterator

getLast

public static <T> T getLast(Iterator<T> iterator)

Returns the last element in the given iterator.

This method consumes the entire iterator to find the last element.

Type Parameters:

T - the type of elements in the iterator

Parameters:

iterator - the iterator to get the last element from, must not be null

Returns:

the last element in the iterator

Throws:

NullPointerException - if the iterator is null

NoSuchElementException - if the iterator is empty