de.caff.generics

## Class NullableUnion<T1,T2>

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

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

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

  This class defines a union structure for two values, where only one of them exists. 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 with valid values:

  - `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`
  And two more for `null` values:
  - `nul1()` will return a static union which contains a `null` value of type `T1`
  - `nul2()` will return a static union which contains a `null` value of type `T2`
  This implementation allows for either type to be `null`. Any consumers should be prepared for `null` values. See `Union` for an implementation which does not allow for `null` values.
  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`.
    `java.lang.Object` | `getValue()` Get the value contained in this union.
    `static <V1,V2> NullableUnion<V1,V2>` | `nul1()` Get a union with a first type of `null`.
    `static <V1,V2> NullableUnion<V1,V2>` | `nul2()` Get a union with a second type of `null`.
    `static <V1,V2> NullableUnion<V1,V2>` | `t1(V1 v1)` Create a union containing a value of type V1.
    `static <V1,V2> NullableUnion<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

          @Nullable
          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`, possibly `null`
      Throws:
        `java.lang.IllegalStateException` - if this union does contain a value of type `T2`
      See Also:
        `UnionBase.has1()`

    - #### get2

          @Nullable
          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`, possibly `null`
      Throws:
        `java.lang.IllegalStateException` - if this union does contain a value of type `T1`
      See Also:
        `UnionBase.has1()`

    - #### getValue

          @Nullable
          public 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`, possibly `null`

    - #### t1

          @NotNull
          public static <V1,V2> NullableUnion<V1,V2> t1(@Nullable
                                                                 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> NullableUnion<V1,V2> t2(@Nullable
                                                                 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`

    - #### nul1

          @NotNull
          public static <V1,V2> NullableUnion<V1,V2> nul1()

      Get a union with a first type of `null`.
      Type Parameters:
        `V1` - first possible type
        `V2` - second possible type
      Returns:
        union of type `V1`, with a value of `null`

    - #### nul2

          @NotNull
          public static <V1,V2> NullableUnion<V1,V2> nul2()

      Get a union with a second type of `null`.
      Type Parameters:
        `V1` - first possible type
        `V2` - second possible type
      Returns:
        union of type `V2`, with a value of `null`