Map a function over all values in the map.

map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")]

map f s is the set obtained by applying f to each element of s. It's worth noting that the size of the result may be smaller if, for some (x,y), x /= y && f x == f y

Map a function over all values in the map.

map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")]

map f s is the set obtained by applying f to each element of s. If f is monotonically non-decreasing, this function takes <math> time. It's worth noting that the size of the result may be smaller if, for some (x,y), x /= y && f x == f y

Finite Maps (lazy interface)

This module re-exports the value lazy Data.Map.Lazy API. The Map k v type represents a finite map (sometimes called a dictionary) from keys of type k to values of type v. A Map is strict in its keys but lazy in its values. The functions in Data.Map.Strict are careful to force values before installing them in a Map. This is usually more efficient in cases where laziness is not essential. The functions in this module do not do so. When deciding if this is the correct data structure to use, consider:

• If you are using Int keys, you will get much better performance for most operations using Data.IntMap.Lazy.
• If you don't care about ordering, consider using Data.HashMap.Lazy from the unordered-containers package instead.

For a walkthrough of the most commonly used functions see the maps introduction. This module is intended to be imported qualified, to avoid name clashes with Prelude functions, e.g.

import Data.Map (Map)
import qualified Data.Map as Map

Note that the implementation is generally left-biased. Functions that take two maps as arguments and combine them, such as union and intersection, prefer the values in the first argument to those in the second.

Warning

The size of a Map must not exceed maxBound :: Int. Violation of this condition is not detected and if the size limit is exceeded, its behaviour is undefined.

Implementation

The implementation of Map is based on size balanced binary trees (or trees of bounded balance) as described by:

• Stephen Adams, "Efficient sets—a balancing act", Journal of Functional Programming 3(4):553-562, October 1993, https://doi.org/10.1017/S0956796800000885, https://groups.csail.mit.edu/mac/users/adams/BB/index.html.
• J. Nievergelt and E.M. Reingold, "Binary search trees of bounded balance", SIAM journal of computing 2(1), March 1973. https://doi.org/10.1137/0202005.
• Yoichi Hirai and Kazuhiko Yamamoto, "Balancing weight-balanced trees", Journal of Functional Programming 21(3):287-307, 2011, https://doi.org/10.1017/S0956796811000104

Bounds for union, intersection, and difference are as given by

• Guy Blelloch, Daniel Ferizovic, and Yihan Sun, "Parallel Ordered Sets Using Join", https://arxiv.org/abs/1602.02120v4.

Performance information

The time complexity is given for each operation in big-O notation, with <math> referring to the number of entries in the map. Operations like lookup, insert, and delete take <math> time. Binary set operations like union and intersection take <math> time, where <math> and <math> are the sizes of the smaller and larger input maps respectively.

A Map from keys k to values a.

The function mapAccum threads an accumulating argument through the map in ascending order of keys.

let f a b = (a ++ b, b ++ "X")
mapAccum f "Everything: " (fromList [(5,"a"), (3,"b")]) == ("Everything: ba", fromList [(3, "bX"), (5, "aX")])

The function mapAccumRWithKey threads an accumulating argument through the map in descending order of keys.

The function mapAccumWithKey threads an accumulating argument through the map in ascending order of keys.

let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X")
mapAccumWithKey f "Everything:" (fromList [(5,"a"), (3,"b")]) == ("Everything: 3-b 5-a", fromList [(3, "bX"), (5, "aX")])

Map values and separate the Left and Right results.

let f a = if a < "c" then Left a else Right a
mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
== (fromList [(3,"b"), (5,"a")], fromList [(1,"x"), (7,"z")])

mapEither (\ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
== (empty, fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])

Map keys/values and separate the Left and Right results.

let f k a = if k < 5 then Left (k * 2) else Right (a ++ a)
mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
== (fromList [(1,2), (3,6)], fromList [(5,"aa"), (7,"zz")])

mapEitherWithKey (\_ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")])
== (empty, fromList [(1,"x"), (3,"b"), (5,"a"), (7,"z")])

Map covariantly over a WhenMatched f k x, using only a 'Functor f' constraint.

Map covariantly over a WhenMissing f x, using only a 'Functor f' constraint.

mapKeys f s is the map obtained by applying f to each key of s. The size of the result may be smaller if f maps two or more distinct keys to the same new key. In this case the value at the greatest of the original keys is retained.

mapKeys (+ 1) (fromList [(5,"a"), (3,"b")])                        == fromList [(4, "b"), (6, "a")]
mapKeys (\ _ -> 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "c"
mapKeys (\ _ -> 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "c"

mapKeysMonotonic f s == mapKeys f s, but works only when f is strictly monotonic. That is, for any values x and y, if x < y then f x < f y. Semi-formally, we have:

and [x < y ==> f x < f y | x <- ls, y <- ls]
==> mapKeysMonotonic f s == mapKeys f s
where ls = keys s

This means that f maps distinct original keys to distinct resulting keys. This function has slightly better performance than mapKeys. Warning: This function should be used only if f is monotonically strictly increasing. This precondition is not checked. Use mapKeys if the precondition may not hold.

mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]

mapKeysWith c f s is the map obtained by applying f to each key of s. The size of the result may be smaller if f maps two or more distinct keys to the same new key. In this case the associated values will be combined using c.

mapKeysWith (++) (\ _ -> 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "cdab"
mapKeysWith (++) (\ _ -> 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "cdab"

Also see the performance note on fromListWith.

Map values and collect the Just results.

let f x = if x == "a" then Just "new a" else Nothing
mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a"

Map over the entries whose keys are missing from the other map, optionally removing some. This is the most powerful SimpleWhenMissing tactic, but others are usually more efficient.

mapMaybeMissing :: (Key -> x -> Maybe y) -> SimpleWhenMissing x y

mapMaybeMissing f = traverseMaybeMissing (\k x -> pure (f k x))

but mapMaybeMissing uses fewer unnecessary Applicative operations.

Map keys/values and collect the Just results.

let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing
mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3"

Map over the entries whose keys are missing from the other map.

mapMissing :: (k -> x -> y) -> SimpleWhenMissing x y

mapMissing f = mapMaybeMissing (\k x -> Just $ f k x)

but mapMissing is somewhat faster.

Map covariantly over a WhenMatched f x y.

Map covariantly over a WhenMissing f x.

Map a function over all values in the map.

let f key x = (show key) ++ ":" ++ x
mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")]

Map over the entries whose keys are missing from the other map, optionally removing some. This is the most powerful SimpleWhenMissing tactic, but others are usually more efficient.

mapMaybeMissing :: (k -> x -> Maybe y) -> SimpleWhenMissing k x y

mapMaybeMissing f = traverseMaybeMissing (\k x -> pure (f k x))

but mapMaybeMissing uses fewer unnecessary Applicative operations.

Map over the entries whose keys are missing from the other map.

mapMissing :: (k -> x -> y) -> SimpleWhenMissing k x y

mapMissing f = mapMaybeMissing (\k x -> Just $ f k x)

but mapMissing is somewhat faster.