ch.claude_martin.enumbitset

Class Pair<T,X extends T,Y extends T>

java.lang.Object

ch.claude_martin.enumbitset.Pair<T,X,Y>

Type Parameters:

T - A common type of both elements. Object.class always works.

X - The type of the first element. Extends <T>.

Y - The type of the second element. Extends <T>.

All Implemented Interfaces:

Serializable, Cloneable, Iterable<T>

public final class Pair<T,X extends T,Y extends T>
extends Object
implements Iterable<T>, Cloneable, Serializable

An immutable, ordered pair (2-tuple) of two non-null elements. This can be used in a Cartesian product.

A special characteristic is that each pair has a generic type argument that is a supertype of both elements. As a Cartesian product often uses two related types this can make it easier to work with such a pair.

A pair should never be recursive, that is it should not contain itself directly or indirectly. Some methods will throw a StackOverflowError on recursion.

Author:

Copyright © 2014 Claude Martin

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
X	first The first value of this pair.
Y	second The first value of this pair.

Method Summary

Modifier and Type	Method and Description
X	_1() Scala-style getter for first.
Y	_2() Scala-style getter for second.
<R> R	applyTo(BiFunction<X,Y,R> f) Applies the given function to both elements of this pair.
Pair<T,X,Y>	clone() Returns this pair, as it is immutable.
void	consumeBy(BiConsumer<X,Y> consumer) Performs the operation of the given consumer on both elements of this pair.
static <TT,TX extends TT,TY extends TT,P extends Pair<TT,TX,TY>,R> BiFunction<TX,TY,R>	curry(Function<P,R> f) Converts a function on pairs to a function on two elements.
boolean	equals(Object obj) Compares two pairs for equality (by value comparison).
int	hashCode()
Iterator<T>	iterator() Iterator using a type that is shared by both values.
static <TT,TX extends TT,TY extends TT> Pair<TT,TX,TY>	of(Class<TT> commonType, TX first, TY second) This creates the Pair and checks the types of both values.
static <TT,TX extends TT,TY extends TT> Pair<TT,TX,TY>	of(TX first, TY second) Creates a new pair.
Spliterator<T>	spliterator()
Stream<T>	stream()
Pair<T,Y,X>	swap() Creates an inverted pair.
Object[]	toArray() This Pair as an array so that first is on index 0 and second is on index 1.
String	toString() Returns a string representation of this Pair.
static <TX,TY,R> Function<Pair<?,TX,TY>,R>	uncurry(BiFunction<TX,TY,R> f) Converts a function on two elements to a function on pairs.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach

Field Detail

first

public final X extends T first

The first value of this pair. Not null.

This is also known as the first coordinate or the left projection of the pair.

second

public final Y extends T second

The first value of this pair. Not null.

This is also known as the second coordinate or the right projection of the pair.

Method Detail

curry

public static <TT,TX extends TT,TY extends TT,P extends Pair<TT,TX,TY>,R> BiFunction<TX,TY,R> curry(Function<P,R> f)

Converts a function on pairs to a function on two elements.

Note: The compiler should be able to infer all types. If not then a lambda should be used instead (see example below). The returned value is a BiFunction, not a function that allows partial application. For that it would have to return Function<A, Function<B, C>> instead of BiFunction<A, B, C>.

Example:
Given the following set:
Set<Pair<A, B, C>> set = new HashSet<>();
We can curry the add method:
Pair.curry(set::add)
This is equivalent to this lambda:
(a, b) -> set.add(Pair.of(a, b))

Type Parameters:

TT - Common type. This isn't actually used.

TX - Type of first element. Extends TT.

TY - Type of second element. Extends TT.

P - Actual type of the Pair. This is exactly Pair<TT, TX, TY>.

R - Return type of the given function f.

Parameters:

f - A function that takes a Pair.

Returns:

A BiFunction that takes two elements and applies a created Pair on the given Function.

See Also:

uncurry(BiFunction)

of

public static <TT,TX extends TT,TY extends TT> Pair<TT,TX,TY> of(Class<TT> commonType,
                                                                 TX first,
                                                                 TY second)

This creates the Pair and checks the types of both values.

The common type is checked at construction, but not available later.

Type Parameters:

TT - Common type

TX - Type of first element. Extends TT.

TY - Type of second element. Extends TT.

Parameters:

commonType - The type that both elements implement.

first - The first element.

second - The second element.

Returns:

A new pair of the given elements.

Throws:

ClassCastException - If and of the two elements is not assignable to commonType.

NullPointerException - If any of the elements is null.

of

public static <TT,TX extends TT,TY extends TT> Pair<TT,TX,TY> of(TX first,
                                                                 TY second)

Creates a new pair.

Type Parameters:

TT - Common type

TX - Type of first element. Extends TT.

TY - Type of second element. Extends TT.

Parameters:

first - The first element.

second - The second element.

Returns:

A new pair of the given elements.

Throws:

NullPointerException - If any of the elements is null.

uncurry

public static <TX,TY,R> Function<Pair<?,TX,TY>,R> uncurry(BiFunction<TX,TY,R> f)

Converts a function on two elements to a function on pairs.

Type Parameters:

TX - Type of first element.

TY - Type of second element.

R - Return type of f.

Parameters:

f - A BiFunction that takes two elements.

Returns:

A Function that takes a pair and applies both elements on the given Function.

See Also:

curry(Function), applyTo(BiFunction)

_1

public X _1()

Scala-style getter for first.

Returns:

the first element (not null).

See Also:

first

_2

public Y _2()

Scala-style getter for second.

Returns:

the second element (not null).

See Also:

second

applyTo

public <R> R applyTo(BiFunction<X,Y,R> f)

Applies the given function to both elements of this pair.

Type Parameters:

R - return type.

Parameters:

f - A function on two elements.

Returns:

The result of applying this pair to f.

Throws:

NullPointerException - if f is null

See Also:

uncurry(BiFunction)

clone

public Pair<T,X,Y> clone()

Returns this pair, as it is immutable.

Overrides:

clone in class Object

Returns:

this

consumeBy

public void consumeBy(BiConsumer<X,Y> consumer)

Performs the operation of the given consumer on both elements of this pair.

Parameters:

consumer - A consumer of two elements.

Throws:

NullPointerException - if consumer is null

See Also:

uncurry(BiFunction)

equals

public boolean equals(Object obj)

Compares two pairs for equality (by value comparison). The given object must also be a pair and contain two elements that are equal to this pair's elements.

Overrides:

equals in class Object

Returns:

true, iff both first and second are equal.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

Returns:

Objects.hash(this.first, this.second)

iterator

public Iterator<T> iterator()

Iterator using a type that is shared by both values. The type is checked before the iterator is created.

Specified by:

iterator in interface Iterable<T>

spliterator

public Spliterator<T> spliterator()

Specified by:

spliterator in interface Iterable<T>

stream

public Stream<T> stream()

swap

public Pair<T,Y,X> swap()

Creates an inverted pair.

(a, b) → (b, a)

Returns:

new Pair<>(this.second, this.first)

toArray

public Object[] toArray()

This Pair as an array so that first is on index 0 and second is on index 1.

Returns:

new Object[] { this.first, this.second };

toString

public String toString()

Returns a string representation of this Pair.

This could lead to recursion in rare cases. Pairs, Collections, Arrays, References etc. are always represented by their type. But this can still lead to a StackOverflowError.

Overrides:

toString in class Object

Returns:

"Pair(first, second)"