A Lens is actually a lens family as described in http://comonad.com/reader/2012/mirrored-lenses/ .

With great power comes great responsibility and a Lens is subject to the three common sense Lens laws:

1) You get back what you put in:

view l (set l v s)  ≡ v

2) Putting back what you got doesn't change anything:

set l (view l s) s  ≡ s

3) Setting twice is the same as setting once:

set l v' (set l v s) ≡ set l v' s

These laws are strong enough that the 4 type parameters of a Lens cannot vary fully independently. For more on how they interact, read the "Why is it a Lens Family?" section of http://comonad.com/reader/2012/mirrored-lenses/ .

There are some emergent properties of these laws:

1) set l s must be injective for every s This is a consequence of law #1

2) set l must be surjective, because of law #2, which indicates that it is possible to obtain any v from some s such that set s v = s

3) Given just the first two laws you can prove a weaker form of law #3 where the values v that you are setting match:

set l v (set l v s) ≡ set l v s

Every Lens can be used directly as a Setter or Traversal .

You can also use a Lens for Getting as if it were a Fold or Getter .

Since every Lens is a valid Traversal , the Traversal laws are required of any Lens you create:

l pure ≡ pure
fmap (l f) . l g ≡ getCompose . l (Compose . fmap f . g)

type Lens s t a b = forall f. Functor f => LensLike f s t a b

type Lens' = Simple Lens

Every IndexedLens is a valid Lens and a valid IndexedTraversal .

type IndexedLens' i = Simple (IndexedLens i)

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

