Isomorphism families can be composed with another Lens using (.) and id.

Note: Composition with an Iso is index- and measure- preserving.

type Iso' = Simple Iso

When you see this as an argument to a function, it expects an Iso.

A Simple AnIso.

Build a simple isomorphism from a pair of inverse functions.

view (iso f g) ≡ f
view (from (iso f g)) ≡ g
over (iso f g) h ≡ g . h . f
over (from (iso f g)) h ≡ f . h . g

Invert an isomorphism.

from (from l) ≡ l

Convert from AnIso back to any Iso.

This is useful when you need to store an isomorphism as a data type inside a container and later reconstitute it as an overloaded function.

See cloneLens or cloneTraversal for more information on why you might want to do this.

Extract the two functions, one from s -> a and one from b -> t that characterize an Iso.

Based on ala from Conor McBride's work on Epigram.

This version is generalized to accept any Iso, not just a newtype.

>>> au (_Unwrapping Sum) foldMap [1,2,3,4]
10

Based on ala' from Conor McBride's work on Epigram.

This version is generalized to accept any Iso, not just a newtype.

For a version you pass the name of the newtype constructor to, see alaf.

Mnemonically, the German auf plays a similar role to à la, and the combinator is au with an extra function argument.

>>> auf (_Unwrapping Sum) (foldMapOf both) Prelude.length ("hello","world")
10

The opposite of working over a Setter is working under an isomorphism.

under ≡ over . from

under :: Iso s t a b -> (t -> s) -> b -> a

This can be used to lift any Iso into an arbitrary Functor.

Composition with this isomorphism is occasionally useful when your Lens, Traversal or Iso has a constraint on an unused argument to force that argument to agree with the type of a used argument and avoid ScopedTypeVariables or other ugliness.

If v is an element of a type a, and a' is a sans the element v, then non v is an isomorphism from Maybe a' to a.

non ≡ non' . only

Keep in mind this is only a real isomorphism if you treat the domain as being Maybe (a sans v).

This is practically quite useful when you want to have a Map where all the entries should have non-zero values.

>>> Map.fromList [("hello",1)] & at "hello" . non 0 +~ 2
fromList [("hello",3)]

>>> Map.fromList [("hello",1)] & at "hello" . non 0 -~ 1
fromList []

>>> Map.fromList [("hello",1)] ^. at "hello" . non 0
1

>>> Map.fromList [] ^. at "hello" . non 0
0

This combinator is also particularly useful when working with nested maps.

e.g. When you want to create the nested Map when it is missing:

>>> Map.empty & at "hello" . non Map.empty . at "world" ?~ "!!!"
fromList [("hello",fromList [("world","!!!")])]

and when have deleting the last entry from the nested Map mean that we should delete its entry from the surrounding one:

>>> fromList [("hello",fromList [("world","!!!")])] & at "hello" . non Map.empty . at "world" .~ Nothing
fromList []

It can also be used in reverse to exclude a given value:

>>> non 0 # rem 10 4
Just 2

>>> non 0 # rem 10 5
Nothing

non' p generalizes non (p # ()) to take any unit Prism

