Cleanup round

* Moved Empty and Leaf1 into the recursive part of the R-tree for performance;

* Removed the .Strict qualifier from module names (since these trees cannot be lazy) and
  added .D2 to signify two-dimensionality;

* Clarified time complexities;

* Merged tree debugging into a single function;

* Generalized tests;

* Bumped version to 1.2.0;

Author: BurningWitness

README.md

@@ -1,15 +1,5 @@
-R-Trees (and in the future also R*-Trees)
-====================
+data-r-tree
 
-R-Tree is a spatial data structure similar to Quadtrees or B-Trees.
+---
 
-An R-Tree is a balanced tree and optimized for lookups. This implemetation useses an R-Tree to privide
-a map to arbitrary values.
-
-Some function names clash with "Prelude" names, therefore this module is usually
-imported ```qualified```, e.g.:
-
-    > import           Data.RTree (RTree)
-    > import qualified Data.RTree as RT
-
-this implemetation is incomplete at the moment. Feel free to send comments, patches or merge requests.
+R/R\*-trees, currently only two-dimensional `Float` and `Double` varieties.

benchmark/space/Main.hs

@@ -2,7 +2,7 @@
 
 module Main where
 
-import qualified Data.RTree.Float.Strict as R
+import qualified Data.RTree.D2.Float as R
 
 import           Control.Monad
 import           Data.Foldable

benchmark/time/Main.hs

@@ -4,8 +4,8 @@
 
 module Main where
 
-import           Data.RTree.Double.Strict (RTree, MBR, Predicate)
-import qualified Data.RTree.Double.Strict as R
+import           Data.RTree.D2.Double (RTree, MBR, Predicate)
+import qualified Data.RTree.D2.Double as R
 
 import           Control.DeepSeq
 import           Control.Monad
@@ -80,7 +80,7 @@ map cat from name pre =
       ) $ \ ~(r, brs) ->
     bench (cat <> "/map/" <> name) $
       flip nf brs $
-             fmap $ \x -> [R.mapRangeWithKey (pre x) (\_ -> (+) 1) r]
+             fmap $ \x -> [R.adjustRangeWithKey (pre x) (\_ -> (+) 1) r]
 
 traversal
   :: String -> ([(MBR, Int)] -> RTree Int)

changelog.md

@@ -1,4 +1,4 @@
-## 1.1.0
+## 1.2.0
 
 Proper rewrite of the library.
 Additions are not listed, only the most important changes are.
@@ -19,32 +19,35 @@ Additions are not listed, only the most important changes are.
 
 * `RTree`:
 
-  - `Data.RTree` is now called `Data.RTree.*.Strict`;
+  - `Data.RTree` is now called `Data.RTree.D2.Double`;
 
-  - Internals are now exposed in `Data.RTree.*.Strict.Unsafe`;
+  - Internals are now exposed in `Data.RTree.D2.Double.Unsafe`;
 
   - `Binary`, `Generic`, `Monoid` and `Semigroup` instances were removed;
 
   - `insertWith`, `union`, `unionWith` and `mapMaybe`,
     `fromList`, `toList`, `keys` and `values` were removed;
 
-  - `length` and `null` are now only accessible from the `Foldable` typeclass;
+  - `length` is now named `size`;
 
   - Conversions between lookup functions:
 
-    - `lookup` is `\ba -> getFirst . foldMap (equals ba) (First . Just)`;
+    - `lookup` is `\ba -> foldrRangeWithKey (equals ba) (\_ x _ -> Just x) Nothing`;
 
-    - `intersect` is `\ba -> foldMap (intersects ba) pure`;
+    - `intersect` is `\ba -> foldrRangeWithKey (intersects ba) (\_ -> (:)) []`;
 
-    - `intersectWithKey` is `\ba -> foldMapWithKey (intersects ba) pure`;
+    - `intersectWithKey` is
+      `\ba -> foldrRangeWithKey (intersects ba) (\bx x -> (:) (bx, x)) []`;
 
-    - `lookupRange` is `\ba -> foldMap (contains ba) pure`;
+    - `lookupRange` is `\ba -> foldrRangeWithKey (containedBy ba) (\_ -> (:)) []`;
 
-    - `lookupRangeWithKey` is `\ba -> foldMapWithKey (contains ba) pure`;
+    - `lookupRangeWithKey` is
+      `\ba -> foldrRangeWithKey (containedBy ba) (\bx x -> (:) (bx, x)) []`;
 
-    - `lookupContainsRange` is `\ba -> foldMap (containedBy ba) pure`;
+    - `lookupContainsRange` is `\ba -> foldrRangeWithKey (contains ba) (\_ -> (:)) []`;
 
