diff --git a/containers-tests/benchmarks/LookupGE/LookupGE_IntMap.hs b/containers-tests/benchmarks/LookupGE/LookupGE_IntMap.hs index ff849b1d2..a6d4e64a4 100644 --- a/containers-tests/benchmarks/LookupGE/LookupGE_IntMap.hs +++ b/containers-tests/benchmarks/LookupGE/LookupGE_IntMap.hs @@ -72,7 +72,7 @@ lookupGE4 k t = k `seq` case t of -- Utilities ------------------------------------------------------------------------------- --- | /O(log n)/. The minimal key of the map. +-- | \(O(\log n)\). The minimal key of the map. findMinMaybe :: IntMap a -> Maybe (Key, a) findMinMaybe m | null m = Nothing diff --git a/containers/src/Data/IntMap.hs b/containers/src/Data/IntMap.hs index 5f6836b44..027d4a573 100644 --- a/containers/src/Data/IntMap.hs +++ b/containers/src/Data/IntMap.hs @@ -50,9 +50,9 @@ -- -- Operation comments contain the operation time complexity in -- the Big-O notation . --- Many operations have a worst-case complexity of /O(min(n,W))/. +-- 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' +-- elements with a maximum of \(W\) -- the number of bits in an 'Int' -- (32 or 64). ----------------------------------------------------------------------------- diff --git a/containers/src/Data/IntMap/Internal.hs b/containers/src/Data/IntMap/Internal.hs index 732765373..2df020ac1 100644 --- a/containers/src/Data/IntMap/Internal.hs +++ b/containers/src/Data/IntMap/Internal.hs @@ -382,7 +382,7 @@ bitmapOf x = shiftLL 1 (x .&. IntSet.suffixBitMask) Operators --------------------------------------------------------------------} --- | /O(min(n,W))/. Find the value at a key. +-- | \(O(\min(n,W))\). Find the value at a key. -- Calls 'error' when the element can not be found. -- -- > fromList [(5,'a'), (3,'b')] ! 1 Error: element not in the map @@ -391,7 +391,7 @@ bitmapOf x = shiftLL 1 (x .&. IntSet.suffixBitMask) (!) :: IntMap a -> Key -> a (!) m k = find k m --- | /O(min(n,W))/. Find the value at a key. +-- | \(O(\min(n,W))\). Find the value at a key. -- Returns 'Nothing' when the element can not be found. -- -- > fromList [(5,'a'), (3,'b')] !? 1 == Nothing @@ -523,7 +523,7 @@ intMapDataType = mkDataType "Data.IntMap.Internal.IntMap" [fromListConstr] {-------------------------------------------------------------------- Query --------------------------------------------------------------------} --- | /O(1)/. Is the map empty? +-- | \(O(1)\). Is the map empty? -- -- > Data.IntMap.null (empty) == True -- > Data.IntMap.null (singleton 1 'a') == False @@ -533,7 +533,7 @@ null Nil = True null _ = False {-# INLINE null #-} --- | /O(n)/. Number of elements in the map. +-- | \(O(n)\). Number of elements in the map. -- -- > size empty == 0 -- > size (singleton 1 'a') == 1 @@ -545,7 +545,7 @@ size = go 0 go acc (Tip _ _) = 1 + acc go acc Nil = acc --- | /O(min(n,W))/. Is the key a member of the map? +-- | \(O(\min(n,W))\). Is the key a member of the map? -- -- > member 5 (fromList [(5,'a'), (3,'b')]) == True -- > member 1 (fromList [(5,'a'), (3,'b')]) == False @@ -560,7 +560,7 @@ member !k = go go (Tip kx _) = k == kx go Nil = False --- | /O(min(n,W))/. Is the key not a member of the map? +-- | \(O(\min(n,W))\). Is the key not a member of the map? -- -- > notMember 5 (fromList [(5,'a'), (3,'b')]) == False -- > notMember 1 (fromList [(5,'a'), (3,'b')]) == True @@ -568,7 +568,7 @@ member !k = go notMember :: Key -> IntMap a -> Bool notMember k m = not $ member k m --- | /O(min(n,W))/. Lookup the value at a key in the map. See also 'Data.Map.lookup'. +-- | \(O(\min(n,W))\). Lookup the value at a key in the map. See also 'Data.Map.lookup'. -- See Note: Local 'go' functions and capturing lookup :: Key -> IntMap a -> Maybe a @@ -592,7 +592,7 @@ find !k = go not_found = error ("IntMap.!: key " ++ show k ++ " is not an element of the map") --- | /O(min(n,W))/. The expression @('findWithDefault' def k map)@ +-- | \(O(\min(n,W))\). The expression @('findWithDefault' def k map)@ -- returns the value at key @k@ or returns @def@ when the key is not an -- element of the map. -- @@ -610,7 +610,7 @@ findWithDefault def !k = go | otherwise = def go Nil = def --- | /O(log n)/. Find largest key smaller than the given one and return the +-- | \(O(\log n)\). Find largest key smaller than the given one and return the -- corresponding (key, value) pair. -- -- > lookupLT 3 (fromList [(3,'a'), (5,'b')]) == Nothing @@ -631,7 +631,7 @@ lookupLT !k t = case t of | otherwise = Just (ky, y) go def Nil = unsafeFindMax def --- | /O(log n)/. Find smallest key greater than the given one and return the +-- | \(O(\log n)\). Find smallest key greater than the given one and return the -- corresponding (key, value) pair. -- -- > lookupGT 4 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b') @@ -652,7 +652,7 @@ lookupGT !k t = case t of | otherwise = Just (ky, y) go def Nil = unsafeFindMin def --- | /O(log n)/. Find largest key smaller or equal to the given one and return +-- | \(O(\log n)\). Find largest key smaller or equal to the given one and return -- the corresponding (key, value) pair. -- -- > lookupLE 2 (fromList [(3,'a'), (5,'b')]) == Nothing @@ -674,7 +674,7 @@ lookupLE !k t = case t of | otherwise = Just (ky, y) go def Nil = unsafeFindMax def --- | /O(log n)/. Find smallest key greater or equal to the given one and return +-- | \(O(\log n)\). Find smallest key greater or equal to the given one and return -- the corresponding (key, value) pair. -- -- > lookupGE 3 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a') @@ -714,7 +714,7 @@ unsafeFindMax (Bin _ _ _ r) = unsafeFindMax r {-------------------------------------------------------------------- Disjoint --------------------------------------------------------------------} --- | /O(n+m)/. Check whether the key sets of two maps are disjoint +-- | \(O(n+m)\). Check whether the key sets of two maps are disjoint -- (i.e. their 'intersection' is empty). -- -- > disjoint (fromList [(2,'a')]) (fromList [(1,()), (3,())]) == True @@ -770,7 +770,7 @@ compose bc !ab {-------------------------------------------------------------------- Construction --------------------------------------------------------------------} --- | /O(1)/. The empty map. +-- | \(O(1)\). The empty map. -- -- > empty == fromList [] -- > size empty == 0 @@ -780,7 +780,7 @@ empty = Nil {-# INLINE empty #-} --- | /O(1)/. A map of one element. +-- | \(O(1)\). A map of one element. -- -- > singleton 1 'a' == fromList [(1, 'a')] -- > size (singleton 1 'a') == 1 @@ -793,7 +793,7 @@ singleton k x {-------------------------------------------------------------------- Insert --------------------------------------------------------------------} --- | /O(min(n,W))/. Insert a new key\/value pair in the map. +-- | \(O(\min(n,W))\). Insert a new key\/value pair in the map. -- If the key is already present in the map, the associated value is -- replaced with the supplied value, i.e. 'insert' is equivalent to -- @'insertWith' 'const'@. @@ -813,7 +813,7 @@ insert k x t@(Tip ky _) insert k x Nil = Tip k x -- right-biased insertion, used by 'union' --- | /O(min(n,W))/. Insert with a combining function. +-- | \(O(\min(n,W))\). Insert with a combining function. -- @'insertWith' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -827,7 +827,7 @@ insertWith :: (a -> a -> a) -> Key -> a -> IntMap a -> IntMap a insertWith f k x t = insertWithKey (\_ x' y' -> f x' y') k x t --- | /O(min(n,W))/. Insert with a combining function. +-- | \(O(\min(n,W))\). Insert with a combining function. -- @'insertWithKey' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -848,7 +848,7 @@ insertWithKey f k x t@(Tip ky y) | otherwise = link k (Tip k x) ky t insertWithKey _ k x Nil = Tip k x --- | /O(min(n,W))/. The expression (@'insertLookupWithKey' f k x map@) +-- | \(O(\min(n,W))\). The expression (@'insertLookupWithKey' f k x map@) -- is a pair where the first element is equal to (@'lookup' k map@) -- and the second element equal to (@'insertWithKey' f k x map@). -- @@ -879,7 +879,7 @@ insertLookupWithKey _ k x Nil = (Nothing,Tip k x) {-------------------------------------------------------------------- Deletion --------------------------------------------------------------------} --- | /O(min(n,W))/. Delete a key and its value from the map. When the key is not +-- | \(O(\min(n,W))\). Delete a key and its value from the map. When the key is not -- a member of the map, the original map is returned. -- -- > delete 5 (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -896,7 +896,7 @@ delete k t@(Tip ky _) | otherwise = t delete _k Nil = Nil --- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not +-- | \(O(\min(n,W))\). Adjust a value at a specific key. When the key is not -- a member of the map, the original map is returned. -- -- > adjust ("new " ++) 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")] @@ -907,7 +907,7 @@ adjust :: (a -> a) -> Key -> IntMap a -> IntMap a adjust f k m = adjustWithKey (\_ x -> f x) k m --- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not +-- | \(O(\min(n,W))\). Adjust a value at a specific key. When the key is not -- a member of the map, the original map is returned. -- -- > let f key x = (show key) ++ ":new " ++ x @@ -925,7 +925,7 @@ adjustWithKey f k t@(Tip ky y) adjustWithKey _ _ Nil = Nil --- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@ +-- | \(O(\min(n,W))\). The expression (@'update' f k map@) updates the value @x@ -- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. -- @@ -938,7 +938,7 @@ update :: (a -> Maybe a) -> Key -> IntMap a -> IntMap a update f = updateWithKey (\_ x -> f x) --- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@ +-- | \(O(\min(n,W))\). The expression (@'update' f k map@) updates the value @x@ -- at @k@ (if it is in the map). If (@f k x@) is 'Nothing', the element is -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. -- @@ -958,7 +958,7 @@ updateWithKey f k t@(Tip ky y) | otherwise = t updateWithKey _ _ Nil = Nil --- | /O(min(n,W))/. Lookup and update. +-- | \(O(\min(n,W))\). Lookup and update. -- The function returns original value, if it is updated. -- This is different behavior than 'Data.Map.updateLookupWithKey'. -- Returns the original key value if the map entry is deleted. @@ -983,7 +983,7 @@ updateLookupWithKey _ _ Nil = (Nothing,Nil) --- | /O(min(n,W))/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. +-- | \(O(\min(n,W))\). The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. -- 'alter' can be used to insert, delete, or update a value in an 'IntMap'. -- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. alter :: (Maybe a -> Maybe a) -> Key -> IntMap a -> IntMap a @@ -1004,7 +1004,7 @@ alter f k Nil = case f Nothing of Just x -> Tip k x Nothing -> Nil --- | /O(log n)/. The expression (@'alterF' f k map@) alters the value @x@ at +-- | \(O(\log n)\). The expression (@'alterF' f k map@) alters the value @x@ at -- @k@, or absence thereof. 'alterF' can be used to inspect, insert, delete, -- or update a value in an 'IntMap'. In short : @'lookup' k <$> 'alterF' f k m = f -- ('lookup' k m)@. @@ -1064,7 +1064,7 @@ unionsWith :: Foldable f => (a->a->a) -> f (IntMap a) -> IntMap a unionsWith f ts = Foldable.foldl' (unionWith f) empty ts --- | /O(n+m)/. The (left-biased) union of two maps. +-- | \(O(n+m)\). The (left-biased) union of two maps. -- It prefers the first map when duplicate keys are encountered, -- i.e. (@'union' == 'unionWith' 'const'@). -- @@ -1074,7 +1074,7 @@ union :: IntMap a -> IntMap a -> IntMap a union m1 m2 = mergeWithKey' Bin const id id m1 m2 --- | /O(n+m)/. The union with a combining function. +-- | \(O(n+m)\). The union with a combining function. -- -- > unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")] @@ -1082,7 +1082,7 @@ unionWith :: (a -> a -> a) -> IntMap a -> IntMap a -> IntMap a unionWith f m1 m2 = unionWithKey (\_ x y -> f x y) m1 m2 --- | /O(n+m)/. The union with a combining function. +-- | \(O(n+m)\). The union with a combining function. -- -- > let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value -- > unionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "5:a|A"), (7, "C")] @@ -1094,7 +1094,7 @@ unionWithKey f m1 m2 {-------------------------------------------------------------------- Difference --------------------------------------------------------------------} --- | /O(n+m)/. Difference between two maps (based on keys). +-- | \(O(n+m)\). Difference between two maps (based on keys). -- -- > difference (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 3 "b" @@ -1102,7 +1102,7 @@ difference :: IntMap a -> IntMap b -> IntMap a difference m1 m2 = mergeWithKey (\_ _ _ -> Nothing) id (const Nil) m1 m2 --- | /O(n+m)/. Difference with a combining function. +-- | \(O(n+m)\). Difference with a combining function. -- -- > let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing -- > differenceWith f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (7, "C")]) @@ -1112,7 +1112,7 @@ differenceWith :: (a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a differenceWith f m1 m2 = differenceWithKey (\_ x y -> f x y) m1 m2 --- | /O(n+m)/. Difference with a combining function. When two equal keys are +-- | \(O(n+m)\). Difference with a combining function. When two equal keys are -- encountered, the combining function is applied to the key and both values. -- If it returns 'Nothing', the element is discarded (proper set difference). -- If it returns (@'Just' y@), the element is updated with a new value @y@. @@ -1127,7 +1127,7 @@ differenceWithKey f m1 m2 -- TODO(wrengr): re-verify that asymptotic bound --- | /O(n+m)/. Remove all the keys in a given set from a map. +-- | \(O(n+m)\). Remove all the keys in a given set from a map. -- -- @ -- m \`withoutKeys\` s = 'filterWithKey' (\k _ -> k ``IntSet.notMember`` s) m @@ -1195,7 +1195,7 @@ withoutBM _ Nil = Nil {-------------------------------------------------------------------- Intersection --------------------------------------------------------------------} --- | /O(n+m)/. The (left-biased) intersection of two maps (based on keys). +-- | \(O(n+m)\). The (left-biased) intersection of two maps (based on keys). -- -- > intersection (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "a" @@ -1205,7 +1205,7 @@ intersection m1 m2 -- TODO(wrengr): re-verify that asymptotic bound --- | /O(n+m)/. The restriction of a map to the keys in a set. +-- | \(O(n+m)\). The restriction of a map to the keys in a set. -- -- @ -- m \`restrictKeys\` s = 'filterWithKey' (\k _ -> k ``IntSet.member`` s) m @@ -1242,7 +1242,7 @@ restrictKeys t1@(Tip k1 _) t2 restrictKeys Nil _ = Nil --- | /O(min(n,W))/. Restrict to the sub-map with all keys matching +-- | \(O(\min(n,W))\). Restrict to the sub-map with all keys matching -- a key prefix. lookupPrefix :: IntSetPrefix -> IntMap a -> IntMap a lookupPrefix !kp t@(Bin p m l r) @@ -1271,7 +1271,7 @@ restrictBM bm t@(Tip k _) restrictBM _ Nil = Nil --- | /O(n+m)/. The intersection with a combining function. +-- | \(O(n+m)\). The intersection with a combining function. -- -- > intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA" @@ -1279,7 +1279,7 @@ intersectionWith :: (a -> b -> c) -> IntMap a -> IntMap b -> IntMap c intersectionWith f m1 m2 = intersectionWithKey (\_ x y -> f x y) m1 m2 --- | /O(n+m)/. The intersection with a combining function. +-- | \(O(n+m)\). The intersection with a combining function. -- -- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar -- > intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A" @@ -1292,7 +1292,7 @@ intersectionWithKey f m1 m2 MergeWithKey --------------------------------------------------------------------} --- | /O(n+m)/. A high-performance universal combining function. Using +-- | \(O(n+m)\). A high-performance universal combining function. Using -- 'mergeWithKey', all combining functions can be defined without any loss of -- efficiency (with exception of 'union', 'difference' and 'intersection', -- where sharing of some nodes is lost with 'mergeWithKey'). @@ -1807,7 +1807,7 @@ filterAMissing f = WhenMissing {-# INLINE filterAMissing #-} --- | /O(n)/. Filter keys and values using an 'Applicative' predicate. +-- | \(O(n)\). Filter keys and values using an 'Applicative' predicate. filterWithKeyA :: Applicative f => (Key -> a -> f Bool) -> IntMap a -> f (IntMap a) filterWithKeyA _ Nil = pure Nil @@ -1848,7 +1848,7 @@ traverseMaybeMissing f = WhenMissing {-# INLINE traverseMaybeMissing #-} --- | /O(n)/. Traverse keys\/values and collect the 'Just' results. +-- | \(O(n)\). Traverse keys\/values and collect the 'Just' results. -- -- @since 0.6.4 traverseMaybeWithKey @@ -2111,7 +2111,7 @@ mergeA Min\/Max --------------------------------------------------------------------} --- | /O(min(n,W))/. Update the value at the minimal key. +-- | \(O(\min(n,W))\). Update the value at the minimal key. -- -- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")] -- > updateMinWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -2127,7 +2127,7 @@ updateMinWithKey f t = Nothing -> Nil go _ Nil = error "updateMinWithKey Nil" --- | /O(min(n,W))/. Update the value at the maximal key. +-- | \(O(\min(n,W))\). Update the value at the maximal key. -- -- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")] -- > updateMaxWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -2146,7 +2146,7 @@ updateMaxWithKey f t = data View a = View {-# UNPACK #-} !Key a !(IntMap a) --- | /O(min(n,W))/. Retrieves the maximal (key,value) pair of the map, and +-- | \(O(\min(n,W))\). Retrieves the maximal (key,value) pair of the map, and -- the map stripped of that element, or 'Nothing' if passed an empty map. -- -- > maxViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((5,"a"), singleton 3 "b") @@ -2174,7 +2174,7 @@ maxViewWithKeySure t = -- See note on NOINLINE at minViewWithKeySure {-# NOINLINE maxViewWithKeySure #-} --- | /O(min(n,W))/. Retrieves the minimal (key,value) pair of the map, and +-- | \(O(\min(n,W))\). Retrieves the minimal (key,value) pair of the map, and -- the map stripped of that element, or 'Nothing' if passed an empty map. -- -- > minViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((3,"b"), singleton 5 "a") @@ -2210,7 +2210,7 @@ minViewWithKeySure t = -- anyway, which should be good enough. {-# NOINLINE minViewWithKeySure #-} --- | /O(min(n,W))/. Update the value at the maximal key. +-- | \(O(\min(n,W))\). Update the value at the maximal key. -- -- > updateMax (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")] -- > updateMax (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -2218,7 +2218,7 @@ minViewWithKeySure t = updateMax :: (a -> Maybe a) -> IntMap a -> IntMap a updateMax f = updateMaxWithKey (const f) --- | /O(min(n,W))/. Update the value at the minimal key. +-- | \(O(\min(n,W))\). Update the value at the minimal key. -- -- > updateMin (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")] -- > updateMin (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -2226,29 +2226,29 @@ updateMax f = updateMaxWithKey (const f) updateMin :: (a -> Maybe a) -> IntMap a -> IntMap a updateMin f = updateMinWithKey (const f) --- | /O(min(n,W))/. Retrieves the maximal key of the map, and the map +-- | \(O(\min(n,W))\). Retrieves the maximal key of the map, and the map -- stripped of that element, or 'Nothing' if passed an empty map. maxView :: IntMap a -> Maybe (a, IntMap a) maxView t = fmap (\((_, x), t') -> (x, t')) (maxViewWithKey t) --- | /O(min(n,W))/. Retrieves the minimal key of the map, and the map +-- | \(O(\min(n,W))\). Retrieves the minimal key of the map, and the map -- stripped of that element, or 'Nothing' if passed an empty map. minView :: IntMap a -> Maybe (a, IntMap a) minView t = fmap (\((_, x), t') -> (x, t')) (minViewWithKey t) --- | /O(min(n,W))/. Delete and find the maximal element. +-- | \(O(\min(n,W))\). Delete and find the maximal element. -- This function throws an error if the map is empty. Use 'maxViewWithKey' -- if the map may be empty. deleteFindMax :: IntMap a -> ((Key, a), IntMap a) deleteFindMax = fromMaybe (error "deleteFindMax: empty map has no maximal element") . maxViewWithKey --- | /O(min(n,W))/. Delete and find the minimal element. +-- | \(O(\min(n,W))\). Delete and find the minimal element. -- This function throws an error if the map is empty. Use 'minViewWithKey' -- if the map may be empty. deleteFindMin :: IntMap a -> ((Key, a), IntMap a) deleteFindMin = fromMaybe (error "deleteFindMin: empty map has no minimal element") . minViewWithKey --- | /O(min(n,W))/. The minimal key of the map. Returns 'Nothing' if the map is empty. +-- | \(O(\min(n,W))\). The minimal key of the map. Returns 'Nothing' if the map is empty. lookupMin :: IntMap a -> Maybe (Key, a) lookupMin Nil = Nothing lookupMin (Tip k v) = Just (k,v) @@ -2259,14 +2259,14 @@ lookupMin (Bin _ m l r) go (Bin _ _ l' _) = go l' go Nil = Nothing --- | /O(min(n,W))/. The minimal key of the map. Calls 'error' if the map is empty. +-- | \(O(\min(n,W))\). The minimal key of the map. Calls 'error' if the map is empty. -- Use 'minViewWithKey' if the map may be empty. findMin :: IntMap a -> (Key, a) findMin t | Just r <- lookupMin t = r | otherwise = error "findMin: empty map has no minimal element" --- | /O(min(n,W))/. The maximal key of the map. Returns 'Nothing' if the map is empty. +-- | \(O(\min(n,W))\). The maximal key of the map. Returns 'Nothing' if the map is empty. lookupMax :: IntMap a -> Maybe (Key, a) lookupMax Nil = Nothing lookupMax (Tip k v) = Just (k,v) @@ -2277,21 +2277,21 @@ lookupMax (Bin _ m l r) go (Bin _ _ _ r') = go r' go Nil = Nothing --- | /O(min(n,W))/. The maximal key of the map. Calls 'error' if the map is empty. +-- | \(O(\min(n,W))\). The maximal key of the map. Calls 'error' if the map is empty. -- Use 'maxViewWithKey' if the map may be empty. findMax :: IntMap a -> (Key, a) findMax t | Just r <- lookupMax t = r | otherwise = error "findMax: empty map has no maximal element" --- | /O(min(n,W))/. Delete the minimal key. Returns an empty map if the map is empty. +-- | \(O(\min(n,W))\). Delete the minimal key. Returns an empty map if the map is empty. -- -- Note that this is a change of behaviour for consistency with 'Data.Map.Map' – -- versions prior to 0.5 threw an error if the 'IntMap' was already empty. deleteMin :: IntMap a -> IntMap a deleteMin = maybe Nil snd . minView --- | /O(min(n,W))/. Delete the maximal key. Returns an empty map if the map is empty. +-- | \(O(\min(n,W))\). Delete the maximal key. Returns an empty map if the map is empty. -- -- Note that this is a change of behaviour for consistency with 'Data.Map.Map' – -- versions prior to 0.5 threw an error if the 'IntMap' was already empty. @@ -2302,13 +2302,13 @@ deleteMax = maybe Nil snd . maxView {-------------------------------------------------------------------- Submap --------------------------------------------------------------------} --- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal). +-- | \(O(n+m)\). Is this a proper submap? (ie. a submap but not equal). -- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). isProperSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool isProperSubmapOf m1 m2 = isProperSubmapOfBy (==) m1 m2 -{- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal). +{- | \(O(n+m)\). Is this a proper submap? (ie. a submap but not equal). The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when @keys m1@ and @keys m2@ are not equal, all keys in @m1@ are in @m2@, and when @f@ returns 'True' when @@ -2357,13 +2357,13 @@ submapCmp predicate (Tip k x) t submapCmp _ Nil Nil = EQ submapCmp _ Nil _ = LT --- | /O(n+m)/. Is this a submap? +-- | \(O(n+m)\). Is this a submap? -- Defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). isSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool isSubmapOf m1 m2 = isSubmapOfBy (==) m1 m2 -{- | /O(n+m)/. +{- | \(O(n+m)\). The expression (@'isSubmapOfBy' f m1 m2@) returns 'True' if all keys in @m1@ are in @m2@, and when @f@ returns 'True' when applied to their respective values. For example, the following @@ -2396,7 +2396,7 @@ isSubmapOfBy _ Nil _ = True {-------------------------------------------------------------------- Mapping --------------------------------------------------------------------} --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")] @@ -2415,7 +2415,7 @@ map f = go #-} #endif --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > let f key x = (show key) ++ ":" ++ x -- > mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")] @@ -2439,7 +2439,7 @@ mapWithKey f t #-} #endif --- | /O(n)/. +-- | \(O(n)\). -- @'traverseWithKey' f s == 'fromList' <$> 'traverse' (\(k, v) -> (,) k <$> f k v) ('toList' m)@ -- That is, behaves exactly like a regular 'traverse' except that the traversing -- function also has access to the key associated with a value. @@ -2456,7 +2456,7 @@ traverseWithKey f = go | otherwise = liftA2 (Bin p m) (go l) (go r) {-# INLINE traverseWithKey #-} --- | /O(n)/. The function @'mapAccum'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccum'@ threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a b = (a ++ b, b ++ "X") @@ -2465,7 +2465,7 @@ traverseWithKey f = go mapAccum :: (a -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) mapAccum f = mapAccumWithKey (\a' _ x -> f a' x) --- | /O(n)/. The function @'mapAccumWithKey'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccumWithKey'@ threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X") @@ -2475,7 +2475,7 @@ mapAccumWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) mapAccumWithKey f a t = mapAccumL f a t --- | /O(n)/. The function @'mapAccumL'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccumL'@ threads an accumulating -- argument through the map in ascending order of keys. mapAccumL :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) mapAccumL f a t @@ -2492,7 +2492,7 @@ mapAccumL f a t Tip k x -> let (a',x') = f a k x in (a',Tip k x') Nil -> (a,Nil) --- | /O(n)/. The function @'mapAccumRWithKey'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccumRWithKey'@ threads an accumulating -- argument through the map in descending order of keys. mapAccumRWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) mapAccumRWithKey f a t @@ -2509,7 +2509,7 @@ mapAccumRWithKey f a t Tip k x -> let (a',x') = f a k x in (a',Tip k x') Nil -> (a,Nil) --- | /O(n*min(n,W))/. +-- | \(O(n \min(n,W))\). -- @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@. -- -- The size of the result may be smaller if @f@ maps two or more distinct @@ -2523,7 +2523,7 @@ mapAccumRWithKey f a t mapKeys :: (Key->Key) -> IntMap a -> IntMap a mapKeys f = fromList . foldrWithKey (\k x xs -> (f k, x) : xs) [] --- | /O(n*min(n,W))/. +-- | \(O(n \min(n,W))\). -- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@. -- -- The size of the result may be smaller if @f@ maps two or more distinct @@ -2537,7 +2537,7 @@ mapKeysWith :: (a -> a -> a) -> (Key->Key) -> IntMap a -> IntMap a mapKeysWith c f = fromListWith c . foldrWithKey (\k x xs -> (f k, x) : xs) [] --- | /O(n*min(n,W))/. +-- | \(O(n \min(n,W))\). -- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@ -- is strictly monotonic. -- That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@. @@ -2560,7 +2560,7 @@ mapKeysMonotonic f {-------------------------------------------------------------------- Filter --------------------------------------------------------------------} --- | /O(n)/. Filter all values that satisfy some predicate. +-- | \(O(n)\). Filter all values that satisfy some predicate. -- -- > filter (> "a") (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" -- > filter (> "x") (fromList [(5,"a"), (3,"b")]) == empty @@ -2570,7 +2570,7 @@ filter :: (a -> Bool) -> IntMap a -> IntMap a filter p m = filterWithKey (\_ x -> p x) m --- | /O(n)/. Filter all keys\/values that satisfy some predicate. +-- | \(O(n)\). Filter all keys\/values that satisfy some predicate. -- -- > filterWithKey (\k _ -> k > 4) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -2581,7 +2581,7 @@ filterWithKey predicate = go go t@(Tip k x) = if predicate k x then t else Nil go (Bin p m l r) = bin p m (go l) (go r) --- | /O(n)/. Partition the map according to some predicate. The first +-- | \(O(n)\). Partition the map according to some predicate. The first -- map contains all elements that satisfy the predicate, the second all -- elements that fail the predicate. See also 'split'. -- @@ -2593,7 +2593,7 @@ partition :: (a -> Bool) -> IntMap a -> (IntMap a,IntMap a) partition p m = partitionWithKey (\_ x -> p x) m --- | /O(n)/. Partition the map according to some predicate. The first +-- | \(O(n)\). Partition the map according to some predicate. The first -- map contains all elements that satisfy the predicate, the second all -- elements that fail the predicate. See also 'split'. -- @@ -2615,7 +2615,7 @@ partitionWithKey predicate0 t0 = toPair $ go predicate0 t0 | otherwise -> (Nil :*: t) Nil -> (Nil :*: Nil) --- | /O(n)/. Map values and collect the 'Just' results. +-- | \(O(n)\). Map values and collect the 'Just' results. -- -- > let f x = if x == "a" then Just "new a" else Nothing -- > mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a" @@ -2623,7 +2623,7 @@ partitionWithKey predicate0 t0 = toPair $ go predicate0 t0 mapMaybe :: (a -> Maybe b) -> IntMap a -> IntMap b mapMaybe f = mapMaybeWithKey (\_ x -> f x) --- | /O(n)/. Map keys\/values and collect the 'Just' results. +-- | \(O(n)\). Map keys\/values and collect the 'Just' results. -- -- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing -- > mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3" @@ -2636,7 +2636,7 @@ mapMaybeWithKey f (Tip k x) = case f k x of Nothing -> Nil mapMaybeWithKey _ Nil = Nil --- | /O(n)/. Map values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map values and separate the 'Left' and 'Right' results. -- -- > let f a = if a < "c" then Left a else Right a -- > mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -2649,7 +2649,7 @@ mapEither :: (a -> Either b c) -> IntMap a -> (IntMap b, IntMap c) mapEither f m = mapEitherWithKey (\_ x -> f x) m --- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map keys\/values and separate the 'Left' and 'Right' results. -- -- > let f k a = if k < 5 then Left (k * 2) else Right (a ++ a) -- > mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -2671,7 +2671,7 @@ mapEitherWithKey f0 t0 = toPair $ go f0 t0 Right z -> (Nil :*: Tip k z) go _ Nil = (Nil :*: Nil) --- | /O(min(n,W))/. The expression (@'split' k map@) is a pair @(map1,map2)@ +-- | \(O(\min(n,W))\). The expression (@'split' k map@) is a pair @(map1,map2)@ -- where all keys in @map1@ are lower than @k@ and all keys in -- @map2@ larger than @k@. Any key equal to @k@ is found in neither @map1@ nor @map2@. -- @@ -2721,7 +2721,7 @@ mapGT :: (IntMap a -> IntMap a) -> SplitLookup a -> SplitLookup a mapGT f (SplitLookup lt fnd gt) = SplitLookup lt fnd (f gt) {-# INLINE mapGT #-} --- | /O(min(n,W))/. Performs a 'split' but also returns whether the pivot +-- | \(O(\min(n,W))\). Performs a 'split' but also returns whether the pivot -- key was found in the original map. -- -- > splitLookup 2 (fromList [(5,"a"), (3,"b")]) == (empty, Nothing, fromList [(3,"b"), (5,"a")]) @@ -2758,7 +2758,7 @@ splitLookup k t = {-------------------------------------------------------------------- Fold --------------------------------------------------------------------} --- | /O(n)/. Fold the values in the map using the given right-associative +-- | \(O(n)\). Fold the values in the map using the given right-associative -- binary operator, such that @'foldr' f z == 'Prelude.foldr' f z . 'elems'@. -- -- For example, @@ -2780,7 +2780,7 @@ foldr f z = \t -> -- Use lambda t to be inlinable with two arguments only. go z' (Bin _ _ l r) = go (go z' r) l {-# INLINE foldr #-} --- | /O(n)/. A strict version of 'foldr'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldr'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldr' :: (a -> b -> b) -> b -> IntMap a -> b @@ -2796,7 +2796,7 @@ foldr' f z = \t -> -- Use lambda t to be inlinable with two arguments only. go z' (Bin _ _ l r) = go (go z' r) l {-# INLINE foldr' #-} --- | /O(n)/. Fold the values in the map using the given left-associative +-- | \(O(n)\). Fold the values in the map using the given left-associative -- binary operator, such that @'foldl' f z == 'Prelude.foldl' f z . 'elems'@. -- -- For example, @@ -2818,7 +2818,7 @@ foldl f z = \t -> -- Use lambda t to be inlinable with two arguments only. go z' (Bin _ _ l r) = go (go z' l) r {-# INLINE foldl #-} --- | /O(n)/. A strict version of 'foldl'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldl'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldl' :: (a -> b -> a) -> a -> IntMap b -> a @@ -2834,7 +2834,7 @@ foldl' f z = \t -> -- Use lambda t to be inlinable with two arguments only. go z' (Bin _ _ l r) = go (go z' l) r {-# INLINE foldl' #-} --- | /O(n)/. Fold the keys and values in the map using the given right-associative +-- | \(O(n)\). Fold the keys and values in the map using the given right-associative -- binary operator, such that -- @'foldrWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@. -- @@ -2857,7 +2857,7 @@ foldrWithKey f z = \t -> -- Use lambda t to be inlinable with two arguments go z' (Bin _ _ l r) = go (go z' r) l {-# INLINE foldrWithKey #-} --- | /O(n)/. A strict version of 'foldrWithKey'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldrWithKey'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldrWithKey' :: (Key -> a -> b -> b) -> b -> IntMap a -> b @@ -2873,7 +2873,7 @@ foldrWithKey' f z = \t -> -- Use lambda t to be inlinable with two argument go z' (Bin _ _ l r) = go (go z' r) l {-# INLINE foldrWithKey' #-} --- | /O(n)/. Fold the keys and values in the map using the given left-associative +-- | \(O(n)\). Fold the keys and values in the map using the given left-associative -- binary operator, such that -- @'foldlWithKey' f z == 'Prelude.foldl' (\\z' (kx, x) -> f z' kx x) z . 'toAscList'@. -- @@ -2896,7 +2896,7 @@ foldlWithKey f z = \t -> -- Use lambda t to be inlinable with two arguments go z' (Bin _ _ l r) = go (go z' l) r {-# INLINE foldlWithKey #-} --- | /O(n)/. A strict version of 'foldlWithKey'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldlWithKey'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldlWithKey' :: (a -> Key -> b -> a) -> a -> IntMap b -> a @@ -2912,7 +2912,7 @@ foldlWithKey' f z = \t -> -- Use lambda t to be inlinable with two argument go z' (Bin _ _ l r) = go (go z' l) r {-# INLINE foldlWithKey' #-} --- | /O(n)/. Fold the keys and values in the map using the given monoid, such that +-- | \(O(n)\). Fold the keys and values in the map using the given monoid, such that -- -- @'foldMapWithKey' f = 'Prelude.fold' . 'mapWithKey' f@ -- @@ -2932,7 +2932,7 @@ foldMapWithKey f = go {-------------------------------------------------------------------- List variations --------------------------------------------------------------------} --- | /O(n)/. +-- | \(O(n)\). -- Return all elements of the map in the ascending order of their keys. -- Subject to list fusion. -- @@ -2942,7 +2942,7 @@ foldMapWithKey f = go elems :: IntMap a -> [a] elems = foldr (:) [] --- | /O(n)/. Return all keys of the map in ascending order. Subject to list +-- | \(O(n)\). Return all keys of the map in ascending order. Subject to list -- fusion. -- -- > keys (fromList [(5,"a"), (3,"b")]) == [3,5] @@ -2951,7 +2951,7 @@ elems = foldr (:) [] keys :: IntMap a -> [Key] keys = foldrWithKey (\k _ ks -> k : ks) [] --- | /O(n)/. An alias for 'toAscList'. Returns all key\/value pairs in the +-- | \(O(n)\). An alias for 'toAscList'. Returns all key\/value pairs in the -- map in ascending key order. Subject to list fusion. -- -- > assocs (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] @@ -2960,7 +2960,7 @@ keys = foldrWithKey (\k _ ks -> k : ks) [] assocs :: IntMap a -> [(Key,a)] assocs = toAscList --- | /O(n*min(n,W))/. The set of all keys of the map. +-- | \(O(n \min(n,W))\). The set of all keys of the map. -- -- > keysSet (fromList [(5,"a"), (3,"b")]) == Data.IntSet.fromList [3,5] -- > keysSet empty == Data.IntSet.empty @@ -2975,7 +2975,7 @@ keysSet (Bin p m l r) computeBm acc (Tip kx _) = acc .|. IntSet.bitmapOf kx computeBm _ Nil = error "Data.IntSet.keysSet: Nil" --- | /O(n)/. Build a map from a set of keys and a function which for each key +-- | \(O(n)\). Build a map from a set of keys and a function which for each key -- computes its value. -- -- > fromSet (\k -> replicate k 'a') (Data.IntSet.fromList [3, 5]) == fromList [(5,"aaaaa"), (3,"aaa")] @@ -3019,7 +3019,7 @@ instance GHCExts.IsList (IntMap a) where toList = toList #endif --- | /O(n)/. Convert the map to a list of key\/value pairs. Subject to list +-- | \(O(n)\). Convert the map to a list of key\/value pairs. Subject to list -- fusion. -- -- > toList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] @@ -3028,7 +3028,7 @@ instance GHCExts.IsList (IntMap a) where toList :: IntMap a -> [(Key,a)] toList = toAscList --- | /O(n)/. Convert the map to a list of key\/value pairs where the +-- | \(O(n)\). Convert the map to a list of key\/value pairs where the -- keys are in ascending order. Subject to list fusion. -- -- > toAscList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] @@ -3036,7 +3036,7 @@ toList = toAscList toAscList :: IntMap a -> [(Key,a)] toAscList = foldrWithKey (\k x xs -> (k,x):xs) [] --- | /O(n)/. Convert the map to a list of key\/value pairs where the keys +-- | \(O(n)\). Convert the map to a list of key\/value pairs where the keys -- are in descending order. Subject to list fusion. -- -- > toDescList (fromList [(5,"a"), (3,"b")]) == [(5,"a"), (3,"b")] @@ -3080,7 +3080,7 @@ foldlFB = foldlWithKey #endif --- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs. +-- | \(O(n \min(n,W))\). Create a map from a list of key\/value pairs. -- -- > fromList [] == empty -- > fromList [(5,"a"), (3,"b"), (5, "c")] == fromList [(5,"c"), (3,"b")] @@ -3092,7 +3092,7 @@ fromList xs where ins t (k,x) = insert k x t --- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. +-- | \(O(n \min(n,W))\). Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. -- -- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"c")] == fromList [(3, "ab"), (5, "cba")] -- > fromListWith (++) [] == empty @@ -3101,7 +3101,7 @@ fromListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a fromListWith f xs = fromListWithKey (\_ x y -> f x y) xs --- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'. +-- | \(O(n \min(n,W))\). Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'. -- -- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value -- > fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"c")] == fromList [(3, "3:a|b"), (5, "5:c|5:b|a")] @@ -3113,7 +3113,7 @@ fromListWithKey f xs where ins t (k,x) = insertWithKey f k x t --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order. -- -- > fromAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] @@ -3123,7 +3123,7 @@ fromAscList :: [(Key,a)] -> IntMap a fromAscList = fromMonoListWithKey Nondistinct (\_ x _ -> x) {-# NOINLINE fromAscList #-} --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order, with a combining function on equal keys. -- /The precondition (input list is ascending) is not checked./ -- @@ -3133,7 +3133,7 @@ fromAscListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a fromAscListWith f = fromMonoListWithKey Nondistinct (\_ x y -> f x y) {-# NOINLINE fromAscListWith #-} --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order, with a combining function on equal keys. -- /The precondition (input list is ascending) is not checked./ -- @@ -3144,7 +3144,7 @@ fromAscListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a fromAscListWithKey f = fromMonoListWithKey Nondistinct f {-# NOINLINE fromAscListWithKey #-} --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order and all distinct. -- /The precondition (input list is strictly ascending) is not checked./ -- @@ -3154,7 +3154,7 @@ fromDistinctAscList :: [(Key,a)] -> IntMap a fromDistinctAscList = fromMonoListWithKey Distinct (\_ x _ -> x) {-# NOINLINE fromDistinctAscList #-} --- | /O(n)/. Build a map from a list of key\/value pairs with monotonic keys +-- | \(O(n)\). Build a map from a list of key\/value pairs with monotonic keys -- and a combining function. -- -- The precise conditions under which this function works are subtle: @@ -3416,7 +3416,7 @@ branchMask p1 p2 Utilities --------------------------------------------------------------------} --- | /O(1)/. Decompose a map into pieces based on the structure +-- | \(O(1)\). Decompose a map into pieces based on the structure -- of the underlying tree. This function is useful for consuming a -- map in parallel. -- @@ -3449,14 +3449,14 @@ splitRoot orig = Debugging --------------------------------------------------------------------} --- | /O(n)/. Show the tree that implements the map. The tree is shown +-- | \(O(n)\). Show the tree that implements the map. The tree is shown -- in a compressed, hanging format. showTree :: Show a => IntMap a -> String showTree s = showTreeWith True False s -{- | /O(n)/. The expression (@'showTreeWith' hang wide map@) shows +{- | \(O(n)\). The expression (@'showTreeWith' hang wide map@) shows the tree that implements the map. If @hang@ is 'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If @wide@ is 'True', an extra wide version is shown. diff --git a/containers/src/Data/IntMap/Lazy.hs b/containers/src/Data/IntMap/Lazy.hs index 238eb66fd..6e5282ed3 100644 --- a/containers/src/Data/IntMap/Lazy.hs +++ b/containers/src/Data/IntMap/Lazy.hs @@ -40,8 +40,8 @@ -- -- == Detailed performance information -- --- The amortized running time is given for each operation, with /n/ referring to --- the number of entries in the map and /W/ referring to the number of bits in +-- The amortized running time is given for each operation, 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). -- -- Benchmarks comparing "Data.IntMap.Lazy" with other dictionary diff --git a/containers/src/Data/IntMap/Strict.hs b/containers/src/Data/IntMap/Strict.hs index 1874a94f6..17863e61a 100644 --- a/containers/src/Data/IntMap/Strict.hs +++ b/containers/src/Data/IntMap/Strict.hs @@ -48,8 +48,8 @@ -- -- == Detailed performance information -- --- The amortized running time is given for each operation, with /n/ referring to --- the number of entries in the map and /W/ referring to the number of bits in +-- The amortized running time is given for each operation, 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). -- -- Benchmarks comparing "Data.IntMap.Strict" with other dictionary diff --git a/containers/src/Data/IntMap/Strict/Internal.hs b/containers/src/Data/IntMap/Strict/Internal.hs index 1e02cfc66..f1a39555e 100644 --- a/containers/src/Data/IntMap/Strict/Internal.hs +++ b/containers/src/Data/IntMap/Strict/Internal.hs @@ -48,8 +48,8 @@ -- -- == Detailed performance information -- --- The amortized running time is given for each operation, with /n/ referring to --- the number of entries in the map and /W/ referring to the number of bits in +-- The amortized running time is given for each operation, 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). -- -- Benchmarks comparing "Data.IntMap.Strict" with other dictionary @@ -352,7 +352,7 @@ import qualified Data.Foldable as Foldable Query --------------------------------------------------------------------} --- | /O(min(n,W))/. The expression @('findWithDefault' def k map)@ +-- | \(O(\min(n,W))\). The expression @('findWithDefault' def k map)@ -- returns the value at key @k@ or returns @def@ when the key is not an -- element of the map. -- @@ -373,7 +373,7 @@ findWithDefault def !k = go {-------------------------------------------------------------------- Construction --------------------------------------------------------------------} --- | /O(1)/. A map of one element. +-- | \(O(1)\). A map of one element. -- -- > singleton 1 'a' == fromList [(1, 'a')] -- > size (singleton 1 'a') == 1 @@ -386,7 +386,7 @@ singleton k !x {-------------------------------------------------------------------- Insert --------------------------------------------------------------------} --- | /O(min(n,W))/. Insert a new key\/value pair in the map. +-- | \(O(\min(n,W))\). Insert a new key\/value pair in the map. -- If the key is already present in the map, the associated value is -- replaced with the supplied value, i.e. 'insert' is equivalent to -- @'insertWith' 'const'@. @@ -408,7 +408,7 @@ insert !k !x t = Nil -> Tip k x -- right-biased insertion, used by 'union' --- | /O(min(n,W))/. Insert with a combining function. +-- | \(O(\min(n,W))\). Insert with a combining function. -- @'insertWith' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -422,7 +422,7 @@ insertWith :: (a -> a -> a) -> Key -> a -> IntMap a -> IntMap a insertWith f k x t = insertWithKey (\_ x' y' -> f x' y') k x t --- | /O(min(n,W))/. Insert with a combining function. +-- | \(O(\min(n,W))\). Insert with a combining function. -- @'insertWithKey' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -448,7 +448,7 @@ insertWithKey f !k x t = | otherwise -> link k (singleton k x) ky t Nil -> singleton k x --- | /O(min(n,W))/. The expression (@'insertLookupWithKey' f k x map@) +-- | \(O(\min(n,W))\). The expression (@'insertLookupWithKey' f k x map@) -- is a pair where the first element is equal to (@'lookup' k map@) -- and the second element equal to (@'insertWithKey' f k x map@). -- @@ -481,7 +481,7 @@ insertLookupWithKey f0 !k0 x0 t0 = toPair $ go f0 k0 x0 t0 {-------------------------------------------------------------------- Deletion --------------------------------------------------------------------} --- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not +-- | \(O(\min(n,W))\). Adjust a value at a specific key. When the key is not -- a member of the map, the original map is returned. -- -- > adjust ("new " ++) 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")] @@ -492,7 +492,7 @@ adjust :: (a -> a) -> Key -> IntMap a -> IntMap a adjust f k m = adjustWithKey (\_ x -> f x) k m --- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not +-- | \(O(\min(n,W))\). Adjust a value at a specific key. When the key is not -- a member of the map, the original map is returned. -- -- > let f key x = (show key) ++ ":new " ++ x @@ -512,7 +512,7 @@ adjustWithKey f !k t = | otherwise -> t Nil -> Nil --- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@ +-- | \(O(\min(n,W))\). The expression (@'update' f k map@) updates the value @x@ -- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. -- @@ -525,7 +525,7 @@ update :: (a -> Maybe a) -> Key -> IntMap a -> IntMap a update f = updateWithKey (\_ x -> f x) --- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@ +-- | \(O(\min(n,W))\). The expression (@'update' f k map@) updates the value @x@ -- at @k@ (if it is in the map). If (@f k x@) is 'Nothing', the element is -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. -- @@ -548,7 +548,7 @@ updateWithKey f !k t = | otherwise -> t Nil -> Nil --- | /O(min(n,W))/. Lookup and update. +-- | \(O(\min(n,W))\). Lookup and update. -- The function returns original value, if it is updated. -- This is different behavior than 'Data.Map.updateLookupWithKey'. -- Returns the original key value if the map entry is deleted. @@ -576,7 +576,7 @@ updateLookupWithKey f0 !k0 t0 = toPair $ go f0 k0 t0 --- | /O(min(n,W))/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. +-- | \(O(\min(n,W))\). The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. -- 'alter' can be used to insert, delete, or update a value in an 'IntMap'. -- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. alter :: (Maybe a -> Maybe a) -> Key -> IntMap a -> IntMap a @@ -599,7 +599,7 @@ alter f !k t = Just !x -> Tip k x Nothing -> Nil --- | /O(log n)/. The expression (@'alterF' f k map@) alters the value @x@ at +-- | \(O(\log n)\). The expression (@'alterF' f k map@) alters the value @x@ at -- @k@, or absence thereof. 'alterF' can be used to inspect, insert, delete, -- or update a value in an 'IntMap'. In short : @'lookup' k <$> 'alterF' f k m = f -- ('lookup' k m)@. @@ -649,7 +649,7 @@ unionsWith :: Foldable f => (a->a->a) -> f (IntMap a) -> IntMap a unionsWith f ts = Foldable.foldl' (unionWith f) empty ts --- | /O(n+m)/. The union with a combining function. +-- | \(O(n+m)\). The union with a combining function. -- -- > unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")] @@ -657,7 +657,7 @@ unionWith :: (a -> a -> a) -> IntMap a -> IntMap a -> IntMap a unionWith f m1 m2 = unionWithKey (\_ x y -> f x y) m1 m2 --- | /O(n+m)/. The union with a combining function. +-- | \(O(n+m)\). The union with a combining function. -- -- > let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value -- > unionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "5:a|A"), (7, "C")] @@ -670,7 +670,7 @@ unionWithKey f m1 m2 Difference --------------------------------------------------------------------} --- | /O(n+m)/. Difference with a combining function. +-- | \(O(n+m)\). Difference with a combining function. -- -- > let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing -- > differenceWith f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (7, "C")]) @@ -680,7 +680,7 @@ differenceWith :: (a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a differenceWith f m1 m2 = differenceWithKey (\_ x y -> f x y) m1 m2 --- | /O(n+m)/. Difference with a combining function. When two equal keys are +-- | \(O(n+m)\). Difference with a combining function. When two equal keys are -- encountered, the combining function is applied to the key and both values. -- If it returns 'Nothing', the element is discarded (proper set difference). -- If it returns (@'Just' y@), the element is updated with a new value @y@. @@ -697,7 +697,7 @@ differenceWithKey f m1 m2 Intersection --------------------------------------------------------------------} --- | /O(n+m)/. The intersection with a combining function. +-- | \(O(n+m)\). The intersection with a combining function. -- -- > intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA" @@ -705,7 +705,7 @@ intersectionWith :: (a -> b -> c) -> IntMap a -> IntMap b -> IntMap c intersectionWith f m1 m2 = intersectionWithKey (\_ x y -> f x y) m1 m2 --- | /O(n+m)/. The intersection with a combining function. +-- | \(O(n+m)\). The intersection with a combining function. -- -- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar -- > intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A" @@ -718,7 +718,7 @@ intersectionWithKey f m1 m2 MergeWithKey --------------------------------------------------------------------} --- | /O(n+m)/. A high-performance universal combining function. Using +-- | \(O(n+m)\). A high-performance universal combining function. Using -- 'mergeWithKey', all combining functions can be defined without any loss of -- efficiency (with exception of 'union', 'difference' and 'intersection', -- where sharing of some nodes is lost with 'mergeWithKey'). @@ -767,7 +767,7 @@ mergeWithKey f g1 g2 = mergeWithKey' bin combine g1 g2 Min\/Max --------------------------------------------------------------------} --- | /O(log n)/. Update the value at the minimal key. +-- | \(O(\log n)\). Update the value at the minimal key. -- -- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")] -- > updateMinWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -783,7 +783,7 @@ updateMinWithKey f t = Nothing -> Nil go _ Nil = error "updateMinWithKey Nil" --- | /O(log n)/. Update the value at the maximal key. +-- | \(O(\log n)\). Update the value at the maximal key. -- -- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")] -- > updateMaxWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -799,7 +799,7 @@ updateMaxWithKey f t = Nothing -> Nil go _ Nil = error "updateMaxWithKey Nil" --- | /O(log n)/. Update the value at the maximal key. +-- | \(O(\log n)\). Update the value at the maximal key. -- -- > updateMax (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")] -- > updateMax (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -807,7 +807,7 @@ updateMaxWithKey f t = updateMax :: (a -> Maybe a) -> IntMap a -> IntMap a updateMax f = updateMaxWithKey (const f) --- | /O(log n)/. Update the value at the minimal key. +-- | \(O(\log n)\). Update the value at the minimal key. -- -- > updateMin (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")] -- > updateMin (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -819,7 +819,7 @@ updateMin f = updateMinWithKey (const f) {-------------------------------------------------------------------- Mapping --------------------------------------------------------------------} --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")] @@ -838,7 +838,7 @@ map f = go #-} #endif --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > let f key x = (show key) ++ ":" ++ x -- > mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")] @@ -880,7 +880,7 @@ mapWithKey f t #-} #endif --- | /O(n)/. +-- | \(O(n)\). -- @'traverseWithKey' f s == 'fromList' <$> 'traverse' (\(k, v) -> (,) k <$> f k v) ('toList' m)@ -- That is, behaves exactly like a regular 'traverse' except that the traversing -- function also has access to the key associated with a value. @@ -897,7 +897,7 @@ traverseWithKey f = go | otherwise = liftA2 (Bin p m) (go l) (go r) {-# INLINE traverseWithKey #-} --- | /O(n)/. Traverse keys\/values and collect the 'Just' results. +-- | \(O(n)\). Traverse keys\/values and collect the 'Just' results. -- -- @since 0.6.4 traverseMaybeWithKey @@ -910,7 +910,7 @@ traverseMaybeWithKey f = go | m < 0 = liftA2 (flip (bin p m)) (go r) (go l) | otherwise = liftA2 (bin p m) (go l) (go r) --- | /O(n)/. The function @'mapAccum'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccum'@ threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a b = (a ++ b, b ++ "X") @@ -919,7 +919,7 @@ traverseMaybeWithKey f = go mapAccum :: (a -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) mapAccum f = mapAccumWithKey (\a' _ x -> f a' x) --- | /O(n)/. The function @'mapAccumWithKey'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccumWithKey'@ threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X") @@ -929,7 +929,7 @@ mapAccumWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) mapAccumWithKey f a t = mapAccumL f a t --- | /O(n)/. The function @'mapAccumL'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccumL'@ threads an accumulating -- argument through the map in ascending order of keys. Strict in -- the accumulating argument and the both elements of the -- result of the function. @@ -950,7 +950,7 @@ mapAccumL f0 a0 t0 = toPair $ go f0 a0 t0 Tip k x -> let !(a',!x') = f a k x in (a' :*: Tip k x') Nil -> (a :*: Nil) --- | /O(n)/. The function @'mapAccumRWithKey'@ threads an accumulating +-- | \(O(n)\). The function @'mapAccumRWithKey'@ threads an accumulating -- argument through the map in descending order of keys. mapAccumRWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) mapAccumRWithKey f0 a0 t0 = toPair $ go f0 a0 t0 @@ -969,7 +969,7 @@ mapAccumRWithKey f0 a0 t0 = toPair $ go f0 a0 t0 Tip k x -> let !(a',!x') = f a k x in (a' :*: Tip k x') Nil -> (a :*: Nil) --- | /O(n*log n)/. +-- | \(O(n \log n)\). -- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@. -- -- The size of the result may be smaller if @f@ maps two or more distinct @@ -985,7 +985,7 @@ mapKeysWith c f = fromListWith c . foldrWithKey (\k x xs -> (f k, x) : xs) [] {-------------------------------------------------------------------- Filter --------------------------------------------------------------------} --- | /O(n)/. Map values and collect the 'Just' results. +-- | \(O(n)\). Map values and collect the 'Just' results. -- -- > let f x = if x == "a" then Just "new a" else Nothing -- > mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a" @@ -993,7 +993,7 @@ mapKeysWith c f = fromListWith c . foldrWithKey (\k x xs -> (f k, x) : xs) [] mapMaybe :: (a -> Maybe b) -> IntMap a -> IntMap b mapMaybe f = mapMaybeWithKey (\_ x -> f x) --- | /O(n)/. Map keys\/values and collect the 'Just' results. +-- | \(O(n)\). Map keys\/values and collect the 'Just' results. -- -- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing -- > mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3" @@ -1006,7 +1006,7 @@ mapMaybeWithKey f (Tip k x) = case f k x of Nothing -> Nil mapMaybeWithKey _ Nil = Nil --- | /O(n)/. Map values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map values and separate the 'Left' and 'Right' results. -- -- > let f a = if a < "c" then Left a else Right a -- > mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -1019,7 +1019,7 @@ mapEither :: (a -> Either b c) -> IntMap a -> (IntMap b, IntMap c) mapEither f m = mapEitherWithKey (\_ x -> f x) m --- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map keys\/values and separate the 'Left' and 'Right' results. -- -- > let f k a = if k < 5 then Left (k * 2) else Right (a ++ a) -- > mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -1045,7 +1045,7 @@ mapEitherWithKey f0 t0 = toPair $ go f0 t0 Conversions --------------------------------------------------------------------} --- | /O(n)/. Build a map from a set of keys and a function which for each key +-- | \(O(n)\). Build a map from a set of keys and a function which for each key -- computes its value. -- -- > fromSet (\k -> replicate k 'a') (Data.IntSet.fromList [3, 5]) == fromList [(5,"aaaaa"), (3,"aaa")] @@ -1075,7 +1075,7 @@ fromSet f (IntSet.Tip kx bm) = buildTree f kx bm (IntSet.suffixBitMask + 1) {-------------------------------------------------------------------- Lists --------------------------------------------------------------------} --- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs. +-- | \(O(n \min(n,W))\). Create a map from a list of key\/value pairs. -- -- > fromList [] == empty -- > fromList [(5,"a"), (3,"b"), (5, "c")] == fromList [(5,"c"), (3,"b")] @@ -1087,7 +1087,7 @@ fromList xs where ins t (k,x) = insert k x t --- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. +-- | \(O(n \min(n,W))\). Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. -- -- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")] -- > fromListWith (++) [] == empty @@ -1096,7 +1096,7 @@ fromListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a fromListWith f xs = fromListWithKey (\_ x y -> f x y) xs --- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'. +-- | \(O(n \min(n,W))\). Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'. -- -- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")] -- > fromListWith (++) [] == empty @@ -1107,7 +1107,7 @@ fromListWithKey f xs where ins t (k,x) = insertWithKey f k x t --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order. -- -- > fromAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] @@ -1117,7 +1117,7 @@ fromAscList :: [(Key,a)] -> IntMap a fromAscList = fromMonoListWithKey Nondistinct (\_ x _ -> x) {-# NOINLINE fromAscList #-} --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order, with a combining function on equal keys. -- /The precondition (input list is ascending) is not checked./ -- @@ -1127,7 +1127,7 @@ fromAscListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a fromAscListWith f = fromMonoListWithKey Nondistinct (\_ x y -> f x y) {-# NOINLINE fromAscListWith #-} --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order, with a combining function on equal keys. -- /The precondition (input list is ascending) is not checked./ -- @@ -1137,7 +1137,7 @@ fromAscListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a fromAscListWithKey f = fromMonoListWithKey Nondistinct f {-# NOINLINE fromAscListWithKey #-} --- | /O(n)/. Build a map from a list of key\/value pairs where +-- | \(O(n)\). Build a map from a list of key\/value pairs where -- the keys are in ascending order and all distinct. -- /The precondition (input list is strictly ascending) is not checked./ -- @@ -1147,7 +1147,7 @@ fromDistinctAscList :: [(Key,a)] -> IntMap a fromDistinctAscList = fromMonoListWithKey Distinct (\_ x _ -> x) {-# NOINLINE fromDistinctAscList #-} --- | /O(n)/. Build a map from a list of key\/value pairs with monotonic keys +-- | \(O(n)\). Build a map from a list of key\/value pairs with monotonic keys -- and a combining function. -- -- The precise conditions under which this function works are subtle: diff --git a/containers/src/Data/IntSet.hs b/containers/src/Data/IntSet.hs index 449138575..f34ac4459 100644 --- a/containers/src/Data/IntSet.hs +++ b/containers/src/Data/IntSet.hs @@ -31,9 +31,9 @@ -- -- == Performance information -- --- Many operations have a worst-case complexity of /O(min(n,W))/. +-- 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' +-- elements with a maximum of \(W\) -- the number of bits in an 'Int' -- (32 or 64). -- -- diff --git a/containers/src/Data/IntSet/Internal.hs b/containers/src/Data/IntSet/Internal.hs index d12b6ea38..1906d2ad7 100644 --- a/containers/src/Data/IntSet/Internal.hs +++ b/containers/src/Data/IntSet/Internal.hs @@ -65,9 +65,9 @@ -- it is likely that many values lie close to each other. The asymptotics are -- not affected by this optimization. -- --- Many operations have a worst-case complexity of /O(min(n,W))/. +-- 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' +-- elements with a maximum of \(W\) -- the number of bits in an 'Int' -- (32 or 64). -- -- @since 0.5.9 @@ -236,7 +236,7 @@ intFromNat w = fromIntegral w {-------------------------------------------------------------------- Operators --------------------------------------------------------------------} --- | /O(n+m)/. See 'difference'. +-- | \(O(n+m)\). See 'difference'. (\\) :: IntSet -> IntSet -> IntSet m1 \\ m2 = difference m1 m2 @@ -314,13 +314,13 @@ intSetDataType = mkDataType "Data.IntSet.Internal.IntSet" [fromListConstr] {-------------------------------------------------------------------- Query --------------------------------------------------------------------} --- | /O(1)/. Is the set empty? +-- | \(O(1)\). Is the set empty? null :: IntSet -> Bool null Nil = True null _ = False {-# INLINE null #-} --- | /O(n)/. Cardinality of the set. +-- | \(O(n)\). Cardinality of the set. size :: IntSet -> Int size = go 0 where @@ -328,7 +328,7 @@ size = go 0 go acc (Tip _ bm) = acc + bitcount 0 bm go acc Nil = acc --- | /O(min(n,W))/. Is the value a member of the set? +-- | \(O(\min(n,W))\). Is the value a member of the set? -- See Note: Local 'go' functions and capturing. member :: Key -> IntSet -> Bool @@ -341,11 +341,11 @@ member !x = go go (Tip y bm) = prefixOf x == y && bitmapOf x .&. bm /= 0 go Nil = False --- | /O(min(n,W))/. Is the element not in the set? +-- | \(O(\min(n,W))\). Is the element not in the set? notMember :: Key -> IntSet -> Bool notMember k = not . member k --- | /O(log n)/. Find largest element smaller than the given one. +-- | \(O(\log n)\). Find largest element smaller than the given one. -- -- > lookupLT 3 (fromList [3, 5]) == Nothing -- > lookupLT 5 (fromList [3, 5]) == Just 3 @@ -366,7 +366,7 @@ lookupLT !x t = case t of go def Nil = unsafeFindMax def --- | /O(log n)/. Find smallest element greater than the given one. +-- | \(O(\log n)\). Find smallest element greater than the given one. -- -- > lookupGT 4 (fromList [3, 5]) == Just 5 -- > lookupGT 5 (fromList [3, 5]) == Nothing @@ -387,7 +387,7 @@ lookupGT !x t = case t of go def Nil = unsafeFindMin def --- | /O(log n)/. Find largest element smaller or equal to the given one. +-- | \(O(\log n)\). Find largest element smaller or equal to the given one. -- -- > lookupLE 2 (fromList [3, 5]) == Nothing -- > lookupLE 4 (fromList [3, 5]) == Just 3 @@ -409,7 +409,7 @@ lookupLE !x t = case t of go def Nil = unsafeFindMax def --- | /O(log n)/. Find smallest element greater or equal to the given one. +-- | \(O(\log n)\). Find smallest element greater or equal to the given one. -- -- > lookupGE 3 (fromList [3, 5]) == Just 3 -- > lookupGE 4 (fromList [3, 5]) == Just 5 @@ -449,13 +449,13 @@ unsafeFindMax (Bin _ _ _ r) = unsafeFindMax r {-------------------------------------------------------------------- Construction --------------------------------------------------------------------} --- | /O(1)/. The empty set. +-- | \(O(1)\). The empty set. empty :: IntSet empty = Nil {-# INLINE empty #-} --- | /O(1)/. A set of one element. +-- | \(O(1)\). A set of one element. singleton :: Key -> IntSet singleton x = Tip (prefixOf x) (bitmapOf x) @@ -464,7 +464,7 @@ singleton x {-------------------------------------------------------------------- Insert --------------------------------------------------------------------} --- | /O(min(n,W))/. Add a value to the set. There is no left- or right bias for +-- | \(O(\min(n,W))\). Add a value to the set. There is no left- or right bias for -- IntSets. insert :: Key -> IntSet -> IntSet insert !x = insertBM (prefixOf x) (bitmapOf x) @@ -480,7 +480,7 @@ insertBM kx bm t@(Tip kx' bm') | otherwise = link kx (Tip kx bm) kx' t insertBM kx bm Nil = Tip kx bm --- | /O(min(n,W))/. Delete a value in the set. Returns the +-- | \(O(\min(n,W))\). Delete a value in the set. Returns the -- original set when the value was not present. delete :: Key -> IntSet -> IntSet delete !x = deleteBM (prefixOf x) (bitmapOf x) @@ -497,7 +497,7 @@ deleteBM kx bm t@(Tip kx' bm') | otherwise = t deleteBM _ _ Nil = Nil --- | /O(min(n,W))/. @('alterF' f x s)@ can delete or insert @x@ in @s@ depending +-- | \(O(\min(n,W))\). @('alterF' f x s)@ can delete or insert @x@ in @s@ depending -- on whether it is already present in @s@. -- -- In short: @@ -541,7 +541,7 @@ unions xs = Foldable.foldl' union empty xs --- | /O(n+m)/. The union of two sets. +-- | \(O(n+m)\). The union of two sets. union :: IntSet -> IntSet -> IntSet union t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) | shorter m1 m2 = union1 @@ -566,7 +566,7 @@ union Nil t = t {-------------------------------------------------------------------- Difference --------------------------------------------------------------------} --- | /O(n+m)/. Difference between two sets. +-- | \(O(n+m)\). Difference between two sets. difference :: IntSet -> IntSet -> IntSet difference t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) | shorter m1 m2 = difference1 @@ -600,7 +600,7 @@ difference Nil _ = Nil {-------------------------------------------------------------------- Intersection --------------------------------------------------------------------} --- | /O(n+m)/. The intersection of two sets. +-- | \(O(n+m)\). The intersection of two sets. intersection :: IntSet -> IntSet -> IntSet intersection t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) | shorter m1 m2 = intersection1 @@ -639,7 +639,7 @@ intersection Nil _ = Nil {-------------------------------------------------------------------- Subset --------------------------------------------------------------------} --- | /O(n+m)/. Is this a proper subset? (ie. a subset but not equal). +-- | \(O(n+m)\). Is this a proper subset? (ie. a subset but not equal). isProperSubsetOf :: IntSet -> IntSet -> Bool isProperSubsetOf t1 t2 = case subsetCmp t1 t2 of @@ -678,7 +678,7 @@ subsetCmp (Tip _ _) Nil = GT -- disjoint subsetCmp Nil Nil = EQ subsetCmp Nil _ = LT --- | /O(n+m)/. Is this a subset? +-- | \(O(n+m)\). Is this a subset? -- @(s1 \`isSubsetOf\` s2)@ tells whether @s1@ is a subset of @s2@. isSubsetOf :: IntSet -> IntSet -> Bool @@ -700,7 +700,7 @@ isSubsetOf Nil _ = True {-------------------------------------------------------------------- Disjoint --------------------------------------------------------------------} --- | /O(n+m)/. Check whether two sets are disjoint (i.e. their intersection +-- | \(O(n+m)\). Check whether two sets are disjoint (i.e. their intersection -- is empty). -- -- > disjoint (fromList [2,4,6]) (fromList [1,3]) == True @@ -748,7 +748,7 @@ disjoint Nil _ = True {-------------------------------------------------------------------- Filter --------------------------------------------------------------------} --- | /O(n)/. Filter all elements that satisfy some predicate. +-- | \(O(n)\). Filter all elements that satisfy some predicate. filter :: (Key -> Bool) -> IntSet -> IntSet filter predicate t = case t of @@ -761,7 +761,7 @@ filter predicate t | otherwise = bm {-# INLINE bitPred #-} --- | /O(n)/. partition the set according to some predicate. +-- | \(O(n)\). partition the set according to some predicate. partition :: (Key -> Bool) -> IntSet -> (IntSet,IntSet) partition predicate0 t0 = toPair $ go predicate0 t0 where @@ -780,7 +780,7 @@ partition predicate0 t0 = toPair $ go predicate0 t0 {-# INLINE bitPred #-} --- | /O(min(n,W))/. The expression (@'split' x set@) is a pair @(set1,set2)@ +-- | \(O(\min(n,W))\). The expression (@'split' x set@) is a pair @(set1,set2)@ -- where @set1@ comprises the elements of @set@ less than @x@ and @set2@ -- comprises the elements of @set@ greater than @x@. -- @@ -814,7 +814,7 @@ split x t = higherBitmap = complement (lowerBitmap + bitmapOf x') go _ Nil = (Nil :*: Nil) --- | /O(min(n,W))/. Performs a 'split' but also returns whether the pivot +-- | \(O(\min(n,W))\). Performs a 'split' but also returns whether the pivot -- element was found in the original set. splitMember :: Key -> IntSet -> (IntSet,Bool,IntSet) splitMember x t = @@ -852,7 +852,7 @@ splitMember x t = Min/Max ----------------------------------------------------------------------} --- | /O(min(n,W))/. Retrieves the maximal key of the set, and the set +-- | \(O(\min(n,W))\). Retrieves the maximal key of the set, and the set -- stripped of that element, or 'Nothing' if passed an empty set. maxView :: IntSet -> Maybe (Key, IntSet) maxView t = @@ -864,7 +864,7 @@ maxView t = go (Tip kx bm) = case highestBitSet bm of bi -> (kx + bi, tip kx (bm .&. complement (bitmapOfSuffix bi))) go Nil = error "maxView Nil" --- | /O(min(n,W))/. Retrieves the minimal key of the set, and the set +-- | \(O(\min(n,W))\). Retrieves the minimal key of the set, and the set -- stripped of that element, or 'Nothing' if passed an empty set. minView :: IntSet -> Maybe (Key, IntSet) minView t = @@ -876,20 +876,20 @@ minView t = go (Tip kx bm) = case lowestBitSet bm of bi -> (kx + bi, tip kx (bm .&. complement (bitmapOfSuffix bi))) go Nil = error "minView Nil" --- | /O(min(n,W))/. Delete and find the minimal element. +-- | \(O(\min(n,W))\). Delete and find the minimal element. -- -- > deleteFindMin set = (findMin set, deleteMin set) deleteFindMin :: IntSet -> (Key, IntSet) deleteFindMin = fromMaybe (error "deleteFindMin: empty set has no minimal element") . minView --- | /O(min(n,W))/. Delete and find the maximal element. +-- | \(O(\min(n,W))\). Delete and find the maximal element. -- -- > deleteFindMax set = (findMax set, deleteMax set) deleteFindMax :: IntSet -> (Key, IntSet) deleteFindMax = fromMaybe (error "deleteFindMax: empty set has no maximal element") . maxView --- | /O(min(n,W))/. The minimal element of the set. +-- | \(O(\min(n,W))\). The minimal element of the set. findMin :: IntSet -> Key findMin Nil = error "findMin: empty set has no minimal element" findMin (Tip kx bm) = kx + lowestBitSet bm @@ -900,7 +900,7 @@ findMin (Bin _ m l r) find (Bin _ _ l' _) = find l' find Nil = error "findMin Nil" --- | /O(min(n,W))/. The maximal element of a set. +-- | \(O(\min(n,W))\). The maximal element of a set. findMax :: IntSet -> Key findMax Nil = error "findMax: empty set has no maximal element" findMax (Tip kx bm) = kx + highestBitSet bm @@ -912,14 +912,14 @@ findMax (Bin _ m l r) find Nil = error "findMax Nil" --- | /O(min(n,W))/. Delete the minimal element. Returns an empty set if the set is empty. +-- | \(O(\min(n,W))\). Delete the minimal element. Returns an empty set if the set is empty. -- -- Note that this is a change of behaviour for consistency with 'Data.Set.Set' – -- versions prior to 0.5 threw an error if the 'IntSet' was already empty. deleteMin :: IntSet -> IntSet deleteMin = maybe Nil snd . minView --- | /O(min(n,W))/. Delete the maximal element. Returns an empty set if the set is empty. +-- | \(O(\min(n,W))\). Delete the maximal element. Returns an empty set if the set is empty. -- -- Note that this is a change of behaviour for consistency with 'Data.Set.Set' – -- versions prior to 0.5 threw an error if the 'IntSet' was already empty. @@ -930,7 +930,7 @@ deleteMax = maybe Nil snd . maxView Map ----------------------------------------------------------------------} --- | /O(n*min(n,W))/. +-- | \(O(n \min(n,W))\). -- @'map' f s@ is the set obtained by applying @f@ to each element of @s@. -- -- It's worth noting that the size of the result may be smaller if, @@ -939,7 +939,7 @@ deleteMax = maybe Nil snd . maxView map :: (Key -> Key) -> IntSet -> IntSet map f = fromList . List.map f . toList --- | /O(n)/. The +-- | \(O(n)\). The -- -- @'mapMonotonic' f s == 'map' f s@, but works only when @f@ is strictly increasing. -- /The precondition is not checked./ @@ -959,7 +959,7 @@ mapMonotonic f = fromDistinctAscList . List.map f . toAscList {-------------------------------------------------------------------- Fold --------------------------------------------------------------------} --- | /O(n)/. Fold the elements in the set using the given right-associative +-- | \(O(n)\). Fold the elements in the set using the given right-associative -- binary operator. This function is an equivalent of 'foldr' and is present -- for compatibility only. -- @@ -968,7 +968,7 @@ fold :: (Key -> b -> b) -> b -> IntSet -> b fold = foldr {-# INLINE fold #-} --- | /O(n)/. Fold the elements in the set using the given right-associative +-- | \(O(n)\). Fold the elements in the set using the given right-associative -- binary operator, such that @'foldr' f z == 'Prelude.foldr' f z . 'toAscList'@. -- -- For example, @@ -985,7 +985,7 @@ foldr f z = \t -> -- Use lambda t to be inlinable with two arguments only. go z' (Bin _ _ l r) = go (go z' r) l {-# INLINE foldr #-} --- | /O(n)/. A strict version of 'foldr'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldr'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldr' :: (Key -> b -> b) -> b -> IntSet -> b @@ -999,7 +999,7 @@ foldr' f z = \t -> -- Use lambda t to be inlinable with two arguments only. go z' (Bin _ _ l r) = go (go z' r) l {-# INLINE foldr' #-} --- | /O(n)/. Fold the elements in the set using the given left-associative +-- | \(O(n)\). Fold the elements in the set using the given left-associative -- binary operator, such that @'foldl' f z == 'Prelude.foldl' f z . 'toAscList'@. -- -- For example, @@ -1016,7 +1016,7 @@ foldl f z = \t -> -- Use lambda t to be inlinable with two arguments only. go z' (Bin _ _ l r) = go (go z' l) r {-# INLINE foldl #-} --- | /O(n)/. A strict version of 'foldl'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldl'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldl' :: (a -> Key -> a) -> a -> IntSet -> a @@ -1033,7 +1033,7 @@ foldl' f z = \t -> -- Use lambda t to be inlinable with two arguments only. {-------------------------------------------------------------------- List variations --------------------------------------------------------------------} --- | /O(n)/. An alias of 'toAscList'. The elements of a set in ascending order. +-- | \(O(n)\). An alias of 'toAscList'. The elements of a set in ascending order. -- Subject to list fusion. elems :: IntSet -> [Key] elems @@ -1051,17 +1051,17 @@ instance GHC.Exts.IsList IntSet where toList = toList #endif --- | /O(n)/. Convert the set to a list of elements. Subject to list fusion. +-- | \(O(n)\). Convert the set to a list of elements. Subject to list fusion. toList :: IntSet -> [Key] toList = toAscList --- | /O(n)/. Convert the set to an ascending list of elements. Subject to list +-- | \(O(n)\). Convert the set to an ascending list of elements. Subject to list -- fusion. toAscList :: IntSet -> [Key] toAscList = foldr (:) [] --- | /O(n)/. Convert the set to a descending list of elements. Subject to list +-- | \(O(n)\). Convert the set to a descending list of elements. Subject to list -- fusion. toDescList :: IntSet -> [Key] toDescList = foldl (flip (:)) [] @@ -1096,26 +1096,26 @@ foldlFB = foldl #endif --- | /O(n*min(n,W))/. Create a set from a list of integers. +-- | \(O(n \min(n,W))\). Create a set from a list of integers. fromList :: [Key] -> IntSet fromList xs = Foldable.foldl' ins empty xs where ins t x = insert x t --- | /O(n)/. Build a set from an ascending list of elements. +-- | \(O(n)\). Build a set from an ascending list of elements. -- /The precondition (input list is ascending) is not checked./ fromAscList :: [Key] -> IntSet fromAscList = fromMonoList {-# NOINLINE fromAscList #-} --- | /O(n)/. Build a set from an ascending list of distinct elements. +-- | \(O(n)\). Build a set from an ascending list of distinct elements. -- /The precondition (input list is strictly ascending) is not checked./ fromDistinctAscList :: [Key] -> IntSet fromDistinctAscList = fromAscList {-# INLINE fromDistinctAscList #-} --- | /O(n)/. Build a set from a monotonic list of elements. +-- | \(O(n)\). Build a set from a monotonic list of elements. -- -- The precise conditions under which this function works are subtle: -- For any branch mask, keys with the same prefix w.r.t. the branch @@ -1243,14 +1243,14 @@ instance NFData IntSet where rnf x = seq x () {-------------------------------------------------------------------- Debugging --------------------------------------------------------------------} --- | /O(n)/. Show the tree that implements the set. The tree is shown +-- | \(O(n)\). Show the tree that implements the set. The tree is shown -- in a compressed, hanging format. showTree :: IntSet -> String showTree s = showTreeWith True False s -{- | /O(n)/. The expression (@'showTreeWith' hang wide map@) shows +{- | \(O(n)\). The expression (@'showTreeWith' hang wide map@) shows the tree that implements the set. If @hang@ is 'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If @wide@ is 'True', an extra wide version is shown. @@ -1603,7 +1603,7 @@ foldr'Bits prefix f z bm = let lb = lowestBitSet bm Utilities --------------------------------------------------------------------} --- | /O(1)/. Decompose a set into pieces based on the structure of the underlying +-- | \(O(1)\). Decompose a set into pieces based on the structure of the underlying -- tree. This function is useful for consuming a set in parallel. -- -- No guarantee is made as to the sizes of the pieces; an internal, but diff --git a/containers/src/Data/Map/Internal.hs b/containers/src/Data/Map/Internal.hs index 588fc14d6..1a52c35a2 100644 --- a/containers/src/Data/Map/Internal.hs +++ b/containers/src/Data/Map/Internal.hs @@ -412,7 +412,7 @@ import Data.Coerce --------------------------------------------------------------------} infixl 9 !,!?,\\ -- --- | /O(log n)/. Find the value at a key. +-- | \(O(\log n)\). Find the value at a key. -- Calls 'error' when the element can not be found. -- -- > fromList [(5,'a'), (3,'b')] ! 1 Error: element not in the map @@ -424,7 +424,7 @@ infixl 9 !,!?,\\ -- {-# INLINE (!) #-} #endif --- | /O(log n)/. Find the value at a key. +-- | \(O(\log n)\). Find the value at a key. -- Returns 'Nothing' when the element can not be found. -- -- prop> fromList [(5, 'a'), (3, 'b')] !? 1 == Nothing @@ -508,7 +508,7 @@ mapDataType = mkDataType "Data.Map.Internal.Map" [fromListConstr] {-------------------------------------------------------------------- Query --------------------------------------------------------------------} --- | /O(1)/. Is the map empty? +-- | \(O(1)\). Is the map empty? -- -- > Data.Map.null (empty) == True -- > Data.Map.null (singleton 1 'a') == False @@ -518,7 +518,7 @@ null Tip = True null (Bin {}) = False {-# INLINE null #-} --- | /O(1)/. The number of elements in the map. +-- | \(O(1)\). The number of elements in the map. -- -- > size empty == 0 -- > size (singleton 1 'a') == 1 @@ -530,7 +530,7 @@ size (Bin sz _ _ _ _) = sz {-# INLINE size #-} --- | /O(log n)/. Lookup the value at a key in the map. +-- | \(O(\log n)\). Lookup the value at a key in the map. -- -- The function will return the corresponding value as @('Just' value)@, -- or 'Nothing' if the key isn't in the map. @@ -572,7 +572,7 @@ lookup = go {-# INLINE lookup #-} #endif --- | /O(log n)/. Is the key a member of the map? See also 'notMember'. +-- | \(O(\log n)\). Is the key a member of the map? See also 'notMember'. -- -- > member 5 (fromList [(5,'a'), (3,'b')]) == True -- > member 1 (fromList [(5,'a'), (3,'b')]) == False @@ -590,7 +590,7 @@ member = go {-# INLINE member #-} #endif --- | /O(log n)/. Is the key not a member of the map? See also 'member'. +-- | \(O(\log n)\). Is the key not a member of the map? See also 'member'. -- -- > notMember 5 (fromList [(5,'a'), (3,'b')]) == False -- > notMember 1 (fromList [(5,'a'), (3,'b')]) == True @@ -603,7 +603,7 @@ notMember k m = not $ member k m {-# INLINE notMember #-} #endif --- | /O(log n)/. Find the value at a key. +-- | \(O(\log n)\). Find the value at a key. -- Calls 'error' when the element can not be found. find :: Ord k => k -> Map k a -> a find = go @@ -619,7 +619,7 @@ find = go {-# INLINE find #-} #endif --- | /O(log n)/. The expression @('findWithDefault' def k map)@ returns +-- | \(O(\log n)\). The expression @('findWithDefault' def k map)@ returns -- the value at key @k@ or returns default value @def@ -- when the key is not in the map. -- @@ -639,7 +639,7 @@ findWithDefault = go {-# INLINE findWithDefault #-} #endif --- | /O(log n)/. Find largest key smaller than the given one and return the +-- | \(O(\log n)\). Find largest key smaller than the given one and return the -- corresponding (key, value) pair. -- -- > lookupLT 3 (fromList [(3,'a'), (5,'b')]) == Nothing @@ -660,7 +660,7 @@ lookupLT = goNothing {-# INLINE lookupLT #-} #endif --- | /O(log n)/. Find smallest key greater than the given one and return the +-- | \(O(\log n)\). Find smallest key greater than the given one and return the -- corresponding (key, value) pair. -- -- > lookupGT 4 (fromList [(3,'a'), (5,'b')]) == Just (5, 'b') @@ -681,7 +681,7 @@ lookupGT = goNothing {-# INLINE lookupGT #-} #endif --- | /O(log n)/. Find largest key smaller or equal to the given one and return +-- | \(O(\log n)\). Find largest key smaller or equal to the given one and return -- the corresponding (key, value) pair. -- -- > lookupLE 2 (fromList [(3,'a'), (5,'b')]) == Nothing @@ -705,7 +705,7 @@ lookupLE = goNothing {-# INLINE lookupLE #-} #endif --- | /O(log n)/. Find smallest key greater or equal to the given one and return +-- | \(O(\log n)\). Find smallest key greater or equal to the given one and return -- the corresponding (key, value) pair. -- -- > lookupGE 3 (fromList [(3,'a'), (5,'b')]) == Just (3, 'a') @@ -732,7 +732,7 @@ lookupGE = goNothing {-------------------------------------------------------------------- Construction --------------------------------------------------------------------} --- | /O(1)/. The empty map. +-- | \(O(1)\). The empty map. -- -- > empty == fromList [] -- > size empty == 0 @@ -741,7 +741,7 @@ empty :: Map k a empty = Tip {-# INLINE empty #-} --- | /O(1)/. A map with a single element. +-- | \(O(1)\). A map with a single element. -- -- > singleton 1 'a' == fromList [(1, 'a')] -- > size (singleton 1 'a') == 1 @@ -753,7 +753,7 @@ singleton k x = Bin 1 k x Tip Tip {-------------------------------------------------------------------- Insertion --------------------------------------------------------------------} --- | /O(log n)/. Insert a new key and value in the map. +-- | \(O(\log n)\). Insert a new key and value in the map. -- If the key is already present in the map, the associated value is -- replaced with the supplied value. 'insert' is equivalent to -- @'insertWith' 'const'@. @@ -833,7 +833,7 @@ insertR kx0 = go kx0 kx0 {-# INLINE insertR #-} #endif --- | /O(log n)/. Insert with a function, combining new value and old value. +-- | \(O(\log n)\). Insert with a function, combining new value and old value. -- @'insertWith' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -885,7 +885,7 @@ insertWithR = go {-# INLINE insertWithR #-} #endif --- | /O(log n)/. Insert with a function, combining key, new value and old value. +-- | \(O(\log n)\). Insert with a function, combining key, new value and old value. -- @'insertWithKey' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -934,7 +934,7 @@ insertWithKeyR = go {-# INLINE insertWithKeyR #-} #endif --- | /O(log n)/. Combines insert operation with old value retrieval. +-- | \(O(\log n)\). Combines insert operation with old value retrieval. -- The expression (@'insertLookupWithKey' f k x map@) -- is a pair where the first element is equal to (@'lookup' k map@) -- and the second element equal to (@'insertWithKey' f k x map@). @@ -975,7 +975,7 @@ insertLookupWithKey f0 k0 x0 = toPair . go f0 k0 x0 {-------------------------------------------------------------------- Deletion --------------------------------------------------------------------} --- | /O(log n)/. Delete a key and its value from the map. When the key is not +-- | \(O(\log n)\). Delete a key and its value from the map. When the key is not -- a member of the map, the original map is returned. -- -- > delete 5 (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -1003,7 +1003,7 @@ delete = go {-# INLINE delete #-} #endif --- | /O(log n)/. Update a value at a specific key with the result of the provided function. +-- | \(O(\log n)\). Update a value at a specific key with the result of the provided function. -- When the key is not -- a member of the map, the original map is returned. -- @@ -1019,7 +1019,7 @@ adjust f = adjustWithKey (\_ x -> f x) {-# INLINE adjust #-} #endif --- | /O(log n)/. Adjust a value at a specific key. When the key is not +-- | \(O(\log n)\). Adjust a value at a specific key. When the key is not -- a member of the map, the original map is returned. -- -- > let f key x = (show key) ++ ":new " ++ x @@ -1043,7 +1043,7 @@ adjustWithKey = go {-# INLINE adjustWithKey #-} #endif --- | /O(log n)/. The expression (@'update' f k map@) updates the value @x@ +-- | \(O(\log n)\). The expression (@'update' f k map@) updates the value @x@ -- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. -- @@ -1060,7 +1060,7 @@ update f = updateWithKey (\_ x -> f x) {-# INLINE update #-} #endif --- | /O(log n)/. The expression (@'updateWithKey' f k map@) updates the +-- | \(O(\log n)\). The expression (@'updateWithKey' f k map@) updates the -- value @x@ at @k@ (if it is in the map). If (@f k x@) is 'Nothing', -- the element is deleted. If it is (@'Just' y@), the key @k@ is bound -- to the new value @y@. @@ -1089,7 +1089,7 @@ updateWithKey = go {-# INLINE updateWithKey #-} #endif --- | /O(log n)/. Lookup and update. See also 'updateWithKey'. +-- | \(O(\log n)\). Lookup and update. See also 'updateWithKey'. -- The function returns changed value, if it is updated. -- Returns the original key value if the map entry is deleted. -- @@ -1122,7 +1122,7 @@ updateLookupWithKey f0 k0 = toPair . go f0 k0 {-# INLINE updateLookupWithKey #-} #endif --- | /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. +-- | \(O(\log n)\). The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. -- 'alter' can be used to insert, delete, or update a value in a 'Map'. -- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. -- @@ -1160,7 +1160,7 @@ alter = go -- Used to choose the appropriate alterF implementation. data AreWeStrict = Strict | Lazy --- | /O(log n)/. The expression (@'alterF' f k map@) alters the value @x@ at +-- | \(O(\log n)\). The expression (@'alterF' f k map@) alters the value @x@ at -- @k@, or absence thereof. 'alterF' can be used to inspect, insert, delete, -- or update a value in a 'Map'. In short: @'lookup' k \<$\> 'alterF' f k m = f -- ('lookup' k m)@. @@ -1420,7 +1420,7 @@ alterFYoneda = go {-------------------------------------------------------------------- Indexing --------------------------------------------------------------------} --- | /O(log n)/. Return the /index/ of a key, which is its zero-based index in +-- | \(O(\log n)\). Return the /index/ of a key, which is its zero-based index in -- the sequence sorted by keys. The index is a number from /0/ up to, but not -- including, the 'size' of the map. Calls 'error' when the key is not -- a 'member' of the map. @@ -1444,7 +1444,7 @@ findIndex = go 0 {-# INLINABLE findIndex #-} #endif --- | /O(log n)/. Lookup the /index/ of a key, which is its zero-based index in +-- | \(O(\log n)\). Lookup the /index/ of a key, which is its zero-based index in -- the sequence sorted by keys. The index is a number from /0/ up to, but not -- including, the 'size' of the map. -- @@ -1467,7 +1467,7 @@ lookupIndex = go 0 {-# INLINABLE lookupIndex #-} #endif --- | /O(log n)/. Retrieve an element by its /index/, i.e. by its zero-based +-- | \(O(\log n)\). Retrieve an element by its /index/, i.e. by its zero-based -- index in the sequence sorted by keys. If the /index/ is out of range (less -- than zero, greater or equal to 'size' of the map), 'error' is called. -- @@ -1528,7 +1528,7 @@ drop i0 m0 = go i0 m0 EQ -> insertMin kx x r where sizeL = size l --- | /O(log n)/. Split a map at a particular index. +-- | \(O(\log n)\). Split a map at a particular index. -- -- @ -- splitAt !n !xs = ('take' n xs, 'drop' n xs) @@ -1551,7 +1551,7 @@ splitAt i0 m0 EQ -> l :*: insertMin kx x r where sizeL = size l --- | /O(log n)/. Update the element at /index/, i.e. by its zero-based index in +-- | \(O(\log n)\). Update the element at /index/, i.e. by its zero-based index in -- the sequence sorted by keys. If the /index/ is out of range (less than zero, -- greater or equal to 'size' of the map), 'error' is called. -- @@ -1577,7 +1577,7 @@ updateAt f !i t = where sizeL = size l --- | /O(log n)/. Delete the element at /index/, i.e. by its zero-based index in +-- | \(O(\log n)\). Delete the element at /index/, i.e. by its zero-based index in -- the sequence sorted by keys. If the /index/ is out of range (less than zero, -- greater or equal to 'size' of the map), 'error' is called. -- @@ -1606,7 +1606,7 @@ lookupMinSure :: k -> a -> Map k a -> (k, a) lookupMinSure k a Tip = (k, a) lookupMinSure _ _ (Bin _ k a l _) = lookupMinSure k a l --- | /O(log n)/. The minimal key of the map. Returns 'Nothing' if the map is empty. +-- | \(O(\log n)\). The minimal key of the map. Returns 'Nothing' if the map is empty. -- -- > lookupMin (fromList [(5,"a"), (3,"b")]) == Just (3,"b") -- > lookupMin empty = Nothing @@ -1617,7 +1617,7 @@ lookupMin :: Map k a -> Maybe (k,a) lookupMin Tip = Nothing lookupMin (Bin _ k x l _) = Just $! lookupMinSure k x l --- | /O(log n)/. The minimal key of the map. Calls 'error' if the map is empty. +-- | \(O(\log n)\). The minimal key of the map. Calls 'error' if the map is empty. -- -- > findMin (fromList [(5,"a"), (3,"b")]) == (3,"b") -- > findMin empty Error: empty map has no minimal element @@ -1627,7 +1627,7 @@ findMin t | Just r <- lookupMin t = r | otherwise = error "Map.findMin: empty map has no minimal element" --- | /O(log n)/. The maximal key of the map. Calls 'error' if the map is empty. +-- | \(O(\log n)\). The maximal key of the map. Calls 'error' if the map is empty. -- -- > findMax (fromList [(5,"a"), (3,"b")]) == (5,"a") -- > findMax empty Error: empty map has no maximal element @@ -1636,7 +1636,7 @@ lookupMaxSure :: k -> a -> Map k a -> (k, a) lookupMaxSure k a Tip = (k, a) lookupMaxSure _ _ (Bin _ k a _ r) = lookupMaxSure k a r --- | /O(log n)/. The maximal key of the map. Returns 'Nothing' if the map is empty. +-- | \(O(\log n)\). The maximal key of the map. Returns 'Nothing' if the map is empty. -- -- > lookupMax (fromList [(5,"a"), (3,"b")]) == Just (5,"a") -- > lookupMax empty = Nothing @@ -1652,7 +1652,7 @@ findMax t | Just r <- lookupMax t = r | otherwise = error "Map.findMax: empty map has no maximal element" --- | /O(log n)/. Delete the minimal key. Returns an empty map if the map is empty. +-- | \(O(\log n)\). Delete the minimal key. Returns an empty map if the map is empty. -- -- > deleteMin (fromList [(5,"a"), (3,"b"), (7,"c")]) == fromList [(5,"a"), (7,"c")] -- > deleteMin empty == empty @@ -1662,7 +1662,7 @@ deleteMin (Bin _ _ _ Tip r) = r deleteMin (Bin _ kx x l r) = balanceR kx x (deleteMin l) r deleteMin Tip = Tip --- | /O(log n)/. Delete the maximal key. Returns an empty map if the map is empty. +-- | \(O(\log n)\). Delete the maximal key. Returns an empty map if the map is empty. -- -- > deleteMax (fromList [(5,"a"), (3,"b"), (7,"c")]) == fromList [(3,"b"), (5,"a")] -- > deleteMax empty == empty @@ -1672,7 +1672,7 @@ deleteMax (Bin _ _ _ l Tip) = l deleteMax (Bin _ kx x l r) = balanceL kx x l (deleteMax r) deleteMax Tip = Tip --- | /O(log n)/. Update the value at the minimal key. +-- | \(O(\log n)\). Update the value at the minimal key. -- -- > updateMin (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")] -- > updateMin (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -1681,7 +1681,7 @@ updateMin :: (a -> Maybe a) -> Map k a -> Map k a updateMin f m = updateMinWithKey (\_ x -> f x) m --- | /O(log n)/. Update the value at the maximal key. +-- | \(O(\log n)\). Update the value at the maximal key. -- -- > updateMax (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")] -- > updateMax (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -1691,7 +1691,7 @@ updateMax f m = updateMaxWithKey (\_ x -> f x) m --- | /O(log n)/. Update the value at the minimal key. +-- | \(O(\log n)\). Update the value at the minimal key. -- -- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")] -- > updateMinWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -1703,7 +1703,7 @@ updateMinWithKey f (Bin sx kx x Tip r) = case f kx x of Just x' -> Bin sx kx x' Tip r updateMinWithKey f (Bin _ kx x l r) = balanceR kx x (updateMinWithKey f l) r --- | /O(log n)/. Update the value at the maximal key. +-- | \(O(\log n)\). Update the value at the maximal key. -- -- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")] -- > updateMaxWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -1715,7 +1715,7 @@ updateMaxWithKey f (Bin sx kx x l Tip) = case f kx x of Just x' -> Bin sx kx x' l Tip updateMaxWithKey f (Bin _ kx x l r) = balanceL kx x l (updateMaxWithKey f r) --- | /O(log n)/. Retrieves the minimal (key,value) pair of the map, and +-- | \(O(\log n)\). Retrieves the minimal (key,value) pair of the map, and -- the map stripped of that element, or 'Nothing' if passed an empty map. -- -- > minViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((3,"b"), singleton 5 "a") @@ -1731,7 +1731,7 @@ minViewWithKey (Bin _ k x l r) = Just $ -- the Just. {-# INLINE minViewWithKey #-} --- | /O(log n)/. Retrieves the maximal (key,value) pair of the map, and +-- | \(O(\log n)\). Retrieves the maximal (key,value) pair of the map, and -- the map stripped of that element, or 'Nothing' if passed an empty map. -- -- > maxViewWithKey (fromList [(5,"a"), (3,"b")]) == Just ((5,"a"), singleton 3 "b") @@ -1745,7 +1745,7 @@ maxViewWithKey (Bin _ k x l r) = Just $ -- See note on inlining at minViewWithKey {-# INLINE maxViewWithKey #-} --- | /O(log n)/. Retrieves the value associated with minimal key of the +-- | \(O(\log n)\). Retrieves the value associated with minimal key of the -- map, and the map stripped of that element, or 'Nothing' if passed an -- empty map. -- @@ -1757,7 +1757,7 @@ minView t = case minViewWithKey t of Nothing -> Nothing Just ~((_, x), t') -> Just (x, t') --- | /O(log n)/. Retrieves the value associated with maximal key of the +-- | \(O(\log n)\). Retrieves the value associated with maximal key of the -- map, and the map stripped of that element, or 'Nothing' if passed an -- empty map. -- @@ -1800,7 +1800,7 @@ unionsWith f ts {-# INLINABLE unionsWith #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). -- The expression (@'union' t1 t2@) takes the left-biased union of @t1@ and @t2@. -- It prefers @t1@ when duplicate keys are encountered, -- i.e. (@'union' == 'unionWith' 'const'@). @@ -1824,7 +1824,7 @@ union t1@(Bin _ k1 x1 l1 r1) t2 = case split k1 t2 of {-------------------------------------------------------------------- Union with a combining function --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. Union with a combining function. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Union with a combining function. -- -- > unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")] @@ -1844,7 +1844,7 @@ unionWith f (Bin _ k1 x1 l1 r1) t2 = case splitLookup k1 t2 of {-# INLINABLE unionWith #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). -- Union with a combining function. -- -- > let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value @@ -1875,7 +1875,7 @@ unionWithKey f (Bin _ k1 x1 l1 r1) t2 = case splitLookup k1 t2 of -- relies on doing it the way we do, and it's not clear whether that -- bound holds the other way. --- | /O(m*log(n\/m + 1)), m <= n/. Difference of two maps. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Difference of two maps. -- Return elements of the first map not existing in the second map. -- -- > difference (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 3 "b" @@ -1894,7 +1894,7 @@ difference t1 (Bin _ k _ l2 r2) = case split k t1 of {-# INLINABLE difference #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. Remove all keys in a 'Set' from a 'Map'. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Remove all keys in a 'Set' from a 'Map'. -- -- @ -- m \`withoutKeys\` s = 'filterWithKey' (\k _ -> k ``Set.notMember`` s) m @@ -1917,7 +1917,7 @@ withoutKeys m (Set.Bin _ k ls rs) = case splitMember k m of {-# INLINABLE withoutKeys #-} #endif --- | /O(n+m)/. Difference with a combining function. +-- | \(O(n+m)\). Difference with a combining function. -- When two equal keys are -- encountered, the combining function is applied to the values of these keys. -- If it returns 'Nothing', the element is discarded (proper set difference). If @@ -1933,7 +1933,7 @@ differenceWith f = merge preserveMissing dropMissing $ {-# INLINABLE differenceWith #-} #endif --- | /O(n+m)/. Difference with a combining function. When two equal keys are +-- | \(O(n+m)\). Difference with a combining function. When two equal keys are -- encountered, the combining function is applied to the key and both values. -- If it returns 'Nothing', the element is discarded (proper set difference). If -- it returns (@'Just' y@), the element is updated with a new value @y@. @@ -1953,7 +1953,7 @@ differenceWithKey f = {-------------------------------------------------------------------- Intersection --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. Intersection of two maps. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Intersection of two maps. -- Return data in the first map for the keys existing in both maps. -- (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@). -- @@ -1975,7 +1975,7 @@ intersection t1@(Bin _ k x l1 r1) t2 {-# INLINABLE intersection #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. Restrict a 'Map' to only those keys +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Restrict a 'Map' to only those keys -- found in a 'Set'. -- -- @ @@ -2000,7 +2000,7 @@ restrictKeys m@(Bin _ k x l1 r1) s {-# INLINABLE restrictKeys #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. Intersection with a combining function. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Intersection with a combining function. -- -- > intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA" @@ -2020,7 +2020,7 @@ intersectionWith f (Bin _ k x1 l1 r1) t2 = case mb of {-# INLINABLE intersectionWith #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. Intersection with a combining function. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Intersection with a combining function. -- -- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar -- > intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A" @@ -2042,7 +2042,7 @@ intersectionWithKey f (Bin _ k x1 l1 r1) t2 = case mb of {-------------------------------------------------------------------- Disjoint --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. Check whether the key sets of two +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Check whether the key sets of two -- maps are disjoint (i.e., their 'intersection' is empty). -- -- > disjoint (fromList [(2,'a')]) (fromList [(1,()), (3,())]) == True @@ -2683,7 +2683,7 @@ mergeA MergeWithKey --------------------------------------------------------------------} --- | /O(n+m)/. An unsafe general combining function. +-- | \(O(n+m)\). An unsafe general combining function. -- -- WARNING: This function can produce corrupt maps and its results -- may depend on the internal structures of its inputs. Users should @@ -2743,7 +2743,7 @@ mergeWithKey f g1 g2 = go {-------------------------------------------------------------------- Submap --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). -- This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). -- isSubmapOf :: (Ord k,Eq a) => Map k a -> Map k a -> Bool @@ -2752,7 +2752,7 @@ isSubmapOf m1 m2 = isSubmapOfBy (==) m1 m2 {-# INLINABLE isSubmapOf #-} #endif -{- | /O(m*log(n\/m + 1)), m <= n/. +{- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if all keys in @t1@ are in tree @t2@, and when @f@ returns 'True' when applied to their respective values. For example, the following @@ -2801,7 +2801,7 @@ submap' f (Bin _ kx x l r) t {-# INLINABLE submap' #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. Is this a proper submap? (ie. a submap but not equal). +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Is this a proper submap? (ie. a submap but not equal). -- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). isProperSubmapOf :: (Ord k,Eq a) => Map k a -> Map k a -> Bool isProperSubmapOf m1 m2 @@ -2810,7 +2810,7 @@ isProperSubmapOf m1 m2 {-# INLINABLE isProperSubmapOf #-} #endif -{- | /O(m*log(n\/m + 1)), m <= n/. Is this a proper submap? (ie. a submap but not equal). +{- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Is this a proper submap? (ie. a submap but not equal). The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when @keys m1@ and @keys m2@ are not equal, all keys in @m1@ are in @m2@, and when @f@ returns 'True' when @@ -2838,7 +2838,7 @@ isProperSubmapOfBy f t1 t2 {-------------------------------------------------------------------- Filter and partition --------------------------------------------------------------------} --- | /O(n)/. Filter all values that satisfy the predicate. +-- | \(O(n)\). Filter all values that satisfy the predicate. -- -- > filter (> "a") (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" -- > filter (> "x") (fromList [(5,"a"), (3,"b")]) == empty @@ -2848,7 +2848,7 @@ filter :: (a -> Bool) -> Map k a -> Map k a filter p m = filterWithKey (\_ x -> p x) m --- | /O(n)/. Filter all keys\/values that satisfy the predicate. +-- | \(O(n)\). Filter all keys\/values that satisfy the predicate. -- -- > filterWithKey (\k _ -> k > 4) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -2862,7 +2862,7 @@ filterWithKey p t@(Bin _ kx x l r) where !pl = filterWithKey p l !pr = filterWithKey p r --- | /O(n)/. Filter keys and values using an 'Applicative' +-- | \(O(n)\). Filter keys and values using an 'Applicative' -- predicate. filterWithKeyA :: Applicative f => (k -> a -> f Bool) -> Map k a -> f (Map k a) filterWithKeyA _ Tip = pure Tip @@ -2874,7 +2874,7 @@ filterWithKeyA p t@(Bin _ kx x l r) = | otherwise = link kx x pl pr combine False pl pr = link2 pl pr --- | /O(log n)/. Take while a predicate on the keys holds. +-- | \(O(\log n)\). Take while a predicate on the keys holds. -- The user is responsible for ensuring that for all keys @j@ and @k@ in the map, -- @j \< k ==\> p j \>= p k@. See note at 'spanAntitone'. -- @@ -2891,7 +2891,7 @@ takeWhileAntitone p (Bin _ kx x l r) | p kx = link kx x l (takeWhileAntitone p r) | otherwise = takeWhileAntitone p l --- | /O(log n)/. Drop while a predicate on the keys holds. +-- | \(O(\log n)\). Drop while a predicate on the keys holds. -- The user is responsible for ensuring that for all keys @j@ and @k@ in the map, -- @j \< k ==\> p j \>= p k@. See note at 'spanAntitone'. -- @@ -2908,7 +2908,7 @@ dropWhileAntitone p (Bin _ kx x l r) | p kx = dropWhileAntitone p r | otherwise = link kx x (dropWhileAntitone p l) r --- | /O(log n)/. Divide a map at the point where a predicate on the keys stops holding. +-- | \(O(\log n)\). Divide a map at the point where a predicate on the keys stops holding. -- The user is responsible for ensuring that for all keys @j@ and @k@ in the map, -- @j \< k ==\> p j \>= p k@. -- @@ -2932,7 +2932,7 @@ spanAntitone p0 m = toPair (go p0 m) | p kx = let u :*: v = go p r in link kx x l u :*: v | otherwise = let u :*: v = go p l in u :*: link kx x v r --- | /O(n)/. Partition the map according to a predicate. The first +-- | \(O(n)\). Partition the map according to a predicate. The first -- map contains all elements that satisfy the predicate, the second all -- elements that fail the predicate. See also 'split'. -- @@ -2944,7 +2944,7 @@ partition :: (a -> Bool) -> Map k a -> (Map k a,Map k a) partition p m = partitionWithKey (\_ x -> p x) m --- | /O(n)/. Partition the map according to a predicate. The first +-- | \(O(n)\). Partition the map according to a predicate. The first -- map contains all elements that satisfy the predicate, the second all -- elements that fail the predicate. See also 'split'. -- @@ -2968,7 +2968,7 @@ partitionWithKey p0 t0 = toPair $ go p0 t0 (l1 :*: l2) = go p l (r1 :*: r2) = go p r --- | /O(n)/. Map values and collect the 'Just' results. +-- | \(O(n)\). Map values and collect the 'Just' results. -- -- > let f x = if x == "a" then Just "new a" else Nothing -- > mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a" @@ -2976,7 +2976,7 @@ partitionWithKey p0 t0 = toPair $ go p0 t0 mapMaybe :: (a -> Maybe b) -> Map k a -> Map k b mapMaybe f = mapMaybeWithKey (\_ x -> f x) --- | /O(n)/. Map keys\/values and collect the 'Just' results. +-- | \(O(n)\). Map keys\/values and collect the 'Just' results. -- -- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing -- > mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3" @@ -2987,7 +2987,7 @@ mapMaybeWithKey f (Bin _ kx x l r) = case f kx x of Just y -> link kx y (mapMaybeWithKey f l) (mapMaybeWithKey f r) Nothing -> link2 (mapMaybeWithKey f l) (mapMaybeWithKey f r) --- | /O(n)/. Traverse keys\/values and collect the 'Just' results. +-- | \(O(n)\). Traverse keys\/values and collect the 'Just' results. -- -- @since 0.5.8 traverseMaybeWithKey :: Applicative f @@ -3002,7 +3002,7 @@ traverseMaybeWithKey = go Nothing -> link2 l' r' Just x' -> link kx x' l' r' --- | /O(n)/. Map values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map values and separate the 'Left' and 'Right' results. -- -- > let f a = if a < "c" then Left a else Right a -- > mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -3015,7 +3015,7 @@ mapEither :: (a -> Either b c) -> Map k a -> (Map k b, Map k c) mapEither f m = mapEitherWithKey (\_ x -> f x) m --- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map keys\/values and separate the 'Left' and 'Right' results. -- -- > let f k a = if k < 5 then Left (k * 2) else Right (a ++ a) -- > mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -3038,7 +3038,7 @@ mapEitherWithKey f0 t0 = toPair $ go f0 t0 {-------------------------------------------------------------------- Mapping --------------------------------------------------------------------} --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")] @@ -3058,7 +3058,7 @@ map f = go where #-} #endif --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > let f key x = (show key) ++ ":" ++ x -- > mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")] @@ -3079,7 +3079,7 @@ mapWithKey f (Bin sx kx x l r) = Bin sx kx (f kx x) (mapWithKey f l) (mapWithKey #-} #endif --- | /O(n)/. +-- | \(O(n)\). -- @'traverseWithKey' f m == 'fromList' <$> 'traverse' (\(k, v) -> (,) k <$> f k v) ('toList' m)@ -- That is, behaves exactly like a regular 'traverse' except that the traversing -- function also has access to the key associated with a value. @@ -3094,7 +3094,7 @@ traverseWithKey f = go go (Bin s k v l r) = liftA3 (flip (Bin s k)) (go l) (f k v) (go r) {-# INLINE traverseWithKey #-} --- | /O(n)/. The function 'mapAccum' threads an accumulating +-- | \(O(n)\). The function 'mapAccum' threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a b = (a ++ b, b ++ "X") @@ -3104,7 +3104,7 @@ mapAccum :: (a -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccum f a m = mapAccumWithKey (\a' _ x' -> f a' x') a m --- | /O(n)/. The function 'mapAccumWithKey' threads an accumulating +-- | \(O(n)\). The function 'mapAccumWithKey' threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X") @@ -3114,7 +3114,7 @@ mapAccumWithKey :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccumWithKey f a t = mapAccumL f a t --- | /O(n)/. The function 'mapAccumL' threads an accumulating +-- | \(O(n)\). The function 'mapAccumL' threads an accumulating -- argument through the map in ascending order of keys. mapAccumL :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccumL _ a Tip = (a,Tip) @@ -3124,7 +3124,7 @@ mapAccumL f a (Bin sx kx x l r) = (a3,r') = mapAccumL f a2 r in (a3,Bin sx kx x' l' r') --- | /O(n)/. The function 'mapAccumRWithKey' threads an accumulating +-- | \(O(n)\). The function 'mapAccumRWithKey' threads an accumulating -- argument through the map in descending order of keys. mapAccumRWithKey :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccumRWithKey _ a Tip = (a,Tip) @@ -3134,7 +3134,7 @@ mapAccumRWithKey f a (Bin sx kx x l r) = (a3,l') = mapAccumRWithKey f a2 l in (a3,Bin sx kx x' l' r') --- | /O(n*log n)/. +-- | \(O(n \log n)\). -- @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@. -- -- The size of the result may be smaller if @f@ maps two or more distinct @@ -3151,7 +3151,7 @@ mapKeys f = fromList . foldrWithKey (\k x xs -> (f k, x) : xs) [] {-# INLINABLE mapKeys #-} #endif --- | /O(n*log n)/. +-- | \(O(n \log n)\). -- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@. -- -- The size of the result may be smaller if @f@ maps two or more distinct @@ -3169,7 +3169,7 @@ mapKeysWith c f = fromListWith c . foldrWithKey (\k x xs -> (f k, x) : xs) [] #endif --- | /O(n)/. +-- | \(O(n)\). -- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@ -- is strictly monotonic. -- That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@. @@ -3196,7 +3196,7 @@ mapKeysMonotonic f (Bin sz k x l r) = Folds --------------------------------------------------------------------} --- | /O(n)/. Fold the values in the map using the given right-associative +-- | \(O(n)\). Fold the values in the map using the given right-associative -- binary operator, such that @'foldr' f z == 'Prelude.foldr' f z . 'elems'@. -- -- For example, @@ -3212,7 +3212,7 @@ foldr f z = go z go z' (Bin _ _ x l r) = go (f x (go z' r)) l {-# INLINE foldr #-} --- | /O(n)/. A strict version of 'foldr'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldr'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldr' :: (a -> b -> b) -> b -> Map k a -> b @@ -3222,7 +3222,7 @@ foldr' f z = go z go z' (Bin _ _ x l r) = go (f x $! go z' r) l {-# INLINE foldr' #-} --- | /O(n)/. Fold the values in the map using the given left-associative +-- | \(O(n)\). Fold the values in the map using the given left-associative -- binary operator, such that @'foldl' f z == 'Prelude.foldl' f z . 'elems'@. -- -- For example, @@ -3238,7 +3238,7 @@ foldl f z = go z go z' (Bin _ _ x l r) = go (f (go z' l) x) r {-# INLINE foldl #-} --- | /O(n)/. A strict version of 'foldl'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldl'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldl' :: (a -> b -> a) -> a -> Map k b -> a @@ -3250,7 +3250,7 @@ foldl' f z = go z in go (f z'' x) r {-# INLINE foldl' #-} --- | /O(n)/. Fold the keys and values in the map using the given right-associative +-- | \(O(n)\). Fold the keys and values in the map using the given right-associative -- binary operator, such that -- @'foldrWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@. -- @@ -3267,7 +3267,7 @@ foldrWithKey f z = go z go z' (Bin _ kx x l r) = go (f kx x (go z' r)) l {-# INLINE foldrWithKey #-} --- | /O(n)/. A strict version of 'foldrWithKey'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldrWithKey'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldrWithKey' :: (k -> a -> b -> b) -> b -> Map k a -> b @@ -3277,7 +3277,7 @@ foldrWithKey' f z = go z go z' (Bin _ kx x l r) = go (f kx x $! go z' r) l {-# INLINE foldrWithKey' #-} --- | /O(n)/. Fold the keys and values in the map using the given left-associative +-- | \(O(n)\). Fold the keys and values in the map using the given left-associative -- binary operator, such that -- @'foldlWithKey' f z == 'Prelude.foldl' (\\z' (kx, x) -> f z' kx x) z . 'toAscList'@. -- @@ -3294,7 +3294,7 @@ foldlWithKey f z = go z go z' (Bin _ kx x l r) = go (f (go z' l) kx x) r {-# INLINE foldlWithKey #-} --- | /O(n)/. A strict version of 'foldlWithKey'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldlWithKey'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldlWithKey' :: (a -> k -> b -> a) -> a -> Map k b -> a @@ -3306,7 +3306,7 @@ foldlWithKey' f z = go z in go (f z'' kx x) r {-# INLINE foldlWithKey' #-} --- | /O(n)/. Fold the keys and values in the map using the given monoid, such that +-- | \(O(n)\). Fold the keys and values in the map using the given monoid, such that -- -- @'foldMapWithKey' f = 'Prelude.fold' . 'mapWithKey' f@ -- @@ -3324,7 +3324,7 @@ foldMapWithKey f = go {-------------------------------------------------------------------- List variations --------------------------------------------------------------------} --- | /O(n)/. +-- | \(O(n)\). -- Return all elements of the map in the ascending order of their keys. -- Subject to list fusion. -- @@ -3334,7 +3334,7 @@ foldMapWithKey f = go elems :: Map k a -> [a] elems = foldr (:) [] --- | /O(n)/. Return all keys of the map in ascending order. Subject to list +-- | \(O(n)\). Return all keys of the map in ascending order. Subject to list -- fusion. -- -- > keys (fromList [(5,"a"), (3,"b")]) == [3,5] @@ -3343,7 +3343,7 @@ elems = foldr (:) [] keys :: Map k a -> [k] keys = foldrWithKey (\k _ ks -> k : ks) [] --- | /O(n)/. An alias for 'toAscList'. Return all key\/value pairs in the map +-- | \(O(n)\). An alias for 'toAscList'. Return all key\/value pairs in the map -- in ascending key order. Subject to list fusion. -- -- > assocs (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] @@ -3353,7 +3353,7 @@ assocs :: Map k a -> [(k,a)] assocs m = toAscList m --- | /O(n)/. The set of all keys of the map. +-- | \(O(n)\). The set of all keys of the map. -- -- > keysSet (fromList [(5,"a"), (3,"b")]) == Data.Set.fromList [3,5] -- > keysSet empty == Data.Set.empty @@ -3362,7 +3362,7 @@ keysSet :: Map k a -> Set.Set k keysSet Tip = Set.Tip keysSet (Bin sz kx _ l r) = Set.Bin sz kx (keysSet l) (keysSet r) --- | /O(n)/. Build a map from a set of keys and a function which for each key +-- | \(O(n)\). Build a map from a set of keys and a function which for each key -- computes its value. -- -- > fromSet (\k -> replicate k 'a') (Data.Set.fromList [3, 5]) == fromList [(5,"aaaaa"), (3,"aaa")] @@ -3384,7 +3384,7 @@ instance (Ord k) => GHCExts.IsList (Map k v) where toList = toList #endif --- | /O(n*log n)/. Build a map from a list of key\/value pairs. See also 'fromAscList'. +-- | \(O(n \log n)\). Build a map from a list of key\/value pairs. See also 'fromAscList'. -- If the list contains more than one value for the same key, the last value -- for the key is retained. -- @@ -3436,7 +3436,7 @@ fromList ((kx0, x0) : xs0) | not_ordered kx0 xs0 = fromList' (Bin 1 kx0 x0 Tip T {-# INLINABLE fromList #-} #endif --- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. +-- | \(O(n \log n)\). Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. -- -- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")] -- > fromListWith (++) [] == empty @@ -3448,7 +3448,7 @@ fromListWith f xs {-# INLINABLE fromListWith #-} #endif --- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'. +-- | \(O(n \log n)\). Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'. -- -- > let f k a1 a2 = (show k) ++ a1 ++ a2 -- > fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "3ab"), (5, "5a5ba")] @@ -3463,7 +3463,7 @@ fromListWithKey f xs {-# INLINABLE fromListWithKey #-} #endif --- | /O(n)/. Convert the map to a list of key\/value pairs. Subject to list fusion. +-- | \(O(n)\). Convert the map to a list of key\/value pairs. Subject to list fusion. -- -- > toList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] -- > toList empty == [] @@ -3471,7 +3471,7 @@ fromListWithKey f xs toList :: Map k a -> [(k,a)] toList = toAscList --- | /O(n)/. Convert the map to a list of key\/value pairs where the keys are +-- | \(O(n)\). Convert the map to a list of key\/value pairs where the keys are -- in ascending order. Subject to list fusion. -- -- > toAscList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] @@ -3479,7 +3479,7 @@ toList = toAscList toAscList :: Map k a -> [(k,a)] toAscList = foldrWithKey (\k x xs -> (k,x):xs) [] --- | /O(n)/. Convert the map to a list of key\/value pairs where the keys +-- | \(O(n)\). Convert the map to a list of key\/value pairs where the keys -- are in descending order. Subject to list fusion. -- -- > toDescList (fromList [(5,"a"), (3,"b")]) == [(5,"a"), (3,"b")] @@ -3529,7 +3529,7 @@ foldlFB = foldlWithKey fromAscList xs == fromList xs fromAscListWith f xs == fromListWith f xs --------------------------------------------------------------------} --- | /O(n)/. Build a map from an ascending list in linear time. +-- | \(O(n)\). Build a map from an ascending list in linear time. -- /The precondition (input list is ascending) is not checked./ -- -- > fromAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] @@ -3556,7 +3556,7 @@ fromAscList xs {-# INLINABLE fromAscList #-} #endif --- | /O(n)/. Build a map from a descending list in linear time. +-- | \(O(n)\). Build a map from a descending list in linear time. -- /The precondition (input list is descending) is not checked./ -- -- > fromDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")] @@ -3584,7 +3584,7 @@ fromDescList xs = fromDistinctDescList (combineEq xs) {-# INLINABLE fromDescList #-} #endif --- | /O(n)/. Build a map from an ascending list in linear time with a combining function for equal keys. +-- | \(O(n)\). Build a map from an ascending list in linear time with a combining function for equal keys. -- /The precondition (input list is ascending) is not checked./ -- -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")] @@ -3598,7 +3598,7 @@ fromAscListWith f xs {-# INLINABLE fromAscListWith #-} #endif --- | /O(n)/. Build a map from a descending list in linear time with a combining function for equal keys. +-- | \(O(n)\). Build a map from a descending list in linear time with a combining function for equal keys. -- /The precondition (input list is descending) is not checked./ -- -- > fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")] @@ -3614,7 +3614,7 @@ fromDescListWith f xs {-# INLINABLE fromDescListWith #-} #endif --- | /O(n)/. Build a map from an ascending list in linear time with a +-- | \(O(n)\). Build a map from an ascending list in linear time with a -- combining function for equal keys. -- /The precondition (input list is ascending) is not checked./ -- @@ -3642,7 +3642,7 @@ fromAscListWithKey f xs {-# INLINABLE fromAscListWithKey #-} #endif --- | /O(n)/. Build a map from a descending list in linear time with a +-- | \(O(n)\). Build a map from a descending list in linear time with a -- combining function for equal keys. -- /The precondition (input list is descending) is not checked./ -- @@ -3670,7 +3670,7 @@ fromDescListWithKey f xs #endif --- | /O(n)/. Build a map from an ascending list of distinct elements in linear time. +-- | \(O(n)\). Build a map from an ascending list of distinct elements in linear time. -- /The precondition is not checked./ -- -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] @@ -3696,7 +3696,7 @@ fromDistinctAscList ((kx0, x0) : xs0) = go (1::Int) (Bin 1 kx0 x0 Tip Tip) xs0 (l :*: (ky, y):ys) -> case create (s `shiftR` 1) ys of (r :*: zs) -> (link ky y l r :*: zs) --- | /O(n)/. Build a map from a descending list of distinct elements in linear time. +-- | \(O(n)\). Build a map from a descending list of distinct elements in linear time. -- /The precondition is not checked./ -- -- > fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")] @@ -3759,7 +3759,7 @@ filterLt !b (Bin _ kx x l r) = {-------------------------------------------------------------------- Split --------------------------------------------------------------------} --- | /O(log n)/. The expression (@'split' k map@) is a pair @(map1,map2)@ where +-- | \(O(\log n)\). The expression (@'split' k map@) is a pair @(map1,map2)@ where -- the keys in @map1@ are smaller than @k@ and the keys in @map2@ larger than @k@. -- Any key equal to @k@ is found in neither @map1@ nor @map2@. -- @@ -3783,7 +3783,7 @@ split !k0 t0 = toPair $ go k0 t0 {-# INLINABLE split #-} #endif --- | /O(log n)/. The expression (@'splitLookup' k map@) splits a map just +-- | \(O(\log n)\). The expression (@'splitLookup' k map@) splits a map just -- like 'split' but also returns @'lookup' k map@. -- -- > splitLookup 2 (fromList [(5,"a"), (3,"b")]) == (empty, Nothing, fromList [(3,"b"), (5,"a")]) @@ -3928,7 +3928,7 @@ maxViewSure = go MaxView km xm r' -> MaxView km xm (balanceL k x l r') {-# NOINLINE maxViewSure #-} --- | /O(log n)/. Delete and find the minimal element. +-- | \(O(\log n)\). Delete and find the minimal element. -- -- > deleteFindMin (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((3,"b"), fromList[(5,"a"), (10,"c")]) -- > deleteFindMin empty Error: can not return the minimal element of an empty map @@ -3938,7 +3938,7 @@ deleteFindMin t = case minViewWithKey t of Nothing -> (error "Map.deleteFindMin: can not return the minimal element of an empty map", Tip) Just res -> res --- | /O(log n)/. Delete and find the maximal element. +-- | \(O(\log n)\). Delete and find the maximal element. -- -- > deleteFindMax (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((10,"c"), fromList [(3,"b"), (5,"a")]) -- > deleteFindMax empty Error: can not return the maximal element of an empty map @@ -4290,7 +4290,7 @@ instance (Show k, Show a) => Show (Map k a) where Utilities --------------------------------------------------------------------} --- | /O(1)/. Decompose a map into pieces based on the structure of the underlying +-- | \(O(1)\). Decompose a map into pieces based on the structure of the underlying -- tree. This function is useful for consuming a map in parallel. -- -- No guarantee is made as to the sizes of the pieces; an internal, but diff --git a/containers/src/Data/Map/Internal/Debug.hs b/containers/src/Data/Map/Internal/Debug.hs index e17aa8aed..f8644007b 100644 --- a/containers/src/Data/Map/Internal/Debug.hs +++ b/containers/src/Data/Map/Internal/Debug.hs @@ -6,7 +6,7 @@ module Data.Map.Internal.Debug where import Data.Map.Internal (Map (..), size, delta) import Control.Monad (guard) --- | /O(n)/. Show the tree that implements the map. The tree is shown +-- | \(O(n)\). Show the tree that implements the map. The tree is shown -- in a compressed, hanging format. See 'showTreeWith'. showTree :: (Show k,Show a) => Map k a -> String showTree m @@ -15,7 +15,7 @@ showTree m showElem k x = show k ++ ":=" ++ show x -{- | /O(n)/. The expression (@'showTreeWith' showelem hang wide map@) shows +{- | \(O(n)\). The expression (@'showTreeWith' showelem hang wide map@) shows the tree that implements the map. Elements are shown using the @showElem@ function. If @hang@ is 'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If @wide@ is 'True', an extra wide version is shown. @@ -103,7 +103,7 @@ withEmpty bars = " ":bars {-------------------------------------------------------------------- Assertions --------------------------------------------------------------------} --- | /O(n)/. Test if the internal map structure is valid. +-- | \(O(n)\). Test if the internal map structure is valid. -- -- > valid (fromAscList [(3,"b"), (5,"a")]) == True -- > valid (fromAscList [(5,"a"), (3,"b")]) == False diff --git a/containers/src/Data/Map/Lazy.hs b/containers/src/Data/Map/Lazy.hs index 6b05603a1..588f908d9 100644 --- a/containers/src/Data/Map/Lazy.hs +++ b/containers/src/Data/Map/Lazy.hs @@ -49,7 +49,7 @@ -- -- == Detailed performance information -- --- The amortized running time is given for each operation, with /n/ referring to +-- The amortized 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 diff --git a/containers/src/Data/Map/Strict.hs b/containers/src/Data/Map/Strict.hs index 8eea8c329..c2e6345a6 100644 --- a/containers/src/Data/Map/Strict.hs +++ b/containers/src/Data/Map/Strict.hs @@ -55,7 +55,7 @@ -- -- == Detailed performance information -- --- The amortized running time is given for each operation, with /n/ referring to +-- The amortized 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 diff --git a/containers/src/Data/Map/Strict/Internal.hs b/containers/src/Data/Map/Strict/Internal.hs index bf814e762..a6d269f23 100644 --- a/containers/src/Data/Map/Strict/Internal.hs +++ b/containers/src/Data/Map/Strict/Internal.hs @@ -461,7 +461,7 @@ import qualified Data.Foldable as Foldable Query --------------------------------------------------------------------} --- | /O(log n)/. The expression @('findWithDefault' def k map)@ returns +-- | \(O(\log n)\). The expression @('findWithDefault' def k map)@ returns -- the value at key @k@ or returns default value @def@ -- when the key is not in the map. -- @@ -487,7 +487,7 @@ findWithDefault def k = k `seq` go Construction --------------------------------------------------------------------} --- | /O(1)/. A map with a single element. +-- | \(O(1)\). A map with a single element. -- -- > singleton 1 'a' == fromList [(1, 'a')] -- > size (singleton 1 'a') == 1 @@ -499,7 +499,7 @@ singleton k x = x `seq` Bin 1 k x Tip Tip {-------------------------------------------------------------------- Insertion --------------------------------------------------------------------} --- | /O(log n)/. Insert a new key and value in the map. +-- | \(O(\log n)\). Insert a new key and value in the map. -- If the key is already present in the map, the associated value is -- replaced with the supplied value. 'insert' is equivalent to -- @'insertWith' 'const'@. @@ -525,7 +525,7 @@ insert = go {-# INLINE insert #-} #endif --- | /O(log n)/. Insert with a function, combining new value and old value. +-- | \(O(\log n)\). Insert with a function, combining new value and old value. -- @'insertWith' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -567,7 +567,7 @@ insertWithR = go {-# INLINE insertWithR #-} #endif --- | /O(log n)/. Insert with a function, combining key, new value and old value. +-- | \(O(\log n)\). Insert with a function, combining key, new value and old value. -- @'insertWithKey' f key value mp@ -- will insert the pair (key, value) into @mp@ if key does -- not exist in the map. If the key does exist, the function will @@ -618,7 +618,7 @@ insertWithKeyR = go {-# INLINE insertWithKeyR #-} #endif --- | /O(log n)/. Combines insert operation with old value retrieval. +-- | \(O(\log n)\). Combines insert operation with old value retrieval. -- The expression (@'insertLookupWithKey' f k x map@) -- is a pair where the first element is equal to (@'lookup' k map@) -- and the second element equal to (@'insertWithKey' f k x map@). @@ -659,7 +659,7 @@ insertLookupWithKey f0 kx0 x0 t0 = toPair $ go f0 kx0 x0 t0 Deletion --------------------------------------------------------------------} --- | /O(log n)/. Update a value at a specific key with the result of the provided function. +-- | \(O(\log n)\). Update a value at a specific key with the result of the provided function. -- When the key is not -- a member of the map, the original map is returned. -- @@ -675,7 +675,7 @@ adjust f = adjustWithKey (\_ x -> f x) {-# INLINE adjust #-} #endif --- | /O(log n)/. Adjust a value at a specific key. When the key is not +-- | \(O(\log n)\). Adjust a value at a specific key. When the key is not -- a member of the map, the original map is returned. -- -- > let f key x = (show key) ++ ":new " ++ x @@ -700,7 +700,7 @@ adjustWithKey = go {-# INLINE adjustWithKey #-} #endif --- | /O(log n)/. The expression (@'update' f k map@) updates the value @x@ +-- | \(O(\log n)\). The expression (@'update' f k map@) updates the value @x@ -- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. -- @@ -717,7 +717,7 @@ update f = updateWithKey (\_ x -> f x) {-# INLINE update #-} #endif --- | /O(log n)/. The expression (@'updateWithKey' f k map@) updates the +-- | \(O(\log n)\). The expression (@'updateWithKey' f k map@) updates the -- value @x@ at @k@ (if it is in the map). If (@f k x@) is 'Nothing', -- the element is deleted. If it is (@'Just' y@), the key @k@ is bound -- to the new value @y@. @@ -746,7 +746,7 @@ updateWithKey = go {-# INLINE updateWithKey #-} #endif --- | /O(log n)/. Lookup and update. See also 'updateWithKey'. +-- | \(O(\log n)\). Lookup and update. See also 'updateWithKey'. -- The function returns changed value, if it is updated. -- Returns the original key value if the map entry is deleted. -- @@ -776,7 +776,7 @@ updateLookupWithKey f0 k0 t0 = toPair $ go f0 k0 t0 {-# INLINE updateLookupWithKey #-} #endif --- | /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. +-- | \(O(\log n)\). The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. -- 'alter' can be used to insert, delete, or update a value in a 'Map'. -- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. -- @@ -811,7 +811,7 @@ alter = go {-# INLINE alter #-} #endif --- | /O(log n)/. The expression (@'alterF' f k map@) alters the value @x@ at @k@, or absence thereof. +-- | \(O(\log n)\). The expression (@'alterF' f k map@) alters the value @x@ at @k@, or absence thereof. -- 'alterF' can be used to inspect, insert, delete, or update a value in a 'Map'. -- In short: @'lookup' k \<$\> 'alterF' f k m = f ('lookup' k m)@. -- @@ -876,7 +876,7 @@ atKeyIdentity k f t = Identity $ atKeyPlain Strict k (coerce f) t Indexing --------------------------------------------------------------------} --- | /O(log n)/. Update the element at /index/. Calls 'error' when an +-- | \(O(\log n)\). Update the element at /index/. Calls 'error' when an -- invalid index is used. -- -- > updateAt (\ _ _ -> Just "x") 0 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "x"), (5, "a")] @@ -905,7 +905,7 @@ updateAt f i t = i `seq` Minimal, Maximal --------------------------------------------------------------------} --- | /O(log n)/. Update the value at the minimal key. +-- | \(O(\log n)\). Update the value at the minimal key. -- -- > updateMin (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")] -- > updateMin (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -914,7 +914,7 @@ updateMin :: (a -> Maybe a) -> Map k a -> Map k a updateMin f m = updateMinWithKey (\_ x -> f x) m --- | /O(log n)/. Update the value at the maximal key. +-- | \(O(\log n)\). Update the value at the maximal key. -- -- > updateMax (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")] -- > updateMax (\ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -924,7 +924,7 @@ updateMax f m = updateMaxWithKey (\_ x -> f x) m --- | /O(log n)/. Update the value at the minimal key. +-- | \(O(\log n)\). Update the value at the minimal key. -- -- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")] -- > updateMinWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" @@ -936,7 +936,7 @@ updateMinWithKey f (Bin sx kx x Tip r) = case f kx x of Just x' -> x' `seq` Bin sx kx x' Tip r updateMinWithKey f (Bin _ kx x l r) = balanceR kx x (updateMinWithKey f l) r --- | /O(log n)/. Update the value at the maximal key. +-- | \(O(\log n)\). Update the value at the maximal key. -- -- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")] -- > updateMaxWithKey (\ _ _ -> Nothing) (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" @@ -968,7 +968,7 @@ unionsWith f ts {-------------------------------------------------------------------- Union with a combining function --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. Union with a combining function. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Union with a combining function. -- -- > unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")] @@ -984,7 +984,7 @@ unionWith f (Bin _ k1 x1 l1 r1) t2 = case splitLookup k1 t2 of {-# INLINABLE unionWith #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). -- Union with a combining function. -- -- > let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value @@ -1006,7 +1006,7 @@ unionWithKey f (Bin _ k1 x1 l1 r1) t2 = case splitLookup k1 t2 of Difference --------------------------------------------------------------------} --- | /O(n+m)/. Difference with a combining function. +-- | \(O(n+m)\). Difference with a combining function. -- When two equal keys are -- encountered, the combining function is applied to the values of these keys. -- If it returns 'Nothing', the element is discarded (proper set difference). If @@ -1022,7 +1022,7 @@ differenceWith f = merge preserveMissing dropMissing (zipWithMaybeMatched $ \_ x {-# INLINABLE differenceWith #-} #endif --- | /O(n+m)/. Difference with a combining function. When two equal keys are +-- | \(O(n+m)\). Difference with a combining function. When two equal keys are -- encountered, the combining function is applied to the key and both values. -- If it returns 'Nothing', the element is discarded (proper set difference). If -- it returns (@'Just' y@), the element is updated with a new value @y@. @@ -1042,7 +1042,7 @@ differenceWithKey f = merge preserveMissing dropMissing (zipWithMaybeMatched f) Intersection --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. Intersection with a combining function. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Intersection with a combining function. -- -- > intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA" @@ -1060,7 +1060,7 @@ intersectionWith f (Bin _ k x1 l1 r1) t2 = case mb of {-# INLINABLE intersectionWith #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. Intersection with a combining function. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Intersection with a combining function. -- -- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar -- > intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A" @@ -1198,7 +1198,7 @@ forceMaybe m@(Just !_) = m MergeWithKey --------------------------------------------------------------------} --- | /O(n+m)/. An unsafe universal combining function. +-- | \(O(n+m)\). An unsafe universal combining function. -- -- WARNING: This function can produce corrupt maps and its results -- may depend on the internal structures of its inputs. Users should @@ -1260,7 +1260,7 @@ mergeWithKey f g1 g2 = go Filter and partition --------------------------------------------------------------------} --- | /O(n)/. Map values and collect the 'Just' results. +-- | \(O(n)\). Map values and collect the 'Just' results. -- -- > let f x = if x == "a" then Just "new a" else Nothing -- > mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a" @@ -1268,7 +1268,7 @@ mergeWithKey f g1 g2 = go mapMaybe :: (a -> Maybe b) -> Map k a -> Map k b mapMaybe f = mapMaybeWithKey (\_ x -> f x) --- | /O(n)/. Map keys\/values and collect the 'Just' results. +-- | \(O(n)\). Map keys\/values and collect the 'Just' results. -- -- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing -- > mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3" @@ -1279,7 +1279,7 @@ mapMaybeWithKey f (Bin _ kx x l r) = case f kx x of Just y -> y `seq` link kx y (mapMaybeWithKey f l) (mapMaybeWithKey f r) Nothing -> link2 (mapMaybeWithKey f l) (mapMaybeWithKey f r) --- | /O(n)/. Traverse keys\/values and collect the 'Just' results. +-- | \(O(n)\). Traverse keys\/values and collect the 'Just' results. -- -- @since 0.5.8 @@ -1295,7 +1295,7 @@ traverseMaybeWithKey = go Nothing -> link2 l' r' Just !x' -> link kx x' l' r' --- | /O(n)/. Map values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map values and separate the 'Left' and 'Right' results. -- -- > let f a = if a < "c" then Left a else Right a -- > mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -1308,7 +1308,7 @@ mapEither :: (a -> Either b c) -> Map k a -> (Map k b, Map k c) mapEither f m = mapEitherWithKey (\_ x -> f x) m --- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results. +-- | \(O(n)\). Map keys\/values and separate the 'Left' and 'Right' results. -- -- > let f k a = if k < 5 then Left (k * 2) else Right (a ++ a) -- > mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) @@ -1331,7 +1331,7 @@ mapEitherWithKey f0 t0 = toPair $ go f0 t0 {-------------------------------------------------------------------- Mapping --------------------------------------------------------------------} --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")] @@ -1351,7 +1351,7 @@ map f = go #-} #endif --- | /O(n)/. Map a function over all values in the map. +-- | \(O(n)\). Map a function over all values in the map. -- -- > let f key x = (show key) ++ ":" ++ x -- > mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")] @@ -1380,7 +1380,7 @@ mapWithKey f (Bin sx kx x l r) = #-} #endif --- | /O(n)/. +-- | \(O(n)\). -- @'traverseWithKey' f m == 'fromList' <$> 'traverse' (\(k, v) -> (\v' -> v' \`seq\` (k,v')) <$> f k v) ('toList' m)@ -- That is, it behaves much like a regular 'traverse' except that the traversing -- function also has access to the key associated with a value and the values are @@ -1396,7 +1396,7 @@ traverseWithKey f = go go (Bin s k v l r) = liftA3 (\ l' !v' r' -> Bin s k v' l' r') (go l) (f k v) (go r) {-# INLINE traverseWithKey #-} --- | /O(n)/. The function 'mapAccum' threads an accumulating +-- | \(O(n)\). The function 'mapAccum' threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a b = (a ++ b, b ++ "X") @@ -1406,7 +1406,7 @@ mapAccum :: (a -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccum f a m = mapAccumWithKey (\a' _ x' -> f a' x') a m --- | /O(n)/. The function 'mapAccumWithKey' threads an accumulating +-- | \(O(n)\). The function 'mapAccumWithKey' threads an accumulating -- argument through the map in ascending order of keys. -- -- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X") @@ -1416,7 +1416,7 @@ mapAccumWithKey :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccumWithKey f a t = mapAccumL f a t --- | /O(n)/. The function 'mapAccumL' threads an accumulating +-- | \(O(n)\). The function 'mapAccumL' threads an accumulating -- argument through the map in ascending order of keys. mapAccumL :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccumL _ a Tip = (a,Tip) @@ -1426,7 +1426,7 @@ mapAccumL f a (Bin sx kx x l r) = (a3,r') = mapAccumL f a2 r in x' `seq` (a3,Bin sx kx x' l' r') --- | /O(n)/. The function 'mapAccumRWithKey' threads an accumulating +-- | \(O(n)\). The function 'mapAccumRWithKey' threads an accumulating -- argument through the map in descending order of keys. mapAccumRWithKey :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) mapAccumRWithKey _ a Tip = (a,Tip) @@ -1436,7 +1436,7 @@ mapAccumRWithKey f a (Bin sx kx x l r) = (a3,l') = mapAccumRWithKey f a2 l in x' `seq` (a3,Bin sx kx x' l' r') --- | /O(n*log n)/. +-- | \(O(n \log n)\). -- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@. -- -- The size of the result may be smaller if @f@ maps two or more distinct @@ -1457,7 +1457,7 @@ mapKeysWith c f = fromListWith c . foldrWithKey (\k x xs -> (f k, x) : xs) [] Conversions --------------------------------------------------------------------} --- | /O(n)/. Build a map from a set of keys and a function which for each key +-- | \(O(n)\). Build a map from a set of keys and a function which for each key -- computes its value. -- -- > fromSet (\k -> replicate k 'a') (Data.Set.fromList [3, 5]) == fromList [(5,"aaaaa"), (3,"aaa")] @@ -1470,7 +1470,7 @@ fromSet f (Set.Bin sz x l r) = case f x of v -> v `seq` Bin sz x v (fromSet f l) {-------------------------------------------------------------------- Lists --------------------------------------------------------------------} --- | /O(n*log n)/. Build a map from a list of key\/value pairs. See also 'fromAscList'. +-- | \(O(n \log n)\). Build a map from a list of key\/value pairs. See also 'fromAscList'. -- If the list contains more than one value for the same key, the last value -- for the key is retained. -- @@ -1522,7 +1522,7 @@ fromList ((kx0, x0) : xs0) | not_ordered kx0 xs0 = x0 `seq` fromList' (Bin 1 kx0 {-# INLINABLE fromList #-} #endif --- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. +-- | \(O(n \log n)\). Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. -- -- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")] -- > fromListWith (++) [] == empty @@ -1534,7 +1534,7 @@ fromListWith f xs {-# INLINABLE fromListWith #-} #endif --- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'. +-- | \(O(n \log n)\). Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'. -- -- > let f k a1 a2 = (show k) ++ a1 ++ a2 -- > fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "3ab"), (5, "5a5ba")] @@ -1561,7 +1561,7 @@ fromListWithKey f xs fromDescListWith f xs == fromListWith f xs --------------------------------------------------------------------} --- | /O(n)/. Build a map from an ascending list in linear time. +-- | \(O(n)\). Build a map from an ascending list in linear time. -- /The precondition (input list is ascending) is not checked./ -- -- > fromAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] @@ -1575,7 +1575,7 @@ fromAscList xs {-# INLINABLE fromAscList #-} #endif --- | /O(n)/. Build a map from a descending list in linear time. +-- | \(O(n)\). Build a map from a descending list in linear time. -- /The precondition (input list is descending) is not checked./ -- -- > fromDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")] @@ -1589,7 +1589,7 @@ fromDescList xs {-# INLINABLE fromDescList #-} #endif --- | /O(n)/. Build a map from an ascending list in linear time with a combining function for equal keys. +-- | \(O(n)\). Build a map from an ascending list in linear time with a combining function for equal keys. -- /The precondition (input list is ascending) is not checked./ -- -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")] @@ -1603,7 +1603,7 @@ fromAscListWith f xs {-# INLINABLE fromAscListWith #-} #endif --- | /O(n)/. Build a map from a descending list in linear time with a combining function for equal keys. +-- | \(O(n)\). Build a map from a descending list in linear time with a combining function for equal keys. -- /The precondition (input list is descending) is not checked./ -- -- > fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")] @@ -1617,7 +1617,7 @@ fromDescListWith f xs {-# INLINABLE fromDescListWith #-} #endif --- | /O(n)/. Build a map from an ascending list in linear time with a +-- | \(O(n)\). Build a map from an ascending list in linear time with a -- combining function for equal keys. -- /The precondition (input list is ascending) is not checked./ -- @@ -1645,7 +1645,7 @@ fromAscListWithKey f xs {-# INLINABLE fromAscListWithKey #-} #endif --- | /O(n)/. Build a map from a descending list in linear time with a +-- | \(O(n)\). Build a map from a descending list in linear time with a -- combining function for equal keys. -- /The precondition (input list is descending) is not checked./ -- @@ -1673,7 +1673,7 @@ fromDescListWithKey f xs {-# INLINABLE fromDescListWithKey #-} #endif --- | /O(n)/. Build a map from an ascending list of distinct elements in linear time. +-- | \(O(n)\). Build a map from an ascending list of distinct elements in linear time. -- /The precondition is not checked./ -- -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] @@ -1700,7 +1700,7 @@ fromDistinctAscList ((kx0, x0) : xs0) = x0 `seq` go (1::Int) (Bin 1 kx0 x0 Tip T (l :*: (ky, y):ys) -> case create (s `shiftR` 1) ys of (r :*: zs) -> y `seq` (link ky y l r :*: zs) --- | /O(n)/. Build a map from a descending list of distinct elements in linear time. +-- | \(O(n)\). Build a map from a descending list of distinct elements in linear time. -- /The precondition is not checked./ -- -- > fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")] diff --git a/containers/src/Data/Sequence.hs b/containers/src/Data/Sequence.hs index 58301a2bc..108c771fd 100644 --- a/containers/src/Data/Sequence.hs +++ b/containers/src/Data/Sequence.hs @@ -78,7 +78,7 @@ -- -- == Detailed performance information -- --- An amortized running time is given for each operation, with /n/ referring +-- 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. -- diff --git a/containers/src/Data/Sequence/Internal.hs b/containers/src/Data/Sequence/Internal.hs index 5d85a4e42..6f1794191 100644 --- a/containers/src/Data/Sequence/Internal.hs +++ b/containers/src/Data/Sequence/Internal.hs @@ -474,7 +474,7 @@ instance Traversable Seq where (\a' b' c' d' -> Four (Elem a') (Elem b') (Elem c') (Elem d')) (f a) (f b) - (f c) <*> + (f c) <*> (f d) traverseDigitN :: Applicative f @@ -792,8 +792,8 @@ squashR (One12 n) m = node2 n m squashR (Two12 n1 n2) m = node3 n1 n2 m --- | /O(m*n)/ (incremental) Takes an /O(m)/ function and a finger tree of size --- /n/ and maps the function over the tree leaves. Unlike the usual 'fmap', the +-- | \(O(mn)\) (incremental) Takes an \(O(m)\) function and a finger tree of size +-- \(n\) and maps the function over the tree leaves. Unlike the usual 'fmap', the -- function is applied to the "leaves" of the 'FingerTree' (i.e., given a -- @FingerTree (Elem a)@, it applies the function to elements of type @Elem -- a@), replacing the leaves with subtrees of at least the same height, e.g., @@ -808,7 +808,7 @@ mapMulNode :: Int -> (a -> b) -> Node a -> Node b mapMulNode mul f (Node2 s a b) = Node2 (mul * s) (f a) (f b) mapMulNode mul f (Node3 s a b c) = Node3 (mul * s) (f a) (f b) (f c) --- | /O(log n)/ (incremental) Takes the extra flexibility out of a 'FingerTree' +-- | \(O(\log n)\) (incremental) Takes the extra flexibility out of a 'FingerTree' -- to make it a genuine 2-3 finger tree. The result of 'rigidify' will have -- only two and three digits at the top level and only one and two -- digits elsewhere. If the tree has fewer than four elements, 'rigidify' @@ -838,7 +838,7 @@ rigidify (Deep s (One a) m sf) = case viewLTree m of Three b c d -> RigidFull $ Rigid s (node2 a b) EmptyTh (node2 c d) Four b c d e -> RigidFull $ Rigid s (node3 a b c) EmptyTh (node2 d e) --- | /O(log n)/ (incremental) Takes a tree whose left side has been rigidified +-- | \(O(\log n)\) (incremental) Takes a tree whose left side has been rigidified -- and finishes the job. rigidifyRight :: Int -> Digit23 (Elem a) -> FingerTree (Node (Elem a)) -> Digit (Elem a) -> Rigidified (Elem a) @@ -855,7 +855,7 @@ rigidifyRight s pr m (One e) = case viewRTree m of Node2 _ a b -> RigidThree a b e Node3 _ a b c -> RigidFull $ Rigid s (node2 a b) EmptyTh (node2 c e) --- | /O(log n)/ (incremental) Rejigger a finger tree so the digits are all ones +-- | \(O(\log n)\) (incremental) Rejigger a finger tree so the digits are all ones -- and twos. thin :: Sized a => FingerTree a -> Thin a -- Note that 'thin12' will produce a 'DeepTh' constructor immediately before @@ -1024,7 +1024,7 @@ instance Sized a => Sized (FingerTree a) where instance Foldable FingerTree where foldMap _ EmptyT = mempty foldMap f' (Single x') = f' x' - foldMap f' (Deep _ pr' m' sf') = + foldMap f' (Deep _ pr' m' sf') = foldMapDigit f' pr' <> foldMapTree (foldMapNode f') m' <> foldMapDigit f' sf' @@ -1032,7 +1032,7 @@ instance Foldable FingerTree where foldMapTree :: Monoid m => (Node a -> m) -> FingerTree (Node a) -> m foldMapTree _ EmptyT = mempty foldMapTree f (Single x) = f x - foldMapTree f (Deep _ pr m sf) = + foldMapTree f (Deep _ pr m sf) = foldMapDigitN f pr <> foldMapTree (foldMapNodeN f) m <> foldMapDigitN f sf @@ -1420,7 +1420,7 @@ instance NFData a => NFData (Elem a) where {-# SPECIALIZE applicativeTree :: Int -> Int -> State s a -> State s (FingerTree a) #-} {-# SPECIALIZE applicativeTree :: Int -> Int -> Identity a -> Identity (FingerTree a) #-} -- Special note: the Identity specialization automatically does node sharing, --- reducing memory usage of the resulting tree to /O(log n)/. +-- reducing memory usage of the resulting tree to \(O(\log n)\). applicativeTree :: Applicative f => Int -> Int -> f a -> f (FingerTree a) applicativeTree n !mSize m = case n of 0 -> pure EmptyT @@ -1714,7 +1714,7 @@ replicateA n x replicateM :: Applicative m => Int -> m a -> m (Seq a) replicateM = replicateA --- | /O(/log/ k)/. @'cycleTaking' k xs@ forms a sequence of length @k@ by +-- | \(O(\log k)\). @'cycleTaking' k xs@ forms a sequence of length @k@ by -- repeatedly concatenating @xs@ with itself. @xs@ may only be empty if -- @k@ is 0. -- @@ -2348,7 +2348,7 @@ index (Seq xs) i -- See note on unsigned arithmetic in splitAt | fromIntegral i < (fromIntegral (size xs) :: Word) = case lookupTree i xs of Place _ (Elem x) -> x - | otherwise = + | otherwise = error $ "index out of bounds in call to: Data.Sequence.index " ++ show i -- | \( O(\log(\min(i,n-i))) \). The element at the specified position, diff --git a/containers/src/Data/Set/Internal.hs b/containers/src/Data/Set/Internal.hs index aab4742d8..55c83302d 100644 --- a/containers/src/Data/Set/Internal.hs +++ b/containers/src/Data/Set/Internal.hs @@ -261,7 +261,7 @@ import Language.Haskell.TH.Syntax (Lift) --------------------------------------------------------------------} infixl 9 \\ -- --- | /O(m*log(n\/m+1)), m <= n/. See 'difference'. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). See 'difference'. (\\) :: Ord a => Set a -> Set a -> Set a m1 \\ m2 = difference m1 m2 #if __GLASGOW_HASKELL__ @@ -364,19 +364,19 @@ setDataType = mkDataType "Data.Set.Internal.Set" [fromListConstr] {-------------------------------------------------------------------- Query --------------------------------------------------------------------} --- | /O(1)/. Is this the empty set? +-- | \(O(1)\). Is this the empty set? null :: Set a -> Bool null Tip = True null (Bin {}) = False {-# INLINE null #-} --- | /O(1)/. The number of elements in the set. +-- | \(O(1)\). The number of elements in the set. size :: Set a -> Int size Tip = 0 size (Bin sz _ _ _) = sz {-# INLINE size #-} --- | /O(log n)/. Is the element in the set? +-- | \(O(\log n)\). Is the element in the set? member :: Ord a => a -> Set a -> Bool member = go where @@ -391,7 +391,7 @@ member = go {-# INLINE member #-} #endif --- | /O(log n)/. Is the element not in the set? +-- | \(O(\log n)\). Is the element not in the set? notMember :: Ord a => a -> Set a -> Bool notMember a t = not $ member a t #if __GLASGOW_HASKELL__ @@ -400,7 +400,7 @@ notMember a t = not $ member a t {-# INLINE notMember #-} #endif --- | /O(log n)/. Find largest element smaller than the given one. +-- | \(O(\log n)\). Find largest element smaller than the given one. -- -- > lookupLT 3 (fromList [3, 5]) == Nothing -- > lookupLT 5 (fromList [3, 5]) == Just 3 @@ -420,7 +420,7 @@ lookupLT = goNothing {-# INLINE lookupLT #-} #endif --- | /O(log n)/. Find smallest element greater than the given one. +-- | \(O(\log n)\). Find smallest element greater than the given one. -- -- > lookupGT 4 (fromList [3, 5]) == Just 5 -- > lookupGT 5 (fromList [3, 5]) == Nothing @@ -440,7 +440,7 @@ lookupGT = goNothing {-# INLINE lookupGT #-} #endif --- | /O(log n)/. Find largest element smaller or equal to the given one. +-- | \(O(\log n)\). Find largest element smaller or equal to the given one. -- -- > lookupLE 2 (fromList [3, 5]) == Nothing -- > lookupLE 4 (fromList [3, 5]) == Just 3 @@ -463,7 +463,7 @@ lookupLE = goNothing {-# INLINE lookupLE #-} #endif --- | /O(log n)/. Find smallest element greater or equal to the given one. +-- | \(O(\log n)\). Find smallest element greater or equal to the given one. -- -- > lookupGE 3 (fromList [3, 5]) == Just 3 -- > lookupGE 4 (fromList [3, 5]) == Just 5 @@ -489,12 +489,12 @@ lookupGE = goNothing {-------------------------------------------------------------------- Construction --------------------------------------------------------------------} --- | /O(1)/. The empty set. +-- | \(O(1)\). The empty set. empty :: Set a empty = Tip {-# INLINE empty #-} --- | /O(1)/. Create a singleton set. +-- | \(O(1)\). Create a singleton set. singleton :: a -> Set a singleton x = Bin 1 x Tip Tip {-# INLINE singleton #-} @@ -502,7 +502,7 @@ singleton x = Bin 1 x Tip Tip {-------------------------------------------------------------------- Insertion, Deletion --------------------------------------------------------------------} --- | /O(log n)/. Insert an element in a set. +-- | \(O(\log n)\). Insert an element in a set. -- If the set already contains an element equal to the given value, -- it is replaced with the new value. @@ -557,7 +557,7 @@ insertR x0 = go x0 x0 {-# INLINE insertR #-} #endif --- | /O(log n)/. Delete an element from a set. +-- | \(O(\log n)\). Delete an element from a set. -- See Note: Type of local 'go' function delete :: Ord a => a -> Set a -> Set a @@ -579,7 +579,7 @@ delete = go {-# INLINE delete #-} #endif --- | /O(log n)/ @('alterF' f x s)@ can delete or insert @x@ in @s@ depending on +-- | \(O(\log n)\) @('alterF' f x s)@ can delete or insert @x@ in @s@ depending on -- whether an equal element is found in @s@. -- -- In short: @@ -646,7 +646,7 @@ alteredSet x0 s0 = go x0 s0 {-------------------------------------------------------------------- Subset --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). -- @(s1 \`isProperSubsetOf\` s2)@ indicates whether @s1@ is a -- proper subset of @s2@. -- @@ -661,7 +661,7 @@ isProperSubsetOf s1 s2 #endif --- | /O(m*log(n\/m + 1)), m <= n/. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). -- @(s1 \`isSubsetOf\` s2)@ indicates whether @s1@ is a subset of @s2@. -- -- @ @@ -716,7 +716,7 @@ isSubsetOfX (Bin _ x l r) t {-------------------------------------------------------------------- Disjoint --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. Check whether two sets are disjoint +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Check whether two sets are disjoint -- (i.e., their intersection is empty). -- -- > disjoint (fromList [2,4,6]) (fromList [1,3]) == True @@ -753,7 +753,7 @@ lookupMinSure :: a -> Set a -> a lookupMinSure x Tip = x lookupMinSure _ (Bin _ x l _) = lookupMinSure x l --- | /O(log n)/. The minimal element of a set. +-- | \(O(\log n)\). The minimal element of a set. -- -- @since 0.5.9 @@ -761,7 +761,7 @@ lookupMin :: Set a -> Maybe a lookupMin Tip = Nothing lookupMin (Bin _ x l _) = Just $! lookupMinSure x l --- | /O(log n)/. The minimal element of a set. +-- | \(O(\log n)\). The minimal element of a set. findMin :: Set a -> a findMin t | Just r <- lookupMin t = r @@ -771,7 +771,7 @@ lookupMaxSure :: a -> Set a -> a lookupMaxSure x Tip = x lookupMaxSure _ (Bin _ x _ r) = lookupMaxSure x r --- | /O(log n)/. The maximal element of a set. +-- | \(O(\log n)\). The maximal element of a set. -- -- @since 0.5.9 @@ -779,19 +779,19 @@ lookupMax :: Set a -> Maybe a lookupMax Tip = Nothing lookupMax (Bin _ x _ r) = Just $! lookupMaxSure x r --- | /O(log n)/. The maximal element of a set. +-- | \(O(\log n)\). The maximal element of a set. findMax :: Set a -> a findMax t | Just r <- lookupMax t = r | otherwise = error "Set.findMax: empty set has no maximal element" --- | /O(log n)/. Delete the minimal element. Returns an empty set if the set is empty. +-- | \(O(\log n)\). Delete the minimal element. Returns an empty set if the set is empty. deleteMin :: Set a -> Set a deleteMin (Bin _ _ Tip r) = r deleteMin (Bin _ x l r) = balanceR x (deleteMin l) r deleteMin Tip = Tip --- | /O(log n)/. Delete the maximal element. Returns an empty set if the set is empty. +-- | \(O(\log n)\). Delete the maximal element. Returns an empty set if the set is empty. deleteMax :: Set a -> Set a deleteMax (Bin _ _ l Tip) = l deleteMax (Bin _ x l r) = balanceL x l (deleteMax r) @@ -807,7 +807,7 @@ unions = Foldable.foldl' union empty {-# INLINABLE unions #-} #endif --- | /O(m*log(n\/m + 1)), m <= n/. The union of two sets, preferring the first set when +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). The union of two sets, preferring the first set when -- equal elements are encountered. union :: Ord a => Set a -> Set a -> Set a union t1 Tip = t1 @@ -827,7 +827,7 @@ union t1@(Bin _ x l1 r1) t2 = case splitS x t2 of {-------------------------------------------------------------------- Difference --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. Difference of two sets. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). Difference of two sets. -- -- Return elements of the first set not existing in the second set. -- @@ -848,7 +848,7 @@ difference t1 (Bin _ x l2 r2) = case split x t1 of {-------------------------------------------------------------------- Intersection --------------------------------------------------------------------} --- | /O(m*log(n\/m + 1)), m <= n/. The intersection of two sets. +-- | \(O\bigl(m \log\bigl(\frac{n+1}{m+1}\bigr)\bigr), \; m \leq n\). The intersection of two sets. -- Elements of the result come from the first set, so for example -- -- > import qualified Data.Set as S @@ -878,7 +878,7 @@ intersection t1@(Bin _ x l1 r1) t2 {-------------------------------------------------------------------- Filter and partition --------------------------------------------------------------------} --- | /O(n)/. Filter all elements that satisfy the predicate. +-- | \(O(n)\). Filter all elements that satisfy the predicate. filter :: (a -> Bool) -> Set a -> Set a filter _ Tip = Tip filter p t@(Bin _ x l r) @@ -890,7 +890,7 @@ filter p t@(Bin _ x l r) !l' = filter p l !r' = filter p r --- | /O(n)/. Partition the set into two sets, one with all elements that satisfy +-- | \(O(n)\). Partition the set into two sets, one with all elements that satisfy -- the predicate and one with all elements that don't satisfy the predicate. -- See also 'split'. partition :: (a -> Bool) -> Set a -> (Set a,Set a) @@ -911,7 +911,7 @@ partition p0 t0 = toPair $ go p0 t0 Map ----------------------------------------------------------------------} --- | /O(n*log n)/. +-- | \(O(n \log n)\). -- @'map' f s@ is the set obtained by applying @f@ to each element of @s@. -- -- It's worth noting that the size of the result may be smaller if, @@ -923,7 +923,7 @@ map f = fromList . List.map f . toList {-# INLINABLE map #-} #endif --- | /O(n)/. The +-- | \(O(n)\). The -- -- @'mapMonotonic' f s == 'map' f s@, but works only when @f@ is strictly increasing. -- /The precondition is not checked./ @@ -940,7 +940,7 @@ mapMonotonic f (Bin sz x l r) = Bin sz (f x) (mapMonotonic f l) (mapMonotonic f {-------------------------------------------------------------------- Fold --------------------------------------------------------------------} --- | /O(n)/. Fold the elements in the set using the given right-associative +-- | \(O(n)\). Fold the elements in the set using the given right-associative -- binary operator. This function is an equivalent of 'foldr' and is present -- for compatibility only. -- @@ -949,7 +949,7 @@ fold :: (a -> b -> b) -> b -> Set a -> b fold = foldr {-# INLINE fold #-} --- | /O(n)/. Fold the elements in the set using the given right-associative +-- | \(O(n)\). Fold the elements in the set using the given right-associative -- binary operator, such that @'foldr' f z == 'Prelude.foldr' f z . 'toAscList'@. -- -- For example, @@ -962,7 +962,7 @@ foldr f z = go z go z' (Bin _ x l r) = go (f x (go z' r)) l {-# INLINE foldr #-} --- | /O(n)/. A strict version of 'foldr'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldr'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldr' :: (a -> b -> b) -> b -> Set a -> b @@ -972,7 +972,7 @@ foldr' f z = go z go z' (Bin _ x l r) = go (f x $! go z' r) l {-# INLINE foldr' #-} --- | /O(n)/. Fold the elements in the set using the given left-associative +-- | \(O(n)\). Fold the elements in the set using the given left-associative -- binary operator, such that @'foldl' f z == 'Prelude.foldl' f z . 'toAscList'@. -- -- For example, @@ -985,7 +985,7 @@ foldl f z = go z go z' (Bin _ x l r) = go (f (go z' l) x) r {-# INLINE foldl #-} --- | /O(n)/. A strict version of 'foldl'. Each application of the operator is +-- | \(O(n)\). A strict version of 'foldl'. Each application of the operator is -- evaluated before using the result in the next application. This -- function is strict in the starting value. foldl' :: (a -> b -> a) -> a -> Set b -> a @@ -1000,7 +1000,7 @@ foldl' f z = go z {-------------------------------------------------------------------- List variations --------------------------------------------------------------------} --- | /O(n)/. An alias of 'toAscList'. The elements of a set in ascending order. +-- | \(O(n)\). An alias of 'toAscList'. The elements of a set in ascending order. -- Subject to list fusion. elems :: Set a -> [a] elems = toAscList @@ -1017,15 +1017,15 @@ instance (Ord a) => GHCExts.IsList (Set a) where toList = toList #endif --- | /O(n)/. Convert the set to a list of elements. Subject to list fusion. +-- | \(O(n)\). Convert the set to a list of elements. Subject to list fusion. toList :: Set a -> [a] toList = toAscList --- | /O(n)/. Convert the set to an ascending list of elements. Subject to list fusion. +-- | \(O(n)\). Convert the set to an ascending list of elements. Subject to list fusion. toAscList :: Set a -> [a] toAscList = foldr (:) [] --- | /O(n)/. Convert the set to a descending list of elements. Subject to list +-- | \(O(n)\). Convert the set to a descending list of elements. Subject to list -- fusion. toDescList :: Set a -> [a] toDescList = foldl (flip (:)) [] @@ -1059,7 +1059,7 @@ foldlFB = foldl {-# RULES "Set.toDescListBack" [1] foldlFB (\xs x -> x : xs) [] = toDescList #-} #endif --- | /O(n*log n)/. Create a set from a list of elements. +-- | \(O(n \log n)\). Create a set from a list of elements. -- -- If the elements are ordered, a linear-time implementation is used, -- with the performance equal to 'fromDistinctAscList'. @@ -1111,7 +1111,7 @@ fromList (x0 : xs0) | not_ordered x0 xs0 = fromList' (Bin 1 x0 Tip Tip) xs0 Note that if [xs] is ascending that: fromAscList xs == fromList xs --------------------------------------------------------------------} --- | /O(n)/. Build a set from an ascending list in linear time. +-- | \(O(n)\). Build a set from an ascending list in linear time. -- /The precondition (input list is ascending) is not checked./ fromAscList :: Eq a => [a] -> Set a fromAscList xs = fromDistinctAscList (combineEq xs) @@ -1119,7 +1119,7 @@ fromAscList xs = fromDistinctAscList (combineEq xs) {-# INLINABLE fromAscList #-} #endif --- | /O(n)/. Build a set from a descending list in linear time. +-- | \(O(n)\). Build a set from a descending list in linear time. -- /The precondition (input list is descending) is not checked./ -- -- @since 0.5.8 @@ -1143,7 +1143,7 @@ combineEq (x : xs) = combineEq' x xs | z == y = combineEq' z ys | otherwise = z : combineEq' y ys --- | /O(n)/. Build a set from an ascending list of distinct elements in linear time. +-- | \(O(n)\). Build a set from an ascending list of distinct elements in linear time. -- /The precondition (input list is strictly ascending) is not checked./ -- For some reason, when 'singleton' is used in fromDistinctAscList or in @@ -1165,7 +1165,7 @@ fromDistinctAscList (x0 : xs0) = go (1::Int) (Bin 1 x0 Tip Tip) xs0 (l :*: (y:ys)) -> case create (s `shiftR` 1) ys of (r :*: zs) -> (link y l r :*: zs) --- | /O(n)/. Build a set from a descending list of distinct elements in linear time. +-- | \(O(n)\). Build a set from a descending list of distinct elements in linear time. -- /The precondition (input list is strictly descending) is not checked./ -- For some reason, when 'singleton' is used in fromDistinctDescList or in @@ -1255,7 +1255,7 @@ instance NFData a => NFData (Set a) where {-------------------------------------------------------------------- Split --------------------------------------------------------------------} --- | /O(log n)/. The expression (@'split' x set@) is a pair @(set1,set2)@ +-- | \(O(\log n)\). The expression (@'split' x set@) is a pair @(set1,set2)@ -- where @set1@ comprises the elements of @set@ less than @x@ and @set2@ -- comprises the elements of @set@ greater than @x@. split :: Ord a => a -> Set a -> (Set a,Set a) @@ -1271,7 +1271,7 @@ splitS x (Bin _ y l r) EQ -> (l :*: r) {-# INLINABLE splitS #-} --- | /O(log n)/. Performs a 'split' but also returns whether the pivot +-- | \(O(\log n)\). Performs a 'split' but also returns whether the pivot -- element was found in the original set. splitMember :: Ord a => a -> Set a -> (Set a,Bool,Set a) splitMember _ Tip = (Tip, False, Tip) @@ -1292,7 +1292,7 @@ splitMember x (Bin _ y l r) Indexing --------------------------------------------------------------------} --- | /O(log n)/. Return the /index/ of an element, which is its zero-based +-- | \(O(\log n)\). Return the /index/ of an element, which is its zero-based -- index in the sorted sequence of elements. The index is a number from /0/ up -- to, but not including, the 'size' of the set. Calls 'error' when the element -- is not a 'member' of the set. @@ -1318,7 +1318,7 @@ findIndex = go 0 {-# INLINABLE findIndex #-} #endif --- | /O(log n)/. Lookup the /index/ of an element, which is its zero-based index in +-- | \(O(\log n)\). Lookup the /index/ of an element, which is its zero-based index in -- the sorted sequence of elements. The index is a number from /0/ up to, but not -- including, the 'size' of the set. -- @@ -1343,7 +1343,7 @@ lookupIndex = go 0 {-# INLINABLE lookupIndex #-} #endif --- | /O(log n)/. Retrieve an element by its /index/, i.e. by its zero-based +-- | \(O(\log n)\). Retrieve an element by its /index/, i.e. by its zero-based -- index in the sorted sequence of elements. If the /index/ is out of range (less -- than zero, greater or equal to 'size' of the set), 'error' is called. -- @@ -1363,7 +1363,7 @@ elemAt i (Bin _ x l r) where sizeL = size l --- | /O(log n)/. Delete the element at /index/, i.e. by its zero-based index in +-- | \(O(\log n)\). Delete the element at /index/, i.e. by its zero-based index in -- the sorted sequence of elements. If the /index/ is out of range (less than zero, -- greater or equal to 'size' of the set), 'error' is called. -- @@ -1427,7 +1427,7 @@ drop i0 m0 = go i0 m0 EQ -> insertMin x r where sizeL = size l --- | /O(log n)/. Split a set at a particular index. +-- | \(O(\log n)\). Split a set at a particular index. -- -- @ -- splitAt !n !xs = ('take' n xs, 'drop' n xs) @@ -1448,7 +1448,7 @@ splitAt i0 m0 EQ -> l :*: insertMin x r where sizeL = size l --- | /O(log n)/. Take while a predicate on the elements holds. +-- | \(O(\log n)\). Take while a predicate on the elements holds. -- The user is responsible for ensuring that for all elements @j@ and @k@ in the set, -- @j \< k ==\> p j \>= p k@. See note at 'spanAntitone'. -- @@ -1465,7 +1465,7 @@ takeWhileAntitone p (Bin _ x l r) | p x = link x l (takeWhileAntitone p r) | otherwise = takeWhileAntitone p l --- | /O(log n)/. Drop while a predicate on the elements holds. +-- | \(O(\log n)\). Drop while a predicate on the elements holds. -- The user is responsible for ensuring that for all elements @j@ and @k@ in the set, -- @j \< k ==\> p j \>= p k@. See note at 'spanAntitone'. -- @@ -1482,7 +1482,7 @@ dropWhileAntitone p (Bin _ x l r) | p x = dropWhileAntitone p r | otherwise = link x (dropWhileAntitone p l) r --- | /O(log n)/. Divide a set at the point where a predicate on the elements stops holding. +-- | \(O(\log n)\). Divide a set at the point where a predicate on the elements stops holding. -- The user is responsible for ensuring that for all elements @j@ and @k@ in the set, -- @j \< k ==\> p j \>= p k@. -- @@ -1577,7 +1577,7 @@ glue l@(Bin sl xl ll lr) r@(Bin sr xr rl rr) | sl > sr = let !(m :*: l') = maxViewSure xl ll lr in balanceR m l' r | otherwise = let !(m :*: r') = minViewSure xr rl rr in balanceL m l r' --- | /O(log n)/. Delete and find the minimal element. +-- | \(O(\log n)\). Delete and find the minimal element. -- -- > deleteFindMin set = (findMin set, deleteMin set) @@ -1586,7 +1586,7 @@ deleteFindMin t | Just r <- minView t = r | otherwise = (error "Set.deleteFindMin: can not return the minimal element of an empty set", Tip) --- | /O(log n)/. Delete and find the maximal element. +-- | \(O(\log n)\). Delete and find the maximal element. -- -- > deleteFindMax set = (findMax set, deleteMax set) deleteFindMax :: Set a -> (a,Set a) @@ -1602,7 +1602,7 @@ minViewSure = go case go xl ll lr of xm :*: l' -> xm :*: balanceR x l' r --- | /O(log n)/. Retrieves the minimal key of the set, and the set +-- | \(O(\log n)\). Retrieves the minimal key of the set, and the set -- stripped of that element, or 'Nothing' if passed an empty set. minView :: Set a -> Maybe (a, Set a) minView Tip = Nothing @@ -1616,7 +1616,7 @@ maxViewSure = go case go xr rl rr of xm :*: r' -> xm :*: balanceL x l r' --- | /O(log n)/. Retrieves the maximal key of the set, and the set +-- | \(O(\log n)\). Retrieves the maximal key of the set, and the set -- stripped of that element, or 'Nothing' if passed an empty set. maxView :: Set a -> Maybe (a, Set a) maxView Tip = Nothing @@ -1759,7 +1759,7 @@ bin x l r Utilities --------------------------------------------------------------------} --- | /O(1)/. Decompose a set into pieces based on the structure of the underlying +-- | \(O(1)\). Decompose a set into pieces based on the structure of the underlying -- tree. This function is useful for consuming a set in parallel. -- -- No guarantee is made as to the sizes of the pieces; an internal, but @@ -1805,7 +1805,7 @@ powerSet :: Set a -> Set (Set a) powerSet xs0 = insertMin empty (foldr' step Tip xs0) where step x pxs = insertMin (singleton x) (insertMin x `mapMonotonic` pxs) `glue` pxs --- | /O(m*n)/ (conjectured). Calculate the Cartesian product of two sets. +-- | \(O(mn)\) (conjectured). Calculate the Cartesian product of two sets. -- -- @ -- cartesianProduct xs ys = fromList $ liftA2 (,) (toList xs) (toList ys) @@ -1875,14 +1875,14 @@ disjointUnion as bs = merge (mapMonotonic Left as) (mapMonotonic Right bs) {-------------------------------------------------------------------- Debugging --------------------------------------------------------------------} --- | /O(n)/. Show the tree that implements the set. The tree is shown +-- | \(O(n)\). Show the tree that implements the set. The tree is shown -- in a compressed, hanging format. showTree :: Show a => Set a -> String showTree s = showTreeWith True False s -{- | /O(n)/. The expression (@showTreeWith hang wide map@) shows +{- | \(O(n)\). The expression (@showTreeWith hang wide map@) shows the tree that implements the set. If @hang@ is @True@, a /hanging/ tree is shown otherwise a rotated tree is shown. If @wide@ is 'True', an extra wide version is shown. @@ -1969,7 +1969,7 @@ withEmpty bars = " ":bars {-------------------------------------------------------------------- Assertions --------------------------------------------------------------------} --- | /O(n)/. Test if the internal set structure is valid. +-- | \(O(n)\). Test if the internal set structure is valid. valid :: Ord a => Set a -> Bool valid t = balanced t && ordered t && validsize t