de.caff.generics

## Class Union<T1,T2>

- java.lang.Object
- - de.caff.generics.UnionBase<T1,T2>
  - - de.caff.generics.Union<T1,T2>

- Type Parameters:
    `T1` - type of the first possible value
    `T2` - type of the second possible value

      public abstract class Union<T1,T2>
      extends UnionBase<T1,T2>

  This class defines a union structure for two exclusive values of different types.

  This is sometimes useful to transport errors from one part to the other, when throwing them is no option. This is a type-safe implementation of a 2-member `union` structure as defined in the C programming language.

  This class allows no overriding to guarantee the following invariances:

  - `u.has1() ^ u.has2()` is always `true`
  A union is immutable in the sense that it itself does not change. The contained values may change if they are mutable.

  There is exactly one way to construct a union of either type:

  - `t1(Object)` will construct a union which contains a value of type `T1`
  - `t2(Object)` will construct a union which contains a value of type `T2`

  This implementation does not allow `null` values. Any consumers can safely assume that the values they achieve are non-`null`. See `NullableUnion` if support for `null` is required.

  Since:
    July 26, 2024
  Author:
    Rammi

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract T1` | `get1()` Get the value if it is of type `T1`.
    `abstract T2` | `get2()` Get the value if it is of type `T2`.
    `abstract java.lang.Object` | `getValue()` Get the value contained in this union.
    `static <V1,V2> Union<V1,V2>` | `t1(V1 v1)` Create a union containing a value of type V1.
    `static <V1,V2> Union<V1,V2>` | `t2(V2 v2)` Create a union containing a value of type V2.

    - ### Methods inherited from class de.caff.generics.UnionBase

      `dispose, disposeFragile1, disposeFragile2, disposeOnly1, disposeOnly2, has1, has2, isEqual1, isEqual2`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### get1

          @NotNull
          public abstract T1 get1()
                                    throws java.lang.IllegalStateException

      Get the value if it is of type `T1`. Throw an exception otherwise.
      Specified by:
        `get1` in class `UnionBase<T1,T2>`
      Returns:
        value of type `T1`
      Throws:
        `java.lang.IllegalStateException` - if this union does contain a value of type `T2`
      See Also:
        `UnionBase.has1()`

    - #### get2

          @NotNull
          public abstract T2 get2()
                                    throws java.lang.IllegalStateException

      Get the value if it is of type `T2`. Throw an exception otherwise.
      Specified by:
        `get2` in class `UnionBase<T1,T2>`
      Returns:
        value of type `T2`
      Throws:
        `java.lang.IllegalStateException` - if this union does contain a value of type `T1`
      See Also:
        `UnionBase.has1()`

    - #### getValue

          @NotNull
          public abstract java.lang.Object getValue()

      Get the value contained in this union.
      Specified by:
        `getValue` in class `UnionBase<T1,T2>`
      Returns:
        the value of this union, having either type `T1` or `T2`

    - #### t1

          @NotNull
          public static <V1,V2> Union<V1,V2> t1(@NotNull
                                                         V1 v1)

      Create a union containing a value of type V1.
      Type Parameters:
        `V1` - value type of contained value
        `V2` - implicit
      Parameters:
        `v1` - value contained in this union
      Returns:
        union with value `v1`

    - #### t2

          @NotNull
          public static <V1,V2> Union<V1,V2> t2(@NotNull
                                                         V2 v2)

      Create a union containing a value of type V2.
      Type Parameters:
        `V1` - implicit
        `V2` - value type of contained value
      Parameters:
        `v2` - value contained in this union
      Returns:
        union with value `v2`