This type can also be used when you need to store a Lens in a container, since it is rank-1. You can turn them back into a Lens with cloneLens , or use it directly with combinators like storing and ( ^# ).

type ALens' = Simple ALens

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

type AnIndexedLens' = Simple (AnIndexedLens i)

Build a Lens from a getter and a setter.

lens :: Functor f => (s -> a) -> (s -> b -> t) -> (a -> f b) -> s -> f t

>>> s ^. lens getter setter
getter s

>>> s & lens getter setter .~ b
setter s b

>>> s & lens getter setter %~ f
setter s (f (getter s))

lens :: (s -> a) -> (s -> a -> s) -> Lens' s a

Build an IndexedLens from a Getter and a Setter .

Build an index-preserving Lens from a Getter and a Setter .

Obtain a getter and a setter from a lens, reversing lens .

( %%~ ) can be used in one of two scenarios:

When applied to a Lens , it can edit the target of the Lens in a structure, extracting a functorial result.

When applied to a Traversal , it can edit the targets of the traversals, extracting an applicative summary of its actions.

>>> [66,97,116,109,97,110] & each %%~ \a -> ("na", chr a)
("nananananana","Batman")

For all that the definition of this combinator is just:

(%%~) ≡ id

It may be beneficial to think about it as if it had these even more restricted types, however:

(%%~) :: Functor f =>     Iso s t a b       -> (a -> f b) -> s -> f t
(%%~) :: Functor f =>     Lens s t a b      -> (a -> f b) -> s -> f t
(%%~) :: Applicative f => Traversal s t a b -> (a -> f b) -> s -> f t

When applied to a Traversal , it can edit the targets of the traversals, extracting a supplemental monoidal summary of its actions, by choosing f = ((,) m)

(%%~) ::             Iso s t a b       -> (a -> (r, b)) -> s -> (r, t)
(%%~) ::             Lens s t a b      -> (a -> (r, b)) -> s -> (r, t)
(%%~) :: Monoid m => Traversal s t a b -> (a -> (m, b)) -> s -> (m, t)

Modify the target of a Lens in the current state returning some extra information of type r or modify all targets of a Traversal in the current state, extracting extra information of type r and return a monoidal summary of the changes.

>>> runState (_1 %%= \x -> (f x, g x)) (a,b)
(f a,(g a,b))

(%%=) ≡ (state .)

It may be useful to think of ( %%= ), instead, as having either of the following more restricted type signatures:

(%%=) :: MonadState s m             => Iso s s a b       -> (a -> (r, b)) -> m r
(%%=) :: MonadState s m             => Lens s s a b      -> (a -> (r, b)) -> m r
(%%=) :: (MonadState s m, Monoid r) => Traversal s s a b -> (a -> (r, b)) -> m r

Adjust the target of an IndexedLens returning a supplementary result, or adjust all of the targets of an IndexedTraversal and return a monoidal summary of the supplementary results and the answer.

(%%@~) ≡ withIndex

(%%@~) :: Functor f => IndexedLens i s t a b      -> (i -> a -> f b) -> s -> f t
(%%@~) :: Applicative f => IndexedTraversal i s t a b -> (i -> a -> f b) -> s -> f t

In particular, it is often useful to think of this function as having one of these even more restricted type signatures:

(%%@~) ::             IndexedLens i s t a b      -> (i -> a -> (r, b)) -> s -> (r, t)
(%%@~) :: Monoid r => IndexedTraversal i s t a b -> (i -> a -> (r, b)) -> s -> (r, t)

Adjust the target of an IndexedLens returning a supplementary result, or adjust all of the targets of an IndexedTraversal within the current state, and return a monoidal summary of the supplementary results.

l %%@= f ≡ state (l %%@~ f)

(%%@=) :: MonadState s m                 => IndexedLens i s s a b      -> (i -> a -> (r, b)) -> s -> m r
(%%@=) :: (MonadState s m, Monoid r) => IndexedTraversal i s s a b -> (i -> a -> (r, b)) -> s -> m r

Adjust the target of an IndexedLens returning the intermediate result, or adjust all of the targets of an IndexedTraversal and return a monoidal summary along with the answer.

l <%~ f ≡ l <%@~ const f

When you do not need access to the index then ( <%~ ) is more liberal in what it can accept.

If you do not need the intermediate result, you can use ( %@~ ) or even ( %~ ).

(<%@~) ::             IndexedLens i s t a b      -> (i -> a -> b) -> s -> (b, t)
(<%@~) :: Monoid b => IndexedTraversal i s t a b -> (i -> a -> b) -> s -> (b, t)

Adjust the target of an IndexedLens returning the intermediate result, or adjust all of the targets of an IndexedTraversal within the current state, and return a monoidal summary of the intermediate results.

(<%@=) :: MonadState s m                 => IndexedLens i s s a b      -> (i -> a -> b) -> m b
(<%@=) :: (MonadState s m, Monoid b) => IndexedTraversal i s s a b -> (i -> a -> b) -> m b

Adjust the target of an IndexedLens returning the old value, or adjust all of the targets of an IndexedTraversal and return a monoidal summary of the old values along with the answer.

(<<%@~) ::             IndexedLens i s t a b      -> (i -> a -> b) -> s -> (a, t)
(<<%@~) :: Monoid a => IndexedTraversal i s t a b -> (i -> a -> b) -> s -> (a, t)

Adjust the target of an IndexedLens returning the old value, or adjust all of the targets of an IndexedTraversal within the current state, and return a monoidal summary of the old values.

(<<%@=) :: MonadState s m                 => IndexedLens i s s a b      -> (i -> a -> b) -> m a
(<<%@=) :: (MonadState s m, Monoid b) => IndexedTraversal i s s a b -> (i -> a -> b) -> m a

& is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator $ , which allows & to be nested in $ .

>>> 5 & (+1) & show
"6"

Since: base-4.8.0.0

Flipped version of <$> .

(<&>) = flip fmap

Examples

>>> Just 2 <&> (+1)
Just 3

>>> [1,2,3] <&> (+1)
[2,3,4]

>>> Right 3 <&> (+1)
Right 4

Since: base-4.11.0.0

This is convenient to flip argument order of composite functions defined as:

fab ?? a = fmap ($ a) fab

For the Functor instance f = ((->) r) you can reason about this function as if the definition was ( ?? ) ≡ flip :

>>> (h ?? x) a
h a x

>>> execState ?? [] $ modify (1:)
[1]

>>> over _2 ?? ("hello","world") $ length
("hello",5)

>>> over ?? length ?? ("hello","world") $ _2
("hello",5)

This can be used to chain lens operations using op= syntax rather than op~ syntax for simple non-type-changing cases.

>>> (10,20) & _1 .~ 30 & _2 .~ 40
(30,40)

>>> (10,20) &~ do _1 .= 30; _2 .= 40
(30,40)

This does not support type-changing assignment, e.g.

>>> (10,20) & _1 .~ "hello"
("hello",20)

Merge two lenses, getters, setters, folds or traversals.

chosen ≡ choosing id id

choosing :: Getter s a     -> Getter s' a     -> Getter (Either s s') a
choosing :: Fold s a       -> Fold s' a       -> Fold (Either s s') a
choosing :: Lens' s a      -> Lens' s' a      -> Lens' (Either s s') a
choosing :: Traversal' s a -> Traversal' s' a -> Traversal' (Either s s') a
choosing :: Setter' s a    -> Setter' s' a    -> Setter' (Either s s') a

This is a Lens that updates either side of an Either , where both sides have the same type.

chosen ≡ choosing id id

>>> Left a^.chosen
a

>>> Right a^.chosen
a

>>> Right "hello"^.chosen
"hello"

>>> Right a & chosen *~ b
Right (a * b)

chosen :: Lens (Either a a) (Either b b) a b
chosen f (Left a)  = Left <$> f a
chosen f (Right a) = Right <$> f a

alongside makes a Lens from two other lenses or a Getter from two other getters by executing them on their respective halves of a product.

>>> (Left a, Right b)^.alongside chosen chosen
(a,b)

>>> (Left a, Right b) & alongside chosen chosen .~ (c,d)
(Left c,Right d)

alongside :: Lens   s t a b -> Lens   s' t' a' b' -> Lens   (s,s') (t,t') (a,a') (b,b')
alongside :: Getter s   a   -> Getter s'    a'    -> Getter (s,s')        (a,a')

Lift a Lens so it can run under a function (or other corepresentable profunctor).

inside :: Lens s t a b -> Lens (e -> s) (e -> t) (e -> a) (e -> b)

>>> (\x -> (x-1,x+1)) ^. inside _1 $ 5
4

>>> runState (modify (1:) >> modify (2:)) ^. (inside _2) $ []
[2,1]

Modify the target of a Lens and return the result.

When you do not need the result of the operation, ( %~ ) is more flexible.

(<%~) ::             Lens s t a b      -> (a -> b) -> s -> (b, t)
(<%~) ::             Iso s t a b       -> (a -> b) -> s -> (b, t)
(<%~) :: Monoid b => Traversal s t a b -> (a -> b) -> s -> (b, t)

Increment the target of a numerically valued Lens and return the result.

When you do not need the result of the addition, ( +~ ) is more flexible.

(<+~) :: Num a => Lens' s a -> a -> s -> (a, s)
(<+~) :: Num a => Iso' s a  -> a -> s -> (a, s)

Decrement the target of a numerically valued Lens and return the result.

When you do not need the result of the subtraction, ( -~ ) is more flexible.

(<-~) :: Num a => Lens' s a -> a -> s -> (a, s)
(<-~) :: Num a => Iso' s a  -> a -> s -> (a, s)

Multiply the target of a numerically valued Lens and return the result.

When you do not need the result of the multiplication, ( *~ ) is more flexible.

(<*~) :: Num a => Lens' s a -> a -> s -> (a, s)
(<*~) :: Num a => Iso'  s a -> a -> s -> (a, s)

Divide the target of a fractionally valued Lens and return the result.

When you do not need the result of the division, ( //~ ) is more flexible.

(<//~) :: Fractional a => Lens' s a -> a -> s -> (a, s)
(<//~) :: Fractional a => Iso'  s a -> a -> s -> (a, s)

Raise the target of a numerically valued Lens to a non-negative Integral power and return the result.

When you do not need the result of the operation, ( ^~ ) is more flexible.

(<^~) :: (Num a, Integral e) => Lens' s a -> e -> s -> (a, s)
(<^~) :: (Num a, Integral e) => Iso' s a -> e -> s -> (a, s)

Raise the target of a fractionally valued Lens to an Integral power and return the result.

When you do not need the result of the operation, ( ^^~ ) is more flexible.

(<^^~) :: (Fractional a, Integral e) => Lens' s a -> e -> s -> (a, s)
(<^^~) :: (Fractional a, Integral e) => Iso' s a -> e -> s -> (a, s)

Raise the target of a floating-point valued Lens to an arbitrary power and return the result.

When you do not need the result of the operation, ( **~ ) is more flexible.

(<**~) :: Floating a => Lens' s a -> a -> s -> (a, s)
(<**~) :: Floating a => Iso' s a  -> a -> s -> (a, s)

Logically || a Boolean valued Lens and return the result.

When you do not need the result of the operation, ( ||~ ) is more flexible.

(<||~) :: Lens' s Bool -> Bool -> s -> (Bool, s)
(<||~) :: Iso' s Bool  -> Bool -> s -> (Bool, s)

Logically && a Boolean valued Lens and return the result.

When you do not need the result of the operation, ( &&~ ) is more flexible.

(<&&~) :: Lens' s Bool -> Bool -> s -> (Bool, s)
(<&&~) :: Iso' s Bool  -> Bool -> s -> (Bool, s)

( <> ) a Semigroup value onto the end of the target of a Lens and return the result.

When you do not need the result of the operation, ( <>~ ) is more flexible.

Modify the target of a Lens , but return the old value.

When you do not need the old value, ( %~ ) is more flexible.

(<<%~) ::             Lens s t a b      -> (a -> b) -> s -> (a, t)
(<<%~) ::             Iso s t a b       -> (a -> b) -> s -> (a, t)
(<<%~) :: Monoid a => Traversal s t a b -> (a -> b) -> s -> (a, t)

Replace the target of a Lens , but return the old value.

When you do not need the old value, ( .~ ) is more flexible.

(<<.~) ::             Lens s t a b      -> b -> s -> (a, t)
(<<.~) ::             Iso s t a b       -> b -> s -> (a, t)
(<<.~) :: Monoid a => Traversal s t a b -> b -> s -> (a, t)

Replace the target of a Lens with a Just value, but return the old value.

If you do not need the old value ( ?~ ) is more flexible.

>>> import qualified Data.Map as Map
>>> _2.at "hello" <<?~ "world" $ (42,Map.fromList [("goodnight","gracie")])
(Nothing,(42,fromList [("goodnight","gracie"),("hello","world")]))

(<<?~) :: Iso s t a (Maybe b)       -> b -> s -> (a, t)
(<<?~) :: Lens s t a (Maybe b)      -> b -> s -> (a, t)
(<<?~) :: Traversal s t a (Maybe b) -> b -> s -> (a, t)

Increment the target of a numerically valued Lens and return the old value.

When you do not need the old value, ( +~ ) is more flexible.

>>> (a,b) & _1 <<+~ c
(a,(a + c,b))

>>> (a,b) & _2 <<+~ c
(b,(a,b + c))

(<<+~) :: Num a => Lens' s a -> a -> s -> (a, s)
(<<+~) :: Num a => Iso' s a -> a -> s -> (a, s)

Decrement the target of a numerically valued Lens and return the old value.

When you do not need the old value, ( -~ ) is more flexible.

>>> (a,b) & _1 <<-~ c
(a,(a - c,b))

>>> (a,b) & _2 <<-~ c
(b,(a,b - c))

(<<-~) :: Num a => Lens' s a -> a -> s -> (a, s)
(<<-~) :: Num a => Iso' s a -> a -> s -> (a, s)

Multiply the target of a numerically valued Lens and return the old value.

When you do not need the old value, ( -~ ) is more flexible.

>>> (a,b) & _1 <<*~ c
(a,(a * c,b))

>>> (a,b) & _2 <<*~ c
(b,(a,b * c))

(<<*~) :: Num a => Lens' s a -> a -> s -> (a, s)
(<<*~) :: Num a => Iso' s a -> a -> s -> (a, s)

Divide the target of a numerically valued Lens and return the old value.

When you do not need the old value, ( //~ ) is more flexible.

>>> (a,b) & _1 <<//~ c
(a,(a / c,b))

>>> ("Hawaii",10) & _2 <<//~ 2
(10.0,("Hawaii",5.0))

(<<//~) :: Fractional a => Lens' s a -> a -> s -> (a, s)
(<<//~) :: Fractional a => Iso' s a -> a -> s -> (a, s)

Raise the target of a numerically valued Lens to a non-negative power and return the old value.

When you do not need the old value, ( ^~ ) is more flexible.

(<<^~) :: (Num a, Integral e) => Lens' s a -> e -> s -> (a, s)
(<<^~) :: (Num a, Integral e) => Iso' s a -> e -> s -> (a, s)

Raise the target of a fractionally valued Lens to an integral power and return the old value.

When you do not need the old value, ( ^^~ ) is more flexible.

(<<^^~) :: (Fractional a, Integral e) => Lens' s a -> e -> s -> (a, s)
(<<^^~) :: (Fractional a, Integral e) => Iso' s a -> e -> S -> (a, s)

Raise the target of a floating-point valued Lens to an arbitrary power and return the old value.

When you do not need the old value, ( **~ ) is more flexible.

>>> (a,b) & _1 <<**~ c
(a,(a**c,b))

>>> (a,b) & _2 <<**~ c
(b,(a,b**c))

(<<**~) :: Floating a => Lens' s a -> a -> s -> (a, s)
(<<**~) :: Floating a => Iso' s a -> a -> s -> (a, s)

Logically || the target of a Bool -valued Lens and return the old value.

When you do not need the old value, ( ||~ ) is more flexible.

>>> (False,6) & _1 <<||~ True
(False,(True,6))

>>> ("hello",True) & _2 <<||~ False
(True,("hello",True))

(<<||~) :: Lens' s Bool -> Bool -> s -> (Bool, s)
(<<||~) :: Iso' s Bool -> Bool -> s -> (Bool, s)

Logically && the target of a Bool -valued Lens and return the old value.

When you do not need the old value, ( &&~ ) is more flexible.

>>> (False,6) & _1 <<&&~ True
(False,(False,6))

>>> ("hello",True) & _2 <<&&~ False
(True,("hello",False))

(<<&&~) :: Lens' s Bool -> Bool -> s -> (Bool, s)
(<<&&~) :: Iso' s Bool -> Bool -> s -> (Bool, s)

Modify the target of a monoidally valued Lens by using ( <> ) a new value and return the old value.

When you do not need the old value, ( <>~ ) is more flexible.

>>> (Sum a,b) & _1 <<<>~ Sum c
(Sum {getSum = a},(Sum {getSum = a + c},b))

>>> _2 <<<>~ ", 007" $ ("James", "Bond")
("Bond",("James","Bond, 007"))

(<<<>~) :: Semigroup r => Lens' s r -> r -> s -> (r, s)
(<<<>~) :: Semigroup r => Iso' s r -> r -> s -> (r, s)

Modify the target of a Lens into your Monad' s state by a user supplied function and return the result.

When applied to a Traversal , it this will return a monoidal summary of all of the intermediate results.

When you do not need the result of the operation, ( %= ) is more flexible.

(<%=) :: MonadState s m             => Lens' s a      -> (a -> a) -> m a
(<%=) :: MonadState s m             => Iso' s a       -> (a -> a) -> m a
(<%=) :: (MonadState s m, Monoid a) => Traversal' s a -> (a -> a) -> m a

Add to the target of a numerically valued Lens into your Monad' s state and return the result.

When you do not need the result of the addition, ( += ) is more flexible.

(<+=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
(<+=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

Subtract from the target of a numerically valued Lens into your Monad' s state and return the result.

When you do not need the result of the subtraction, ( -= ) is more flexible.

(<-=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
(<-=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

Multiply the target of a numerically valued Lens into your Monad' s state and return the result.

When you do not need the result of the multiplication, ( *= ) is more flexible.

(<*=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
(<*=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

Divide the target of a fractionally valued Lens into your Monad' s state and return the result.

When you do not need the result of the division, ( //= ) is more flexible.

(<//=) :: (MonadState s m, Fractional a) => Lens' s a -> a -> m a
(<//=) :: (MonadState s m, Fractional a) => Iso' s a -> a -> m a

Raise the target of a numerically valued Lens into your Monad' s state to a non-negative Integral power and return the result.

When you do not need the result of the operation, ( ^= ) is more flexible.

(<^=) :: (MonadState s m, Num a, Integral e) => Lens' s a -> e -> m a
(<^=) :: (MonadState s m, Num a, Integral e) => Iso' s a -> e -> m a

Raise the target of a fractionally valued Lens into your Monad' s state to an Integral power and return the result.

When you do not need the result of the operation, ( ^^= ) is more flexible.

(<^^=) :: (MonadState s m, Fractional b, Integral e) => Lens' s a -> e -> m a
(<^^=) :: (MonadState s m, Fractional b, Integral e) => Iso' s a  -> e -> m a

Raise the target of a floating-point valued Lens into your Monad' s state to an arbitrary power and return the result.

When you do not need the result of the operation, ( **= ) is more flexible.

(<**=) :: (MonadState s m, Floating a) => Lens' s a -> a -> m a
(<**=) :: (MonadState s m, Floating a) => Iso' s a -> a -> m a

Logically || a Boolean valued Lens into your Monad' s state and return the result.

When you do not need the result of the operation, ( ||= ) is more flexible.

(<||=) :: MonadState s m => Lens' s Bool -> Bool -> m Bool
(<||=) :: MonadState s m => Iso' s Bool  -> Bool -> m Bool

Logically && a Boolean valued Lens into your Monad' s state and return the result.

When you do not need the result of the operation, ( &&= ) is more flexible.

(<&&=) :: MonadState s m => Lens' s Bool -> Bool -> m Bool
(<&&=) :: MonadState s m => Iso' s Bool  -> Bool -> m Bool

( <> ) a Semigroup value onto the end of the target of a Lens into your Monad' s state and return the result.

When you do not need the result of the operation, ( <>= ) is more flexible.

Modify the target of a Lens into your Monad' s state by a user supplied function and return the old value that was replaced.

When applied to a Traversal , this will return a monoidal summary of all of the old values present.

When you do not need the result of the operation, ( %= ) is more flexible.

(<<%=) :: MonadState s m             => Lens' s a      -> (a -> a) -> m a
(<<%=) :: MonadState s m             => Iso' s a       -> (a -> a) -> m a
(<<%=) :: (MonadState s m, Monoid a) => Traversal' s a -> (a -> a) -> m a

(<<%=) :: MonadState s m => LensLike ((,)a) s s a b -> (a -> b) -> m a

Replace the target of a Lens into your Monad' s state with a user supplied value and return the old value that was replaced.

When applied to a Traversal , this will return a monoidal summary of all of the old values present.

When you do not need the result of the operation, ( .= ) is more flexible.

(<<.=) :: MonadState s m             => Lens' s a      -> a -> m a
(<<.=) :: MonadState s m             => Iso' s a       -> a -> m a
(<<.=) :: (MonadState s m, Monoid a) => Traversal' s a -> a -> m a

Replace the target of a Lens into your Monad' s state with Just a user supplied value and return the old value that was replaced.

When applied to a Traversal , this will return a monoidal summary of all of the old values present.

When you do not need the result of the operation, ( ?= ) is more flexible.

(<<?=) :: MonadState s m             => Lens s t a (Maybe b)      -> b -> m a
(<<?=) :: MonadState s m             => Iso s t a (Maybe b)       -> b -> m a
(<<?=) :: (MonadState s m, Monoid a) => Traversal s t a (Maybe b) -> b -> m a

Modify the target of a Lens into your Monad' s state by adding a value and return the old value that was replaced.

When you do not need the result of the operation, ( += ) is more flexible.

(<<+=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
(<<+=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

Modify the target of a Lens into your Monad' s state by subtracting a value and return the old value that was replaced.

When you do not need the result of the operation, ( -= ) is more flexible.

(<<-=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
(<<-=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

Modify the target of a Lens into your Monad' s state by multipling a value and return the old value that was replaced.

When you do not need the result of the operation, ( *= ) is more flexible.

(<<*=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
(<<*=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

Modify the target of a Lens into your Monad s state by dividing by a value and return the old value that was replaced.

When you do not need the result of the operation, ( //= ) is more flexible.

(<<//=) :: (MonadState s m, Fractional a) => Lens' s a -> a -> m a
(<<//=) :: (MonadState s m, Fractional a) => Iso' s a -> a -> m a

Modify the target of a Lens into your Monad' s state by raising it by a non-negative power and return the old value that was replaced.

When you do not need the result of the operation, ( ^= ) is more flexible.

(<<^=) :: (MonadState s m, Num a, Integral e) => Lens' s a -> e -> m a
(<<^=) :: (MonadState s m, Num a, Integral e) => Iso' s a -> a -> m a

Modify the target of a Lens into your Monad' s state by raising it by an integral power and return the old value that was replaced.

When you do not need the result of the operation, ( ^^= ) is more flexible.

(<<^^=) :: (MonadState s m, Fractional a, Integral e) => Lens' s a -> e -> m a
(<<^^=) :: (MonadState s m, Fractional a, Integral e) => Iso' s a -> e -> m a

Modify the target of a Lens into your Monad' s state by raising it by an arbitrary power and return the old value that was replaced.

When you do not need the result of the operation, ( **= ) is more flexible.

(<<**=) :: (MonadState s m, Floating a) => Lens' s a -> a -> m a
(<<**=) :: (MonadState s m, Floating a) => Iso' s a -> a -> m a

Modify the target of a Lens into your Monad' s state by taking its logical || with a value and return the old value that was replaced.

When you do not need the result of the operation, ( ||= ) is more flexible.

(<<||=) :: MonadState s m => Lens' s Bool -> Bool -> m Bool
(<<||=) :: MonadState s m => Iso' s Bool -> Bool -> m Bool

Modify the target of a Lens into your Monad' s state by taking its logical && with a value and return the old value that was replaced.

When you do not need the result of the operation, ( &&= ) is more flexible.

(<<&&=) :: MonadState s m => Lens' s Bool -> Bool -> m Bool
(<<&&=) :: MonadState s m => Iso' s Bool -> Bool -> m Bool

Modify the target of a Lens into your Monad' s state by using ( <> ) and return the old value that was replaced.

When you do not need the result of the operation, ( <>= ) is more flexible.

(<<<>=) :: (MonadState s m, Semigroup r) => Lens' s r -> r -> m r
(<<<>=) :: (MonadState s m, Semigroup r) => Iso' s r -> r -> m r

Run a monadic action, and set the target of Lens to its result.

(<<~) :: MonadState s m => Iso s s a b   -> m b -> m b
(<<~) :: MonadState s m => Lens s s a b  -> m b -> m b

NB: This is limited to taking an actual Lens than admitting a Traversal because there are potential loss of state issues otherwise.

Cloning a Lens is one way to make sure you aren't given something weaker, such as a Traversal and can be used as a way to pass around lenses that have to be monomorphic in f .

Note: This only accepts a proper Lens .

>>> let example l x = set (cloneLens l) (x^.cloneLens l + 1) x in example _2 ("hello",1,"you")
("hello",2,"you")

Clone a Lens as an IndexedPreservingLens that just passes through whatever index is on any IndexedLens , IndexedFold , IndexedGetter or IndexedTraversal it is composed with.

Clone an IndexedLens as an IndexedLens with the same index.

over for Arrows.

Unlike over , overA can't accept a simple Setter , but requires a full lens, or close enough.

>>> overA _1 ((+1) *** (+2)) ((1,2),6)
((2,4),6)

overA :: Arrow ar => Lens s t a b -> ar a b -> ar s t

A version of set that works on ALens .

>>> storing _2 "world" ("hello","there")
("hello","world")

A version of ( ^. ) that works on ALens .

>>> ("hello","world")^#_2
"world"

A version of ( .~ ) that works on ALens .

>>> ("hello","there") & _2 #~ "world"
("hello","world")

A version of ( %~ ) that works on ALens .

>>> ("hello","world") & _2 #%~ length
("hello",5)

A version of ( %%~ ) that works on ALens .

>>> ("hello","world") & _2 #%%~ \x -> (length x, x ++ "!")
(5,("hello","world!"))

A version of ( <.~ ) that works on ALens .

>>> ("hello","there") & _2 <#~ "world"
("world",("hello","world"))

A version of ( <%~ ) that works on ALens .

>>> ("hello","world") & _2 <#%~ length
(5,("hello",5))

A version of ( .= ) that works on ALens .

A version of ( %= ) that works on ALens .

A version of ( %%= ) that works on ALens .

A version of ( <.= ) that works on ALens .

A version of ( <%= ) that works on ALens .

There is a field for every type in the Void . Very zen.

>>> [] & mapped.devoid +~ 1
[]

>>> Nothing & mapped.devoid %~ abs
Nothing

devoid :: Lens' Void a

We can always retrieve a () from any type.

>>> "hello"^.united
()

>>> "hello" & united .~ ()
"hello"

A Lens focusing on the first element of a Traversable1 container.

>>> 2 :| [3, 4] & head1 +~ 10
12 :| [3,4]

>>> Identity True ^. head1
True

A Lens focusing on the last element of a Traversable1 container.

>>> 2 :| [3, 4] & last1 +~ 10
2 :| [3,14]

>>> Node 'a' [Node 'b' [], Node 'c' []] ^. last1
'c'

The indexed store can be used to characterize a Lens and is used by cloneLens .

Context a b t is isomorphic to newtype Context a b t = Context { runContext :: forall f. Functor f => (a -> f b) -> f t } , and to exists s. (s, Lens s t a b) .

A Context is like a Lens that has already been applied to a some structure.

type Context' a s = Context a a s

This Lens lets you view the current pos of any indexed store comonad and seek to a new position. This reduces the API for working these instances to a single Lens .

ipos w ≡ w ^. locus
iseek s w ≡ w & locus .~ s
iseeks f w ≡ w & locus %~ f

locus :: Lens' (Context' a s) a
locus :: Conjoined p => Lens' (Pretext' p a s) a
locus :: Conjoined p => Lens' (PretextT' p g a s) a

Fuse a composition of lenses using Yoneda to provide fmap fusion.

In general, given a pair of lenses foo and bar

fusing (foo.bar) = foo.bar

however, foo and bar are either going to fmap internally or they are trivial.

fusing exploits the Yoneda lemma to merge these separate uses into a single fmap .

This is particularly effective when the choice of functor f is unknown at compile time or when the Lens foo.bar in the above description is recursive or complex enough to prevent inlining.

fusing :: Lens s t a b -> Lens s t a b