Add foldSubmap and submap

Addresses #113 and #71.

Author: hdgarrood

src/Data/Map.purs

@@ -273,41 +273,83 @@ findMin (Three left k1 v1 _ _ _ _) = Just $ fromMaybe { key: k1, value: v1 } $ f
 foldSubmap :: forall k v m. Ord k => Monoid m => Maybe k -> Maybe k -> (k -> v -> m) -> Map k v -> m
 foldSubmap kmin kmax f =
   let
-    geqMin = case kmin of
-               Just kmin' ->
-                 \x -> x >= kmin'
-               Nothing ->
-                 const true
-    leqMax = case kmax of
-               Just kmax' ->
-                 \x -> x <= kmax'
-               Nothing ->
-                 const true
-
+    tooSmall =
+      case kmin of
+        Just kmin' ->
+          \k -> k < kmin'
+        Nothing ->
+          const false
+
+    tooLarge =
+      case kmax of
+        Just kmax' ->
+          \k -> k > kmax'
+        Nothing ->
+          const false
+
+    inBounds =
+      case kmin, kmax of
+        Just kmin', Just kmax' ->
+          \k -> kmin' <= k && k <= kmax'
+        Just kmin', Nothing ->
+          \k -> kmin' <= k
+        Nothing, Just kmax' ->
+          \k -> k <= kmax'
+        Nothing, Nothing ->
+          const true
+
+    -- We can take advantage of the invariants of the tree structure to reduce
+    -- the amount of work we need to do. For example, in the following tree:
+    --
+    --      [2][4]
+    --      / |  \
+    --     /  |   \
+    --   [1] [3] [5]
+    --
+    -- If we are given a lower bound of 3, we do not need to inspect the left
+    -- subtree, because we know that every entry in it is less than or equal to
+    -- 2. Similarly, if we are given a lower bound of 5, we do not need to
+    -- inspect the central subtree, because we know that every entry in it must
+    -- be less than or equal to 4.
+    --
+    -- Unfortunately we cannot extract `if cond then x else mempty` into a
+    -- function because of strictness.
     go = case _ of
       Leaf ->
         mempty
       Two left k v right ->
-           (if geqMin k then go left else mempty)
-        <> (if geqMin k && leqMax k then f k v else mempty)
-        <> (if leqMax k then go right else mempty)
+           (if tooSmall k then mempty else go left)
+        <> (if inBounds k then f k v else mempty)
+        <> (if tooLarge k then mempty else go right)
       Three left k1 v1 mid k2 v2 right ->
-           (if geqMin k1 then go left else mempty)
-        <> (if geqMin k1 && leqMax k1 then f k1 v1 else mempty)
-        <> (if geqMin k1 && leqMax k2 then go mid else mempty)
-        <> (if geqMin k2 && leqMax k2 then f k2 v2 else mempty)
-        <> (if leqMax k2 then go right else mempty)
+           (if tooSmall k1 then mempty else go left)
+        <> (if inBounds k1 then f k1 v1 else mempty)
+        <> (if tooSmall k2 || tooLarge k1 then mempty else go mid)
+        <> (if inBounds k2 then f k2 v2 else mempty)
+        <> (if tooLarge k2 then mempty else go right)
   in
     go
 
--- | Returns a new map containing all entries of the argument map which lie
+-- | Returns a new map containing all entries of the given map which lie
 -- | between a given lower and upper bound, treating `Nothing` as no bound i.e.
 -- | including the smallest (or largest) key in the map, no matter how small
--- | (or large) it is. The function is entirely specified by the following
+-- | (or large) it is. For example:
+-- |
+-- | ```purescript
+-- | submap (Just 1) (Just 2)
+-- |   (fromFoldable [Tuple 0 "zero", Tuple 1 "one", Tuple 2 "two", Tuple 3 "three"])
+-- |   == fromFoldable [Tuple 1 "one", Tuple 2 "two"]
+-- |
+-- | submap Nothing (Just 2)
+-- |   (fromFoldable [Tuple 0 "zero", Tuple 1 "one", Tuple 2 "two", Tuple 3 "three"])
+-- |   == fromFoldable [Tuple 0 "zero", Tuple 1 "one", Tuple 2 "two"]
+-- | ```
+-- |
+-- | The function is entirely specified by the following
 -- | property:
 -- |
 -- | ```purescript
--- | forall m :: Map k v, mmin :: Maybe k, mmax :: Maybe k, key :: k,
+-- | Given any m :: Map k v, mmin :: Maybe k, mmax :: Maybe k, key :: k,
 -- |   let m' = submap mmin mmax m in
 -- |     if (maybe true (\min -> min <= key) mmin &&
 -- |         maybe true (\max -> max >= key) mmax)