org.threadly.util

Class Pair<L,R>

java.lang.Object

org.threadly.util.Pair<L,R>

Type Parameters:

L - Type of 'left' object to be held

R - Type of 'right' object to be held

Direct Known Subclasses:

MutablePair

public class Pair<L,R>
extends java.lang.Object

A simple tuple implementation (every library needs one, right?). This is designed to be a minimal and light weight pair holder.

Since:

4.4.0

Constructor Summary

Constructors

Constructor and Description
Pair(L left, R right) Constructs a new pair, providing the left and right objects to be held.

Method Summary

Modifier and Type	Method and Description
static <L> void	applyToLeft(java.lang.Iterable<? extends Pair<? extends L,?>> source, java.util.function.Consumer<? super L> consumer) Goes through source Iterable and provides all left entries to a given consumer.
static <R> void	applyToRight(java.lang.Iterable<? extends Pair<?,? extends R>> source, java.util.function.Consumer<? super R> consumer) Goes through source Iterable and provides all right entries to a given consumer.
static <T> java.util.List<T>	collectLeft(java.util.Collection<? extends Pair<? extends T,?>> source) Collect all the non-null left references into a new List.
static <T> java.util.List<T>	collectRight(java.util.Collection<? extends Pair<?,? extends T>> source) Collect all the non-null right references into a new List.
static boolean	containsLeft(java.lang.Iterable<? extends Pair<?,?>> search, java.lang.Object value) Simple search to see if a collection of pairs contains a given left value.
static boolean	containsRight(java.lang.Iterable<? extends Pair<?,?>> search, java.lang.Object value) Simple search to see if a collection of pairs contains a given right value.
static <L,R> java.util.List<Pair<L,R>>	convertMap(java.util.Map<? extends L,? extends R> map) Convert a map into a list of Pair's where the left side of the pair contains the value and the right side is the corresponding value.
boolean	equals(java.lang.Object o)
L	getLeft() Getter to get the left reference stored in the pair.
static <T> T	getLeftFromRight(java.lang.Iterable<? extends Pair<? extends T,?>> search, java.lang.Object right) Get the left side of a pair by searching for a matching right side.
R	getRight() Getter to get the right reference stored in the pair.
static <T> T	getRightFromLeft(java.lang.Iterable<? extends Pair<?,? extends T>> search, java.lang.Object left) Get the right side of a pair by searching for a matching left side.
int	hashCode()
static <T> java.lang.Iterable<T>	iterateLeft(java.lang.Iterable<? extends Pair<? extends T,?>> i) Convert a Pair Iterator into an iterator that returns the left items.
static <T> java.util.Iterator<T>	iterateLeft(java.util.Iterator<? extends Pair<? extends T,?>> i) Convert a Pair Iterator into an iterator that returns the left items.
static <T> java.lang.Iterable<T>	iterateRight(java.lang.Iterable<? extends Pair<?,? extends T>> i) Convert a Pair Iterator into an iterator that returns the right items.
static <T> java.util.Iterator<T>	iterateRight(java.util.Iterator<? extends Pair<?,? extends T>> i) Convert a Pair Iterator into an iterator that returns the right items.
static <L,R> Pair<java.util.List<L>,java.util.List<R>>	split(java.util.Collection<? extends Pair<? extends L,? extends R>> source) Split a collection of pair's into a pair of two collections.
java.lang.String	toString()
static <OL,NL,OR,NR> java.util.List<Pair<NL,NR>>	transform(java.util.Collection<? extends Pair<? extends OL,? extends OR>> source, java.util.function.Function<? super OL,? extends NL> leftTransformer, java.util.function.Function<? super OR,? extends NR> rightTransformer) Function to assist in transforming a collection of pairs into a new resulting list.
static <OL,NL,R> java.util.List<Pair<NL,R>>	transformLeft(java.util.Collection<? extends Pair<? extends OL,? extends R>> source, java.util.function.Function<? super OL,? extends NL> transformer) Function to assist in transforming the left side of pairs from one form to another.
static <L,OR,NR> java.util.List<Pair<L,NR>>	transformRight(java.util.Collection<? extends Pair<? extends L,? extends OR>> source, java.util.function.Function<? super OR,? extends NR> transformer) Function to assist in transforming the right side of pairs from one form to another.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Pair

public Pair(L left,
            R right)

Constructs a new pair, providing the left and right objects to be held.

Parameters:

left - Left reference

right - Right reference

Method Detail

transformLeft

