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

Package org.apache.commons.lang3.tuple

# 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>`

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 org.apache.commons.lang3.tuple.Pair

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

  ### Methods inherited from class java.lang.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.

    This factory allows the pair to be created using inference to obtain the generic types.

    Type Parameters:
      `L` - the left element type
      `R` - the right element type
    Parameters:
      `left` - the left element, may be null
    Returns:
      a pair 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.

    This factory allows the pair to be created using inference to obtain 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:
      a pair 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.

    This factory allows the pair to be created using inference to obtain the generic types.

    Type Parameters:
      `L` - the left element type
      `R` - the right element type
    Parameters:
      `pair` - the existing map entry.
    Returns:
      a pair 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.

    This factory allows the pair to be created using inference to obtain 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:
      a pair 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.

    This factory allows the pair to be created using inference to obtain the generic types.

    Type Parameters:
      `L` - the left element type
      `R` - the right element type
    Parameters:
      `right` - the right element, may be null
    Returns:
      a pair 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