Top Description Fields Constructors Methods
org.apache.commons.lang3.tuple

public abstract Class Pair<L, R>

extends Object
implements Map.Entry<L, R>, Comparable<Pair<L, R>>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.lang.Comparable, java.util.Map.Entry
Known Direct Subclasses
org.apache.commons.lang3.builder.Diff, org.apache.commons.lang3.tuple.ImmutablePair, org.apache.commons.lang3.tuple.MutablePair
Type Parameters
<L>
the left element type.
<R>
the right element type.
Imports
java.io.Serializable, java.util.Map, .Objects, org.apache.commons.lang3.builder.CompareToBuilder, org.apache.commons.lang3.function.FailableBiConsumer, .FailableBiFunction
A pair consisting of two elements.

This class is an abstract implementation defining the basic API. It refers to the elements as 'left' and 'right'. It also implements the Map.Entry interface where the key is 'left' and the value is 'right'.

Subclass implementations may be mutable or immutable. However, there is no restriction on the type of the stored objects that may be stored. If mutable objects are stored in the pair, then the pair itself effectively becomes mutable.

Since
3.0

Field Summary

Modifier and TypeField and Description
public static final Pair<?, ?>[]
EMPTY_ARRAY

An empty array.

private static final long
serialVersionUID

Serialization version

Constructor Summary

AccessConstructor and Description
public
Pair()

Constructs a new instance.

Method Summary

Modifier and TypeMethod and Description
public <
The kind of thrown exception or error.
E extends Throwable> void
accept(final FailableBiConsumer<L, R, E>
the consumer to call.
consumer)

Accepts this key and value as arguments to the given consumer.

public <
The function return type.
V,
The kind of thrown exception or error.
E extends Throwable> V

Returns:

the function's return value.
apply(final FailableBiFunction<L, R, V, E>
the consumer to call.
function)

Applies this key and value as arguments to the given function.

public int

Returns:

negative if this is less, zero if equal, positive if greater.
compareTo(final Pair<L, R>
the other pair, not null.
other)

Implements java.lang.Comparable.compareTo.

Compares the pair based on the left element followed by the right element.

public static <
the left element type.
L,
the right element type.
R> Pair<L, R>[]

Returns:

the empty array singleton that can be assigned without compiler warning.
emptyArray()

Returns the empty array singleton that can be assigned without compiler warning.

public boolean

Returns:

true if the elements of the pair are equal.
equals(final Object
the object to compare to, null returns false.
obj)

Overrides java.lang.Object.equals.

Implements java.util.Map.Entry.equals.

Compares this pair to another based on the two elements.

public final L

Returns:

the left element as the key, may be null.
getKey()

Implements java.util.Map.Entry.getKey.

Gets the key from this pair.

public abstract L

Returns:

the left element, may be null.
getLeft()

Gets the left element from this pair.

public abstract R

Returns:

the right element, may be null.
getRight()

Gets the right element from this pair.

public R

Returns:

the right element as the value, may be null.
getValue()

Implements java.util.Map.Entry.getValue.

Gets the value from this pair.

public int

Returns:

the hash code.
hashCode()

Overrides java.lang.Object.hashCode.

Implements java.util.Map.Entry.hashCode.

Returns a suitable hash code.

public static <
the left element type.
L,
the right element type.
R> Pair<L, R>

Returns:

an immutable pair formed from the two parameters, not null.
of(final L
the left element, may be null.
left, final R
the right element, may be null.
right)

Creates an immutable pair of two objects inferring the generic types.

public static <
the left element type.
L,
the right element type.
R> Pair<L, R>

Returns:

an immutable pair formed from the map entry.
of(final Map.Entry<L, R>
the map entry.
pair)

Creates an immutable pair from a map entry.

public static <
the left element type.
L,
the right element type.
R> Pair<L, R>

Returns:

an immutable pair formed from the two parameters, not null.
ofNonNull(final L
the left element, may not be null.
left, final R
the right element, may not be null.
right)

Creates an immutable pair of two non-null objects inferring the generic types.

public String

Returns:

a string describing this object, not null.
toString()

Overrides java.lang.Object.toString.

Returns a String representation of this pair using the format (left,right).

public String

Returns:

the formatted string, not null.
toString(final String
the format string, optionally containing %1$s and %2$s, not null.
format)

Formats the receiver using the given format.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

EMPTY_ARRAYback to summary
public static final Pair<?, ?>[] EMPTY_ARRAY

An empty array.

Consider using emptyArray() to avoid generics warnings.

Since
3.10
serialVersionUIDback to summary
private static final long serialVersionUID

Serialization version

Constructor Detail

