Add/correct some time complexities (#889)

Added:
* Set: take, drop, powerSet, disjointUnion
* Map: take, drop, splitMember

Corrected:
* Set: cartesianProduct, showTree, showTreeWith
* Map: showTree, showTreeWith
* IntSet: lookupLT, lookupGT, lookupLE, lookupGE, showTree, showTreeWith
* IntMap: lookupLT, lookupGT, lookupLE, lookupGE, alterF, showTree, showTreeWith

* Update comments with complexity analysis

Author: meooow25

containers/src/Data/IntMap/Internal.hs

@@ -616,7 +616,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(\min(n,W))\). Find largest key smaller than the given one and return the
 -- corresponding (key, value) pair.
 --
 -- > lookupLT 3 (fromList [(3,'a'), (5,'b')]) == Nothing
@@ -637,7 +637,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(\min(n,W))\). 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')
@@ -658,7 +658,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(\min(n,W))\). 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
@@ -680,7 +680,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(\min(n,W))\). 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')
@@ -1010,7 +1010,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(\min(n,W))\). 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)@.
@@ -3550,14 +3550,14 @@ splitRoot orig =
   Debugging
 --------------------------------------------------------------------}
 
--- | \(O(n)\). Show the tree that implements the map. The tree is shown
+-- | \(O(n \min(n,W))\). 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 \min(n,W))\). 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.

containers/src/Data/IntSet/Internal.hs

@@ -352,7 +352,7 @@ member !x = go
 notMember :: Key -> IntSet -> Bool
 notMember k = not . member k
 
--- | \(O(\log n)\). Find largest element smaller than the given one.
+-- | \(O(\min(n,W))\). Find largest element smaller than the given one.
 --
 -- > lookupLT 3 (fromList [3, 5]) == Nothing
 -- > lookupLT 5 (fromList [3, 5]) == Just 3
@@ -373,7 +373,7 @@ lookupLT !x t = case t of
     go def Nil = unsafeFindMax def
 
 
--- | \(O(\log n)\). Find smallest element greater than the given one.
+-- | \(O(\min(n,W))\). Find smallest element greater than the given one.
 --
 -- > lookupGT 4 (fromList [3, 5]) == Just 5
 -- > lookupGT 5 (fromList [3, 5]) == Nothing
@@ -394,7 +394,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(\min(n,W))\). Find largest element smaller or equal to the given one.
 --
 -- > lookupLE 2 (fromList [3, 5]) == Nothing
 -- > lookupLE 4 (fromList [3, 5]) == Just 3
@@ -416,7 +416,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(\min(n,W))\). Find smallest element greater or equal to the given one.
 --
 -- > lookupGE 3 (fromList [3, 5]) == Just 3
 -- > lookupGE 4 (fromList [3, 5]) == Just 5
@@ -1353,14 +1353,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 \min(n,W))\). 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 \min(n,W))\). 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.

containers/src/Data/Map/Internal.hs

@@ -1489,7 +1489,7 @@ elemAt i (Bin _ kx x l r)
   where
     sizeL = size l
 
--- | Take a given number of entries in key order, beginning
+-- | \(O(\log n)\). Take a given number of entries in key order, beginning
 -- with the smallest keys.
 --
 -- @
@@ -1511,7 +1511,7 @@ take i0 m0 = go i0 m0
         EQ -> l
       where sizeL = size l
 
--- | Drop a given number of entries in key order, beginning
+-- | \(O(\log n)\). Drop a given number of entries in key order, beginning
 -- with the smallest keys.
 --
 -- @