-    - `lookupContainsRangeWithKey` is `\ba -> foldMapWithKey (containedBy ba) pure`;
+    - `lookupContainsRangeWithKey` is
+      `\ba -> foldrRangeWithKey (contains ba) (\bx x -> (:) (bx, x)) []`;
 
 ## 0.6.0
 

data-r-tree.cabal

@@ -1,10 +1,9 @@
 cabal-version: 2.2
 
 name:                   data-r-tree
-version:                1.1.0
-synopsis:               Two-dimensional R-trees.
-description:            Two-dimensional spatial trees utilizing R-tree and R*-tree
-                        algorithms.
+version:                1.2.0
+synopsis:               R/R*-trees.
+description:            Spatial trees utilizing R-tree and R*-tree algorithms.
 
 license:                MIT
 license-file:           LICENSE
@@ -32,15 +31,15 @@ library
 
   hs-source-dirs:       src
 
-  exposed-modules:      Data.RTree.Double.Strict
-                        Data.RTree.Double.Strict.Debug
-                        Data.RTree.Double.Strict.Unsafe
-                        Data.RTree.Float.Strict
-                        Data.RTree.Float.Strict.Debug
-                        Data.RTree.Float.Strict.Unsafe
+  exposed-modules:      Data.RTree.D2.Double
+                        Data.RTree.D2.Double.Debug
+                        Data.RTree.D2.Double.Unsafe
+                        Data.RTree.D2.Float
+                        Data.RTree.D2.Float.Debug
+                        Data.RTree.D2.Float.Unsafe
 
-  other-modules:        Data.RTree.Double.Strict.Internal
-                        Data.RTree.Float.Strict.Internal
+  other-modules:        Data.RTree.D2.Double.Internal
+                        Data.RTree.D2.Float.Internal
 
   ghc-options:          -Wall
 

no/Data/NoTree/Strict.hs renamed to no/No/Tree/D2.hs

@@ -6,9 +6,9 @@
      Every fold/map is \(O (n)\).
 -}
 
-module Data.NoTree.Strict where
+module No.Tree.D2 where
 
-import           Data.RTree.Double.Strict.Unsafe (MBR (..), Predicate (..))
+import           Data.RTree.D2.Double.Unsafe (MBR (..), Predicate (..))
 
 import           Control.DeepSeq
 import qualified Data.Foldable as Fold
@@ -70,8 +70,8 @@ delete ba no = let (xs, ys) = break ((== ba) . fst) $ toList no
 mapWithKey :: (MBR -> a -> b) -> NoTree a -> NoTree b
 mapWithKey f = NoTree . fmap (\ ~(ba, a) -> (ba, f ba a) ) . toList
 
-mapRangeWithKey :: Predicate -> (MBR -> a -> a) -> NoTree a -> NoTree a
-mapRangeWithKey (Predicate _ checkLeaf) f =
+adjustRangeWithKey :: Predicate -> (MBR -> a -> a) -> NoTree a -> NoTree a
+adjustRangeWithKey (Predicate _ checkLeaf) f =
   NoTree . fmap (\(ba, a) -> (ba, opt ba a)) . toList
   where
     opt ba a | checkLeaf ba = f ba a

src/Data/RTree/Double/Strict.hs renamed to src/Data/RTree/D2/Double.hs