public static <OL,NL,R> java.util.List<Pair<NL,R>> transformLeft(java.util.Collection<? extends Pair<? extends OL,? extends R>> source,
                                                                 java.util.function.Function<? super OL,? extends NL> transformer)

Function to assist in transforming the left side of pairs from one form to another. This will iterate through the source, applying the provided transformer function to each left side entry. The resulting list will contain new pair instances with the transformed left entries and the original right side entries.

If both the left and right sides must be transformed please see transform(Collection, Function, Function).

Type Parameters:

OL - Original left side type for input source

NL - Transformed left side type for resulting list

R - Type of object held as pair's right reference

Parameters:

source - Source collection to be iterating over

transformer - Function to apply to the left side entries

Returns:

New list of transformed pairs

transformRight

public static <L,OR,NR> java.util.List<Pair<L,NR>> transformRight(java.util.Collection<? extends Pair<? extends L,? extends OR>> source,
                                                                  java.util.function.Function<? super OR,? extends NR> transformer)

Function to assist in transforming the right side of pairs from one form to another. This will iterate through the source, applying the provided transformer function to each right side entry. The resulting list will contain new pair instances with the transformed right entries and the original left side entries.

If both the left and right sides must be transformed please see transform(Collection, Function, Function).

Type Parameters:

OR - Original right side type for input source

NR - Transformed right side type for resulting list

L - Type of object held as pair's left reference

Parameters:

source - Source collection to be iterating over

transformer - Function to apply to the right side entries

Returns:

New list of transformed pairs

transform

public static <OL,NL,OR,NR> java.util.List<Pair<NL,NR>> transform(java.util.Collection<? extends Pair<? extends OL,? extends OR>> source,
                                                                  java.util.function.Function<? super OL,? extends NL> leftTransformer,
                                                                  java.util.function.Function<? super OR,? extends NR> rightTransformer)

Function to assist in transforming a collection of pairs into a new resulting list. This simply iterates over the provided collection and applies the left and right transformers to each pair. Returning a new list with the resulting transformed values contained in the pairs.

Type Parameters:

OL - Original left side type for input source

OR - Original right side type for input source

NL - Transformed left side type for resulting list

NR - Transformed right side type for resulting list

Parameters:

source - Source collection to be iterating over

leftTransformer - Function to apply to the left side entries

rightTransformer - Function to apply to the right side entries

Returns:

New list of transformed pairs

applyToLeft

public static <L> void applyToLeft(java.lang.Iterable<? extends Pair<? extends L,?>> source,
                                   java.util.function.Consumer<? super L> consumer)

Goes through source Iterable and provides all left entries to a given consumer.

Type Parameters:

L - Type of object held as pair's left reference

Parameters:

source - Source to iterate through

consumer - Consumer to provide left entries to

applyToRight

public static <R> void applyToRight(java.lang.Iterable<? extends Pair<?,? extends R>> source,
                                    java.util.function.Consumer<? super R> consumer)

Goes through source Iterable and provides all right entries to a given consumer.

Type Parameters:

R - Type of object held as pair's right reference

Parameters:

source - Source to iterate through

consumer - Consumer to provide right entries to

convertMap

public static <L,R> java.util.List<Pair<L,R>> convertMap(java.util.Map<? extends L,? extends R> map)

Convert a map into a list of Pair's where the left side of the pair contains the value and the right side is the corresponding value.

Type Parameters:

L - Type of object held as pair's left reference

R - Type of object held as pair's right reference

Parameters:

map - Map to source entries from

Returns:

A list of pairs sourced from the map's entries

split

public static <L,R> Pair<java.util.List<L>,java.util.List<R>> split(java.util.Collection<? extends Pair<? extends L,? extends R>> source)

Split a collection of pair's into a pair of two collections. This is more efficient than invoking getLeft() and getRight() separately. Similar to those functions, this will only collect non-null entries. If there is a null left or right entry then the indexes will no longer match each other between the two lists.

Type Parameters:

L - Type of object held as pair's left reference

R - Type of object held as pair's right reference

Parameters:

source - Source collection of pairs

Returns:

Pair of two collections with the left and right halves

iterateLeft

public static <T> java.lang.Iterable<T> iterateLeft(java.lang.Iterable<? extends Pair<? extends T,?>> i)

