Make node constructors public, add RTree::new_from_root

rstar/CHANGELOG.md

@@ -1,3 +1,11 @@
+# Unreleased
+
+## Added
+- Added `RTree::new_from_root`.
+
+## Changed
+- `ParentNode::new_root` and `ParentNode::new_parent` are now public.
+
 # 0.11.0
 
 ## Added

rstar/src/node.rs

@@ -85,7 +85,8 @@ where
         self.envelope.clone()
     }
 
-    pub(crate) fn new_root<Params>() -> Self
+    /// Creates an empty root ParentNode.
+    pub fn new_root<Params>() -> Self
     where
         Params: RTreeParams,
     {
@@ -95,7 +96,8 @@ where
         }
     }
 
-    pub(crate) fn new_parent(children: Vec<RTreeNode<T>>) -> Self {
+    /// Creates a ParentNode with the specified children.
+    pub fn new_parent(children: Vec<RTreeNode<T>>) -> Self {
         let envelope = envelope_for_children(&children);
 
         ParentNode { envelope, children }

rstar/src/rtree.rs

@@ -242,6 +242,32 @@ where
         Self::new_from_bulk_loading(elements, bulk_load::bulk_load_sequential::<_, Params>)
     }
 
+    /// Creates a new r-tree from an existing root node. The size parameter must match the number of
+    /// leaves in the tree.
+    ///
+    /// **Warning:** Manually constructed trees are **NOT** officially supported. You may only use
+    /// this method to load an r-tree previously constructed using this crate through a sequence of
+    /// safe operations such as [RTree::bulk_load], [RTree::insert], and [RTree::remove].
+    /// The leaf nodes' envelopes should match the envelopes of the items used to construct the
+    /// tree being loaded. Do not use this method to load a subtree of an r-tree as its own tree.
+    /// Failure to uphold any of the internal invariants will result in unexpected panics and
+    /// potentially incorrect behavior.
+    ///
+    /// **Warning:** The tree with the specified root node must be a correct r-tree as produced by
+    /// the current version of this crate with the same compile time parameters. Forward and
+    /// backward compatibility is **NOT** guaranteed.
+    ///
+    /// The tree's compile time parameters must be specified. Refer to the
+    /// [RTreeParams] trait for more information and a usage example.
+    pub fn new_from_root(root: ParentNode<T>, size: usize) -> Self {
+        verify_parameters::<T, Params>();
+        RTree {
+            root: root,
+            size: size,
+            _params: Default::default(),
+        }
+    }
+
     /// Returns the number of objects in an r-tree.
     ///
     /// # Example