lens-3.7.0.2: Lenses, Folds and Traversals

Portability Rank2Types provisional Edward Kmett Safe-Inferred

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 `Lens`-like 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 an 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)]
```

# Building Setters

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

Build a 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:

``` `sets` `.` `over` ≡ `id`
`over` `.` `sets` ≡ `id`
```

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

# 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","!!!")]
```

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

# Functional Combinators

over :: Setting s t a b -> (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`

mapOf :: Setting s t a b -> (a -> b) -> s -> tSource

Deprecated: Use `over`

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

set :: Setting 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
```

(.~) :: Setting 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
```

(%~) :: Setting s t a b -> (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],[3]]
```
``` (`%~`) :: `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 => Setting 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 => `Simple` `Setter` s a -> a -> s -> s
(`+~`) :: Num a => `Simple` `Iso` s a -> a -> s -> s
(`+~`) :: Num a => `Simple` `Lens` s a -> a -> s -> s
(`+~`) :: Num a => `Simple` `Traversal` s a -> a -> s -> s
```

(-~) :: Num a => Setting 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 => `Simple` `Setter` s a -> a -> s -> s
(`-~`) :: `Num` a => `Simple` `Iso` s a -> a -> s -> s
(`-~`) :: `Num` a => `Simple` `Lens` s a -> a -> s -> s
(`-~`) :: `Num` a => `Simple` `Traversal` s a -> a -> s -> s
```

(*~) :: Num a => Setting 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 => `Simple` `Setter` s a -> a -> s -> s
(`*~`) :: `Num` a => `Simple` `Iso` s a -> a -> s -> s
(`*~`) :: `Num` a => `Simple` `Lens` s a -> a -> s -> s
(`*~`) :: `Num` a => `Simple` `Traversal` s a -> a -> s -> s
```

(//~) :: Fractional s => Setting a b s s -> s -> a -> bSource

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 => `Simple` `Setter` s a -> a -> s -> s
(`//~`) :: `Fractional` a => `Simple` `Iso` s a -> a -> s -> s
(`//~`) :: `Fractional` a => `Simple` `Lens` s a -> a -> s -> s
(`//~`) :: `Fractional` a => `Simple` `Traversal` s a -> a -> s -> s
```

(^~) :: (Num a, Integral e) => Setting 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) => `Simple` `Setter` s a -> e -> s -> s
(`^~`) :: (`Num` a, `Integral` e) => `Simple` `Iso` s a -> e -> s -> s
(`^~`) :: (`Num` a, `Integral` e) => `Simple` `Lens` s a -> e -> s -> s
(`^~`) :: (`Num` a, `Integral` e) => `Simple` `Traversal` s a -> e -> s -> s
```

(^^~) :: (Fractional a, Integral e) => Setting 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) => `Simple` `Setter` s a -> e -> s -> s
(`^^~`) :: (`Fractional` a, `Integral` e) => `Simple` `Iso` s a -> e -> s -> s
(`^^~`) :: (`Fractional` a, `Integral` e) => `Simple` `Lens` s a -> e -> s -> s
(`^^~`) :: (`Fractional` a, `Integral` e) => `Simple` `Traversal` s a -> e -> s -> s
```

(**~) :: Floating a => Setting 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 **~ pi \$ (1,3)
```(1,31.54428070019754)
```
``` (`**~`) :: `Floating` a => `Simple` `Setter` s a -> a -> s -> s
(`**~`) :: `Floating` a => `Simple` `Iso` s a -> a -> s -> s
(`**~`) :: `Floating` a => `Simple` `Lens` s a -> a -> s -> s
(`**~`) :: `Floating` a => `Simple` `Traversal` s a -> a -> s -> s
```

(||~) :: Setting 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)
```
``` (`||~`) :: `Simple` `Setter` s `Bool` -> `Bool` -> s -> s
(`||~`) :: `Simple` `Iso` s `Bool` -> `Bool` -> s -> s
(`||~`) :: `Simple` `Lens` s `Bool` -> `Bool` -> s -> s
(`||~`) :: `Simple` `Traversal` s `Bool` -> `Bool` -> s -> s
```

(<>~) :: Monoid a => Setting 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
```

(&&~) :: Setting 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)
```
``` (`&&~`) :: `Simple` `Setter` s `Bool` -> `Bool` -> s -> s
(`&&~`) :: `Simple` `Iso` s `Bool` -> `Bool` -> s -> s
(`&&~`) :: `Simple` `Lens` s `Bool` -> `Bool` -> s -> s
(`&&~`) :: `Simple` `Traversal` s `Bool` -> `Bool` -> s -> s
```

