diff --git a/containers/src/Data/IntMap.hs b/containers/src/Data/IntMap.hs index 44613cc64..32b93dcfb 100644 --- a/containers/src/Data/IntMap.hs +++ b/containers/src/Data/IntMap.hs @@ -14,16 +14,30 @@ -- Maintainer : libraries@haskell.org -- Portability : portable -- --- The @'IntMap' v@ type represents a finite map (sometimes called a dictionary) --- from key of type @Int@ to values of type @v@. +-- +-- = Finite Int Maps (lazy interface) -- -- This module re-exports the value lazy "Data.IntMap.Lazy" API. -- --- This module is intended to be imported qualified, to avoid name --- clashes with Prelude functions, e.g. +-- The @'IntMap' v@ type represents a finite map (sometimes called a dictionary) +-- from keys of type @Int@ to values of type @v@. +-- +-- The functions in "Data.IntMap.Strict" are careful to force values before +-- installing them in an 'IntMap'. This is usually more efficient in cases where +-- laziness is not essential. The functions in this module do not do so. -- --- > import Data.IntMap (IntMap) --- > import qualified Data.IntMap as IntMap +-- For a walkthrough of the most commonly used functions see the +-- . +-- +-- This module is intended to be imported qualified, to avoid name clashes with +-- Prelude functions, e.g. +-- +-- > import Data.IntMap.Lazy (IntMap) +-- > import qualified Data.IntMap.Lazy as IntMap +-- +-- Note that the implementation is generally /left-biased/. Functions that take +-- two maps as arguments and combine them, such as `union` and `intersection`, +-- prefer the values in the first argument to those in the second. -- -- -- == Implementation @@ -52,11 +66,11 @@ -- referring to the number of entries in the map and \(W\) referring to the -- number of bits in an 'Int' (32 or 64). -- --- Many operations have a worst-case complexity of \(O(\min(n,W))\). --- This means that the operation can become linear in the number of --- elements with a maximum of \(W\) -- the number of bits in an 'Int' --- (32 or 64). These peculiar asymptotics are determined by the depth --- of the Patricia trees: +-- Operations like 'lookup', 'insert', and 'delete' have a worst-case +-- complexity of \(O(\min(n,W))\). This means that the operation can become +-- linear in the number of elements with a maximum of \(W\) -- the number of +-- bits in an 'Int' (32 or 64). These peculiar asymptotics are determined by the +-- depth of the Patricia trees: -- -- * even for an extremely unbalanced tree, the depth cannot be larger than -- the number of elements \(n\), @@ -74,6 +88,10 @@ -- The worst scenario are exponentially growing keys \(1,2,4,\ldots,2^n\), -- for which complexity grows as fast as \(n\) but again is capped by \(W\). -- +-- Binary set operations like 'union' and 'intersection' take +-- \(O(\min(n, m \log \frac{2^W}{m}))\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input maps respectively. +-- ----------------------------------------------------------------------------- module Data.IntMap diff --git a/containers/src/Data/IntMap/Internal.hs b/containers/src/Data/IntMap/Internal.hs index 3cd3c4a8e..cada7ea70 100644 --- a/containers/src/Data/IntMap/Internal.hs +++ b/containers/src/Data/IntMap/Internal.hs @@ -37,10 +37,30 @@ -- Authors importing this module are expected to track development -- closely. -- --- = Description -- --- This defines the data structures and core (hidden) manipulations --- on representations. +-- = Finite Int Maps (lazy interface internals) +-- +-- The @'IntMap' v@ type represents a finite map (sometimes called a dictionary) +-- from keys of type @Int@ to values of type @v@. +-- +-- +-- == Implementation +-- +-- The implementation is based on /big-endian patricia trees/. This data +-- structure performs especially well on binary operations like 'union' +-- and 'intersection'. Additionally, benchmarks show that it is also +-- (much) faster on insertions and deletions when compared to a generic +-- size-balanced map implementation (see "Data.Map"). +-- +-- * Chris Okasaki and Andy Gill, +-- \"/Fast Mergeable Integer Maps/\", +-- Workshop on ML, September 1998, pages 77-86, +-- . +-- +-- * D.R. Morrison, +-- \"/PATRICIA -- Practical Algorithm To Retrieve Information Coded In Alphanumeric/\", +-- Journal of the ACM, 15(4), October 1968, pages 514-534, +-- . -- -- @since 0.5.9 ----------------------------------------------------------------------------- diff --git a/containers/src/Data/IntMap/Lazy.hs b/containers/src/Data/IntMap/Lazy.hs index 3bb4d7df3..fedcb44d8 100644 --- a/containers/src/Data/IntMap/Lazy.hs +++ b/containers/src/Data/IntMap/Lazy.hs @@ -28,7 +28,7 @@ -- . -- -- This module is intended to be imported qualified, to avoid name clashes with --- Prelude functions: +-- Prelude functions, e.g. -- -- > import Data.IntMap.Lazy (IntMap) -- > import qualified Data.IntMap.Lazy as IntMap @@ -64,11 +64,11 @@ -- referring to the number of entries in the map and \(W\) referring to the -- number of bits in an 'Int' (32 or 64). -- --- Many operations have a worst-case complexity of \(O(\min(n,W))\). --- This means that the operation can become linear in the number of --- elements with a maximum of \(W\) -- the number of bits in an 'Int' --- (32 or 64). These peculiar asymptotics are determined by the depth --- of the Patricia trees: +-- Operations like 'lookup', 'insert', and 'delete' have a worst-case +-- complexity of \(O(\min(n,W))\). This means that the operation can become +-- linear in the number of elements with a maximum of \(W\) -- the number of +-- bits in an 'Int' (32 or 64). These peculiar asymptotics are determined by the +-- depth of the Patricia trees: -- -- * even for an extremely unbalanced tree, the depth cannot be larger than -- the number of elements \(n\), @@ -86,6 +86,10 @@ -- The worst scenario are exponentially growing keys \(1,2,4,\ldots,2^n\), -- for which complexity grows as fast as \(n\) but again is capped by \(W\). -- +-- Binary set operations like 'union' and 'intersection' take +-- \(O(\min(n, m \log \frac{2^W}{m}))\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input maps respectively. +-- -- Benchmarks comparing "Data.IntMap.Lazy" with other dictionary -- implementations can be found at https://github.com/haskell-perf/dictionaries. -- diff --git a/containers/src/Data/IntMap/Strict.hs b/containers/src/Data/IntMap/Strict.hs index edac09997..d708365b5 100644 --- a/containers/src/Data/IntMap/Strict.hs +++ b/containers/src/Data/IntMap/Strict.hs @@ -35,7 +35,7 @@ -- . -- -- This module is intended to be imported qualified, to avoid name clashes with --- Prelude functions: +-- Prelude functions, e.g. -- -- > import Data.IntMap.Strict (IntMap) -- > import qualified Data.IntMap.Strict as IntMap @@ -80,11 +80,11 @@ -- referring to the number of entries in the map and \(W\) referring to the -- number of bits in an 'Int' (32 or 64). -- --- Many operations have a worst-case complexity of \(O(\min(n,W))\). --- This means that the operation can become linear in the number of --- elements with a maximum of \(W\) -- the number of bits in an 'Int' --- (32 or 64). These peculiar asymptotics are determined by the depth --- of the Patricia trees: +-- Operations like 'lookup', 'insert', and 'delete' have a worst-case +-- complexity of \(O(\min(n,W))\). This means that the operation can become +-- linear in the number of elements with a maximum of \(W\) -- the number of +-- bits in an 'Int' (32 or 64). These peculiar asymptotics are determined by the +-- depth of the Patricia trees: -- -- * even for an extremely unbalanced tree, the depth cannot be larger than -- the number of elements \(n\), @@ -102,6 +102,10 @@ -- The worst scenario are exponentially growing keys \(1,2,4,\ldots,2^n\), -- for which complexity grows as fast as \(n\) but again is capped by \(W\). -- +-- Binary set operations like 'union' and 'intersection' take +-- \(O(\min(n, m \log \frac{2^W}{m}))\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input maps respectively. +-- -- Benchmarks comparing "Data.IntMap.Strict" with other dictionary -- implementations can be found at https://github.com/haskell-perf/dictionaries. -- diff --git a/containers/src/Data/IntMap/Strict/Internal.hs b/containers/src/Data/IntMap/Strict/Internal.hs index d17c26478..4beb84a6f 100644 --- a/containers/src/Data/IntMap/Strict/Internal.hs +++ b/containers/src/Data/IntMap/Strict/Internal.hs @@ -28,44 +28,11 @@ -- closely. -- -- --- = Description +-- = Finite Int Maps (strict interface internals) -- -- The @'IntMap' v@ type represents a finite map (sometimes called a dictionary) -- from key of type @Int@ to values of type @v@. -- --- Each function in this module is careful to force values before installing --- them in an 'IntMap'. This is usually more efficient when laziness is not --- necessary. When laziness /is/ required, use the functions in --- "Data.IntMap.Lazy". --- --- In particular, the functions in this module obey the following law: --- --- - If all values stored in all maps in the arguments are in WHNF, then all --- values stored in all maps in the results will be in WHNF once those maps --- are evaluated. --- --- For a walkthrough of the most commonly used functions see the --- . --- --- This module is intended to be imported qualified, to avoid name clashes with --- Prelude functions: --- --- > import Data.IntMap.Strict (IntMap) --- > import qualified Data.IntMap.Strict as IntMap --- --- Note that the implementation is generally /left-biased/. Functions that take --- two maps as arguments and combine them, such as `union` and `intersection`, --- prefer the values in the first argument to those in the second. --- --- --- == Warning --- --- The 'IntMap' type is shared between the lazy and strict modules, meaning that --- the same 'IntMap' value can be passed to functions in both modules. This --- means that the 'Functor', 'Traversable' and 'Data.Data.Data' instances are --- the same as for the "Data.IntMap.Lazy" module, so if they are used the --- resulting map may contain suspended values (thunks). --- -- -- == Implementation -- diff --git a/containers/src/Data/IntSet.hs b/containers/src/Data/IntSet.hs index c35dc3332..2e0c12b31 100644 --- a/containers/src/Data/IntSet.hs +++ b/containers/src/Data/IntSet.hs @@ -34,7 +34,7 @@ -- -- The implementation is based on /big-endian patricia trees/. This data -- structure performs especially well on binary operations like 'union' --- and 'intersection'. However, my benchmarks show that it is also +-- and 'intersection'. Additionally, benchmarks show that it is also -- (much) faster on insertions and deletions when compared to a generic -- size-balanced set implementation (see "Data.Set"). -- @@ -57,16 +57,16 @@ -- -- == Performance information -- --- Operation comments contain the operation time complexity in +-- The time complexity is given for each operation in -- [big-O notation](http://en.wikipedia.org/wiki/Big_O_notation), with \(n\) -- referring to the number of entries in the map and \(W\) referring to the -- number of bits in an 'Int' (32 or 64). -- --- Many operations have a worst-case complexity of \(O(\min(n,W))\). --- This means that the operation can become linear in the number of --- elements with a maximum of \(W\) -- the number of bits in an 'Int' --- (32 or 64). These peculiar asymptotics are determined by the depth --- of the Patricia trees: +-- Operations like 'member', 'insert', and 'delete' have a worst-case +-- complexity of \(O(\min(n,W))\). This means that the operation can become +-- linear in the number of elements with a maximum of \(W\) -- the number of +-- bits in an 'Int' (32 or 64). These peculiar asymptotics are determined by the +-- depth of the Patricia trees: -- -- * even for an extremely unbalanced tree, the depth cannot be larger than -- the number of elements \(n\), @@ -79,10 +79,15 @@ -- the set is sufficiently "dense", this becomes \(O(\min(n, \log n))\) or -- simply the familiar \(O(\log n)\), matching balanced binary trees. -- --- The most performant scenario for 'IntSet' are keys from a contiguous subset, --- in which case the complexity is proportional to \(\log n\), capped by \(W\). --- The worst scenario are exponentially growing elements \(1,2,4,\ldots,2^n\), --- for which complexity grows as fast as \(n\) but again is capped by \(W\). +-- The most performant scenario for 'IntSet' are elements from a contiguous +-- subset, in which case the complexity is proportional to \(\log n\), capped +-- by \(W\). The worst scenario are exponentially growing elements \(1,2,4, +-- \ldots,2^n\), for which complexity grows as fast as \(n\) but again is capped +-- by \(W\). +-- +-- Binary set operations like 'union' and 'intersection' take +-- \(O(\min(n, m \log \frac{2^W}{m}))\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input sets respectively. -- ----------------------------------------------------------------------------- diff --git a/containers/src/Data/IntSet/Internal.hs b/containers/src/Data/IntSet/Internal.hs index ca4a558fa..cc6f7f13b 100644 --- a/containers/src/Data/IntSet/Internal.hs +++ b/containers/src/Data/IntSet/Internal.hs @@ -34,22 +34,18 @@ -- Authors importing this module are expected to track development -- closely. -- --- = Description -- --- An efficient implementation of integer sets. +-- = Finite Int Sets (internals) -- --- These modules are intended to be imported qualified, to avoid name --- clashes with Prelude functions, e.g. --- --- > import Data.IntSet (IntSet) --- > import qualified Data.IntSet as IntSet +-- The @'IntSet'@ type represents a set of elements of type @Int@. An @IntSet@ +-- is strict in its elements. -- -- -- == Implementation -- -- The implementation is based on /big-endian patricia trees/. This data -- structure performs especially well on binary operations like 'union' --- and 'intersection'. However, my benchmarks show that it is also +-- and 'intersection'. Additionally, benchmarks show that it is also -- (much) faster on insertions and deletions when compared to a generic -- size-balanced set implementation (see "Data.Set"). -- diff --git a/containers/src/Data/Map.hs b/containers/src/Data/Map.hs index 67feef361..12dff75fa 100644 --- a/containers/src/Data/Map.hs +++ b/containers/src/Data/Map.hs @@ -14,16 +14,50 @@ -- Maintainer : libraries@haskell.org -- Portability : portable -- +-- +-- = Finite Maps (lazy interface) +-- +-- This module re-exports the value lazy "Data.Map.Lazy" API. +-- -- The @'Map' k v@ type represents a finite map (sometimes called a dictionary) -- from keys of type @k@ to values of type @v@. A 'Map' is strict in its keys but lazy -- in its values. -- --- This module re-exports the value lazy "Data.Map.Lazy" API. +-- The functions in "Data.Map.Strict" are careful to force values before +-- installing them in a 'Map'. This is usually more efficient in cases where +-- laziness is not essential. The functions in this module do not do so. +-- +-- When deciding if this is the correct data structure to use, consider: +-- +-- * If you are using 'Prelude.Int' keys, you will get much better performance for most +-- operations using "Data.IntMap.Lazy". +-- +-- * If you don't care about ordering, consider using @Data.HashMap.Lazy@ from the +-- +-- package instead. +-- +-- For a walkthrough of the most commonly used functions see the +-- . -- --- This module is intended to be imported qualified, to avoid name --- clashes with Prelude functions, e.g. +-- This module is intended to be imported qualified, to avoid name clashes with +-- Prelude functions, e.g. -- --- > import qualified Data.Map as Map +-- > import Data.Map (Map) +-- > import qualified Data.Map as Map +-- +-- Note that the implementation is generally /left-biased/. Functions that take +-- two maps as arguments and combine them, such as `union` and `intersection`, +-- prefer the values in the first argument to those in the second. +-- +-- +-- == Warning +-- +-- The size of a 'Map' must not exceed @'Prelude.maxBound' :: 'Prelude.Int'@. +-- Violation of this condition is not detected and if the size limit is exceeded, +-- its behaviour is undefined. +-- +-- +-- == Implementation -- -- The implementation of 'Map' is based on /size balanced/ binary trees (or -- trees of /bounded balance/) as described by: @@ -48,16 +82,19 @@ -- \"/Parallel Ordered Sets Using Join/\", -- . -- --- Note that the implementation is /left-biased/ -- the elements of a --- first argument are always preferred to the second, for example in --- 'union' or 'insert'. -- --- /Warning/: The size of the map must not exceed @maxBound::Int@. Violation of --- this condition is not detected and if the size limit is exceeded, its --- behaviour is undefined. +-- == Performance information +-- +-- The time complexity is given for each operation in +-- [big-O notation](http://en.wikipedia.org/wiki/Big_O_notation), with \(n\) +-- referring to the number of entries in the map. +-- +-- Operations like 'lookup', 'insert', and 'delete' take \(O(\log n)\) time. +-- +-- Binary set operations like 'union' and 'intersection' take +-- \(O\bigl(m \log\bigl(\frac{n}{m}+1\bigr)\bigr)\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input maps respectively. -- --- Operation comments contain the operation time complexity in --- the Big-O notation (). ----------------------------------------------------------------------------- module Data.Map diff --git a/containers/src/Data/Map/Internal.hs b/containers/src/Data/Map/Internal.hs index 1c2616738..8ddfac03a 100644 --- a/containers/src/Data/Map/Internal.hs +++ b/containers/src/Data/Map/Internal.hs @@ -43,15 +43,15 @@ -- Authors importing this module are expected to track development -- closely. -- --- = Description -- --- An efficient implementation of maps from keys to values (dictionaries). +-- = Finite Maps (lazy interface internals) -- --- Since many function names (but not the type name) clash with --- "Prelude" names, this module is usually imported @qualified@, e.g. +-- The @'Map' k v@ type represents a finite map (sometimes called a dictionary) +-- from keys of type @k@ to values of type @v@. A 'Map' is strict in its keys +-- but lazy in its values. -- --- > import Data.Map (Map) --- > import qualified Data.Map as Map +-- +-- == Implementation -- -- The implementation of 'Map' is based on /size balanced/ binary trees (or -- trees of /bounded balance/) as described by: @@ -76,12 +76,6 @@ -- \"/Parallel Ordered Sets Using Join/\", -- . -- --- Note that the implementation is /left-biased/ -- the elements of a --- first argument are always preferred to the second, for example in --- 'union' or 'insert'. --- --- Operation comments contain the operation time complexity in --- the Big-O notation . -- -- @since 0.5.9 ----------------------------------------------------------------------------- diff --git a/containers/src/Data/Map/Lazy.hs b/containers/src/Data/Map/Lazy.hs index d32c5a83b..7ae61c77d 100644 --- a/containers/src/Data/Map/Lazy.hs +++ b/containers/src/Data/Map/Lazy.hs @@ -38,8 +38,9 @@ -- . -- -- This module is intended to be imported qualified, to avoid name clashes with --- Prelude functions: +-- Prelude functions, e.g. -- +-- > import Data.Map.Lazy (Map) -- > import qualified Data.Map.Lazy as Map -- -- Note that the implementation is generally /left-biased/. Functions that take @@ -47,15 +48,6 @@ -- prefer the values in the first argument to those in the second. -- -- --- == Detailed performance information --- --- The running time is given for each operation, with \(n\) referring to --- the number of entries in the map. --- --- Benchmarks comparing "Data.Map.Lazy" with other dictionary implementations --- can be found at https://github.com/haskell-perf/dictionaries. --- --- -- == Warning -- -- The size of a 'Map' must not exceed @'Prelude.maxBound' :: 'Prelude.Int'@. @@ -88,6 +80,22 @@ -- \"/Parallel Ordered Sets Using Join/\", -- . -- +-- +-- == Performance information +-- +-- The time complexity is given for each operation in +-- [big-O notation](http://en.wikipedia.org/wiki/Big_O_notation), with \(n\) +-- referring to the number of entries in the map. +-- +-- Operations like 'lookup', 'insert', and 'delete' take \(O(\log n)\) time. +-- +-- Binary set operations like 'union' and 'intersection' take +-- \(O\bigl(m \log\bigl(\frac{n}{m}+1\bigr)\bigr)\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input maps respectively. +-- +-- Benchmarks comparing "Data.Map.Lazy" with other dictionary implementations +-- can be found at https://github.com/haskell-perf/dictionaries. +-- ----------------------------------------------------------------------------- module Data.Map.Lazy ( diff --git a/containers/src/Data/Map/Strict.hs b/containers/src/Data/Map/Strict.hs index d1d1b6cba..9eabf20c8 100644 --- a/containers/src/Data/Map/Strict.hs +++ b/containers/src/Data/Map/Strict.hs @@ -43,8 +43,9 @@ -- . -- -- This module is intended to be imported qualified, to avoid name clashes with --- Prelude functions: +-- Prelude functions, e.g. -- +-- > import Data.Map.Strict (Map) -- > import qualified Data.Map.Strict as Map -- -- Note that the implementation is generally /left-biased/. Functions that take @@ -52,15 +53,6 @@ -- prefer the values in the first argument to those in the second. -- -- --- == Detailed performance information --- --- The running time is given for each operation, with \(n\) referring to --- the number of entries in the map. --- --- Benchmarks comparing "Data.Map.Strict" with other dictionary implementations --- can be found at https://github.com/haskell-perf/dictionaries. --- --- -- == Warning -- -- The size of a 'Map' must not exceed @maxBound::Int@. Violation of this @@ -100,6 +92,21 @@ -- . -- -- +-- == Performance information +-- +-- The time complexity is given for each operation in +-- [big-O notation](http://en.wikipedia.org/wiki/Big_O_notation), with \(n\) +-- referring to the number of entries in the map. +-- +-- Operations like 'lookup', 'insert', and 'delete' take \(O(\log n)\) time. +-- +-- Binary set operations like 'union' and 'intersection' take +-- \(O\bigl(m \log\bigl(\frac{n}{m}+1\bigr)\bigr)\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input maps respectively. +-- +-- Benchmarks comparing "Data.Map.Strict" with other dictionary implementations +-- can be found at https://github.com/haskell-perf/dictionaries. +-- ----------------------------------------------------------------------------- -- See the notes at the beginning of Data.Map.Internal. diff --git a/containers/src/Data/Map/Strict/Internal.hs b/containers/src/Data/Map/Strict/Internal.hs index 34272bf7e..0a23bd987 100644 --- a/containers/src/Data/Map/Strict/Internal.hs +++ b/containers/src/Data/Map/Strict/Internal.hs @@ -28,21 +28,14 @@ -- Authors importing this module are expected to track development -- closely. -- --- = Description -- --- An efficient implementation of ordered maps from keys to values --- (dictionaries). +-- = Finite Maps (strict interface internals) -- --- API of this module is strict in both the keys and the values. --- If you need value-lazy maps, use "Data.Map.Lazy" instead. --- The 'Map' type is shared between the lazy and strict modules, --- meaning that the same 'Map' value can be passed to functions in --- both modules (although that is rarely needed). +-- The @'Map' k v@ type represents a finite map (sometimes called a dictionary) +-- from keys of type @k@ to values of type @v@. -- --- These modules are intended to be imported qualified, to avoid name --- clashes with Prelude functions, e.g. -- --- > import qualified Data.Map.Strict as Map +-- == Implementation -- -- The implementation of 'Map' is based on /size balanced/ binary trees (or -- trees of /bounded balance/) as described by: @@ -67,29 +60,12 @@ -- \"/Parallel Ordered Sets Using Join/\", -- . -- --- Note that the implementation is /left-biased/ -- the elements of a --- first argument are always preferred to the second, for example in --- 'union' or 'insert'. --- --- /Warning/: The size of the map must not exceed @maxBound::Int@. Violation of --- this condition is not detected and if the size limit is exceeded, its --- behaviour is undefined. --- --- Operation comments contain the operation time complexity in --- the Big-O notation (). --- --- Be aware that the 'Functor', 'Traversable' and 'Data.Data.Data' instances --- are the same as for the "Data.Map.Lazy" module, so if they are used --- on strict maps, the resulting maps will be lazy. ----------------------------------------------------------------------------- -- See the notes at the beginning of Data.Map.Internal. module Data.Map.Strict.Internal ( - -- * Strictness properties - -- $strictness - -- * Map type Map(..) -- instance Eq,Show,Read , L.Size @@ -449,24 +425,6 @@ import Data.Functor.Identity (Identity (..)) import qualified Data.Foldable as Foldable --- $strictness --- --- This module satisfies the following strictness properties: --- --- 1. Key arguments are evaluated to WHNF; --- --- 2. Keys and values are evaluated to WHNF before they are stored in --- the map. --- --- Here's an example illustrating the first property: --- --- > delete undefined m == undefined --- --- Here are some examples that illustrate the second property: --- --- > map (\ v -> undefined) m == undefined -- m is not empty --- > mapKeys (\ k -> undefined) m == undefined -- m is not empty - -- [Note: Pointer equality for sharing] -- -- We use pointer equality to enhance sharing between the arguments diff --git a/containers/src/Data/Sequence/Internal.hs b/containers/src/Data/Sequence/Internal.hs index da8a8abb4..9fa069c6a 100644 --- a/containers/src/Data/Sequence/Internal.hs +++ b/containers/src/Data/Sequence/Internal.hs @@ -47,16 +47,13 @@ -- Authors importing this module are expected to track development -- closely. -- --- = Description -- --- General purpose finite sequences. --- Apart from being finite and having strict operations, sequences --- also differ from lists in supporting a wider variety of operations --- efficiently. +-- = Finite sequences (internals) -- --- An amortized running time is given for each operation, with \( n \) referring --- to the length of the sequence and \( i \) being the integral index used by --- some operations. These bounds hold even in a persistent (shared) setting. +-- The @'Seq' a@ type represents a finite sequence of values of type @a@. +-- +-- +-- == Implementation -- -- The implementation uses 2-3 finger trees annotated with sizes, -- as described in section 4.2 of @@ -66,17 +63,6 @@ -- Journal of Functional Programming 16:2 (2006) pp 197-217. -- . -- --- /Note/: Many of these operations have the same names as similar --- operations on lists in the "Prelude". The ambiguity may be resolved --- using either qualification or the @hiding@ clause. --- --- /Warning/: The size of a 'Seq' must not exceed @maxBound::Int@. Violation --- of this condition is not detected and if the size limit is exceeded, the --- behaviour of the sequence is undefined. This is unlikely to occur in most --- applications, but some care may be required when using '><', '<*>', '*>', or --- '>>', particularly repeatedly and particularly in combination with --- 'replicate' or 'fromFunction'. --- -- @since 0.5.9 ----------------------------------------------------------------------------- diff --git a/containers/src/Data/Set.hs b/containers/src/Data/Set.hs index a4847d2e9..64a03840f 100644 --- a/containers/src/Data/Set.hs +++ b/containers/src/Data/Set.hs @@ -23,18 +23,18 @@ -- For a walkthrough of the most commonly used functions see the -- . -- +-- This module is intended to be imported qualified, to avoid name clashes with +-- Prelude functions, e.g. +-- +-- > import Data.Set (Set) +-- > import qualified Data.Set as Set +-- -- Note that the implementation is generally /left-biased/. Functions that take -- two sets as arguments and combine them, such as `union` and `intersection`, -- prefer the entries in the first argument to those in the second. Of course, -- this bias can only be observed when equality is an equivalence relation -- instead of structural equality. -- --- These modules are intended to be imported qualified, to avoid name --- clashes with Prelude functions, e.g. --- --- > import Data.Set (Set) --- > import qualified Data.Set as Set --- -- -- == Warning -- @@ -68,6 +68,19 @@ -- \"/Parallel Ordered Sets Using Join/\", -- . -- +-- +-- == Performance information +-- +-- The time complexity is given for each operation in +-- [big-O notation](http://en.wikipedia.org/wiki/Big_O_notation), with \(n\) +-- referring to the number of entries in the set. +-- +-- Operations like 'member', 'insert', and 'delete' take \(O(\log n)\) time. +-- +-- Binary set operations like 'union' and 'intersection' take +-- \(O\bigl(m \log\bigl(\frac{n}{m}+1\bigr)\bigr)\) time, where \(m\) and \(n\) +-- are the sizes of the smaller and larger input sets respectively. +-- ----------------------------------------------------------------------------- module Data.Set ( diff --git a/containers/src/Data/Set/Internal.hs b/containers/src/Data/Set/Internal.hs index aa2b5aadb..f4fd36082 100644 --- a/containers/src/Data/Set/Internal.hs +++ b/containers/src/Data/Set/Internal.hs @@ -33,15 +33,15 @@ -- Authors importing this module are expected to track development -- closely. -- --- = Description -- --- An efficient implementation of sets. +-- = Finite Sets (internals) -- --- These modules are intended to be imported qualified, to avoid name --- clashes with Prelude functions, e.g. +-- The @'Set' e@ type represents a set of elements of type @e@. Most operations +-- require that @e@ be an instance of the 'Ord' class. A 'Set' is strict in its +-- elements. -- --- > import Data.Set (Set) --- > import qualified Data.Set as Set +-- +-- == Implementation -- -- The implementation of 'Set' is based on /size balanced/ binary trees (or -- trees of /bounded balance/) as described by: @@ -66,15 +66,6 @@ -- \"/Parallel Ordered Sets Using Join/\", -- . -- --- Note that the implementation is /left-biased/ -- the elements of a --- first argument are always preferred to the second, for example in --- 'union' or 'insert'. Of course, left-biasing can only be observed --- when equality is an equivalence relation instead of structural --- equality. --- --- /Warning/: The size of the set must not exceed @maxBound::Int@. Violation of --- this condition is not detected and if the size limit is exceeded, the --- behavior of the set is completely undefined. -- -- @since 0.5.9 -----------------------------------------------------------------------------