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 invariance:

• u.has1() ^ u.has2() is always true

A union is immutable in the sense that it itself does not change. The contained value may change if it is 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.

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. You can safely assume that both consumers will only get non-null arguments.
• Use UnionBase.test(Predicate, Predicate) to perform a test on the values in this union. You can safely assume that both predicates will only get non-null arguments.
• Use UnionBase.condense(Function, Function) to combine both types of values into one common outcoming value. You can safely assume that both functions will only get non-null arguments.

An example for the latter is

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

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

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

@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