|
14 | 14 | |
15 | 15 | -- Portability : portable |
16 | 16 | -- |
| 17 | +-- |
| 18 | +-- = Finite Maps (lazy interface) |
| 19 | +-- |
| 20 | +-- This module re-exports the value lazy "Data.Map.Lazy" API. |
| 21 | +-- |
17 | 22 | -- The @'Map' k v@ type represents a finite map (sometimes called a dictionary) |
18 | 23 | -- from keys of type @k@ to values of type @v@. A 'Map' is strict in its keys but lazy |
19 | 24 | -- in its values. |
20 | 25 | -- |
21 | | --- This module re-exports the value lazy "Data.Map.Lazy" API. |
| 26 | +-- The functions in "Data.Map.Strict" are careful to force values before |
| 27 | +-- installing them in a 'Map'. This is usually more efficient in cases where |
| 28 | +-- laziness is not essential. The functions in this module do not do so. |
| 29 | +-- |
| 30 | +-- When deciding if this is the correct data structure to use, consider: |
| 31 | +-- |
| 32 | +-- * If you are using 'Prelude.Int' keys, you will get much better performance for most |
| 33 | +-- operations using "Data.IntMap.Lazy". |
| 34 | +-- |
| 35 | +-- * If you don't care about ordering, consider using @Data.HashMap.Lazy@ from the |
| 36 | +-- <https://hackage.haskell.org/package/unordered-containers unordered-containers> |
| 37 | +-- package instead. |
| 38 | +-- |
| 39 | +-- For a walkthrough of the most commonly used functions see the |
| 40 | +-- <https://haskell-containers.readthedocs.io/en/latest/map.html maps introduction>. |
22 | 41 | -- |
23 | | --- This module is intended to be imported qualified, to avoid name |
24 | | --- clashes with Prelude functions, e.g. |
| 42 | +-- This module is intended to be imported qualified, to avoid name clashes with |
| 43 | +-- Prelude functions, e.g. |
25 | 44 | -- |
26 | | --- > import qualified Data.Map as Map |
| 45 | +-- > import Data.Map (Map) |
| 46 | +-- > import qualified Data.Map as Map |
| 47 | +-- |
| 48 | +-- Note that the implementation is generally /left-biased/. Functions that take |
| 49 | +-- two maps as arguments and combine them, such as `union` and `intersection`, |
| 50 | +-- prefer the values in the first argument to those in the second. |
| 51 | +-- |
| 52 | +-- |
| 53 | +-- == Warning |
| 54 | +-- |
| 55 | +-- The size of a 'Map' must not exceed @'Prelude.maxBound' :: 'Prelude.Int'@. |
| 56 | +-- Violation of this condition is not detected and if the size limit is exceeded, |
| 57 | +-- its behaviour is undefined. |
| 58 | +-- |
| 59 | +-- |
| 60 | +-- == Implementation |
27 | 61 | -- |
28 | 62 | -- The implementation of 'Map' is based on /size balanced/ binary trees (or |
29 | 63 | -- trees of /bounded balance/) as described by: |
|
48 | 82 | -- \"/Parallel Ordered Sets Using Join/\", |
49 | 83 | -- <https://arxiv.org/abs/1602.02120v4>. |
50 | 84 | -- |
51 | | --- Note that the implementation is /left-biased/ -- the elements of a |
52 | | --- first argument are always preferred to the second, for example in |
53 | | --- 'union' or 'insert'. |
54 | 85 | -- |
55 | | --- /Warning/: The size of the map must not exceed @maxBound::Int@. Violation of |
56 | | --- this condition is not detected and if the size limit is exceeded, its |
57 | | --- behaviour is undefined. |
| 86 | +-- == Performance information |
| 87 | +-- |
| 88 | +-- The time complexity is given for each operation in |
| 89 | +-- [big-O notation](http://en.wikipedia.org/wiki/Big_O_notation), with \(n\) |
| 90 | +-- referring to the number of entries in the map. |
| 91 | +-- |
| 92 | +-- Operations like 'lookup', 'insert', and 'delete' take \(O(\log n)\) time. |
| 93 | +-- |
| 94 | +-- Binary set operations like 'union' and 'intersection' take |
| 95 | +-- \(O\bigl(m \log\bigl(\frac{n}{m}+1\bigr)\bigr)\) time, where \(m\) and \(n\) |
| 96 | +-- are the sizes of the smaller and larger input maps respectively. |
58 | 97 | -- |
59 | | --- Operation comments contain the operation time complexity in |
60 | | --- the Big-O notation (<http://en.wikipedia.org/wiki/Big_O_notation>). |
61 | 98 | ----------------------------------------------------------------------------- |
62 | 99 |
|
63 | 100 | module Data.Map |
|
0 commit comments