map -package:basement -is:exact -package:base package:imports

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]
[2,3,4]

A Map from keys k to values a. The Semigroup operation for Map is union, which prefers values from the left operand. If m1 maps a key k to a value a1, and m2 maps the same key to a different value a2, then their union m1 <> m2 maps k to a1.

The mapAccumL function behaves like a combination of fmap and foldl; it applies a function to each element of a structure, passing an accumulating parameter from left to right, and returning a final value of this accumulator together with the new structure.

Examples

Basic usage:

>>> mapAccumL (\a b -> (a + b, a)) 0 [1..10]
(55,[0,1,3,6,10,15,21,28,36,45])

>>> mapAccumL (\a b -> (a <> show b, a)) "0" [1..5]
("012345",["0","01","012","0123","01234"])

The mapAccumR function behaves like a combination of fmap and foldr; it applies a function to each element of a structure, passing an accumulating parameter from right to left, and returning a final value of this accumulator together with the new structure.

Examples

Basic usage:

>>> mapAccumR (\a b -> (a + b, a)) 0 [1..10]
(55,[54,52,49,45,40,34,27,19,10,0])

>>> mapAccumR (\a b -> (a <> show b, a)) "0" [1..5]
("054321",["05432","0543","054","05","0"])

The mapAndUnzipM function maps its first argument over a list, returning the result as a pair of lists. This function is mainly used with complicated data structures or a state monad.

The mapBoth function takes two functions and applies the first if iff the value takes the form Left _ and the second if the value takes the form Right _. Using Data.Bifunctor:

mapBoth = bimap

Using Control.Arrow:

mapBoth = (+++)

>>> mapBoth (*2) (*3) (Left 4)
Left 8

>>> mapBoth (*2) (*3) (Right 4)
Right 12

The mapLeft function takes a function and applies it to an Either value iff the value takes the form Left _. Using Data.Bifunctor:

mapLeft = first

Using Control.Arrow:

mapLeft = (left)

Using Control.Lens:

mapLeft = over _Left

>>> mapLeft (*2) (Left 4)
Left 8

>>> mapLeft (*2) (Right "hello")
Right "hello"

Transform the value returned by a Reader.

• runReader (mapReader f m) = f .
  runReader m

Transform the computation inside a ReaderT.

• runReaderT (mapReaderT f m) = f .
  runReaderT m

The mapRight function takes a function and applies it to an Either value iff the value takes the form Right _. Using Data.Bifunctor:

mapRight = second

Using Control.Arrow:

mapRight = (right)

Using Control.Lens:

mapRight = over _Right

>>> mapRight (*2) (Left "hello")
Left "hello"

>>> mapRight (*2) (Right 4)
Right 8

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.

A map from keys to values. A map cannot contain duplicate keys; each key can map to at most one value.

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

Map a function over all the elements of a container and concatenate the resulting lists.

Examples

Basic usage:

>>> concatMap (take 3) [[1..], [10..], [100..], [1000..]]
[1,2,3,10,11,12,100,101,102,1000,1001,1002]

>>> concatMap (take 3) (Just [1..])
[1,2,3]

fmap is used to apply a function of type (a -> b) to a value of type f a, where f is a functor, to produce a value of type f b. Note that for any type constructor with more than one parameter (e.g., Either), only the last type parameter can be modified with fmap (e.g., b in `Either a b`). Some type constructors with two parameters or more have a Bifunctor instance that allows both the last and the penultimate parameters to be mapped over.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> fmap show Nothing
Nothing

>>> fmap show (Just 3)
Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> fmap show (Left 17)
Left 17

>>> fmap show (Right 17)
Right "17"

Double each element of a list:

>>> fmap (*2) [1,2,3]
[2,4,6]

Apply even to the second element of a pair:

>>> fmap even (2,2)
(2,True)

It may seem surprising that the function is only applied to the last element of the tuple compared to the list example above which applies it to every element in the list. To understand, remember that tuples are type constructors with multiple type parameters: a tuple of 3 elements (a,b,c) can also be written (,,) a b c and its Functor instance is defined for Functor ((,,) a b) (i.e., only the third parameter is free to be mapped over with fmap). It explains why fmap can be used with tuples containing values of different types as in the following example:

>>> fmap even ("hello", 1.0, 4)
("hello",1.0,True)