Adding zippers and pointers to radix trees.

* Also fixes ambiguous links in documentation

* v1.1 bump.

CHANGELOG.md

@@ -1,4 +1,13 @@
-## 1.0.0.0 -- September 2024
+## 1.1.0.0 -- October 2024
+
+* Added `Zipper` modules for non-empty radix trees;
+
+* Removed `Cursor`s from radix tree modules.
+  Their functionality is subsumed by the appropriate `Zipper` modules.
+
+* Added `Pointer` modules for strict radix trees;
+
+## 1.0.0.2 -- September 2024
 
 * Fixed `Data.Zebra.Word.fillRange`.
   Previously it produced malformed trees in certain cases.

radix-tree.cabal

@@ -1,5 +1,5 @@
 name:          radix-tree
-version:       1.0.0.2
+version:       1.1.0.0
 
 category:      Data Structures
 synopsis:      Radix trees
@@ -45,6 +45,7 @@ library
                     Data.RadixTree.Word8.Lazy.Unsafe
                     Data.RadixTree.Word8.Strict
                     Data.RadixTree.Word8.Strict.Debug
+                    Data.RadixTree.Word8.Strict.Pointer
                     Data.RadixTree.Word8.Strict.TH
                     Data.RadixTree.Word8.Strict.Unsafe
 
@@ -54,10 +55,13 @@ library
                     Data.Radix1Tree.Word8.Lazy.Debug
                     Data.Radix1Tree.Word8.Lazy.TH
                     Data.Radix1Tree.Word8.Lazy.Unsafe
+                    Data.Radix1Tree.Word8.Lazy.Zipper
                     Data.Radix1Tree.Word8.Strict
                     Data.Radix1Tree.Word8.Strict.Debug
+                    Data.Radix1Tree.Word8.Strict.Pointer
                     Data.Radix1Tree.Word8.Strict.TH
                     Data.Radix1Tree.Word8.Strict.Unsafe
+                    Data.Radix1Tree.Word8.Strict.Zipper
 
                     Data.Zebra.Word
                     Data.Zebra.Word.Debug
@@ -80,6 +84,7 @@ library
                     Data.RadixNTree.Word8.Lazy.TH
                     Data.RadixNTree.Word8.Strict
                     Data.RadixNTree.Word8.Strict.Debug
+                    Data.RadixNTree.Word8.Strict.Pointer
                     Data.RadixNTree.Word8.Strict.TH
 
                     Data.Zebra.Word.Internal

src/Data/Patricia/Word/Lazy/Internal.hs