@@ -3831,7 +3831,7 @@ splitLookup k0 m = case go k0 m of
 {-# INLINABLE splitLookup #-}
 #endif
 
--- | A variant of 'splitLookup' that indicates only whether the
+-- | \(O(\log n)\). A variant of 'splitLookup' that indicates only whether the
 -- key was present, rather than producing its value. This is used to
 -- implement 'intersection' to avoid allocating unnecessary 'Just'
 -- constructors.

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 \log 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 \log 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.

containers/src/Data/Set/Internal.hs

@@ -1407,7 +1407,7 @@ deleteAt !i t =
       where
         sizeL = size l
 
--- | Take a given number of elements in order, beginning
+-- | \(O(\log n)\). Take a given number of elements in order, beginning
 -- with the smallest ones.
 --
 -- @
@@ -1428,7 +1428,7 @@ take i0 m0 = go i0 m0
         EQ -> l
       where sizeL = size l
 
--- | Drop a given number of elements in order, beginning
+-- | \(O(\log n)\). Drop a given number of elements in order, beginning
 -- with the smallest ones.
 --
 -- @
@@ -1809,7 +1809,7 @@ splitRoot orig =
 {-# INLINE splitRoot #-}
 
 
--- | Calculate the power set of a set: the set of all its subsets.
+-- | \(O(2^n \log n)\). Calculate the power set of a set: the set of all its subsets.
 --
 -- @
 -- t ``member`` powerSet s == t ``isSubsetOf`` s
@@ -1823,11 +1823,22 @@ splitRoot orig =
 -- @
 --
 -- @since 0.5.11
+
+-- Proof of complexity: step executes n times. At the ith step,
+-- "insertMin x `mapMonotonic` pxs" takes O(2^i log i) time since pxs has size
+-- 2^i - 1 and we insertMin into its elements which are sets of size <= i.
+-- "insertMin (singleton x)" and "`glue` pxs" are cheaper operations that both
+-- take O(i) time. Over n steps, we have a total cost of
+--
+--   O(\sum_{i=1}^{n-1} 2^i log i)
+-- = O(log n * \sum_{i=1}^{n-1} 2^i)
+-- = O(2^n log n)
+
 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(mn)\) (conjectured). Calculate the Cartesian product of two sets.
+-- | \(O(nm)\). Calculate the Cartesian product of two sets.
 --
 -- @
 -- cartesianProduct xs ys = fromList $ liftA2 (,) (toList xs) (toList ys)
@@ -1842,11 +1853,7 @@ powerSet xs0 = insertMin empty (foldr' step Tip xs0) where
 --
 -- @since 0.5.11
 cartesianProduct :: Set a -> Set b -> Set (a, b)
--- I don't know for sure if this implementation (slightly modified from one
--- that Edward Kmett hacked together) is optimal. TODO: try to prove or
--- refute it.
---
--- We could definitely get big-O optimal (O(m * n)) in a rather simple way:
+-- The obvious big-O optimal (O(nm)) implementation would be
 --
 --   cartesianProduct _as Tip = Tip
 --   cartesianProduct as bs = fromDistinctAscList
@@ -1855,8 +1862,31 @@ cartesianProduct :: Set a -> Set b -> Set (a, b)
 -- Unfortunately, this is much slower in practice, at least when the sets are
 -- constructed from ascending lists. I tried doing the same thing using a
 -- known-length (perfect balancing) variant of fromDistinctAscList, but it
--- still didn't come close to the performance of Kmett's version in my very
--- informal tests.
+-- still didn't come close to the performance of the implementation we use in my
+-- very informal tests.
+--
+-- The implementation we use (slightly modified from one that Edward Kmett
+-- hacked together) is also optimal but performs better in practice. We map
+-- each element a in as to a set made up of (a,b) for every element b in bs,
+-- taking O(nm) overall. Then we merge these sets up the tree of as, which takes
+-- O(n log m). A brief sketch of proof for the latter:
+--
+-- Consider all nodes in the tree at the same distance from the root to be at
+-- the same "level". The nodes farthest from the root are at level 0, with
+-- levels increasing by 1 towards the root. Being a balanced tree, there are
+-- O(n/2^i) nodes at level i. At every node at level i, we merge the merged left
+-- set, current set, and merged right set into a set of size O(2^i*m) in
+-- O(log (2^i*m)) = O(i + log m) time. Over all levels, we do a total work of
+--
+--   O(\sum_{i=0}^{root_level} n * (i + log m) / 2^i)
+-- = O(  \sum_{i=0}^{root_level} n * i / 2^i
+--     + \sum_{i=0}^{root_level} n * log m / 2^i)
+-- = O(  n * \sum_{i=0}^{root_level} i/2^i
+--     + n * log m * \sum_{i=0}^{root_level} 1/2^i)
+-- = O(  n * \sum_{i=0}^{inf} i/2^i
+--     + n * log m * \sum_{i=0}^{inf} 1/2^i)
+--
+-- The sum terms converge, and we get O(n log m).
 
 -- When the second argument has at most one element, we can be a little
 -- clever.
@@ -1879,7 +1909,7 @@ instance Monoid (MergeSet a) where
 
   mappend = (<>)
 
--- | Calculate the disjoint union of two sets.
+-- | \(O(n+m)\). Calculate the disjoint union of two sets.
 --
 -- @ disjointUnion xs ys = map Left xs ``union`` map Right ys @
 --
@@ -1897,14 +1927,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 \log 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 \log 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.