lens-5.3.3: Lenses, Folds and Traversals

Copyright | (C) 2014-2016 Edward Kmett
License | BSD-style (see the file LICENSE)
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | experimental
Portability | non-portable
Safe Haskell | Safe-Inferred
Language | Haskell2010

Data.Map.Lens

Description

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")]
    (4,"Jupiter")

    >>> itoList $ Map.fromList [(5, "Saturn")]
    [(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
    Nothing

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"

Synopsis

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

# Documentation

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

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

The construction is left-biased (see `union`), i.e. the first occurrences 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