@@ -1,5 +1,7 @@
+{-# LANGUAGE PatternSynonyms #-}
+
 {- |
-     Module     : Data.RTree.Double.Strict
+     Module     : Data.RTree.D2.Double
      Copyright  : Copyright (c) 2015, Birte Wagner, Sebastian Philipp
                   Copyright (c) 2022, Oleksii Divak
      License    : MIT
@@ -8,7 +10,7 @@
      Stability  : experimental
      Portability: not portable
 
-     @'RTree' a@ represents a two-dimensional spatial tree
+     @'RTree' a@ is a spine-strict two-dimensional spatial tree
      from bounding rectangles of type 'Double' to values of type @a@.
 
      R-trees have no notion of element order, as such:
@@ -23,15 +25,22 @@
 
      == Laziness
 
-     Evaluating the root of the tree (i.e. @(_ :: 'RTree' a)@) to WHNF evaluates the entire
-     spine of the tree to normal form. This does not apply to values however, as such
-     care must be taken to evaluate values properly before inserting them.
+     Evaluating the root of the tree (i.e. @(_ :: 'RTree' a)@) to WHNF
+     evaluates the entire spine of the tree to normal form.
+
+     Functions do not perform any additional evaluations unless
+     their documentation directly specifies so.
 
      == Performance
 
-     Unless noted otherwise, operation complexity specified is worst-case.
+     Each function's time complexity is provided in the documentation.
+     
      \(n\) refers to the total number of entries in the tree.
 
+     \(r\) refers to the time complexity of the chosen 'Predicate' lookup,
+     ranging from \(\mathcal{O}(\log n)\) (well-balanced)
+     to \(\mathcal{O}(n)\) (worst-case) depending on tree quality.
+
      == Implementation
 
      The implementation is heavily specialized for constants
@@ -53,46 +62,27 @@
          <https://ia800900.us.archive.org/27/items/nasa_techdoc_19970016975/19970016975.pdf>
 -}
 
-module Data.RTree.Double.Strict
+module Data.RTree.D2.Double
   ( MBR (MBR)
   , RTree
 
-    -- * Construction
+    -- * Construct
   , empty
   , singleton
 
-    -- * Queries
-    -- ** Value-only
-    -- *** Map
-  , Data.RTree.Double.Strict.Internal.map
-  , map'
-
-    -- *** Fold
-  , Data.RTree.Double.Strict.Internal.foldl
-  , Data.RTree.Double.Strict.Internal.foldr
-  , Data.RTree.Double.Strict.Internal.foldMap
-  , Data.RTree.Double.Strict.Internal.foldl'
-  , Data.RTree.Double.Strict.Internal.foldr'
-
-    -- *** Traversal
-  , Data.RTree.Double.Strict.Internal.traverse
-
-    -- ** MBR/value
-    -- *** Map
-  , mapWithKey
-  , mapWithKey'
+    -- ** Bulk-loading
+  , bulkSTR
 
-    -- *** Fold
-  , foldlWithKey
-  , foldrWithKey
-  , foldMapWithKey
-  , foldlWithKey'
-  , foldrWithKey'
+    -- * Single-key
+    -- ** Insert
+  , insert
+  , insertGut
 
-    -- *** Traversal
-  , traverseWithKey
+    -- ** Delete
+  , delete
 
-    -- ** Range
+    -- * Range
+    -- | NOTE: both 'Predicate's and functions using them inline heavily.
   , Predicate
   , equals
   , intersects
@@ -102,39 +92,63 @@ module Data.RTree.Double.Strict
   , containedBy
   , containedBy'
 
-    -- *** Map
-  , mapRangeWithKey
-  , mapRangeWithKey'
+    -- ** Map
+  , adjustRangeWithKey
+  , adjustRangeWithKey'
 
-    -- *** Fold
+    -- ** Fold
   , foldlRangeWithKey
   , foldrRangeWithKey
   , foldMapRangeWithKey
   , foldlRangeWithKey'
   , foldrRangeWithKey'
 
-    -- *** Traversal
+    -- ** Traverse
   , traverseRangeWithKey
 
-    -- * Insertion
-  , insert
-  , insertGut
+    -- * Full tree
+    -- ** Size
+  , Data.RTree.D2.Double.Internal.null
+  , size
 
-    -- * Deletion
-  , delete
+    -- ** Map
+  , Data.RTree.D2.Double.Internal.map
+  , map'
+  , mapWithKey
+  , mapWithKey'
 
-    -- * Bulk-loading
-  , bulkSTR
+    -- ** Fold
+    -- | === Left-to-right
+  , Data.RTree.D2.Double.Internal.foldl
+  , Data.RTree.D2.Double.Internal.foldl'
+  , foldlWithKey
+  , foldlWithKey'
+
+    -- | === Right-to-left
+  , Data.RTree.D2.Double.Internal.foldr
+  , Data.RTree.D2.Double.Internal.foldr'
+  , foldrWithKey
+  , foldrWithKey'
+
+    -- | === Monoid
+  , Data.RTree.D2.Double.Internal.foldMap
+  , foldMapWithKey
+
+    -- ** Traverse
+  , Data.RTree.D2.Double.Internal.traverse
+  , traverseWithKey
   ) where
 
-import           Data.RTree.Double.Strict.Internal
+import           Data.RTree.D2.Double.Internal
 
 
 
--- | \(\mathcal{O}(1)\). Empty R-tree.
+-- | \(\mathcal{O}(1)\).
+--   Empty tree.
 empty :: RTree a
 empty = Empty
 
--- | \(\mathcal{O}(1)\). R-tree with a single entry.
+-- | \(\mathcal{O}(1)\).
+--   Tree with a single entry.
 singleton :: MBR -> a -> RTree a
 singleton = Leaf1