Clear warnings in docs for some construction funcs

haskell · Jan 6, 2025 · 6435801 · 6435801
1 parent 32c80d8
commit 6435801
Show file tree

Hide file tree

Showing 6 changed files with 137 additions and 33 deletions.
diff --git a/containers/src/Data/IntMap/Internal.hs b/containers/src/Data/IntMap/Internal.hs
@@ -2618,7 +2618,6 @@ mapKeysWith c f
 -- @'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@.
--- /The precondition is not checked./
 -- Semi-formally, we have:
 --
 -- > and [x < y ==> f x < f y | x <- ls, y <- ls]
@@ -2628,6 +2627,10 @@ mapKeysWith c f
 -- This means that @f@ maps distinct original keys to distinct resulting keys.
 -- This function has slightly better performance than 'mapKeys'.
 --
+-- __Warning__: This function should be used only if @f@ is monotonically
+-- strictly increasing. This precondition is not checked. Use 'mapKeys' if the
+-- precondition may not hold.
+--
 -- > mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]
 
 mapKeysMonotonic :: (Key->Key) -> IntMap a -> IntMap a
@@ -3338,6 +3341,10 @@ fromListWithKey f xs
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order.
 --
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
+--
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
 
@@ -3347,7 +3354,10 @@ fromAscList = fromMonoListWithKey Nondistinct (\_ x _ -> x)
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 --
@@ -3359,7 +3369,10 @@ fromAscListWith f = fromMonoListWithKey Nondistinct (\_ x y -> f x y)
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
 -- > fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "5:b|a")]
@@ -3372,7 +3385,10 @@ fromAscListWithKey f = fromMonoListWithKey Nondistinct f
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 

diff --git a/containers/src/Data/IntMap/Strict/Internal.hs b/containers/src/Data/IntMap/Strict/Internal.hs
@@ -1136,6 +1136,10 @@ fromListWithKey f xs
 -- | \(O(n)\). Build a map from a list of key\/value pairs where
 -- the keys are in ascending order.
 --
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
+--
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
 
@@ -1145,7 +1149,10 @@ fromAscList = fromMonoListWithKey Nondistinct (\_ x _ -> x)
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 --
@@ -1157,7 +1164,10 @@ fromAscListWith f = fromMonoListWithKey Nondistinct (\_ x y -> f x y)
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 --
@@ -1169,7 +1179,10 @@ fromAscListWithKey f = fromMonoListWithKey Nondistinct f
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 

diff --git a/containers/src/Data/IntSet/Internal.hs b/containers/src/Data/IntSet/Internal.hs
@@ -1152,13 +1152,16 @@ map f = fromList . List.map f . toList
 -- | \(O(n)\). The
 --
 -- @'mapMonotonic' f s == 'map' f s@, but works only when @f@ is strictly increasing.
--- /The precondition is not checked./
 -- Semi-formally, we have:
 --
 -- > and [x < y ==> f x < f y | x <- ls, y <- ls]
 -- >                     ==> mapMonotonic f s == map f s
 -- >     where ls = toList s
 --
+-- __Warning__: This function should be used only if @f@ is monotonically
+-- strictly increasing. This precondition is not checked. Use 'map' if the
+-- precondition may not hold.
+--
 -- @since 0.6.3.1
 
 -- Note that for now the test is insufficient to support any fancier implementation.
