lens-4.18.1: Lenses, Folds and Traversals

Copyright(C) 2014-2016 Edward Kmett
LicenseBSD-style (see the file LICENSE)
MaintainerEdward Kmett <ekmett@gmail.com>
Safe HaskellSafe



One of most commonly-asked questions about this package is whether it provides lenses for working with Map. It does, but their uses are perhaps obscured by their genericity. This module exists to provide documentation for them.

Map is an instance of At, so we have a lenses on values at keys:

>>> Map.fromList [(1, "world")] ^.at 1
Just "world"
>>> at 1 .~ Just "world" $ Map.empty
fromList [(1,"world")]
>>> at 0 ?~ "hello" $ Map.empty
fromList [(0,"hello")]

We can traverse, fold over, and map over key-value pairs in a Map, thanks to its TraversableWithIndex, FoldableWithIndex, and FunctorWithIndex instances.

>>> imap const $ Map.fromList [(1, "Venus")]
fromList [(1,1)]
>>> ifoldMap (\i _ -> Sum i) $ Map.fromList [(2, "Earth"), (3, "Mars")]
Sum {getSum = 5}
>>> itraverse_ (curry print) $ Map.fromList [(4, "Jupiter")]
>>> itoList $ Map.fromList [(5, "Saturn")]

A related class, Ixed, allows us to use ix to traverse a value at a particular key.

>>> ix 2 %~ ("New " ++) $ Map.fromList [(2, "Earth")]
fromList [(2,"New Earth")]
>>> preview (ix 8) $ Map.empty

Additionally, Map has TraverseMin and TraverseMax instances, which let us traverse over the value at the least and greatest keys, respectively.

>>> preview traverseMin $ Map.fromList [(5, "Saturn"), (6, "Uranus")]
Just "Saturn"
>>> preview traverseMax $ Map.fromList [(5, "Saturn"), (6, "Uranus")]
Just "Uranus"


toMapOf :: IndexedGetting i (Map i a) s a -> s -> Map i a Source #

Construct a map from a IndexedGetter, IndexedFold, IndexedTraversal or IndexedLens

The construction is left-biased (see union), i.e. the first occurences of keys in the fold or traversal order are preferred.

>>> toMapOf folded ["hello", "world"]
fromList [(0,"hello"),(1,"world")]
>>> toMapOf (folded . ifolded) [('a',"alpha"),('b', "beta")]
fromList [('a',"alpha"),('b',"beta")]
>>> toMapOf (folded <.> folded) ["foo", "bar"]
fromList [((0,0),'f'),((0,1),'o'),((0,2),'o'),((1,0),'b'),((1,1),'a'),((1,2),'r')]
>>> toMapOf ifolded $ Map.fromList [('a', "hello"), ('b', "world")]
fromList [('a',"hello"),('b',"world")]
toMapOf ::          IndexedGetter i s a     -> s -> Map i a
toMapOf :: Ord i => IndexedFold i s a       -> s -> Map i a
toMapOf ::          IndexedLens' i s a      -> s -> Map i a
toMapOf :: Ord i => IndexedTraversal' i s a -> s -> Map i a