This function generates an isomorphism between Maybe (a | isn't p a) and a.

>>> Map.singleton "hello" Map.empty & at "hello" . non' _Empty . at "world" ?~ "!!!"
fromList [("hello",fromList [("world","!!!")])]

>>> fromList [("hello",fromList [("world","!!!")])] & at "hello" . non' _Empty . at "world" .~ Nothing
fromList []

anon a p generalizes non a to take any value and a predicate.

This function assumes that p a holds True and generates an isomorphism between Maybe (a | not (p a)) and a.

>>> Map.empty & at "hello" . anon Map.empty Map.null . at "world" ?~ "!!!"
fromList [("hello",fromList [("world","!!!")])]

>>> fromList [("hello",fromList [("world","!!!")])] & at "hello" . anon Map.empty Map.null . at "world" .~ Nothing
fromList []

This isomorphism can be used to convert to or from an instance of Enum.

>>> LT^.from enum
0

>>> 97^.enum :: Char
'a'

Note: this is only an isomorphism from the numeric range actually used and it is a bit of a pleasant fiction, since there are questionable Enum instances for Double, and Float that exist solely for [1.0 .. 4.0] sugar and the instances for those and Integer don't cover all values in their range.

The canonical isomorphism for currying and uncurrying a function.

curried = iso curry uncurry

>>> (fst^.curried) 3 4
3

>>> view curried fst 3 4
3

The canonical isomorphism for uncurrying and currying a function.

uncurried = iso uncurry curry

uncurried = from curried

>>> ((+)^.uncurried) (1,2)
3

The isomorphism for flipping a function.

>>> ((,)^.flipped) 1 2
(2,1)

This class provides for symmetric bifunctors.

Ad hoc conversion between "strict" and "lazy" versions of a structure, such as Text or ByteString.

An Iso between the strict variant of a structure and its lazy counterpart.

lazy = from strict

See http://hackage.haskell.org/package/strict-base-types for an example use.

This class provides a generalized notion of list reversal extended to other containers.

An Iso between a list, ByteString, Text fragment, etc. and its reversal.

>>> "live" ^. reversed
"evil"

>>> "live" & reversed %~ ('d':)
"lived"

Given a function that is its own inverse, this gives you an Iso using it in both directions.

involuted ≡ join iso

>>> "live" ^. involuted reverse
"evil"

>>> "live" & involuted reverse %~ ('d':)
"lived"

This isomorphism can be used to inspect a Traversal to see how it associates the structure and it can also be used to bake the Traversal into a Magma so that you can traverse over it multiple times.

This isomorphism can be used to inspect an IndexedTraversal to see how it associates the structure and it can also be used to bake the IndexedTraversal into a Magma so that you can traverse over it multiple times with access to the original indices.

This provides a way to peek at the internal structure of a Traversal or IndexedTraversal

Lift an Iso into a Contravariant functor.

contramapping :: Contravariant f => Iso s t a b -> Iso (f a) (f b) (f s) (f t)
contramapping :: Contravariant f => Iso' s a -> Iso' (f a) (f s)

Formally, the class Profunctor represents a profunctor from Hask -> Hask.

Intuitively it is a bifunctor where the first argument is contravariant and the second argument is covariant.

You can define a Profunctor by either defining dimap or by defining both lmap and rmap.

If you supply dimap, you should ensure that:

dimap id id ≡ id

If you supply lmap and rmap, ensure:

lmap id ≡ id
rmap id ≡ id

If you supply both, you should also ensure:

dimap f g ≡ lmap f . rmap g

These ensure by parametricity:

dimap (f . g) (h . i) ≡ dimap g h . dimap f i
lmap (f . g) ≡ lmap g . lmap f
rmap (f . g) ≡ rmap f . rmap g

Lift two Isos into both arguments of a Profunctor simultaneously.

dimapping :: Profunctor p => Iso s t a b -> Iso s' t' a' b' -> Iso (p a s') (p b t') (p s a') (p t b')
dimapping :: Profunctor p => Iso' s a -> Iso' s' a' -> Iso' (p a s') (p s a')

Lift an Iso contravariantly into the left argument of a Profunctor.

lmapping :: Profunctor p => Iso s t a b -> Iso (p a x) (p b y) (p s x) (p t y)
lmapping :: Profunctor p => Iso' s a -> Iso' (p a x) (p s x)

Lift an Iso covariantly into the right argument of a Profunctor.

rmapping :: Profunctor p => Iso s t a b -> Iso (p x s) (p y t) (p x a) (p y b)
rmapping :: Profunctor p => Iso' s a -> Iso' (p x s) (p x a)

Lift two Isos into both arguments of a Bifunctor.

bimapping :: Profunctor p => Iso s t a b -> Iso s' t' a' b' -> Iso (p s s') (p t t') (p a a') (p b b')
bimapping :: Profunctor p => Iso' s a -> Iso' s' a' -> Iso' (p s s') (p a a')