@@ -2348,7 +2348,7 @@ lookupMin t   = let !(# a #) = unsafeLookupMin t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMin :: Patricia a -> (# a #)
 unsafeLookupMin t =
   case t of
@@ -2366,7 +2366,7 @@ lookupMinWithKey t   = Just $! unsafeLookupMinWithKey t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMinWithKey :: Patricia a -> Lookup a
 unsafeLookupMinWithKey t =
   case t of
@@ -2386,7 +2386,7 @@ lookupMax t   = let !(# a #) = unsafeLookupMax t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMax :: Patricia a -> (# a #)
 unsafeLookupMax t =
   case t of
@@ -2404,7 +2404,7 @@ lookupMaxWithKey t   = Just $! unsafeLookupMaxWithKey t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMaxWithKey :: Patricia a -> Lookup a
 unsafeLookupMaxWithKey t =
   case t of
@@ -2543,7 +2543,7 @@ data ViewL a = ViewL {-# UNPACK #-} !(Lookup a) !(Patricia a)
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up the leftmost value and return it alongside the tree without it.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeMinView :: Patricia a -> ViewL a
 unsafeMinView t =
   case t of
@@ -2570,7 +2570,7 @@ data ViewR a = ViewR !(Patricia a) {-# UNPACK #-} !(Lookup a)
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up the rightmost value and return it alongside the tree without it.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeMaxView :: Patricia a -> ViewR a
 unsafeMaxView t =
   case t of

src/Data/Patricia/Word/Strict/Internal.hs

@@ -2755,7 +2755,7 @@ lookupMin t   = let !(# a #) = unsafeLookupMin t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMin :: Patricia a -> (# a #)
 unsafeLookupMin t =
   case t of
@@ -2773,7 +2773,7 @@ lookupMinWithKey t   = Just $! unsafeLookupMinWithKey t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMinWithKey :: Patricia a -> Lookup a
 unsafeLookupMinWithKey t =
   case t of
@@ -2793,7 +2793,7 @@ lookupMax t   = let !(# a #) = unsafeLookupMax t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMax :: Patricia a -> (# a #)
 unsafeLookupMax t =
   case t of
@@ -2811,7 +2811,7 @@ lookupMaxWithKey t   = Just $! unsafeLookupMaxWithKey t
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMaxWithKey :: Patricia a -> Lookup a
 unsafeLookupMaxWithKey t =
   case t of
@@ -3011,7 +3011,7 @@ data ViewL a = ViewL {-# UNPACK #-} !(Lookup a) !(Patricia a)
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up the leftmost value and return it alongside the tree without it.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeMinView :: Patricia a -> ViewL a
 unsafeMinView t =
   case t of
@@ -3038,7 +3038,7 @@ data ViewR a = ViewR !(Patricia a) {-# UNPACK #-} !(Lookup a)
 -- | \(\mathcal{O}(\min(n,W))\).
 --   Look up the rightmost value and return it alongside the tree without it.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeMaxView :: Patricia a -> ViewR a
 unsafeMaxView t =
   case t of

src/Data/Radix1Tree/Word8/Lazy.hs

@@ -69,21 +69,6 @@ module Data.Radix1Tree.Word8.Lazy
   , Data.Radix1Tree.Word8.Lazy.member
   , subtree
 
-    -- *** Chunked
-    --
-    -- | Chunked lookup allows providing the key piece by piece while retaining
-    --   the ability to check for early failure.
-    --
-    --   Note that while 'subtree' can be used to achieve the same result,
-    --   it is more expensive allocation-wise, as it must ensure that
-    --   the resulting tree is well-formed after each chunk application.
-  , Cursor
-  , cursor
-  , move
-  , stop
-  , Location (..)
-  , locate
-
     -- ** Insert
   , insert
   , insertWith
@@ -457,18 +442,6 @@ prefix :: Feed1 -> RadixTree a -> Radix1Tree a
 prefix = prefix1
 
 
--- | \(\mathcal{O}(1)\).
---   Make a cursor that points to the root of the tree.
-cursor :: Radix1Tree a -> Cursor a
-cursor = cursor1
-
-{-# INLINE move #-}
--- | \(\mathcal{O}(\min(x,k))\).
---   Move the cursor down by the extent of the given key.
-move :: Feed1 -> Cursor a -> Cursor a
-move = move1
-
-
 
 {-# INLINE insert #-}
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(\min(x,k))\).

src/Data/Radix1Tree/Word8/Lazy/Unsafe.hs

@@ -86,56 +86,56 @@ import           Radix.Word.Foundation
 -- | \(\mathcal{O}(k)\).
 --   Look up a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMin :: Radix1Tree a -> (# a #)
 unsafeLookupMin = unsafeLookupMin1
 
 -- | \(\mathcal{O}(k)\).
 --   Look up a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMinWithKey :: Radix1Tree a -> Lookup1 a
 unsafeLookupMinWithKey = unsafeLookupMinWithKey1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Delete a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeDeleteMin :: Radix1Tree a -> Radix1Tree a
 unsafeDeleteMin = unsafeDeleteMin1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeAdjustMin :: (a -> a) -> Radix1Tree a -> Radix1Tree a
 unsafeAdjustMin = unsafeAdjustMin1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeAdjustMinWithKey :: (Build1 -> a -> a) -> Radix1Tree a -> Radix1Tree a
 unsafeAdjustMinWithKey = unsafeAdjustMinWithKey1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update or delete a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeUpdateMin :: (a -> Maybe a) -> Radix1Tree a -> Radix1Tree a
 unsafeUpdateMin = unsafeUpdateMin1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update or delete a value at the leftmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeUpdateMinWithKey :: (Build1 -> a -> Maybe a) -> Radix1Tree a -> Radix1Tree a
 unsafeUpdateMinWithKey = unsafeUpdateMinWithKey1
 
 -- | \(\mathcal{O}(\min(x,k))\).
 --   Look up the leftmost value and return it alongside the tree without it.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeMinView :: Radix1Tree a -> ViewL1 a
 unsafeMinView = unsafeMinView1
 
@@ -144,56 +144,56 @@ unsafeMinView = unsafeMinView1
 -- | \(\mathcal{O}(k)\).
 --   Look up a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMax :: Radix1Tree a -> (# a #)
 unsafeLookupMax = unsafeLookupMax1
 
 -- | \(\mathcal{O}(k)\).
 --   Look up a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeLookupMaxWithKey :: Radix1Tree a -> Lookup1 a
 unsafeLookupMaxWithKey = unsafeLookupMaxWithKey1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Delete a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeDeleteMax :: Radix1Tree a -> Radix1Tree a
 unsafeDeleteMax = unsafeDeleteMax1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeAdjustMax :: (a -> a) -> Radix1Tree a -> Radix1Tree a
 unsafeAdjustMax = unsafeAdjustMax1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeAdjustMaxWithKey :: (Build1 -> a -> a) -> Radix1Tree a -> Radix1Tree a
 unsafeAdjustMaxWithKey = unsafeAdjustMaxWithKey1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update or delete a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeUpdateMax :: (a -> Maybe a) -> Radix1Tree a -> Radix1Tree a
 unsafeUpdateMax = unsafeUpdateMax1
 
 -- | \(\mathcal{O}(1)\texttt{+}, \mathcal{O}(k)\).
 --   Update or delete a value at the rightmost key in the tree.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeUpdateMaxWithKey :: (Build1 -> a -> Maybe a) -> Radix1Tree a -> Radix1Tree a
 unsafeUpdateMaxWithKey = unsafeUpdateMaxWithKey1
 
 -- | \(\mathcal{O}(\min(x,k))\).
 --   Look up the rightmost value and return it alongside the tree without it.
 --
---   Throws 'MalformedTree' if the tree is empty.
+--   Throws t'MalformedTree' if the tree is empty.
 unsafeMaxView :: Radix1Tree a -> ViewR1 a
 unsafeMaxView = unsafeMaxView1