Convert a Pair Iterator into an iterator that returns the left items. This has the minor advantage over collectLeft(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.

Type Parameters:

T - Type of object held as pair's left reference

Parameters:

i - Iterable to source pairs from

Returns:

An iterator that extracts out the left entry of each pair

iterateLeft

public static <T> java.util.Iterator<T> iterateLeft(java.util.Iterator<? extends Pair<? extends T,?>> i)

Convert a Pair Iterator into an iterator that returns the left items. This has the minor advantage over collectLeft(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.

Type Parameters:

T - Type of object held as pair's left reference

Parameters:

i - Iterator to source pairs from

Returns:

An iterator that extracts out the left entry of each pair

iterateRight

public static <T> java.lang.Iterable<T> iterateRight(java.lang.Iterable<? extends Pair<?,? extends T>> i)

Convert a Pair Iterator into an iterator that returns the right items. This has the minor advantage over collectRight(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.

Type Parameters:

T - Type of object held as pair's right reference

Parameters:

i - Iterable to source pairs from

Returns:

An iterator that extracts out the right entry of each pair

iterateRight

public static <T> java.util.Iterator<T> iterateRight(java.util.Iterator<? extends Pair<?,? extends T>> i)

Convert a Pair Iterator into an iterator that returns the right items. This has the minor advantage over collectRight(Collection) in that the collection is not iterated / copied. Allowing for potential concurrent structures to provide their special iterator behavior through this, as well as avoiding a potential short term memory copy.

Type Parameters:

T - Type of object held as pair's right reference

Parameters:

i - Iterator to source pairs from

Returns:

An iterator that extracts out the right entry of each pair

collectLeft

public static <T> java.util.List<T> collectLeft(java.util.Collection<? extends Pair<? extends T,?>> source)

Collect all the non-null left references into a new List. A simple implementation which iterates over a source collection and collects all non-null left references into a new list that can be manipulated or referenced.

Type Parameters:

T - Type of object held as pair's left reference

Parameters:

source - Source collection of pairs

Returns:

New list that contains non-null left references

collectRight

public static <T> java.util.List<T> collectRight(java.util.Collection<? extends Pair<?,? extends T>> source)

Collect all the non-null right references into a new List. A simple implementation which iterates over a source collection and collects all non-null right references into a new list that can be manipulated or referenced.

Type Parameters:

T - Type of object held as pair's right reference

Parameters:

source - Source collection of pairs

Returns:

New list that contains non-null right references

containsLeft

public static boolean containsLeft(java.lang.Iterable<? extends Pair<?,?>> search,
                                   java.lang.Object value)

Simple search to see if a collection of pairs contains a given left value. It is assumed that the iterator will not return any null elements.

Parameters:

search - Iterable to search over

value - Value to be searching for from left elements

Returns:

true if the value is found as a left element from the iterable provided

containsRight

public static boolean containsRight(java.lang.Iterable<? extends Pair<?,?>> search,
                                    java.lang.Object value)

Simple search to see if a collection of pairs contains a given right value. It is assumed that the iterator will not return any null elements.

Parameters:

search - Iterable to search over

value - Value to be searching for from right elements

Returns:

true if the value is found as a right element from the iterable provided

getRightFromLeft

public static <T> T getRightFromLeft(java.lang.Iterable<? extends Pair<?,? extends T>> search,
                                     java.lang.Object left)

Get the right side of a pair by searching for a matching left side. This iterates over the provided source, and once the first pair with a left that matches (via Object.equals(Object)), the right side is returned. If no match is found, null will be returned. Although the implementer must be aware that since nulls can be kept kept inside pairs, that does not strictly indicate a match failure.

Type Parameters:

T - Type of object held as pair's right reference

Parameters:

search - Iteratable to search through looking for a match

left - Object to be looking searching for as a left reference

Returns:

Corresponding right reference or null if none is found

getLeftFromRight

public static <T> T getLeftFromRight(java.lang.Iterable<? extends Pair<? extends T,?>> search,
                                     java.lang.Object right)

Get the left side of a pair by searching for a matching right side. This iterates over the provided source, and once the first pair with a right that matches (via Object.equals(Object)), the left side is returned. If no match is found, null will be returned. Although the implementer must be aware that since nulls can be kept kept inside pairs, that does not strictly indicate a match failure.

Type Parameters:

T - Type of object held as pair's left reference

Parameters:

search - Iteratable to search through looking for a match

right - Object to be looking searching for as a left reference

Returns:

Corresponding left reference or null if none is found

getLeft

public L getLeft()

Getter to get the left reference stored in the pair.

Returns:

Left reference

getRight

public R getRight()

Getter to get the right reference stored in the pair.

Returns:

Right reference

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object