Package com.graphaware.common.util

Class IterableUtils

java.lang.Object

com.graphaware.common.util.IterableUtils

public final class IterableUtils
extends Object

Utility methods for dealing with Iterables.

Method Summary

Modifier and Type	Method	Description
static <T> boolean	contains(Iterable<T> iterable, T object)	Check whether an iterable contains the given object.
static long	count(Iterable<?> iterable)	Count items in an iterable.
static long	countNodes(Transaction tx)	Count all nodes in a database.
static <T> T	getFirst(Iterable<T> iterable, String notFoundMessage)	Get the first element from iterable.
static <T> T	getFirst(Iterator<T> iterator, String notFoundMessage)	Get the first element from iterator.
static <T> T	getFirstOrNull(Iterable<T> iterable)	Get the first element from iterable.
static <T> T	getFirstOrNull(Iterator<T> iterator)	Get the first element from iterator.
static <T> T	getSingle(Iterable<T> iterable)	Get a single element from iterable.
static <T> T	getSingle(Iterable<T> iterable, String notFoundMessage)	Get a single element from iterable.
static <T> T	getSingle(Iterator<T> iterator)	Get a single element from iterator.
static <T> T	getSingle(Iterator<T> iterator, String notFoundMessage)	Get a single element from iterator.
static <T> T	getSingleOrNull(Iterable<T> iterable)	Get a single element from iterable.
static <T> T	getSingleOrNull(Iterator<T> iterator)	Get a single element from iterator.
static <T> T	random(Iterable<T> iterable)	Get a random element of the given Iterable.
static <T> Iterable<T>	random(Iterable<T> iterable, int numberOfSamples)	Sample an Iterable using reservoir sampling.
static <T> List<T>	toList(Iterable<T> iterable)	Convert an iterable to a list.

Methods inherited from class java.lang.Object

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

Method Detail

countNodes

public static long countNodes(Transaction tx)

Count all nodes in a database.

Please note that this can be an expensive operation! As such, it is intended mainly for testing.

Parameters:

tx - in which to count nodes.

Returns:

all nodes in the database (including root with ID 0, i.e. an brand new database will have 1 node).

count

public static long count(Iterable<?> iterable)

Count items in an iterable.

Parameters:

iterable - to count items in.

Returns:

number of items in the iterable.

contains

public static <T> boolean contains(Iterable<T> iterable,
                                   T object)

Check whether an iterable contains the given object.

Type Parameters:

T - type of the objects stored in the iterable.

Parameters:

iterable - to check in.

object - to look for.

Returns:

true iff the object is contained in the iterable.

toList

public static <T> List<T> toList(Iterable<T> iterable)

Convert an iterable to a list.

Type Parameters:

T - type of the items held.

Parameters:

iterable - to convert.

Returns:

a list.

random

public static <T> T random(Iterable<T> iterable)

Get a random element of the given Iterable. This is functionally equivalent to calling random(Iterable, int) with a sample size of 1.

Type Parameters:

T - The type of the element, as dictated by the given argument.

Parameters:

iterable - The Iterable from which to get a random element.

Returns:

A random element from the given iterable.

Throws:

IllegalArgumentException - if invoked with an empty Iterable.

random

public static <T> Iterable<T> random(Iterable<T> iterable,
                                     int numberOfSamples)

Sample an Iterable using reservoir sampling.

Type Parameters:

T - The type of the element, as dictated by the given Iterable.

Parameters:

iterable - The Iterable from which to sample.

numberOfSamples - The number of elements to return.

Returns:

A new Iterable containing a number of random elements sampled from the Iterable argument.

Throws:

IllegalArgumentException - if invoked with an empty Iterable.

getSingle

public static <T> T getSingle(Iterator<T> iterator,
                              String notFoundMessage)

Get a single element from iterator.

Type Parameters:

T - type of the element.

Parameters:

iterator - to find a single element.

notFoundMessage - exception message if there are no elements.

Returns:

the element iff there is exactly one.

Throws:

NotFoundException - in case there are no elements.

IllegalStateException - in case the iterable contains more than 1 element.

getSingle

public static <T> T getSingle(Iterable<T> iterable,
                              String notFoundMessage)

Get a single element from iterable.

Type Parameters:

T - type of the element.

Parameters:

iterable - to find a single element.

notFoundMessage - exception message if there are no elements.

Returns:

the element iff there is exactly one.

Throws:

NotFoundException - in case there are no elements.

IllegalStateException - in case the iterable contains more than 1 element.

getSingle

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

Get a single element from iterator.

Type Parameters:

T - type of the element.

Parameters:

iterator - to find a single element.

Returns:

the element iff there is exactly one.

Throws:

NotFoundException - in case there are no elements.

IllegalStateException - in case the iterable contains more than 1 element.

getSingle

public static <T> T getSingle(Iterable<T> iterable)

Get a single element from iterable.

Type Parameters:

T - type of the element.

Parameters:

iterable - to find a single element.

Returns:

the element iff there is exactly one.

Throws:

NotFoundException - in case there are no elements.

IllegalStateException - in case the iterable contains more than 1 element.

getSingleOrNull

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

Get a single element from iterator.

Type Parameters:

T - type of the element.

Parameters:

iterator - to find a single element.

Returns:

the element iff there is exactly one, null iff there is 0.

Throws:

IllegalStateException - in case the iterable contains more than 1 element.

getSingleOrNull

public static <T> T getSingleOrNull(Iterable<T> iterable)

Get a single element from iterable.

Type Parameters:

T - type of the element.

Parameters:

iterable - to find a single element.

Returns:

the element iff there is exactly one, null iff there is 0.

Throws:

IllegalStateException - in case the iterable contains more than 1 element.

getFirst

public static <T> T getFirst(Iterator<T> iterator,
                             String notFoundMessage)

Get the first element from iterator.

Type Parameters:

T - type of the element.

Parameters:

iterator - to find the first element.

notFoundMessage - exception message if there are no elements.

Returns:

the element iff there is one or more.

Throws:

NotFoundException - in case there are no elements.

getFirst

public static <T> T getFirst(Iterable<T> iterable,
                             String notFoundMessage)

Get the first element from iterable.

Type Parameters:

T - type of the element.

Parameters:

iterable - to find the first element.

notFoundMessage - exception message if there are no elements.

Returns:

the element iff there is one or more.

Throws:

NotFoundException - in case there are no elements.

getFirstOrNull

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

Get the first element from iterator.

Type Parameters:

T - type of the element.

Parameters:

iterator - to find the first element.

Returns:

the element iff there is one or more, null if there is none.

getFirstOrNull

public static <T> T getFirstOrNull(Iterable<T> iterable)

Get the first element from iterable.

Type Parameters:

T - type of the element.

Parameters:

iterable - to find the first element.

Returns:

the element iff there is one or more, null if there is none.