Pairback to summary
public Pair()

Constructs a new instance.

Method Detail

acceptback to summary
public <E extends Throwable> void accept(final FailableBiConsumer<L, R, E> consumer) throws FailableBiConsumer:E

Accepts this key and value as arguments to the given consumer.

Parameters
<E>
The kind of thrown exception or error.
consumer:FailableBiConsumer<L, R, E>

the consumer to call.

Exceptions
FailableBiConsumer:E:
Thrown when the consumer fails.
Since
3.13.0
applyback to summary
public <V, E extends Throwable> V apply(final FailableBiFunction<L, R, V, E> function) throws FailableBiConsumer:E

Applies this key and value as arguments to the given function.

Parameters
<V>
The function return type.
<E>
The kind of thrown exception or error.
function:FailableBiFunction<L, R, V, E>

the consumer to call.

Returns:V

the function's return value.

Exceptions
FailableBiConsumer:E:
Thrown when the consumer fails.
Since
3.13.0
compareToback to summary
public int compareTo(final Pair<L, R> other)

Implements java.lang.Comparable.compareTo.

Compares the pair based on the left element followed by the right element. The types must be Comparable.

Parameters
other:Pair<L, R>

the other pair, not null.

Returns:int

negative if this is less, zero if equal, positive if greater.

Annotations
@Override
emptyArrayback to summary
public static <L, R> Pair<L, R>[] emptyArray()

Returns the empty array singleton that can be assigned without compiler warning.

Parameters
<L>
the left element type.
<R>
the right element type.
Returns:Pair<L, R>[]

the empty array singleton that can be assigned without compiler warning.

Annotations
@SuppressWarnings:unchecked
Since
3.10
equalsback to summary
public boolean equals(final Object obj)

Overrides java.lang.Object.equals.

Implements java.util.Map.Entry.equals.

Compares this pair to another based on the two elements.

Parameters
obj:Object

the object to compare to, null returns false.

Returns:boolean

true if the elements of the pair are equal.

Annotations
@Override
getKeyback to summary
public final L getKey()

Implements java.util.Map.Entry.getKey.

Gets the key from this pair.

This method implements the Map.Entry interface returning the left element as the key.

Returns:L

the left element as the key, may be null.

Annotations
@Override
getLeftback to summary
public abstract L getLeft()

Gets the left element from this pair.

When treated as a key-value pair, this is the key.

Returns:L

the left element, may be null.

getRightback to summary
public abstract R getRight()

Gets the right element from this pair.

When treated as a key-value pair, this is the value.

Returns:R

the right element, may be null.

getValueback to summary
public R getValue()

Implements java.util.Map.Entry.getValue.

Gets the value from this pair.

This method implements the Map.Entry interface returning the right element as the value.

Returns:R

the right element as the value, may be null.

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Implements java.util.Map.Entry.hashCode.

Returns a suitable hash code.

The hash code follows the definition in Map.Entry.

Returns:int

the hash code.

Annotations
@Override
ofback to summary
public static <L, R> Pair<L, R> of(final L left, final R right)

Creates an immutable pair of two objects inferring the generic types.

Parameters
<L>
the left element type.
<R>
the right element type.
left:L

the left element, may be null.

right:R

the right element, may be null.

Returns:Pair<L, R>

an immutable pair formed from the two parameters, not null.

ofback to summary
public static <L, R> Pair<L, R> of(final Map.Entry<L, R> pair)

Creates an immutable pair from a map entry.

Parameters
<L>
the left element type.
<R>
the right element type.
pair:Map.Entry<L, R>

the map entry.

Returns:Pair<L, R>

an immutable pair formed from the map entry.

Since
3.10
ofNonNullback to summary
public static <L, R> Pair<L, R> ofNonNull(final L left, final R right)

Creates an immutable pair of two non-null objects inferring the generic types.

Parameters
<L>
the left element type.
<R>
the right element type.
left:L

the left element, may not be null.

right:R

the right element, may not be null.

Returns:Pair<L, R>

an immutable pair formed from the two parameters, not null.

Exceptions
NullPointerException:
if any input is null.
Since
3.13.0
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a String representation of this pair using the format (left,right).

Returns:String

a string describing this object, not null.

Annotations
@Override
toStringback to summary
public String toString(final String format)

Formats the receiver using the given format.

This uses String#format(String, Object...) to the format. Two variables may be used to embed the left and right elements. Use %1$s for the left element (key) and %2$s for the right element (value).

Parameters
format:String

the format string, optionally containing %1$s and %2$s, not null.

Returns:String

the formatted string, not null.

See Also
String#format(String, Object...)