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>>
AnIso
(short for "isomorphism") is an invertibleLens
: anOptic
encoding of a bi-directional focusing of two types, and like
, can beLens
es
,View
edSet
, and
.updated
As an example, consider the isomorphism between valid
String
s andInteger
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"
stringIntIso
can be viewed as an
, and can beOptic
<String, String, Integer, Integer>
and viewed as amirror()
ed
.Optic
<Integer, Integer, String, String>As with
Lens
, variance is supported betweenS/T
andA/B
, and where these pairs do not vary, aIso.Simple
iso can be used (for instance, in the previous example,stringIntIso
could have had the simplifiedIso.Simple<String, Integer>
type).For more information, read about isos.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static 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
All Methods Static Methods Instance Methods Default Methods Modifier and Type Method Description default <Z,C>
Iso<S,T,Z,C>andThen(Optic<? super Profunctor<?,?,?>,? super Functor<?,?>,A,B,Z,C> f)
Left-to-right composition of optics.default <R,U>
Iso<R,U,A,B>compose(Optic<? super Profunctor<?,?,?>,? super Functor<?,?>,R,U,S,T> g)
Right-to-Left composition of optics.default <R> Iso<R,T,A,B>
contraMap(Fn1<? super R,? extends S> fn)
Contravariantly mapA <- B
.default <R,U>
Iso<R,U,A,B>diMap(Fn1<? super R,? extends S> lFn, Fn1<? super T,? extends U> rFn)
Dually map contravariantly over the left parameter and covariantly over the right parameter.default <R> Iso<R,T,A,B>
diMapL(Fn1<? super R,? extends S> fn)
Contravariantly map over the left parameter.default <U> Iso<S,U,A,B>
diMapR(Fn1<? super T,? extends U> fn)
Covariantly map over the right parameter.default <U> Iso<S,U,A,B>
discardL(Applicative<U,Iso<S,?,A,B>> appB)
Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
.default <U> Iso<S,T,A,B>
discardR(Applicative<U,Iso<S,?,A,B>> appB)
Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
.default <U> Iso<S,U,A,B>
flatMap(Fn1<? super T,? extends Monad<U,Iso<S,?,A,B>>> fn)
Chain dependent computations that may continue or short-circuit based on previous results.default <U> Iso<S,U,A,B>
fmap(Fn1<? super T,? extends U> fn)
Covariantly transmute this functor's parameter using the given mapping function.static <S,T,A,B>
Iso<S,T,A,B>iso(Fn1<? super S,? extends A> f, Fn1<? super B,? extends T> g)
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
.default <C> Iso<S,T,C,B>
mapA(Fn1<? super A,? extends C> fn)
Covariantly mapA
toC
, yielding a new optic.default <Z> Iso<S,T,A,Z>
mapB(Fn1<? super Z,? extends B> fn)
Contravariantly mapB
toZ
, yielding a new optic.default <R> Iso<R,T,A,B>
mapS(Fn1<? super R,? extends S> fn)
Contravariantly mapS
toR
, yielding a new optic.default <U> Iso<S,U,A,B>
mapT(Fn1<? super T,? extends U> fn)
Covariantly mapT
toU
, yielding a new optic.default Iso<B,A,T,S>
mirror()
Flip thisIso
around.default <U> Iso<S,U,A,B>
pure(U u)
Lift the valueb
into this applicative functor.static <S,A,B>
Pure<Iso<S,?,A,B>>pureIso(Fn1<? super S,? extends A> sa)
static <S,A>
Iso.Simple<S,A>simpleIso(Fn1<? super S,? extends A> f, Fn1<? super A,? extends S> g)
Static factory method for creating a simpleIso
from a function and its inverse.default Lens<S,T,A,B>
toLens()
default <U> Iso<S,U,A,B>
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.default Tuple2<Fn1<? super S,? extends A>,Fn1<? super B,? extends T>>
unIso()
default <U> Iso<S,U,A,B>
zip(Applicative<Fn1<? super T,? extends U>,Iso<S,?,A,B>> appFn)
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 Detail
-
unIso
default Tuple2<Fn1<? super S,? extends A>,Fn1<? super B,? extends T>> unIso()
- Returns:
- the destructured iso
-
fmap
default <U> Iso<S,U,A,B> fmap(Fn1<? super T,? extends U> fn)
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)
-
zip
default <U> Iso<S,U,A,B> zip(Applicative<Fn1<? super T,? extends U>,Iso<S,?,A,B>> appFn)
Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
-
discardL
default <U> Iso<S,U,A,B> discardL(Applicative<U,Iso<S,?,A,B>> appB)
Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
. This is generally useful for sequentially performing side-effects.
-
discardR
default <U> Iso<S,T,A,B> discardR(Applicative<U,Iso<S,?,A,B>> appB)
Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
. This is generally useful for sequentially performing side-effects.
-
flatMap
default <U> Iso<S,U,A,B> flatMap(Fn1<? super T,? extends Monad<U,Iso<S,?,A,B>>> fn)
Chain dependent computations that may continue or short-circuit based on previous results.
-
trampolineM
default <U> Iso<S,U,A,B> 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.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:
for a basic implementation
,for a implementation
,for an implementation leveraging an already stack-safe
,for a implementation
-
diMapL
default <R> Iso<R,T,A,B> diMapL(Fn1<? super R,? extends S> fn)
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
default <U> Iso<S,U,A,B> diMapR(Fn1<? super T,? extends U> fn)
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
default <R,U> Iso<R,U,A,B> diMap(Fn1<? super R,? extends S> lFn, Fn1<? super T,? extends U> rFn)
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
default <R> Iso<R,T,A,B> contraMap(Fn1<? super R,? extends S> fn)
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
default <R> Iso<R,T,A,B> mapS(Fn1<? super R,? extends S> fn)
Contravariantly mapS
toR
, yielding a new optic.
-
mapT
default <U> Iso<S,U,A,B> mapT(Fn1<? super T,? extends U> fn)
Covariantly mapT
toU
, yielding a new optic.
-
mapA
default <C> Iso<S,T,C,B> mapA(Fn1<? super A,? extends C> fn)
Covariantly mapA
toC
, yielding a new optic.
-
mapB
default <Z> Iso<S,T,A,Z> mapB(Fn1<? super Z,? extends B> fn)
Contravariantly mapB
toZ
, yielding a new optic.
-
andThen
default <Z,C> Iso<S,T,Z,C> andThen(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,A,B> compose(Optic<? super Profunctor<?,?,?>,? super Functor<?,?>,R,U,S,T> g)
Right-to-Left composition of optics. Requires compatibility betweenA
andB
.
-
iso
static <S,T,A,B> Iso<S,T,A,B> iso(Fn1<? super S,? extends A> f, Fn1<? super B,? extends T> g)
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,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
.
-
simpleIso
static <S,A> Iso.Simple<S,A> simpleIso(Fn1<? super S,? extends A> f, Fn1<? super A,? extends S> g)
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
-
-