com.mojang.datafixers.optics

Interface Lens<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:

Lens<S::A,T::B>, Optic<Cartesian _,S::A,T::B>

All Known Implementing Classes:

Proj1, Proj2

public interface Lens<S,T,A,B>
extends Optic<Cartesian _,S::A,T::B>

A lens is an optic the provides access and modification to a single field. It provides functionality to extract a single 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 for using a lens is to extract and update a field of a struct type, using the C meaning of struct.

In order to be a lawful lens, the implementations of view(Object) and update(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. update(b2, update(b1, s)) == update(b2, s) - Updating twice is equivalent to updating once.
2. view(update(b, s)) == b - Viewing after an update yields the value used to update.
3. update(view(s), s) == s - Updating with a viewed value yields the original object.

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

Type Shape:

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

See Also:

Record Types

Nested Class Summary

Nested Classes

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

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(Cartesian P proofBox) Evaluates this lens to produce a function that, when given a transformation between field types, produces a transformation between object types.
T	update(B b, S s) Combines a value of the output field type with a value of the input object type to produce a combined value of the output object type.
A	view(S s) Extracts a value of the input field type from the input object type.

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

compose, composeUnchecked, upCast

Method Detail

view

A view(S s)

Extracts a value of the input field type from the input object type.

This method is analogous to a "getter" in traditional object-oriented programming.

Implementation Requirements:

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

Parameters:

s - A value of the input object type.

Returns:

The extracted value of the input field type.

update

T update(B b,
         S s)

Combines a value of the output field type with a value of the input object type to produce a combined value of the output object type.

This method is analogous to a "setter" in traditional object-oriented programming. Note that the given field b does not necessarily have to correspond with the straightforward transformation from the input object to the output object.

Implementation Requirements:

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

Parameters:

b - A value of the output field type with which to update the output object.

s - A value of the input object type to be converted to a value of the output object type.

Returns:

A value of the output object type, with the output field updated with the given value.

eval

default <P extends K2> (P<A,B>) -> P<S,T> eval(Cartesian P proofBox)

Evaluates this lens to produce a function that, when given a transformation between field types, produces a transformation between object types. The transformation extracts a value from the input object, uses the given transformation to produce a new value of the output field type, and finally uses that value to update the corresponding field in the output object.

Specified by:

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

Type Parameters:

P - The type of transformation.

Parameters:

proofBox - The Cartesian 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:

Lens.Instance