lens-4.12.3: Lenses, Folds and Traversals

Control.Lens.Iso

Description

Synopsis

# Isomorphism Lenses

type Iso s t a b = forall p f. (Profunctor p, Functor f) => p a (f b) -> p s (f t) Source

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

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

type Iso' s a = Iso s s a a Source

```type `Iso'` = `Simple` `Iso`
```

type AnIso s t a b = Exchange a b a (Identity b) -> Exchange a b s (Identity t) Source

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

type AnIso' s a = AnIso s s a a Source

A `Simple` `AnIso`.

# Isomorphism Construction

iso :: (s -> a) -> (b -> t) -> Iso s t a b Source

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
```

# Consuming Isomorphisms

from :: AnIso s t a b -> Iso b a t s Source

Invert an isomorphism.

````from` (`from` l) ≡ l
```

cloneIso :: AnIso s t a b -> Iso s t a b Source

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.

withIso :: AnIso s t a b -> ((s -> a) -> (b -> t) -> r) -> r Source

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

# Working with isomorphisms

au :: AnIso s t a b -> ((b -> t) -> e -> s) -> e -> a Source

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

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

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

auf :: Profunctor p => AnIso s t a b -> (p r a -> e -> b) -> p r s -> e -> t Source

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
```

under :: AnIso s t a b -> (t -> s) -> b -> a Source

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
```

mapping :: (Functor f, Functor g) => AnIso s t a b -> Iso (f s) (g t) (f a) (g b) Source

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

## Common Isomorphisms

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.

non :: Eq a => a -> Iso' (Maybe a) a Source

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' :: APrism' a () -> Iso' (Maybe a) a Source

`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 -> (a -> Bool) -> Iso' (Maybe a) a Source

`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 []
```

enum :: Enum a => Iso' Int a Source

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.

curried :: Iso ((a, b) -> c) ((d, e) -> f) (a -> b -> c) (d -> e -> f) Source

The canonical isomorphism for currying and uncurrying a function.

````curried` = `iso` `curry` `uncurry`
```
````>>> ````(fst^.curried) 3 4
```3
```
````>>> ````view curried fst 3 4
```3
```

uncurried :: Iso (a -> b -> c) (d -> e -> f) ((a, b) -> c) ((d, e) -> f) Source

The canonical isomorphism for uncurrying and currying a function.

````uncurried` = `iso` `uncurry` `curry`
```
````uncurried` = `from` `curried`
```
````>>> ````((+)^.uncurried) (1,2)
```3
```

flipped :: Iso (a -> b -> c) (a' -> b' -> c') (b -> a -> c) (b' -> a' -> c') Source

The isomorphism for flipping a function.

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

class Bifunctor p => Swapped p where Source

This class provides for symmetric bifunctors.

Methods

swapped :: Iso (p a b) (p c d) (p b a) (p d c) Source

````swapped` `.` `swapped` ≡ `id`
`first` f `.` `swapped` = `swapped` `.` `second` f
`second` g `.` `swapped` = `swapped` `.` `first` g
`bimap` f g `.` `swapped` = `swapped` `.` `bimap` g f
```
````>>> ````(1,2)^.swapped
```(2,1)
```

Instances

 Source Methodsswapped :: (Profunctor p, Functor f) => p (Either b a) (f (Either d c)) -> p (Either a b) (f (Either c d)) Source Source Methodsswapped :: (Profunctor p, Functor f) => p (b, a) (f (d, c)) -> p (a, b) (f (c, d)) Source

class Strict lazy strict | lazy -> strict, strict -> lazy where Source

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

Methods

strict :: Iso' lazy strict Source

Instances

 Source Methods Source Methods Strict (StateT s m a) (StateT s m a) Source Methodsstrict :: Iso' (StateT s m a) (StateT s m a) Source Strict (WriterT w m a) (WriterT w m a) Source Methodsstrict :: Iso' (WriterT w m a) (WriterT w m a) Source Strict (RWST r w s m a) (RWST r w s m a) Source Methodsstrict :: Iso' (RWST r w s m a) (RWST r w s m a) Source

lazy :: Strict lazy strict => Iso' strict lazy Source

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.

class Reversing t where Source

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

Methods

reversing :: t -> t Source

Instances

 Source Methods Source Methods Source Methods Source Methods Reversing [a] Source Methodsreversing :: [a] -> [a] Source Reversing (Seq a) Source Methodsreversing :: Seq a -> Seq a Source Source Methodsreversing :: Vector a -> Vector a Source Unbox a => Reversing (Vector a) Source Methodsreversing :: Vector a -> Vector a Source Storable a => Reversing (Vector a) Source Methodsreversing :: Vector a -> Vector a Source Prim a => Reversing (Vector a) Source Methodsreversing :: Vector a -> Vector a Source Source Methodsreversing :: Deque a -> Deque a Source

reversed :: Reversing a => Iso' a a Source

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

````>>> ````"live" ^. reversed
```"evil"
```
````>>> ````"live" & reversed %~ ('d':)
```"lived"
```

involuted :: (a -> a) -> Iso' a a Source

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"
```

