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.

It is more efficient to use the following branchless methods for handling unions instead of combinations of UnionBase.has1()/get1() and UnionBase.has2()/get2():

• Use UnionBase.dispose(Consumer, Consumer) to handle the value wrapped in this union. Note that the consumers must expect null arguments.
• Use UnionBase.test(Predicate, Predicate) to perform a test on the values in this union. Note that the predicates must expect null arguments.
• Use UnionBase.condense(Function, Function) to combine both types of values into one common outcoming value. Note that the functions must expect null arguments.

An example for the latter is

 String txt = u.condense(Objects::toString, Objects::toString);

(note that Objects::toString is used instead of Object::toString (look for an 's') because of possible null values).

Since:

July 26, 2024

Author:

Rammi

Method Summary

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 value of null.
static <V1,V2> NullableUnion<V1,V2>	nul2() Get a union with a second value 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

condense, dispose, disposeFragile1, disposeFragile2, disposeOnly1, disposeOnly2, has1, has2, isEqual1, isEqual2, map, swap, test

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 value of null.

Type Parameters:

V1 - first possible type

V2 - second possible type

Returns:

union with a null value of type V1

nul2

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

Get a union with a second value of null.

Type Parameters:

V1 - first possible type

V2 - second possible type

Returns:

union with a null value of type V2