ImmutablePair (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3.tuple, class: ImmutablePair

# Class ImmutablePair<L,R>

java.lang.Object
org.apache.commons.lang3.tuple.Pair<L,R>
org.apache.commons.lang3.tuple.ImmutablePair<L,R>

Type Parameters:
  `L` - the left element type
  `R` - the right element type

All Implemented Interfaces:
  `Serializable, Comparable<Pair<L,R>>, Map.Entry<L,R>`

Direct Known Subclasses:
  `StopWatch.Split`

public class ImmutablePair<L,R> extends Pair<L,R>
An immutable pair consisting of two `Object` elements.

Although the implementation is immutable, there is no restriction on the objects that may be stored. If mutable objects are stored in the pair, then the pair itself effectively becomes mutable.

#ThreadSafe# if both paired objects are thread-safe

Since:
  3.0
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ImmutablePair<?,?>[]`
  `EMPTY_ARRAY`
  An empty array.
  `final L`
  `left`
  Left object
  `final R`
  `right`
  Right object

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ImmutablePair(L left, R right)`
  Create a new pair instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <L,R> ImmutablePair<L,R>[]`
  `emptyArray()`
  Returns the empty array singleton that can be assigned without compiler warning.
  `L`
  `getLeft()`
  Gets the left element from this pair.
  `R`
  `getRight()`
  Gets the right element from this pair.
  `static <L,R> Pair<L,R>`
  `left(L left)`
  Creates an immutable pair of two objects inferring the generic types.
  `static <L,R> ImmutablePair<L,R>`
  `nullPair()`
  Returns an immutable pair of nulls.
  `static <L,R> ImmutablePair<L,R>`
  `of(Map.Entry<L,R> pair)`
  Creates an immutable pair from a map entry.
  `static <L,R> ImmutablePair<L,R>`
  `of(L left, R right)`
  Creates an immutable pair of two objects inferring the generic types.
  `static <L,R> ImmutablePair<L,R>`
  `ofNonNull(L left, R right)`
  Creates an immutable pair of two non-null objects inferring the generic types.
  `static <L,R> Pair<L,R>`
  `right(R right)`
  Creates an immutable pair of two objects inferring the generic types.
  `R`
  `setValue(R value)`
  Throws `UnsupportedOperationException`.

  ### Methods inherited from class Pair

  `accept, apply, compareTo, equals, getKey, getValue, hashCode, toString, toString`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### EMPTY_ARRAY

    public static final ImmutablePair<?,?>[] EMPTY_ARRAY
    An empty array.

    Consider using `emptyArray()` to avoid generics warnings.

    Since:
      3.10

  - ### left

    public final L left
    Left object

  - ### right

    public final R right
    Right object

- ## Constructor Details

  - ### ImmutablePair

    public ImmutablePair(L left, R right)
    Create a new pair instance.
    Parameters:
      `left` - the left value, may be null
      `right` - the right value, may be null

- ## Method Details

  - ### emptyArray

    public static <L,R> ImmutablePair<L,R>[] emptyArray()
    Returns the empty array singleton that can be assigned without compiler warning.
    Type Parameters:
      `L` - the left element type
      `R` - the right element type
    Returns:
      the empty array singleton that can be assigned without compiler warning.
    Since:
      3.10

  - ### left

    public static <L,R> Pair<L,R> left(L left)
    Creates an immutable pair of two objects inferring the generic types.
    Type Parameters:
      `L` - the left element type.
      `R` - the right element type.
    Parameters:
      `left` - the left element, may be null.
    Returns:
      an immutable formed from the two parameters, not null.
    Since:
      3.11

  - ### nullPair

    public static <L,R> ImmutablePair<L,R> nullPair()
    Returns an immutable pair of nulls.
    Type Parameters:
      `L` - the left element of this pair. Value is `null`.
      `R` - the right element of this pair. Value is `null`.
    Returns:
      an immutable pair of nulls.
    Since:
      3.6

  - ### of

    public static <L,R> ImmutablePair<L,R> of(L left, R right)
    Creates an immutable pair of two objects inferring the generic types.
    Type Parameters:
      `L` - the left element type.
      `R` - the right element type.
    Parameters:
      `left` - the left element, may be null.
      `right` - the right element, may be null.
    Returns:
      an immutable formed from the two parameters, not null.

  - ### of

    public static <L,R> ImmutablePair<L,R> of(Map.Entry<L,R> pair)
    Creates an immutable pair from a map entry.
    Type Parameters:
      `L` - the left element type.
      `R` - the right element type.
    Parameters:
      `pair` - the existing map entry.
    Returns:
      an immutable formed from the map entry.
    Since:
      3.10

  - ### ofNonNull

    public static <L,R> ImmutablePair<L,R> ofNonNull(L left, R right)
    Creates an immutable pair of two non-null objects inferring the generic types.
    Type Parameters:
      `L` - the left element type.
      `R` - the right element type.
    Parameters:
      `left` - the left element, may not be null.
      `right` - the right element, may not be null.
    Returns:
      an immutable formed from the two parameters, not null.
    Throws:
      `NullPointerException` - if any input is null.
    Since:
      3.13.0

  - ### right

    public static <L,R> Pair<L,R> right(R right)
    Creates an immutable pair of two objects inferring the generic types.
    Type Parameters:
      `L` - the left element type.
      `R` - the right element type.
    Parameters:
      `right` - the right element, may be null.
    Returns:
      an immutable formed from the two parameters, not null.
    Since:
      3.11

  - ### getLeft

    public L getLeft()
    Gets the left element from this pair.

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

    Specified by:
      `getLeft` in class `Pair<L,R>`
    Returns:
      the left element, may be null.

  - ### getRight

    public R getRight()
    Gets the right element from this pair.

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

    Specified by:
      `getRight` in class `Pair<L,R>`
    Returns:
      the right element, may be null.

  - ### setValue

    public R setValue(R value)
    Throws `UnsupportedOperationException`.

    This pair is immutable, so this operation is not supported.

    Parameters:
      `value` - the value to set
    Returns:
      never
    Throws:
      `UnsupportedOperationException` - as this operation is not supported