## Uncommon Isomorphisms

magma :: LensLike (Mafic a b) s t a b -> Iso s u (Magma Int t b a) (Magma j u c c) Source

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.

imagma :: Over (Indexed i) (Molten i a b) s t a b -> Iso s t' (Magma i t b a) (Magma j t' c c) Source

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.

data Magma i t b a Source

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

Instances

 TraversableWithIndex i (Magma i t b) Source Methodsitraverse :: Applicative f => (i -> a -> f c) -> Magma i t b a -> f (Magma i t b c) Sourceitraversed :: (Indexable i p, Applicative f) => p a (f c) -> Magma i t b a -> f (Magma i t b c) Source FoldableWithIndex i (Magma i t b) Source MethodsifoldMap :: Monoid m => (i -> a -> m) -> Magma i t b a -> m Sourceifolded :: (Indexable i p, Contravariant f, Applicative f) => p a (f a) -> Magma i t b a -> f (Magma i t b a) Sourceifoldr :: (i -> a -> c -> c) -> c -> Magma i t b a -> c Sourceifoldl :: (i -> a -> c -> a) -> a -> Magma i t b c -> a Sourceifoldr' :: (i -> a -> c -> c) -> c -> Magma i t b a -> c Sourceifoldl' :: (i -> a -> c -> a) -> a -> Magma i t b c -> a Source FunctorWithIndex i (Magma i t b) Source Methodsimap :: (i -> a -> c) -> Magma i t b a -> Magma i t b c Sourceimapped :: (Indexable i p, Settable f) => p a (f c) -> Magma i t b a -> f (Magma i t b c) Source Functor (Magma i t b) Source Methodsfmap :: (a -> c) -> Magma i t b a -> Magma i t b c(<\$) :: a -> Magma i t b c -> Magma i t b a Foldable (Magma i t b) Source Methodsfold :: Monoid m => Magma i t b m -> mfoldMap :: Monoid m => (a -> m) -> Magma i t b a -> mfoldr :: (a -> c -> c) -> c -> Magma i t b a -> cfoldr' :: (a -> c -> c) -> c -> Magma i t b a -> cfoldl :: (a -> c -> a) -> a -> Magma i t b c -> afoldl' :: (a -> c -> a) -> a -> Magma i t b c -> afoldr1 :: (a -> a -> a) -> Magma i t b a -> afoldl1 :: (a -> a -> a) -> Magma i t b a -> atoList :: Magma i t b a -> [a]null :: Magma i t b a -> Boollength :: Magma i t b a -> Intelem :: Eq a => a -> Magma i t b a -> Boolmaximum :: Ord a => Magma i t b a -> aminimum :: Ord a => Magma i t b a -> asum :: Num a => Magma i t b a -> aproduct :: Num a => Magma i t b a -> a Traversable (Magma i t b) Source Methodstraverse :: Applicative f => (a -> f c) -> Magma i t b a -> f (Magma i t b c)sequenceA :: Applicative f => Magma i t b (f a) -> f (Magma i t b a)mapM :: Monad m => (a -> m c) -> Magma i t b a -> m (Magma i t b c)sequence :: Monad m => Magma i t b (m a) -> m (Magma i t b a) (Show i, Show a) => Show (Magma i t b a) Source MethodsshowsPrec :: Int -> Magma i t b a -> ShowSshow :: Magma i t b a -> StringshowList :: [Magma i t b a] -> ShowS

## Contravariant functors

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

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)
```

# Profunctors

class Profunctor p where

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
```

Minimal complete definition

Methods

dimap :: (a -> b) -> (c -> d) -> p b c -> p a d

Map over both arguments at the same time.

