lens-4.3.3: Lenses, Folds and Traversals

Portability Rank2Types provisional Edward Kmett Trustworthy

Control.Lens.Setter

Description

A `Setter s t a b` is a generalization of `fmap` from `Functor`. It allows you to map into a structure and change out the contents, but it isn't strong enough to allow you to enumerate those contents. Starting with `fmap :: Functor f => (a -> b) -> f a -> f b` we monomorphize the type to obtain `(a -> b) -> s -> t` and then decorate it with `Identity` to obtain:

``` type `Setter` s t a b = (a -> `Identity` b) -> s -> `Identity` t
```

Every `Traversal` is a valid `Setter`, since `Identity` is `Applicative`.

Everything you can do with a `Functor`, you can do with a `Setter`. There are combinators that generalize `fmap` and (`<\$`).

Synopsis

# Setters

type Setter s t a b = forall f. Settable f => (a -> f b) -> s -> f tSource

The only `LensLike` law that can apply to a `Setter` `l` is that

``` `set` l y (`set` l x a) ≡ `set` l y a
```

You can't `view` a `Setter` in general, so the other two laws are irrelevant.

However, two `Functor` laws apply to a `Setter`:

``` `over` l `id` ≡ `id`
`over` l f `.` `over` l g ≡ `over` l (f `.` g)
```

These can be stated more directly:

``` l `pure` ≡ `pure`
l f `.` `untainted` `.` l g ≡ l (f `.` `untainted` `.` g)
```

You can compose a `Setter` with a `Lens` or a `Traversal` using (`.`) from the `Prelude` and the result is always only a `Setter` and nothing more.

````>>> ````over traverse f [a,b,c,d]
```[f a,f b,f c,f d]
```
````>>> ````over _1 f (a,b)
```(f a,b)
```
````>>> ````over (traverse._1) f [(a,b),(c,d)]
```[(f a,b),(f c,d)]
```
````>>> ````over both f (a,b)
```(f a,f b)
```
````>>> ````over (traverse.both) f [(a,b),(c,d)]
```[(f a,f b),(f c,f d)]
```

type Setter' s a = Setter s s a aSource

A `Setter'` is just a `Setter` that doesn't change the types.

These are particularly common when talking about monomorphic containers. e.g.

``` `sets` Data.Text.map :: `Setter'` `Text` `Char`
```
``` type `Setter'` = `Setter'`
```

type IndexedSetter i s t a b = forall f p. (Indexable i p, Settable f) => p a (f b) -> s -> f tSource

Every `IndexedSetter` is a valid `Setter`.

The `Setter` laws are still required to hold.

type IndexedSetter' i s a = IndexedSetter i s s a aSource

``` type `IndexedSetter'` i = `Simple` (`IndexedSetter` i)
```

type ASetter s t a b = (a -> Identity b) -> s -> Identity tSource

Running a `Setter` instantiates it to a concrete type.

When consuming a setter directly to perform a mapping, you can use this type, but most user code will not need to use this type.

type ASetter' s a = ASetter s s a aSource

This is a useful alias for use when consuming a `Setter'`.

Most user code will never have to use this type.

``` type `ASetter'` = `Simple` `ASetter`
```

type AnIndexedSetter i s t a b = Indexed i a (Identity b) -> s -> Identity tSource

Running an `IndexedSetter` instantiates it to a concrete type.

When consuming a setter directly to perform a mapping, you can use this type, but most user code will not need to use this type.

type AnIndexedSetter' i s a = AnIndexedSetter i s s a aSource

``` type `AnIndexedSetter'` i = `Simple` (`AnIndexedSetter` i)
```

type Setting p s t a b = p a (Identity b) -> s -> Identity tSource

This is a convenient alias when defining highly polymorphic code that takes both `ASetter` and `AnIndexedSetter` as appropriate. If a function takes this it is expecting one of those two things based on context.

type Setting' p s a = Setting p s s a aSource

This is a convenient alias when defining highly polymorphic code that takes both `ASetter'` and `AnIndexedSetter'` as appropriate. If a function takes this it is expecting one of those two things based on context.

# Building Setters

sets :: (Profunctor p, Profunctor q, Settable f) => (p a b -> q s t) -> Optical p q f s t a bSource

Build a `Setter`, `IndexedSetter` or `IndexPreservingSetter` depending on your choice of `Profunctor`.

``` `sets` :: ((a -> b) -> s -> t) -> `Setter` s t a b
```

setting :: ((a -> b) -> s -> t) -> IndexPreservingSetter s t a bSource

Build an index-preserving `Setter` from a map-like function.

Your supplied function `f` is required to satisfy:

``` f `id` ≡ `id`
f g `.` f h ≡ f (g `.` h)
```

Equational reasoning:

``` `setting` `.` `over` ≡ `id`
`over` `.` `setting` ≡ `id`
```

Another way to view `sets` is that it takes a "semantic editor combinator" and transforms it into a `Setter`.

``` `setting` :: ((a -> b) -> s -> t) -> `Setter` s t a b
```

cloneSetter :: ASetter s t a b -> Setter s t a bSource

Restore `ASetter` to a full `Setter`.

cloneIndexPreservingSetter :: ASetter s t a b -> IndexPreservingSetter s t a bSource

Build an `IndexPreservingSetter` from any `Setter`.

cloneIndexedSetter :: AnIndexedSetter i s t a b -> IndexedSetter i s t a bSource

Clone an `IndexedSetter`.

# Common Setters

mapped :: Functor f => Setter (f a) (f b) a bSource

This `Setter` can be used to map over all of the values in a `Functor`.

``` `fmap` ≡ `over` `mapped`
`fmapDefault` ≡ `over` `traverse`
(`<\$`) ≡ `set` `mapped`
```
````>>> ````over mapped f [a,b,c]
```[f a,f b,f c]
```
````>>> ````over mapped (+1) [1,2,3]
```[2,3,4]
```
````>>> ````set mapped x [a,b,c]
```[x,x,x]
```
````>>> ````[[a,b],[c]] & mapped.mapped +~ x
```[[a + x,b + x],[c + x]]
```
````>>> ````over (mapped._2) length [("hello","world"),("leaders","!!!")]
```
``` `mapped` :: `Functor` f => `Setter` (f a) (f b) a b
```