(<.~) :: Setting 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)
```

(?~) :: Setting 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
```

(<?~) :: Setting 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 b    -> (`Maybe` 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 => Setting 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 => `Simple` `Iso` s a       -> a -> m ()
`assign` :: `MonadState` s m => `Simple` `Lens` s a      -> a -> m ()
`assign` :: `MonadState` s m => `Simple` `Traversal` s a -> a -> m ()
`assign` :: `MonadState` s m => `Simple` `Setter` s a    -> a -> m ()
```

(.=) :: MonadState s m => Setting 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 => `Simple` `Iso` s a       -> a -> m ()
(`.=`) :: `MonadState` s m => `Simple` `Lens` s a      -> a -> m ()
(`.=`) :: `MonadState` s m => `Simple` `Traversal` s a -> a -> m ()
(`.=`) :: `MonadState` s m => `Simple` `Setter` s a    -> a -> m ()
```

(%=) :: MonadState s m => Setting s s a b -> (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 => `Simple` `Iso` s a       -> (a -> a) -> m ()
(`%=`) :: `MonadState` s m => `Simple` `Lens` s a      -> (a -> a) -> m ()
(`%=`) :: `MonadState` s m => `Simple` `Traversal` s a -> (a -> a) -> m ()
(`%=`) :: `MonadState` s m => `Simple` `Setter` s a    -> (a -> a) -> m ()
```

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

Modify the target(s) of a `Simple` `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) => `Simple` `Setter` s a -> a -> m ()
(`+=`) :: (`MonadState` s m, `Num` a) => `Simple` `Iso` s a -> a -> m ()
(`+=`) :: (`MonadState` s m, `Num` a) => `Simple` `Lens` s a -> a -> m ()
(`+=`) :: (`MonadState` s m, `Num` a) => `Simple` `Traversal` s a -> a -> m ()
```

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

Modify the target(s) of a `Simple` `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) => `Simple` `Setter` s a -> a -> m ()
(`-=`) :: (`MonadState` s m, `Num` a) => `Simple` `Iso` s a -> a -> m ()
(`-=`) :: (`MonadState` s m, `Num` a) => `Simple` `Lens` s a -> a -> m ()
(`-=`) :: (`MonadState` s m, `Num` a) => `Simple` `Traversal` s a -> a -> m ()
```

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

Modify the target(s) of a `Simple` `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) => `Simple` `Setter` s a -> a -> m ()
(`*=`) :: (`MonadState` s m, `Num` a) => `Simple` `Iso` s a -> a -> m ()
(`*=`) :: (`MonadState` s m, `Num` a) => `Simple` `Lens` s a -> a -> m ()
(`*=`) :: (`MonadState` s m, `Num` a) => `Simple` `Traversal` s a -> a -> m ()
```

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

Modify the target(s) of a `Simple` `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) => `Simple` `Setter` s a -> a -> m ()
(`//=`) :: (`MonadState` s m, `Fractional` a) => `Simple` `Iso` s a -> a -> m ()
(`//=`) :: (`MonadState` s m, `Fractional` a) => `Simple` `Lens` s a -> a -> m ()
(`//=`) :: (`MonadState` s m, `Fractional` a) => `Simple` `Traversal` s a -> a -> m ()
```

(^=) :: (MonadState s m, Num a, Integral e) => SimpleSetting 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) => `Simple` `Setter` s a -> e -> m ()
(`^=`) ::  (`MonadState` s m, `Num` a, `Integral` e) => `Simple` `Iso` s a -> e -> m ()
(`^=`) ::  (`MonadState` s m, `Num` a, `Integral` e) => `Simple` `Lens` s a -> e -> m ()
(`^=`) ::  (`MonadState` s m, `Num` a, `Integral` e) => `Simple` `Traversal` s a -> e -> m ()
```

