# map package:lens

map f xs is the list obtained by applying f to each element of xs, i.e.,
```map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
map f [x1, x2, ...] == [f x1, f x2, ...]
```
```>>> map (+1) [1, 2, 3]
```
This Setter can be used to purely map over the Exceptions an arbitrary expression might throw; it is a variant of mapException in the same way that mapped is a variant of fmap.
```'mapException' ≡ 'over' 'mappedException'
```
This view that every Haskell expression can be regarded as carrying a bag of Exceptions is detailed in “A Semantics for Imprecise Exceptions” by Peyton Jones & al. at PLDI ’99. The following maps failed assertions to arithmetic overflow:
```>>> handling _Overflow (\_ -> return "caught") \$ assert False (return "uncaught") & mappedException %~ \ (AssertionFailed _) -> Overflow
"caught"
```
This is a type restricted version of mappedException, which avoids the type ambiguity in the input Exception when using set. The following maps any exception to arithmetic overflow:
```>>> handling _Overflow (\_ -> return "caught") \$ assert False (return "uncaught") & mappedException' .~ Overflow
"caught"
```
This generalizes mapAccumL to an arbitrary Traversal.
```mapAccumL ≡ mapAccumLOf traverse
```
mapAccumLOf accumulates State from left to right.
```mapAccumLOf :: Iso s t a b       -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumLOf :: Lens s t a b      -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumLOf :: Traversal s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
```
```mapAccumLOf :: LensLike (State acc) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumLOf l f acc0 s = swap (runState (l (a -> state (acc -> swap (f acc a))) s) acc0)
```
This generalizes mapAccumR to an arbitrary Traversal.
```mapAccumR ≡ mapAccumROf traverse
```
mapAccumROf accumulates State from right to left.
```mapAccumROf :: Iso s t a b       -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumROf :: Lens s t a b      -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumROf :: Traversal s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
```
```mapAccumROf :: LensLike (Backwards (State acc)) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
```
We can use Equality to do substitution into anything.
Map each element of a structure targeted by a Lens to a monadic action, evaluate these actions from left to right, and collect the results.
```>>> mapMOf both (\x -> [x, x + 1]) (1,3)
[(1,3),(1,4),(2,3),(2,4)]
```
```mapM ≡ mapMOf traverse
imapMOf l ≡ forM l . Indexed
```
```mapMOf :: Monad m => Iso s t a b       -> (a -> m b) -> s -> m t
mapMOf :: Monad m => Lens s t a b      -> (a -> m b) -> s -> m t
mapMOf :: Monad m => Traversal s t a b -> (a -> m b) -> s -> m t
```
Map each target of a Fold on a structure to a monadic action, evaluate these actions from left to right, and ignore the results.
```>>> mapMOf_ both putStrLn ("hello","world")
hello
world
```
```mapM_ ≡ mapMOf_ folded
```
```mapMOf_ :: Monad m => Getter s a     -> (a -> m r) -> s -> m ()
mapMOf_ :: Monad m => Fold s a       -> (a -> m r) -> s -> m ()
mapMOf_ :: Monad m => Lens' s a      -> (a -> m r) -> s -> m ()
mapMOf_ :: Monad m => Iso' s a       -> (a -> m r) -> s -> m ()
mapMOf_ :: Monad m => Traversal' s a -> (a -> m r) -> s -> m ()
mapMOf_ :: Monad m => Prism' s a     -> (a -> m r) -> s -> m ()
```
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.
This can be used to lift any Iso into an arbitrary Functor.
Create a FieldNamer from a mapping function. If the function returns [], it creates no lens for the field.
Map each element of a structure to a monadic action, evaluate these actions from left to right, and collect the results. For a version that ignores the results see mapM_.
Map each element of a structure to a monadic action, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results see mapM. As of base 4.8.0.0, mapM_ is just traverse_, specialized to Monad.
An associative operation NOTE: This method is redundant and has the default implementation mappend = (<>) since base-4.11.0.0. Should it be implemented manually, since mappend is a synonym for (<>), it is expected that the two functions are defined the same way. In a future GHC release mappend will be removed from Monoid.
Map over both arguments at the same time.
```bimap f g ≡ first f . second g
```

#### Examples

```>>> bimap toUpper (+1) ('j', 3)
('J',4)
```
```>>> bimap toUpper (+1) (Left 'j')
Left 'J'
```
```>>> bimap toUpper (+1) (Right 3)
Right 4
```
Lift two Isos 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')
```
Map a function over all the targets of a Fold of a container and concatenate the resulting lists.
```>>> concatMapOf both (\x -> [x, x + 1]) (1,3)
[1,2,3,4]
```
```concatMap ≡ concatMapOf folded
```
```concatMapOf :: Getter s a     -> (a -> [r]) -> s -> [r]
concatMapOf :: Fold s a       -> (a -> [r]) -> s -> [r]
concatMapOf :: Lens' s a      -> (a -> [r]) -> s -> [r]
concatMapOf :: Iso' s a       -> (a -> [r]) -> s -> [r]
concatMapOf :: Traversal' s a -> (a -> [r]) -> s -> [r]
```
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]
```
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)
```
Map over both arguments at the same time.
```dimap f g ≡ lmap f . rmap g
```
Lift two Isos into both arguments of a Profunctor simultaneously.
```dimapping :: Profunctor p => Iso s t a b -> Iso s' t' a' b' -> Iso (p a s') (p b t') (p s a') (p t b')
dimapping :: Profunctor p => Iso' s a -> Iso' s' a' -> Iso' (p a s') (p s a')
```
Fold a value using its Foldable instance using explicitly provided Monoid operations. This is like foldMap where the Monoid instance can be manually specified.
```foldMapBy mappend mempty ≡ foldMap
```
```>>> foldMapBy (+) 0 length ["hello","world"]
10
```
Fold a value using a specified Fold and Monoid operations. This is like foldMapBy where the Foldable instance can be manually specified.
```foldMapByOf folded ≡ foldMapBy
```
```foldMapByOf :: Getter s a     -> (r -> r -> r) -> r -> (a -> r) -> s -> r
foldMapByOf :: Fold s a       -> (r -> r -> r) -> r -> (a -> r) -> s -> r
foldMapByOf :: Traversal' s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r
foldMapByOf :: Lens' s a      -> (r -> r -> r) -> r -> (a -> r) -> s -> r
foldMapByOf :: Iso' s a       -> (r -> r -> r) -> r -> (a -> r) -> s -> r
```
```>>> foldMapByOf both (+) 0 length ("hello","world")
10
```