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