@@ -1389,13 +1392,19 @@ fromRange (lx,rx)
     {-# INLINE shr1 #-}
 
 -- | \(O(n)\). Build a set from an ascending list of elements.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the elements are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 fromAscList :: [Key] -> IntSet
 fromAscList = fromMonoList
 {-# NOINLINE fromAscList #-}
 
 -- | \(O(n)\). Build a set from an ascending list of distinct elements.
--- /The precondition (input list is strictly ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the elements are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 fromDistinctAscList :: [Key] -> IntSet
 fromDistinctAscList = fromAscList
 {-# INLINE fromDistinctAscList #-}

diff --git a/containers/src/Data/Map/Internal.hs b/containers/src/Data/Map/Internal.hs
@@ -3293,7 +3293,6 @@ mapKeysWith c f m =
 -- @'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@.
--- /The precondition is not checked./
 -- Semi-formally, we have:
 --
 -- > and [x < y ==> f x < f y | x <- ls, y <- ls]
@@ -3303,6 +3302,10 @@ mapKeysWith c f m =
 -- This means that @f@ maps distinct original keys to distinct resulting keys.
 -- This function has better performance than 'mapKeys'.
 --
+-- __Warning__: This function should be used only if @f@ is monotonically
+-- strictly increasing. This precondition is not checked. Use 'mapKeys' if the
+-- precondition may not hold.
+--
 -- > mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")]
 -- > valid (mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")])) == True
 -- > valid (mapKeysMonotonic (\ _ -> 1)     (fromList [(5,"a"), (3,"b")])) == False
@@ -3663,7 +3666,10 @@ foldlFB = foldlWithKey
     fromAscListWith f xs == fromListWith f xs
 --------------------------------------------------------------------}
 -- | \(O(n)\). Build a map from an ascending list in linear time.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
@@ -3675,7 +3681,10 @@ fromAscList xs = fromAscListWithKey (\_ x _ -> x) xs
 {-# INLINE fromAscList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list in linear time.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromDescList [(5,"a"), (3,"b")]          == fromList [(3, "b"), (5, "a")]
 -- > fromDescList [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "b")]
@@ -3689,7 +3698,10 @@ fromDescList xs = fromDescListWithKey (\_ x _ -> x) xs
 {-# INLINE fromDescList #-}  -- INLINE for fusion
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]) == True
@@ -3703,6 +3715,10 @@ fromAscListWith f xs
 -- | \(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./
 --
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
+--
 -- > fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")]) == True
 -- > valid (fromDescListWith (++) [(5,"a"), (3,"b"), (5,"b")]) == False
@@ -3718,7 +3734,10 @@ fromDescListWith f xs
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -3740,7 +3759,10 @@ fromAscListWithKey f xs = ascLinkAll (Foldable.foldl' next Nada xs)
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -3762,7 +3784,10 @@ fromDescListWithKey f xs = descLinkAll (Foldable.foldl' next Nada xs)
 
 
 -- | \(O(n)\). Build a map from an ascending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctAscList [(3,"b"), (5,"a")])          == True
@@ -3789,7 +3814,10 @@ ascLinkAll stk = foldl'Stack (\r kx x l -> link kx x l r) Tip stk
 {-# INLINABLE ascLinkAll #-}
 
 -- | \(O(n)\). Build a map from a descending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly decreasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctDescList [(5,"a"), (3,"b")])          == True

diff --git a/containers/src/Data/Map/Strict/Internal.hs b/containers/src/Data/Map/Strict/Internal.hs
@@ -1570,7 +1570,10 @@ fromListWithKey f xs =
 --------------------------------------------------------------------}
 
 -- | \(O(n)\). Build a map from an ascending list in linear time.
--- /The precondition (input list is ascending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")]
 -- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")]
@@ -1582,7 +1585,10 @@ fromAscList xs
 {-# INLINE fromAscList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list in linear time.
--- /The precondition (input list is descending) is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromList' if the
+-- precondition may not hold.
 --
 -- > fromDescList [(5,"a"), (3,"b")]          == fromList [(3, "b"), (5, "a")]
 -- > fromDescList [(5,"a"), (5,"b"), (3,"a")] == fromList [(3, "b"), (5, "b")]
@@ -1594,7 +1600,10 @@ fromDescList xs
 {-# INLINE fromDescList #-}  -- INLINE for fusion
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]) == True
@@ -1608,7 +1617,10 @@ fromAscListWith f xs
 {-# INLINE fromAscListWith #-}  -- INLINE for fusion
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWith' if
+-- the precondition may not hold.
 --
 -- > fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "ba")]
 -- > valid (fromDescListWith (++) [(5,"a"), (5,"b"), (3,"b")]) == True
@@ -1623,7 +1635,10 @@ fromDescListWith f xs
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-decreasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -1646,7 +1661,10 @@ fromAscListWithKey f xs = ascLinkAll (Foldable.foldl' next Nada xs)
 
 -- | \(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./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- non-increasing order. This precondition is not checked. Use 'fromListWithKey'
+-- if the precondition may not hold.
 --
 -- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
 -- > fromDescListWithKey f [(5,"a"), (5,"b"), (5,"b"), (3,"b")] == fromList [(3, "b"), (5, "5:b5:ba")]
@@ -1668,7 +1686,10 @@ fromDescListWithKey f xs = descLinkAll (Foldable.foldl' next Nada xs)
 {-# INLINE fromDescListWithKey #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from an ascending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly increasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctAscList [(3,"b"), (5,"a")])          == True
@@ -1684,7 +1705,10 @@ fromDistinctAscList xs = ascLinkAll (Foldable.foldl' next Nada xs)
 {-# INLINE fromDistinctAscList #-}  -- INLINE for fusion
 
 -- | \(O(n)\). Build a map from a descending list of distinct elements in linear time.
--- /The precondition is not checked./
+--
+-- __Warning__: This function should be used only if the keys are in
+-- strictly decreasing order. This precondition is not checked. Use 'fromList'
+-- if the precondition may not hold.
 --
 -- > fromDistinctDescList [(5,"a"), (3,"b")] == fromList [(3, "b"), (5, "a")]
 -- > valid (fromDistinctDescList [(5,"a"), (3,"b")])          == True