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. The class is also `final`, so a subclass can not add undesirable behavior.

  #ThreadSafe# if both paired objects are thread-safe

  Since:
    3.0
  See Also:
    Serialized Form

- - ### Field Summary

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

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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(L left, R right)` Creates an immutable pair of two objects inferring the generic types.
    `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>` | `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`

    - ### Methods inherited from interface java.util.Map.Entry

      `comparingByKey, comparingByKey, comparingByValue, comparingByValue`

- - ### Field Detail

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

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

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

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.