map -package:containers -package:bytestring -package:text -package:vector package:relude

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.

Contains implementation of polymorphic type classes for data types Set and Map.

Deprecated: Use toFst from Tuple instead

Deprecated: Use toSnd from Tuple instead

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"])

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_.

Examples

mapM is literally a traverse with a type signature restricted to Monad. Its implementation may be more efficient due to additional power of Monad.

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. mapM_ is just like traverse_, but specialised to monadic actions.

The monadic version of the mapMaybe function.

>>> :{
evenInHalf :: Int -> IO (Maybe Int)
evenInHalf n
| even n = pure $ Just $ n `div` 2
| otherwise = pure Nothing
:}

>>> mapMaybeM evenInHalf [1..10]
[1,2,3,4,5]

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 mapMaybe function is a version of map which can throw out elements. In particular, the functional argument returns something of type Maybe b. If this is Nothing, no element is added on to the result list. If it is Just b, then b is included in the result list.

Examples

Using mapMaybe f x is a shortcut for catMaybes $ map f x in most cases:

>>> import Text.Read ( readMaybe )

>>> let readMaybeInt = readMaybe :: String -> Maybe Int

>>> mapMaybe readMaybeInt ["1", "Foo", "3"]
[1,3]

>>> catMaybes $ map readMaybeInt ["1", "Foo", "3"]
[1,3]

If we map the Just constructor, the entire list should be returned:

>>> mapMaybe Just [1,2,3]
[1,2,3]

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.

A map of integers to values a.

inverseMap f creates a function that is the inverse of a given function f. It does so by constructing Map internally for each value f a. The implementation makes sure that the Map is constructed only once and then shared for every call. Memory usage note: don't inverse functions that have types like Int as their input. In this case the created Map will have huge size. The complexity of reversed mapping is <math>. Performance note: make sure to specialize monomorphic type of your functions that use inverseMap to avoid Map reconstruction. One of the common inverseMap use-case is inverting the show or a show-like function.

>>> data Color = Red | Green | Blue deriving (Show, Enum, Bounded)

>>> parse = inverseMap show :: String -> Maybe Color

>>> parse "Red"
Just Red

>>> parse "Black"
Nothing

Correctness note: inverseMap expects injective function as its argument, i.e. the function must map distinct arguments to distinct values. Typical usage of this function looks like this:

data GhcVer
= Ghc802
| Ghc822
| Ghc844
| Ghc865
| Ghc881
deriving (Eq, Ord, Show, Enum, Bounded)

showGhcVer :: GhcVer -> Text
showGhcVer = \case
Ghc802 -> "8.0.2"
Ghc822 -> "8.2.2"
Ghc844 -> "8.4.4"
Ghc865 -> "8.6.5"
Ghc881 -> "8.8.1"

parseGhcVer :: Text -> Maybe GhcVer
parseGhcVer = inverseMap showGhcVer

Maps a function over both elements of a bifunctor.

>>> bimapBoth length ([True], [False, True])
(1,2)

>>> map (bimapBoth not) [Left True, Right False]
[Left False,Right True]

Fmaps functions for nested bifunctor. Short for fmap (bimap f g).

>>> bimapF not length $ Just (False, ['a', 'b'])
Just (True,2)

Map each element of the non-empty structure to a semigroup, and combine the results.

>>> foldMap1 SG.Sum (1 :| [2, 3, 4])
Sum {getSum = 10}

>>> foldMap1 show (123 :| [456, 789, 0])
"1234567890"

Modifiable Map.

Read-only map or set. Contains polymorphic functions which work for both sets and maps.

Like fmap, but also keep the original value in the snd position. A dual to fmapToSnd.

>>> fmapToFst show [3, 10, 2]
[("3",3),("10",10),("2",2)]

Like fmap, but also keep the original value in the fst position. A dual to fmapToFst.

>>> fmapToSnd show [3, 10, 2]
[(3,"3"),(10,"10"),(2,"2")]

Alternative version of asum that takes a function to map over.

>>> asumMap (\x -> if x > 2 then Just x else Nothing) [1..4]
Just 3

Polymorphic version of the concatMapA function.

>>> foldMapA @[Int] (Just . replicate 3) [1..3]
Just [1,1,1,2,2,2,3,3,3]