1-----------------------------------------------------------------------------
2-- |
3-- Copyright   :  (C) 2014-2016 Edward Kmett
4-- License     :  BSD-style (see the file LICENSE)
5-- Maintainer  :  Edward Kmett <ekmett@gmail.com>
6-- Stability   :  experimental
7-- Portability :  non-portable
8--
9-- One of most commonly-asked questions about this package is whether
10-- it provides lenses for working with 'Data.Map.Map'. It does, but their uses
11-- are perhaps obscured by their genericity. This module exists to provide
12-- documentation for them.
13--
14-- 'Data.Map.Map' is an instance of 'Control.Lens.At.At', so we have a lenses
15-- on values at keys:
16--
17-- >>> Map.fromList [(1, "world")] ^.at 1
18-- Just "world"
19--
20-- >>> at 1 .~ Just "world" $ Map.empty
21-- fromList [(1,"world")]
22--
23-- >>> at 0 ?~ "hello" $ Map.empty
24-- fromList [(0,"hello")]
25--
26-- We can traverse, fold over, and map over key-value pairs in a
27-- 'Data.Map.Map', thanks to its 'Control.Lens.Indexed.TraversableWithIndex',
28-- 'Control.Lens.Indexed.FoldableWithIndex', and
29-- 'Control.Lens.Indexed.FunctorWithIndex' instances.
30--
31-- >>> imap const $ Map.fromList [(1, "Venus")]
32-- fromList [(1,1)]
33--
34-- >>> ifoldMap (\i _ -> Sum i) $ Map.fromList [(2, "Earth"), (3, "Mars")]
35-- Sum {getSum = 5}
36--
37-- >>> itraverse_ (curry print) $ Map.fromList [(4, "Jupiter")]
38-- (4,"Jupiter")
39--
40-- >>> itoList $ Map.fromList [(5, "Saturn")]
41-- [(5,"Saturn")]
42--
43-- A related class, 'Control.Lens.At.Ixed', allows us to use
44-- 'Control.Lens.At.ix' to traverse a value at a particular key.
45--
46-- >>> ix 2 %~ ("New " ++) $ Map.fromList [(2, "Earth")]
47-- fromList [(2,"New Earth")]
48--
49-- >>> preview (ix 8) $ Map.empty
50-- Nothing
51--
52-- Additionally, 'Data.Map.Map' has 'Control.Lens.Traversal.TraverseMin' and
53-- 'Control.Lens.Traversal.TraverseMax' instances, which let us traverse over
54-- the value at the least and greatest keys, respectively.
55--
56-- >>> preview traverseMin $ Map.fromList [(5, "Saturn"), (6, "Uranus")]
57-- Just "Saturn"
58--
59-- >>> preview traverseMax $ Map.fromList [(5, "Saturn"), (6, "Uranus")]
60-- Just "Uranus"
61--
62-----------------------------------------------------------------------------
63module Data.Map.Lens
64  ( toMapOf
65  ) where
66
67import Control.Lens.Getter ( IndexedGetting, iviews )
68import qualified Data.Map as Map
69
70-- $setup
71-- >>> import Control.Lens
72-- >>> import Data.Monoid
73-- >>> :set -XNoOverloadedStrings
74
75-- | Construct a map from a 'IndexedGetter', 'Control.Lens.Fold.IndexedFold', 'Control.Lens.Traversal.IndexedTraversal' or 'Control.Lens.Lens.IndexedLens'
76--
77-- The construction is left-biased (see 'Data.Map.Lazy.union'), i.e. the first
78-- occurrences of keys in the fold or traversal order are preferred.
79--
80-- >>> toMapOf folded ["hello", "world"]
81-- fromList [(0,"hello"),(1,"world")]
82--
83-- >>> toMapOf (folded . ifolded) [('a',"alpha"),('b', "beta")]
84-- fromList [('a',"alpha"),('b',"beta")]
85--
86-- >>> toMapOf (folded <.> folded) ["foo", "bar"]
87-- fromList [((0,0),'f'),((0,1),'o'),((0,2),'o'),((1,0),'b'),((1,1),'a'),((1,2),'r')]
88--
89-- >>> toMapOf ifolded $ Map.fromList [('a', "hello"), ('b', "world")]
90-- fromList [('a',"hello"),('b',"world")]
91--
92-- @
93-- 'toMapOf' ::          'IndexedGetter' i s a     -> s -> 'Map.Map' i a
94-- 'toMapOf' :: 'Ord' i => 'IndexedFold' i s a       -> s -> 'Map.Map' i a
95-- 'toMapOf' ::          'IndexedLens'' i s a      -> s -> 'Map.Map' i a
96-- 'toMapOf' :: 'Ord' i => 'IndexedTraversal'' i s a -> s -> 'Map.Map' i a
97-- @
98toMapOf :: IndexedGetting i (Map.Map i a) s a -> s -> Map.Map i a
99toMapOf l = iviews l Map.singleton
100