(^^=) :: (MonadState s m, Fractional a, Integral e) => SimpleSetting 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) => `Simple` `Setter` s a -> e -> m ()
(`^^=`) ::  (`MonadState` s m, `Fractional` a, `Integral` e) => `Simple` `Iso` s a -> e -> m ()
(`^^=`) ::  (`MonadState` s m, `Fractional` a, `Integral` e) => `Simple` `Lens` s a -> e -> m ()
(`^^=`) ::  (`MonadState` s m, `Fractional` a, `Integral` e) => `Simple` `Traversal` s a -> e -> m ()
```

(**=) :: (MonadState s m, Floating a) => SimpleSetting 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) => `Simple` `Setter` s a -> a -> m ()
(`**=`) ::  (`MonadState` s m, `Floating` a) => `Simple` `Iso` s a -> a -> m ()
(`**=`) ::  (`MonadState` s m, `Floating` a) => `Simple` `Lens` s a -> a -> m ()
(`**=`) ::  (`MonadState` s m, `Floating` a) => `Simple` `Traversal` s a -> a -> m ()
```

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

Modify the target(s) of a `Simple` `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 => `Simple` `Setter` s `Bool` -> `Bool` -> m ()
(`||=`) :: `MonadState` s m => `Simple` `Iso` s `Bool` -> `Bool` -> m ()
(`||=`) :: `MonadState` s m => `Simple` `Lens` s `Bool` -> `Bool` -> m ()
(`||=`) :: `MonadState` s m => `Simple` `Traversal` s `Bool` -> `Bool` -> m ()
```

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

Modify the target(s) of a `Simple` `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) => `Simple` `Setter` s a -> a -> m ()
(`<>=`) :: (`MonadState` s m, `Monoid` a) => `Simple` `Iso` s a -> a -> m ()
(`<>=`) :: (`MonadState` s m, `Monoid` a) => `Simple` `Lens` s a -> a -> m ()
(`<>=`) :: (`MonadState` s m, `Monoid` a) => `Simple` `Traversal` s a -> a -> m ()
```

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

Modify the target(s) of a `Simple` `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 => `Simple` `Setter` s `Bool` -> `Bool` -> m ()
(`&&=`) :: `MonadState` s m => `Simple` `Iso` s `Bool` -> `Bool` -> m ()
(`&&=`) :: `MonadState` s m => `Simple` `Lens` s `Bool` -> `Bool` -> m ()
(`&&=`) :: `MonadState` s m => `Simple` `Traversal` s `Bool` -> `Bool` -> m ()
```

(<.=) :: MonadState s m => Setting 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 => Setting 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 => `Simple` `Iso` s (`Maybe` a)       -> a -> m ()
(`?=`) :: `MonadState` s m => `Simple` `Lens` s (`Maybe` a)      -> a -> m ()
(`?=`) :: `MonadState` s m => `Simple` `Traversal` s (`Maybe` a) -> a -> m ()
(`?=`) :: `MonadState` s m => `Simple` `Setter` s (`Maybe` a)    -> a -> m ()
```

(<?=) :: MonadState s m => Setting 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 => Setting 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`.

# Simplified State Setting

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

Replace the target of a `Lens` or all of the targets of a `Simple` `Setter` or `Simple` `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'` :: `Simple` `Setter` s a    -> a -> s -> s
`set'` :: `Simple` `Iso` s a       -> a -> s -> s
`set'` :: `Simple` `Lens` s a      -> a -> s -> s
`set'` :: `Simple` `Traversal` s a -> a -> s -> s
```

# Storing Setters

newtype ReifiedSetter s t a b Source

Reify a setter so it can be stored safely in a container.

Constructors

 ReifySetter FieldsreflectSetter :: Setter s t a b

# Setter Internals

type Setting s t a b = (a -> Mutator b) -> s -> Mutator 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.

By choosing `Mutator` rather than `Identity`, we get nicer error messages.

type SimpleSetting s a = Setting s s a aSource

This is a useful alias for use when consuming a `SimpleSetter`.

Most user code will never have to use this type.

`type `SimpleSetting` m = `Simple` `Setting``

# Simplicity

type SimpleSetter s a = Setter s s a aSource

A Simple 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 :: `SimpleSetter` `Text` `Char``
`type `SimpleSetter` = `Simple` `Setter``

type SimpleReifiedSetter s a = ReifiedSetter s s a aSource

`type `SimpleReifiedSetter` = `Simple` `ReifiedSetter``

# Exported for legible error messages

class Applicative f => Settable f Source

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

Instances

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

data Mutator a Source

`Mutator` is just a renamed `Identity` functor to give better error messages when someone attempts to use a getter as a setter.

Most user code will never need to see this type.

Instances

 Functor Mutator Applicative Mutator Settable Mutator