Interface Iso<S,T,A,B>
- Type Parameters:
S
- the larger type for focusingT
- the larger type for mirrored focusingA
- the smaller type for focusingB
- the smaller type for mirrored focusing
- All Superinterfaces:
Applicative<T,
,Iso<S, ?, A, B>> Contravariant<S,
,Profunctor<?, T, Iso<?, ?, A, B>>> Functor<T,
,Iso<S, ?, A, B>> Monad<T,
,Iso<S, ?, A, B>> MonadRec<T,
,Iso<S, ?, A, B>> Optic<Profunctor<?,
,?, ?>, Functor<?, ?>, S, T, A, B> Profunctor<S,
T, Iso<?, ?, A, B>>
- All Known Subinterfaces:
Iso.Simple<S,
,A> TypeSafeKey<A,
,B> TypeSafeKey.Simple<A>
- Functional Interface:
- This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface
public interface Iso<S,T,A,B>
extends Optic<Profunctor<?,?,?>,Functor<?,?>,S,T,A,B>, MonadRec<T,Iso<S,?,A,B>>, Profunctor<S,T,Iso<?,?,A,B>>
An
Iso
(short for "isomorphism") is an invertible Lens
: an Optic
encoding of a
bi-directional focusing of two types, and like Lens
es
, can be View
ed
,
Set
, and updated
.
As an example, consider the isomorphism between valid String
s and Integer
s:
Iso<String, String, Integer, Integer> stringIntIso = Iso.iso(Integer::parseInt, Object::toString);
Integer asInt = view(stringIntIso, "123"); // 123
String asString = view(stringIntIso.mirror(), 123); // "123"
In the previous example, stringIntIso
can be viewed as an
Optic
<String, String, Integer, Integer>
, and can be mirror()
ed
and
viewed as a Optic
<Integer, Integer, String, String>
.
As with Lens
, variance is supported between S/T
and A/B
, and where these pairs do
not vary, a Iso.Simple
iso can be used (for instance, in the previous example, stringIntIso
could
have had the simplified Iso.Simple<String, Integer>
type).
For more information, read about isos.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
Iso.Simple<S,
A> A convenience type with a simplified type signature for common isos with both unified "larger" values and unified "smaller" values. -
Method Summary
Modifier and TypeMethodDescriptionLeft-to-right composition of optics.Right-to-Left composition of optics.Contravariantly mapA <- B
.Dually map contravariantly over the left parameter and covariantly over the right parameter.Contravariantly map over the left parameter.Covariantly map over the right parameter.Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
.Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
.Chain dependent computations that may continue or short-circuit based on previous results.Covariantly transmute this functor's parameter using the given mapping function.static <S,
T, A, B>
Iso<S, T, A, B> Static factory method for creating an iso from a function and it's inverse.static <S,
T, A, B>
Iso<S, T, A, B> iso
(Optic<? super Profunctor<?, ?, ?>, ? super Functor<?, ?>, S, T, A, B> optic) Promote an optic with compatible bounds to anIso
.Covariantly mapA
toC
, yielding a new optic.Contravariantly mapB
toZ
, yielding a new optic.Contravariantly mapS
toR
, yielding a new optic.Covariantly mapT
toU
, yielding a new optic.mirror()
Flip thisIso
around.pure
(U u) Lift the valueb
into this applicative functor.static <S,
A> Iso.Simple <S, A> Static factory method for creating a simpleIso
from a function and its inverse.toLens()
trampolineM
(Fn1<? super T, ? extends MonadRec<RecursiveResult<T, U>, Iso<S, ?, A, B>>> fn) Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
instruction.unIso()
Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.Methods inherited from interface com.jnape.palatable.lambda.optics.Optic
apply, monomorphize
-
Method Details
-
toLens
- Returns:
- the equivalent lens
-
mirror
Flip thisIso
around.- Returns:
- the mirrored
Iso
-
unIso
- Returns:
- the destructured iso
-
fmap
Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.- Specified by:
fmap
in interfaceApplicative<S,
T> - Specified by:
fmap
in interfaceFunctor<S,
T> - Specified by:
fmap
in interfaceMonad<S,
T> - Specified by:
fmap
in interfaceMonadRec<S,
T> - Type Parameters:
U
- the new parameter type- Parameters:
fn
- the mapping function- Returns:
- a functor over B (the new parameter type)
-
pure
Lift the valueb
into this applicative functor. -
zip
Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports. -
discardL
Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
. This is generally useful for sequentially performing side-effects. -
discardR
Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
. This is generally useful for sequentially performing side-effects. -
flatMap
Chain dependent computations that may continue or short-circuit based on previous results. -
trampolineM
default <U> Iso<S,U, trampolineMA, B> (Fn1<? super T, ? extends MonadRec<RecursiveResult<T, U>, Iso<S, ?, A, B>>> fn) Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
instruction.Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.
- Specified by:
trampolineM
in interfaceMonadRec<S,
T> - Type Parameters:
U
- the ultimate resulting carrier type- Parameters:
fn
- the function to internally trampoline- Returns:
- the trampolined
MonadRec
- See Also:
-
diMapL
Contravariantly map over the left parameter.- Specified by:
diMapL
in interfaceProfunctor<S,
T, A> - Type Parameters:
R
- the new left parameter type- Parameters:
fn
- the mapping function- Returns:
- a profunctor over Z (the new left parameter type) and C (the same right parameter type)
-
diMapR
Covariantly map over the right parameter. For all profunctors that are also functors, it should hold thatdiMapR(f) == fmap(f)
.- Specified by:
diMapR
in interfaceProfunctor<S,
T, A> - Type Parameters:
U
- the new right parameter type- Parameters:
fn
- the mapping function- Returns:
- a profunctor over A (the same left parameter type) and C (the new right parameter type)
-
diMap
Dually map contravariantly over the left parameter and covariantly over the right parameter. This is isomorphic todiMapL(lFn).diMapR(rFn)
.- Specified by:
diMap
in interfaceProfunctor<S,
T, A> - Type Parameters:
R
- the new left parameter typeU
- the new right parameter type- Parameters:
lFn
- the left parameter mapping functionrFn
- the right parameter mapping function- Returns:
- a profunctor over Z (the new left parameter type) and C (the new right parameter type)
-
contraMap
Contravariantly mapA <- B
.- Specified by:
contraMap
in interfaceContravariant<S,
T> - Specified by:
contraMap
in interfaceProfunctor<S,
T, A> - Type Parameters:
R
- the new parameter type- Parameters:
fn
- the mapping function- Returns:
- the mapped Contravariant functor instance
-
mapS
Contravariantly mapS
toR
, yielding a new optic. -
mapT
Covariantly mapT
toU
, yielding a new optic. -
mapA
Covariantly mapA
toC
, yielding a new optic. -
mapB
Contravariantly mapB
toZ
, yielding a new optic. -
andThen
default <Z,C> Iso<S,T, andThenZ, C> (Optic<? super Profunctor<?, ?, ?>, ? super Functor<?, ?>, A, B, Z, C> f) Left-to-right composition of optics. Requires compatibility betweenS
andT
. -
compose
default <R,U> Iso<R,U, composeA, B> (Optic<? super Profunctor<?, ?, ?>, ? super Functor<?, ?>, R, U, S, T> g) Right-to-Left composition of optics. Requires compatibility betweenA
andB
. -
iso
Static factory method for creating an iso from a function and it's inverse.- Type Parameters:
S
- the larger type for focusingT
- the larger type for mirrored focusingA
- the smaller type for focusingB
- the smaller type for mirrored focusing- Parameters:
f
- the functiong
- f's inverse- Returns:
- the iso
-
iso
static <S,T, Iso<S,A, B> T, isoA, B> (Optic<? super Profunctor<?, ?, ?>, ? super Functor<?, ?>, S, T, A, B> optic) Promote an optic with compatible bounds to anIso
. -
simpleIso
Static factory method for creating a simpleIso
from a function and its inverse.- Type Parameters:
S
- one side of the isomorphismA
- the other side of the isomorphism- Parameters:
f
- a functiong
- f's inverse- Returns:
- the simple iso
-
pureIso
- Type Parameters:
S
- the larger type for focusingA
- the smaller type for focusingB
- the smaller type for mirrored focusing- Parameters:
sa
- one side of the isomorphism- Returns:
- the
Pure
instance
-