If you want an `IndexPreservingSetter` use `setting fmap`.

lifted :: Monad m => Setter (m a) (m b) a bSource

This `setter` can be used to modify all of the values in a `Monad`.

You sometimes have to use this rather than `mapped` -- due to temporary insanity `Functor` is not a superclass of `Monad`.

``` `liftM` ≡ `over` `lifted`
```
````>>> ````over lifted f [a,b,c]
```[f a,f b,f c]
```
````>>> ````set lifted b (Just a)
```Just b
```

If you want an `IndexPreservingSetter` use `setting liftM`.

contramapped :: Contravariant f => Setter (f b) (f a) a bSource

This `Setter` can be used to map over all of the inputs to a `Contravariant`.

``` `contramap` ≡ `over` `contramapped`
```
````>>> ````getPredicate (over contramapped (*2) (Predicate even)) 5
```True
```
````>>> ````getOp (over contramapped (*5) (Op show)) 100
```"500"
```
````>>> ````Prelude.map (\$ 1) \$ over (mapped . _Unwrapping' Op . contramapped) (*12) [(*2),(+1),(^3)]
```[24,13,1728]
```

argument :: Profunctor p => Setter (p b r) (p a r) a bSource

This `Setter` can be used to map over the input of a `Profunctor`.

The most common `Profunctor` to use this with is `(->)`.

````>>> ````(argument %~ f) g x
```g (f x)
```
````>>> ````(argument %~ show) length [1,2,3]
```7
```
````>>> ````(argument %~ f) h x y
```h (f x) y
```

Map over the argument of the result of a function -- i.e., its second argument:

````>>> ````(mapped.argument %~ f) h x y
```h x (f y)
```
``` `argument` :: `Setter` (b -> r) (a -> r) a b
```

# Functional Combinators

over :: Profunctor p => Setting p s t a b -> p a b -> s -> tSource

Modify the target of a `Lens` or all the targets of a `Setter` or `Traversal` with a function.

``` `fmap` ≡ `over` `mapped`
`fmapDefault` ≡ `over` `traverse`
`sets` `.` `over` ≡ `id`
`over` `.` `sets` ≡ `id`
```

Given any valid `Setter` `l`, you can also rely on the law:

``` `over` l f `.` `over` l g = `over` l (f `.` g)
```

e.g.

````>>> ````over mapped f (over mapped g [a,b,c]) == over mapped (f . g) [a,b,c]
```True
```

Another way to view `over` is to say that it transforms a `Setter` into a "semantic editor combinator".

````>>> ````over mapped f (Just a)
```Just (f a)
```
````>>> ````over mapped (*10) [1,2,3]
```[10,20,30]
```
````>>> ````over _1 f (a,b)
```(f a,b)
```
````>>> ````over _1 show (10,20)
```("10",20)
```
``` `over` :: `Setter` s t a b -> (a -> b) -> s -> t
`over` :: `ASetter` s t a b -> (a -> b) -> s -> t
```

set :: ASetter s t a b -> b -> s -> tSource

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` with a constant value.

``` (`<\$`) ≡ `set` `mapped`
```
````>>> ````set _2 "hello" (1,())
```(1,"hello")
```
````>>> ````set mapped () [1,2,3,4]
```[(),(),(),()]
```

Note: Attempting to `set` a `Fold` or `Getter` will fail at compile time with an relatively nice error message.

``` `set` :: `Setter` s t a b    -> b -> s -> t
`set` :: `Iso` s t a b       -> b -> s -> t
`set` :: `Lens` s t a b      -> b -> s -> t
`set` :: `Traversal` s t a b -> b -> s -> t
```

(.~) :: ASetter s t a b -> b -> s -> tSource

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` with a constant value.

This is an infix version of `set`, provided for consistency with (`.=`).

``` f `<\$` a ≡ `mapped` `.~` f `\$` a
```
````>>> ````(a,b,c,d) & _4 .~ e
```(a,b,c,e)
```
````>>> ````(42,"world") & _1 .~ "hello"
```("hello","world")
```
````>>> ````(a,b) & both .~ c
```(c,c)
```
``` (`.~`) :: `Setter` s t a b    -> b -> s -> t
(`.~`) :: `Iso` s t a b       -> b -> s -> t
(`.~`) :: `Lens` s t a b      -> b -> s -> t
(`.~`) :: `Traversal` s t a b -> b -> s -> t
```

(%~) :: Profunctor p => Setting p s t a b -> p a b -> s -> tSource

Modifies the target of a `Lens` or all of the targets of a `Setter` or `Traversal` with a user supplied function.

This is an infix version of `over`.

``` `fmap` f ≡ `mapped` `%~` f
`fmapDefault` f ≡ `traverse` `%~` f
```
````>>> ````(a,b,c) & _3 %~ f
```(a,b,f c)
```
````>>> ````(a,b) & both %~ f
```(f a,f b)
```
````>>> ````_2 %~ length \$ (1,"hello")
```(1,5)
```
````>>> ````traverse %~ f \$ [a,b,c]
```[f a,f b,f c]
```
````>>> ````traverse %~ even \$ [1,2,3]
```[False,True,False]
```
````>>> ````traverse.traverse %~ length \$ [["hello","world"],["!!!"]]
```[[5,5],]
```
``` (`%~`) :: `Setter` s t a b    -> (a -> b) -> s -> t
(`%~`) :: `Iso` s t a b       -> (a -> b) -> s -> t
(`%~`) :: `Lens` s t a b      -> (a -> b) -> s -> t
(`%~`) :: `Traversal` s t a b -> (a -> b) -> s -> t
```

(+~) :: Num a => ASetter s t a a -> a -> s -> tSource

Increment the target(s) of a numerically valued `Lens`, `Setter` or `Traversal`.

````>>> ````(a,b) & _1 +~ c
```(a + c,b)
```
````>>> ````(a,b) & both +~ c
```(a + c,b + c)
```
````>>> ````(1,2) & _2 +~ 1
```(1,3)
```
````>>> ````[(a,b),(c,d)] & traverse.both +~ e
```[(a + e,b + e),(c + e,d + e)]
```
``` (`+~`) :: `Num` a => `Setter'` s a    -> a -> s -> s
(`+~`) :: `Num` a => `Iso'` s a       -> a -> s -> s
(`+~`) :: `Num` a => `Lens'` s a      -> a -> s -> s
(`+~`) :: `Num` a => `Traversal'` s a -> a -> s -> s
```

(-~) :: Num a => ASetter s t a a -> a -> s -> tSource

Decrement the target(s) of a numerically valued `Lens`, `Iso`, `Setter` or `Traversal`.

````>>> ````(a,b) & _1 -~ c
```(a - c,b)
```
````>>> ````(a,b) & both -~ c
```(a - c,b - c)
```
````>>> ````_1 -~ 2 \$ (1,2)
```(-1,2)
```
````>>> ````mapped.mapped -~ 1 \$ [[4,5],[6,7]]
```[[3,4],[5,6]]
```
``` (`-~`) :: `Num` a => `Setter'` s a    -> a -> s -> s
(`-~`) :: `Num` a => `Iso'` s a       -> a -> s -> s
(`-~`) :: `Num` a => `Lens'` s a      -> a -> s -> s
(`-~`) :: `Num` a => `Traversal'` s a -> a -> s -> s
```

(*~) :: Num a => ASetter s t a a -> a -> s -> tSource

Multiply the target(s) of a numerically valued `Lens`, `Iso`, `Setter` or `Traversal`.

````>>> ````(a,b) & _1 *~ c
```(a * c,b)
```
````>>> ````(a,b) & both *~ c
```(a * c,b * c)
```
````>>> ````(1,2) & _2 *~ 4
```(1,8)
```
````>>> ````Just 24 & mapped *~ 2
```Just 48
```
``` (`*~`) :: `Num` a => `Setter'` s a    -> a -> s -> s
(`*~`) :: `Num` a => `Iso'` s a       -> a -> s -> s
(`*~`) :: `Num` a => `Lens'` s a      -> a -> s -> s
(`*~`) :: `Num` a => `Traversal'` s a -> a -> s -> s
```

(//~) :: Fractional a => ASetter s t a a -> a -> s -> tSource

Divide the target(s) of a numerically valued `Lens`, `Iso`, `Setter` or `Traversal`.

````>>> ````(a,b) & _1 //~ c
```(a / c,b)
```
````>>> ````(a,b) & both //~ c
```(a / c,b / c)
```
````>>> ````("Hawaii",10) & _2 //~ 2
```("Hawaii",5.0)
```
``` (`//~`) :: `Fractional` a => `Setter'` s a    -> a -> s -> s
(`//~`) :: `Fractional` a => `Iso'` s a       -> a -> s -> s
(`//~`) :: `Fractional` a => `Lens'` s a      -> a -> s -> s
(`//~`) :: `Fractional` a => `Traversal'` s a -> a -> s -> s
```

(^~) :: (Num a, Integral e) => ASetter s t a a -> e -> s -> tSource

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to a non-negative integral power.

````>>> ````(1,3) & _2 ^~ 2
```(1,9)
```
``` (`^~`) :: (`Num` a, `Integral` e) => `Setter'` s a    -> e -> s -> s
(`^~`) :: (`Num` a, `Integral` e) => `Iso'` s a       -> e -> s -> s
(`^~`) :: (`Num` a, `Integral` e) => `Lens'` s a      -> e -> s -> s
(`^~`) :: (`Num` a, `Integral` e) => `Traversal'` s a -> e -> s -> s
```

(^^~) :: (Fractional a, Integral e) => ASetter s t a a -> e -> s -> tSource

Raise the target(s) of a fractionally valued `Lens`, `Setter` or `Traversal` to an integral power.

````>>> ````(1,2) & _2 ^^~ (-1)
```(1,0.5)
```
``` (`^^~`) :: (`Fractional` a, `Integral` e) => `Setter'` s a    -> e -> s -> s
(`^^~`) :: (`Fractional` a, `Integral` e) => `Iso'` s a       -> e -> s -> s
(`^^~`) :: (`Fractional` a, `Integral` e) => `Lens'` s a      -> e -> s -> s
(`^^~`) :: (`Fractional` a, `Integral` e) => `Traversal'` s a -> e -> s -> s
```

(**~) :: Floating a => ASetter s t a a -> a -> s -> tSource

Raise the target(s) of a floating-point valued `Lens`, `Setter` or `Traversal` to an arbitrary power.

````>>> ````(a,b) & _1 **~ c
```(a**c,b)
```
````>>> ````(a,b) & both **~ c
```(a**c,b**c)
```
````>>> ````_2 **~ 10 \$ (3,2)
```(3,1024.0)
```
``` (`**~`) :: `Floating` a => `Setter'` s a    -> a -> s -> s
(`**~`) :: `Floating` a => `Iso'` s a       -> a -> s -> s
(`**~`) :: `Floating` a => `Lens'` s a      -> a -> s -> s
(`**~`) :: `Floating` a => `Traversal'` s a -> a -> s -> s
```

(||~) :: ASetter s t Bool Bool -> Bool -> s -> tSource

Logically `||` the target(s) of a `Bool`-valued `Lens` or `Setter`.

````>>> ````both ||~ True \$ (False,True)
```(True,True)
```
````>>> ````both ||~ False \$ (False,True)
```(False,True)
```
``` (`||~`) :: `Setter'` s `Bool`    -> `Bool` -> s -> s
(`||~`) :: `Iso'` s `Bool`       -> `Bool` -> s -> s
(`||~`) :: `Lens'` s `Bool`      -> `Bool` -> s -> s
(`||~`) :: `Traversal'` s `Bool` -> `Bool` -> s -> s
```

(<>~) :: Monoid a => ASetter s t a a -> a -> s -> tSource

Modify the target of a monoidally valued by `mappend`ing another value.

````>>> ````(Sum a,b) & _1 <>~ Sum c
```(Sum {getSum = a + c},b)
```
````>>> ````(Sum a,Sum b) & both <>~ Sum c
```(Sum {getSum = a + c},Sum {getSum = b + c})
```
````>>> ````both <>~ "!!!" \$ ("hello","world")
```("hello!!!","world!!!")
```
``` (`<>~`) :: `Monoid` a => `Setter` s t a a    -> a -> s -> t
(`<>~`) :: `Monoid` a => `Iso` s t a a       -> a -> s -> t
(`<>~`) :: `Monoid` a => `Lens` s t a a      -> a -> s -> t
(`<>~`) :: `Monoid` a => `Traversal` s t a a -> a -> s -> t
```

(&&~) :: ASetter s t Bool Bool -> Bool -> s -> tSource

Logically `&&` the target(s) of a `Bool`-valued `Lens` or `Setter`.

````>>> ````both &&~ True \$ (False, True)
```(False,True)
```
````>>> ````both &&~ False \$ (False, True)
```(False,False)
```
``` (`&&~`) :: `Setter'` s `Bool`    -> `Bool` -> s -> s
(`&&~`) :: `Iso'` s `Bool`       -> `Bool` -> s -> s
(`&&~`) :: `Lens'` s `Bool`      -> `Bool` -> s -> s
(`&&~`) :: `Traversal'` s `Bool` -> `Bool` -> s -> s
```

(<.~) :: ASetter s t a b -> b -> s -> (b, t)Source

Set with pass-through.

This is mostly present for consistency, but may be useful for for chaining assignments.

If you do not need a copy of the intermediate result, then using `l .~ t` directly is a good idea.

````>>> ````(a,b) & _1 <.~ c
```(c,(c,b))
```
````>>> ````("good","morning","vietnam") & _3 <.~ "world"
```("world",("good","morning","world"))
```
````>>> ````(42,Map.fromList [("goodnight","gracie")]) & _2.at "hello" <.~ Just "world"
```(Just "world",(42,fromList [("goodnight","gracie"),("hello","world")]))
```
``` (`<.~`) :: `Setter` s t a b    -> b -> s -> (b, t)
(`<.~`) :: `Iso` s t a b       -> b -> s -> (b, t)
(`<.~`) :: `Lens` s t a b      -> b -> s -> (b, t)
(`<.~`) :: `Traversal` s t a b -> b -> s -> (b, t)
```

(?~) :: ASetter s t a (Maybe b) -> b -> s -> tSource

Set the target of a `Lens`, `Traversal` or `Setter` to `Just` a value.

``` l `?~` t ≡ `set` l (`Just` t)
```
````>>> ````Nothing & id ?~ a
```Just a
```
````>>> ````Map.empty & at 3 ?~ x
```fromList [(3,x)]
```
``` (`?~`) :: `Setter` s t a (`Maybe` b)    -> b -> s -> t
(`?~`) :: `Iso` s t a (`Maybe` b)       -> b -> s -> t
(`?~`) :: `Lens` s t a (`Maybe` b)      -> b -> s -> t
(`?~`) :: `Traversal` s t a (`Maybe` b) -> b -> s -> t
```

(<?~) :: ASetter s t a (Maybe b) -> b -> s -> (b, t)Source

Set to `Just` a value with pass-through.

This is mostly present for consistency, but may be useful for for chaining assignments.

If you do not need a copy of the intermediate result, then using `l ?~ d` directly is a good idea.

````>>> ````import Data.Map as Map
````>>> ````_2.at "hello" <?~ "world" \$ (42,Map.fromList [("goodnight","gracie")])
```("world",(42,fromList [("goodnight","gracie"),("hello","world")]))
```
``` (`<?~`) :: `Setter` s t a (`Maybe` b)    -> b -> s -> (b, t)
(`<?~`) :: `Iso` s t a (`Maybe` b)       -> b -> s -> (b, t)
(`<?~`) :: `Lens` s t a (`Maybe` b)      -> b -> s -> (b, t)
(`<?~`) :: `Traversal` s t a (`Maybe` b) -> b -> s -> (b, t)
```

# State Combinators

assign :: MonadState s m => ASetter s s a b -> b -> m ()Source

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state with a new value, irrespective of the old.

This is an alias for (`.=`).

````>>> ````execState (do assign _1 c; assign _2 d) (a,b)
```(c,d)
```
````>>> ````execState (both .= c) (a,b)
```(c,c)
```
``` `assign` :: `MonadState` s m => `Iso'` s a       -> a -> m ()
`assign` :: `MonadState` s m => `Lens'` s a      -> a -> m ()
`assign` :: `MonadState` s m => `Traversal'` s a -> a -> m ()
`assign` :: `MonadState` s m => `Setter'` s a    -> a -> m ()
```

(.=) :: MonadState s m => ASetter s s a b -> b -> m ()Source

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state with a new value, irrespective of the old.

This is an infix version of `assign`.

````>>> ````execState (do _1 .= c; _2 .= d) (a,b)
```(c,d)
```
````>>> ````execState (both .= c) (a,b)
```(c,c)
```
``` (`.=`) :: `MonadState` s m => `Iso'` s a       -> a -> m ()
(`.=`) :: `MonadState` s m => `Lens'` s a      -> a -> m ()
(`.=`) :: `MonadState` s m => `Traversal'` s a -> a -> m ()
(`.=`) :: `MonadState` s m => `Setter'` s a    -> a -> m ()
```

It puts the state in the monad or it gets the hose again.

(%=) :: (Profunctor p, MonadState s m) => Setting p s s a b -> p a b -> m ()Source

Map over the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state.

````>>> ````execState (do _1 %= f;_2 %= g) (a,b)
```(f a,g b)
```
````>>> ````execState (do both %= f) (a,b)
```(f a,f b)
```
``` (`%=`) :: `MonadState` s m => `Iso'` s a       -> (a -> a) -> m ()
(`%=`) :: `MonadState` s m => `Lens'` s a      -> (a -> a) -> m ()
(`%=`) :: `MonadState` s m => `Traversal'` s a -> (a -> a) -> m ()
(`%=`) :: `MonadState` s m => `Setter'` s a    -> (a -> a) -> m ()
```
``` (`%=`) :: `MonadState` s m => `ASetter` s s a b -> (a -> b) -> m ()
```

(+=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by adding a value.

Example:

``` `fresh` :: `MonadState` `Int` m => m `Int`
`fresh` = do
`id` `+=` 1
`use` `id`
```
````>>> ````execState (do _1 += c; _2 += d) (a,b)
```(a + c,b + d)
```
````>>> ````execState (do _1.at 1.non 0 += 10) (Map.fromList [(2,100)],"hello")
```(fromList [(1,10),(2,100)],"hello")
```
``` (`+=`) :: (`MonadState` s m, `Num` a) => `Setter'` s a    -> a -> m ()
(`+=`) :: (`MonadState` s m, `Num` a) => `Iso'` s a       -> a -> m ()
(`+=`) :: (`MonadState` s m, `Num` a) => `Lens'` s a      -> a -> m ()
(`+=`) :: (`MonadState` s m, `Num` a) => `Traversal'` s a -> a -> m ()
```

(-=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by subtracting a value.

````>>> ````execState (do _1 -= c; _2 -= d) (a,b)
```(a - c,b - d)
```
``` (`-=`) :: (`MonadState` s m, `Num` a) => `Setter'` s a    -> a -> m ()
(`-=`) :: (`MonadState` s m, `Num` a) => `Iso'` s a       -> a -> m ()
(`-=`) :: (`MonadState` s m, `Num` a) => `Lens'` s a      -> a -> m ()
(`-=`) :: (`MonadState` s m, `Num` a) => `Traversal'` s a -> a -> m ()
```

(*=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by multiplying by value.

````>>> ````execState (do _1 *= c; _2 *= d) (a,b)
```(a * c,b * d)
```
``` (`*=`) :: (`MonadState` s m, `Num` a) => `Setter'` s a    -> a -> m ()
(`*=`) :: (`MonadState` s m, `Num` a) => `Iso'` s a       -> a -> m ()
(`*=`) :: (`MonadState` s m, `Num` a) => `Lens'` s a      -> a -> m ()
(`*=`) :: (`MonadState` s m, `Num` a) => `Traversal'` s a -> a -> m ()
```

(//=) :: (MonadState s m, Fractional a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by dividing by a value.

````>>> ````execState (do _1 //= c; _2 //= d) (a,b)
```(a / c,b / d)
```
``` (`//=`) :: (`MonadState` s m, `Fractional` a) => `Setter'` s a    -> a -> m ()
(`//=`) :: (`MonadState` s m, `Fractional` a) => `Iso'` s a       -> a -> m ()
(`//=`) :: (`MonadState` s m, `Fractional` a) => `Lens'` s a      -> a -> m ()
(`//=`) :: (`MonadState` s m, `Fractional` a) => `Traversal'` s a -> a -> m ()
```

(^=) :: (MonadState s m, Num a, Integral e) => ASetter' s a -> e -> m ()Source

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to a non-negative integral power.

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

(^^=) :: (MonadState s m, Fractional a, Integral e) => ASetter' s a -> e -> m ()Source

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to an integral power.

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

(**=) :: (MonadState s m, Floating a) => ASetter' s a -> a -> m ()Source

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to an arbitrary power

````>>> ````execState (do _1 **= c; _2 **= d) (a,b)
```(a**c,b**d)
```
``` (`**=`) ::  (`MonadState` s m, `Floating` a) => `Setter'` s a    -> a -> m ()
(`**=`) ::  (`MonadState` s m, `Floating` a) => `Iso'` s a       -> a -> m ()
(`**=`) ::  (`MonadState` s m, `Floating` a) => `Lens'` s a      -> a -> m ()
(`**=`) ::  (`MonadState` s m, `Floating` a) => `Traversal'` s a -> a -> m ()
```

(||=) :: MonadState s m => ASetter' s Bool -> Bool -> m ()Source

Modify the target(s) of a `Lens'`, 'Iso, `Setter` or `Traversal` by taking their logical `||` with a value.

````>>> ````execState (do _1 ||= True; _2 ||= False; _3 ||= True; _4 ||= False) (True,True,False,False)
```(True,True,True,False)
```
``` (`||=`) :: `MonadState` s m => `Setter'` s `Bool`    -> `Bool` -> m ()
(`||=`) :: `MonadState` s m => `Iso'` s `Bool`       -> `Bool` -> m ()
(`||=`) :: `MonadState` s m => `Lens'` s `Bool`      -> `Bool` -> m ()
(`||=`) :: `MonadState` s m => `Traversal'` s `Bool` -> `Bool` -> m ()
```

(<>=) :: (MonadState s m, Monoid a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by `mappend`ing a value.

````>>> ````execState (do _1 <>= Sum c; _2 <>= Product d) (Sum a,Product b)
```(Sum {getSum = a + c},Product {getProduct = b * d})
```
````>>> ````execState (both <>= "!!!") ("hello","world")
```("hello!!!","world!!!")
```
``` (`<>=`) :: (`MonadState` s m, `Monoid` a) => `Setter'` s a -> a -> m ()
(`<>=`) :: (`MonadState` s m, `Monoid` a) => `Iso'` s a -> a -> m ()
(`<>=`) :: (`MonadState` s m, `Monoid` a) => `Lens'` s a -> a -> m ()
(`<>=`) :: (`MonadState` s m, `Monoid` a) => `Traversal'` s a -> a -> m ()
```

(&&=) :: MonadState s m => ASetter' s Bool -> Bool -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by taking their logical `&&` with a value.

````>>> ````execState (do _1 &&= True; _2 &&= False; _3 &&= True; _4 &&= False) (True,True,False,False)
```(True,False,False,False)
```
``` (`&&=`) :: `MonadState` s m => `Setter'` s `Bool`    -> `Bool` -> m ()
(`&&=`) :: `MonadState` s m => `Iso'` s `Bool`       -> `Bool` -> m ()
(`&&=`) :: `MonadState` s m => `Lens'` s `Bool`      -> `Bool` -> m ()
(`&&=`) :: `MonadState` s m => `Traversal'` s `Bool` -> `Bool` -> m ()
```

(<.=) :: MonadState s m => ASetter s s a b -> b -> m bSource

Set with pass-through

This is useful for chaining assignment without round-tripping through your `Monad` stack.

``` do x <- `_2` `<.=` ninety_nine_bottles_of_beer_on_the_wall
```

If you do not need a copy of the intermediate result, then using `l .= d` will avoid unused binding warnings.

``` (`<.=`) :: `MonadState` s m => `Setter` s s a b    -> b -> m b
(`<.=`) :: `MonadState` s m => `Iso` s s a b       -> b -> m b
(`<.=`) :: `MonadState` s m => `Lens` s s a b      -> b -> m b
(`<.=`) :: `MonadState` s m => `Traversal` s s a b -> b -> m b
```

(?=) :: MonadState s m => ASetter s s a (Maybe b) -> b -> m ()Source

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state with `Just` a new value, irrespective of the old.

````>>> ````execState (do at 1 ?= a; at 2 ?= b) Map.empty
```fromList [(1,a),(2,b)]
```
````>>> ````execState (do _1 ?= b; _2 ?= c) (Just a, Nothing)
```(Just b,Just c)
```
``` (`?=`) :: `MonadState` s m => `Iso'` s (`Maybe` a)       -> a -> m ()
(`?=`) :: `MonadState` s m => `Lens'` s (`Maybe` a)      -> a -> m ()
(`?=`) :: `MonadState` s m => `Traversal'` s (`Maybe` a) -> a -> m ()
(`?=`) :: `MonadState` s m => `Setter'` s (`Maybe` a)    -> a -> m ()
```

(<?=) :: MonadState s m => ASetter s s a (Maybe b) -> b -> m bSource

Set `Just` a value with pass-through

This is useful for chaining assignment without round-tripping through your `Monad` stack.

``` do x <- `at` foo `<?=` ninety_nine_bottles_of_beer_on_the_wall
```

If you do not need a copy of the intermediate result, then using `l ?= d` will avoid unused binding warnings.

``` (`<?=`) :: `MonadState` s m => `Setter` s s a (`Maybe` b)    -> b -> m b
(`<?=`) :: `MonadState` s m => `Iso` s s a (`Maybe` b)       -> b -> m b
(`<?=`) :: `MonadState` s m => `Lens` s s a (`Maybe` b)      -> b -> m b
(`<?=`) :: `MonadState` s m => `Traversal` s s a (`Maybe` b) -> b -> m b
```

(<~) :: MonadState s m => ASetter s s a b -> m b -> m ()Source

Run a monadic action, and set all of the targets of a `Lens`, `Setter` or `Traversal` to its result.

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

As a reasonable mnemonic, this lets you store the result of a monadic action in a `Lens` rather than in a local variable.

``` do foo <- bar
...
```

will store the result in a variable, while

``` do foo `<~` bar
...
```

will store the result in a `Lens`, `Setter`, or `Traversal`.

# Writer Combinators

scribe :: (MonadWriter t m, Monoid s) => ASetter s t a b -> b -> m ()Source

Write to a fragment of a larger `Writer` format.

passing :: MonadWriter w m => Setter w w u v -> m (a, u -> v) -> m aSource

This is a generalization of `pass` that alows you to modify just a portion of the resulting `MonadWriter`.

ipassing :: MonadWriter w m => IndexedSetter i w w u v -> m (a, i -> u -> v) -> m aSource

This is a generalization of `pass` that alows you to modify just a portion of the resulting `MonadWriter` with access to the index of an `IndexedSetter`.

censoring :: MonadWriter w m => Setter w w u v -> (u -> v) -> m a -> m aSource

This is a generalization of `censor` that alows you to `censor` just a portion of the resulting `MonadWriter`.

icensoring :: MonadWriter w m => IndexedSetter i w w u v -> (i -> u -> v) -> m a -> m aSource

This is a generalization of `censor` that alows you to `censor` just a portion of the resulting `MonadWriter`, with access to the index of an `IndexedSetter`.

# Simplified State Setting

set' :: ASetter' s a -> a -> s -> sSource

Replace the target of a `Lens` or all of the targets of a `Setter'` or `Traversal` with a constant value, without changing its type.

This is a type restricted version of `set`, which retains the type of the original.

````>>> ````set' mapped x [a,b,c,d]
```[x,x,x,x]
```
````>>> ````set' _2 "hello" (1,"world")
```(1,"hello")
```
````>>> ````set' mapped 0 [1,2,3,4]
```[0,0,0,0]
```

Note: Attempting to adjust `set'` a `Fold` or `Getter` will fail at compile time with an relatively nice error message.

``` `set'` :: `Setter'` s a    -> a -> s -> s
`set'` :: `Iso'` s a       -> a -> s -> s
`set'` :: `Lens'` s a      -> a -> s -> s
`set'` :: `Traversal'` s a -> a -> s -> s
```

# Indexed Setters

imapOf :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> tSource

Deprecated: Use `iover`

Map with index. (Deprecated alias for `iover`).

When you do not need access to the index, then `mapOf` is more liberal in what it can accept.

``` `mapOf` l ≡ `imapOf` l `.` `const`
```
``` `imapOf` :: `IndexedSetter` i s t a b    -> (i -> a -> b) -> s -> t
`imapOf` :: `IndexedLens` i s t a b      -> (i -> a -> b) -> s -> t
`imapOf` :: `IndexedTraversal` i s t a b -> (i -> a -> b) -> s -> t
```

iover :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> tSource

Map with index. This is an alias for `imapOf`.

When you do not need access to the index, then `over` is more liberal in what it can accept.

``` `over` l ≡ `iover` l `.` `const`
`iover` l ≡ `over` l `.` `Indexed`
```
``` `iover` :: `IndexedSetter` i s t a b    -> (i -> a -> b) -> s -> t
`iover` :: `IndexedLens` i s t a b      -> (i -> a -> b) -> s -> t
`iover` :: `IndexedTraversal` i s t a b -> (i -> a -> b) -> s -> t
```

isets :: ((i -> a -> b) -> s -> t) -> IndexedSetter i s t a bSource

Build an `IndexedSetter` from an `imap`-like function.

Your supplied function `f` is required to satisfy:

``` f `id` ≡ `id`
f g `.` f h ≡ f (g `.` h)
```

Equational reasoning:

``` `isets` `.` `iover` ≡ `id`
`iover` `.` `isets` ≡ `id`
```

Another way to view `sets` is that it takes a "semantic editor combinator" and transforms it into a `Setter`.

(%@~) :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> tSource

Adjust every target of an `IndexedSetter`, `IndexedLens` or `IndexedTraversal` with access to the index.

``` (`%@~`) ≡ `imapOf`
```

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

``` l `%~` f ≡ l `%@~` `const` f
```
``` (`%@~`) :: `IndexedSetter` i s t a b    -> (i -> a -> b) -> s -> t
(`%@~`) :: `IndexedLens` i s t a b      -> (i -> a -> b) -> s -> t
(`%@~`) :: `IndexedTraversal` i s t a b -> (i -> a -> b) -> s -> t
```

(%@=) :: MonadState s m => AnIndexedSetter i s s a b -> (i -> a -> b) -> m ()Source

Adjust every target in the current state of an `IndexedSetter`, `IndexedLens` or `IndexedTraversal` with access to the index.

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

``` l `%=` f ≡ l `%@=` `const` f
```
``` (`%@=`) :: `MonadState` s m => `IndexedSetter` i s s a b    -> (i -> a -> b) -> m ()
(`%@=`) :: `MonadState` s m => `IndexedLens` i s s a b      -> (i -> a -> b) -> m ()
(`%@=`) :: `MonadState` s m => `IndexedTraversal` i s t a b -> (i -> a -> b) -> m ()
```

# Arrow operators

assignA :: Arrow p => ASetter s t a b -> p s b -> p s tSource

Run an arrow command and use the output to set all the targets of a `Lens`, `Setter` or `Traversal` to the result.

`assignA` can be used very similarly to (`<~`), except that the type of the object being modified can change; for example:

``` runKleisli action ((), (), ()) where
action =      assignA _1 (Kleisli (const getVal1))
>>> assignA _2 (Kleisli (const getVal2))
>>> assignA _3 (Kleisli (const getVal3))
getVal1 :: Either String Int
getVal1 = ...
getVal2 :: Either String Bool
getVal2 = ...
getVal3 :: Either String Char
getVal3 = ...
```

has the type `Either String (Int, Bool, Char)`

``` `assignA` :: `Arrow` p => `Iso` s t a b       -> p s b -> p s t
`assignA` :: `Arrow` p => `Lens` s t a b      -> p s b -> p s t
`assignA` :: `Arrow` p => `Traversal` s t a b -> p s b -> p s t
`assignA` :: `Arrow` p => `Setter` s t a b    -> p s b -> p s t
```

# Exported for legible error messages

class (Applicative f, Distributive f, Traversable f) => Settable f Source

Anything `Settable` must be isomorphic to the `Identity` `Functor`.

Instances

 Settable Identity So you can pass our `Setter` into combinators from other lens libraries. Settable f => Settable (Backwards f) `backwards` (Settable f, Settable g) => Settable (Compose f g)

newtype Identity a

Constructors

 Identity FieldsrunIdentity :: a

Instances

 Monad Identity Functor Identity MonadFix Identity Applicative Identity Foldable Identity Traversable Identity Comonad Identity ComonadApply Identity Distributive Identity Traversable1 Identity Foldable1 Identity Apply Identity Bind Identity Extend Identity Eq1 Identity Ord1 Identity Read1 Identity Show1 Identity Settable Identity So you can pass our `Setter` into combinators from other lens libraries. TraversableWithIndex () Identity FoldableWithIndex () Identity FunctorWithIndex () Identity Effective Identity r (Const r) Eq a => Eq (Identity a) Ord a => Ord (Identity a) Read a => Read (Identity a) Show a => Show (Identity a) Wrapped (Identity a) Ixed (Identity a) ~ * t (Identity b) => Rewrapped (Identity a) t Field1 (Identity a) (Identity b) a b Each (Identity a) (Identity b) a b ``each` :: `Traversal` (`Identity` a) (`Identity` b) a b`

# Deprecated

mapOf :: Profunctor p => Setting p s t a b -> p a b -> s -> tSource

Deprecated: Use `over`

`mapOf` is a deprecated alias for `over`.