``dimap` f g ≡ `lmap` f `.` `rmap` g`

lmap :: (a -> b) -> p b c -> p a c

Map the first argument contravariantly.

``lmap` f ≡ `dimap` f `id``

rmap :: (b -> c) -> p a b -> p a c

Map the second argument covariantly.

``rmap` ≡ `dimap` `id``

Instances

 Profunctor (->) Methodsdimap :: (a -> b) -> (c -> d) -> (b -> c) -> a -> dlmap :: (a -> b) -> (b -> c) -> a -> crmap :: (b -> c) -> (a -> b) -> a -> c(#.) :: Coercible * c b => (b -> c) -> (a -> b) -> a -> c(.#) :: Coercible * b a => (b -> c) -> (a -> b) -> a -> c Methodsdimap :: (a -> b) -> (c -> d) -> ReifiedFold b c -> ReifiedFold a dlmap :: (a -> b) -> ReifiedFold b c -> ReifiedFold a crmap :: (b -> c) -> ReifiedFold a b -> ReifiedFold a c(#.) :: Coercible * c b => (b -> c) -> ReifiedFold a b -> ReifiedFold a c(.#) :: Coercible * b a => ReifiedFold b c -> (a -> b) -> ReifiedFold a c Methodsdimap :: (a -> b) -> (c -> d) -> ReifiedGetter b c -> ReifiedGetter a dlmap :: (a -> b) -> ReifiedGetter b c -> ReifiedGetter a crmap :: (b -> c) -> ReifiedGetter a b -> ReifiedGetter a c(#.) :: Coercible * c b => (b -> c) -> ReifiedGetter a b -> ReifiedGetter a c(.#) :: Coercible * b a => ReifiedGetter b c -> (a -> b) -> ReifiedGetter a c Monad m => Profunctor (Kleisli m) Methodsdimap :: (a -> b) -> (c -> d) -> Kleisli m b c -> Kleisli m a dlmap :: (a -> b) -> Kleisli m b c -> Kleisli m a crmap :: (b -> c) -> Kleisli m a b -> Kleisli m a c(#.) :: Coercible * c b => (b -> c) -> Kleisli m a b -> Kleisli m a c(.#) :: Coercible * b a => Kleisli m b c -> (a -> b) -> Kleisli m a c Functor w => Profunctor (Cokleisli w) Methodsdimap :: (a -> b) -> (c -> d) -> Cokleisli w b c -> Cokleisli w a dlmap :: (a -> b) -> Cokleisli w b c -> Cokleisli w a crmap :: (b -> c) -> Cokleisli w a b -> Cokleisli w a c(#.) :: Coercible * c b => (b -> c) -> Cokleisli w a b -> Cokleisli w a c(.#) :: Coercible * b a => Cokleisli w b c -> (a -> b) -> Cokleisli w a c Functor f => Profunctor (Star f) Methodsdimap :: (a -> b) -> (c -> d) -> Star f b c -> Star f a dlmap :: (a -> b) -> Star f b c -> Star f a crmap :: (b -> c) -> Star f a b -> Star f a c(#.) :: Coercible * c b => (b -> c) -> Star f a b -> Star f a c(.#) :: Coercible * b a => Star f b c -> (a -> b) -> Star f a c Functor f => Profunctor (Costar f) Methodsdimap :: (a -> b) -> (c -> d) -> Costar f b c -> Costar f a dlmap :: (a -> b) -> Costar f b c -> Costar f a crmap :: (b -> c) -> Costar f a b -> Costar f a c(#.) :: Coercible * c b => (b -> c) -> Costar f a b -> Costar f a c(.#) :: Coercible * b a => Costar f b c -> (a -> b) -> Costar f a c Arrow p => Profunctor (WrappedArrow p) Methodsdimap :: (a -> b) -> (c -> d) -> WrappedArrow p b c -> WrappedArrow p a dlmap :: (a -> b) -> WrappedArrow p b c -> WrappedArrow p a crmap :: (b -> c) -> WrappedArrow p a b -> WrappedArrow p a c(#.) :: Coercible * c b => (b -> c) -> WrappedArrow p a b -> WrappedArrow p a c(.#) :: Coercible * b a => WrappedArrow p b c -> (a -> b) -> WrappedArrow p a c Methodsdimap :: (a -> b) -> (c -> d) -> Forget r b c -> Forget r a dlmap :: (a -> b) -> Forget r b c -> Forget r a crmap :: (b -> c) -> Forget r a b -> Forget r a c(#.) :: Coercible * c b => (b -> c) -> Forget r a b -> Forget r a c(.#) :: Coercible * b a => Forget r b c -> (a -> b) -> Forget r a c Methodsdimap :: (a -> b) -> (c -> d) -> Tagged * b c -> Tagged * a dlmap :: (a -> b) -> Tagged * b c -> Tagged * a crmap :: (b -> c) -> Tagged * a b -> Tagged * a c(#.) :: Coercible * c b => (b -> c) -> Tagged * a b -> Tagged * a c(.#) :: Coercible * b a => Tagged * b c -> (a -> b) -> Tagged * a c Methodsdimap :: (a -> b) -> (c -> d) -> Indexed i b c -> Indexed i a dlmap :: (a -> b) -> Indexed i b c -> Indexed i a crmap :: (b -> c) -> Indexed i a b -> Indexed i a c(#.) :: Coercible * c b => (b -> c) -> Indexed i a b -> Indexed i a c(.#) :: Coercible * b a => Indexed i b c -> (a -> b) -> Indexed i a c Methodsdimap :: (a -> b) -> (c -> d) -> ReifiedIndexedFold i b c -> ReifiedIndexedFold i a dlmap :: (a -> b) -> ReifiedIndexedFold i b c -> ReifiedIndexedFold i a crmap :: (b -> c) -> ReifiedIndexedFold i a b -> ReifiedIndexedFold i a c(#.) :: Coercible * c b => (b -> c) -> ReifiedIndexedFold i a b -> ReifiedIndexedFold i a c(.#) :: Coercible * b a => ReifiedIndexedFold i b c -> (a -> b) -> ReifiedIndexedFold i a c Methodsdimap :: (a -> b) -> (c -> d) -> ReifiedIndexedGetter i b c -> ReifiedIndexedGetter i a dlmap :: (a -> b) -> ReifiedIndexedGetter i b c -> ReifiedIndexedGetter i a crmap :: (b -> c) -> ReifiedIndexedGetter i a b -> ReifiedIndexedGetter i a c(#.) :: Coercible * c b => (b -> c) -> ReifiedIndexedGetter i a b -> ReifiedIndexedGetter i a c(.#) :: Coercible * b a => ReifiedIndexedGetter i b c -> (a -> b) -> ReifiedIndexedGetter i a c Profunctor (Market a b) Methodsdimap :: (c -> d) -> (e -> f) -> Market a b d e -> Market a b c flmap :: (c -> d) -> Market a b d e -> Market a b c ermap :: (c -> d) -> Market a b e c -> Market a b e d(#.) :: Coercible * d c => (c -> d) -> Market a b e c -> Market a b e d(.#) :: Coercible * c e => Market a b c d -> (e -> c) -> Market a b e d Profunctor (Exchange a b) Methodsdimap :: (c -> d) -> (e -> f) -> Exchange a b d e -> Exchange a b c flmap :: (c -> d) -> Exchange a b d e -> Exchange a b c ermap :: (c -> d) -> Exchange a b e c -> Exchange a b e d(#.) :: Coercible * d c => (c -> d) -> Exchange a b e c -> Exchange a b e d(.#) :: Coercible * c e => Exchange a b c d -> (e -> c) -> Exchange a b e d

dimapping :: (Profunctor p, Profunctor q) => AnIso s t a b -> AnIso s' t' a' b' -> Iso (p a s') (q b t') (p s a') (q t b') Source

Lift two `Iso`s 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')
```

lmapping :: (Profunctor p, Profunctor q) => AnIso s t a b -> Iso (p a x) (q b y) (p s x) (q t y) Source

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)
```

rmapping :: (Profunctor p, Profunctor q) => AnIso s t a b -> Iso (p x s) (q y t) (p x a) (q y b) Source

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)
```

# Bifunctors

bimapping :: (Bifunctor f, Bifunctor g) => AnIso s t a b -> AnIso s' t' a' b' -> Iso (f s s') (g t t') (f a a') (g b b') Source

Lift two `Iso`s into both arguments of a `Bifunctor`.

```bimapping :: `Bifunctor` 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 :: `Bifunctor` p => `Iso'` s a -> `Iso'` s' a' -> `Iso'` (p s s') (p a a')
```