com.mojang.datafixers.optics

Interface Affine<S,T,A,B>

Type Parameters:

S - The input object type.

T - The output object type.

A - The input field type.

B - The output field type.

All Superinterfaces:

Affine<S::A,T::B>, Optic<AffineP _,S::A,T::B>

public interface Affine<S,T,A,B>
extends Optic<AffineP _,S::A,T::B>

An affine is an optic that provides access and modification to a single optional field. It provides functionality to extract an optional value of the input field type A from the input object type S and to combine the input S and the transformed field type B into the output object type T.

The canonical example of an affine is retrieving and storing a value in a dynamic key-value store.

In order to be a lawful affine, the implementations of preview(Object) and set(Object, Object) must satisfy certain requirements. Assume that the object types S and T are implicitly convertible between each other and that the field types A and B are similarly convertible. Then the following rules must hold (== here represents logical equality and not reference equality).

1. set(b2, set(b1, s)) == set(b2, s) - Setting twice is equivalent to setting once.
2. preview(update(b, s)) == Right(b) - Previewing after setting yields the value used to set.
3. set?(preview(s), s) == s - Setting with a previewed value yields the original object.

Affine optics that are not lawful are said to be either neutral or chaotic, depending on the degree to which the affine laws are broken.

Type Shape:

%.Type.[%0::%2,%1::%3]

API Note:

Note that the affine laws shown here are quite similar to the lens laws. In fact, an affine optic is a combination of a Lens and a Prism. Colloquially, the term "prism" may actually refer to this optic, and not to Prism.

See Also:

Lens, Prism

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Affine.Instance<A2,B2> The AffineP type class instance for Affine.

Nested classes/interfaces inherited from interface com.mojang.datafixers.optics.Optic

Optic.CompositionOptic<Proof extends K1,S,T,A,B,A1,B1>

Method Summary

Modifier and Type	Method and Description
default <P extends K2> (P<A,B>) -> P<S,T>	eval(AffineP P proof) Evaluates this affine to produce a function that, when given a transformation between field types, produces a transformation between object types.
(T|A)	preview(S s) Extracts an optional value from the input object.
T	set(B b, S s) Combines the given output field and an input object to produce an output object.

Methods inherited from interface com.mojang.datafixers.optics.Optic

compose, composeUnchecked, upCast

Method Detail

preview

(T|A) preview(S s)

Extracts an optional value from the input object. Returns the straightforward transformation of the input object to the output object if the input field is not present.

The method is analogous to partial getter methods such as Map.get(Object).

Implementation Requirements:

The implementation must, in conjunction with set(Object, Object), satisfy the affine laws in order for this affine to be a lawful affine.

Parameters:

s - The input object.

Returns:

Either the extracted field value, or a value of the output object equivalent to the input.

set

T set(B b,
      S s)

Combines the given output field and an input object to produce an output object. If the field is already present in the input object, the existing value is overwritten; otherwise the field is added.

Implementation Requirements:

The implementation must, in conjunction with preview(Object), satisfy the affine laws in order for this affine to be a lawful affine.

Parameters:

b - A value of the output field type.

s - A value of the input object type.

Returns:

A value of the output object type that contains the output field.

eval

default <P extends K2> (P<A,B>) -> P<S,T> eval(AffineP P proof)

Evaluates this affine to produce a function that, when given a transformation between field types, produces a transformation between object types. The transformation extracts an optional value from the input object, and either sets the output field with the transformed field value or returns the converted input object.

Specified by:

eval in interface Optic<AffineP _,S::A,T::B>

Type Parameters:

P - The type of transformation.

Parameters:

proof - The AffineP type class instance for the transformation type.

Returns:

A function that takes a transformation between field types and produces a transformation between object types.

See Also:

Affine.Instance