diff --git a/rstar/CHANGELOG.md b/rstar/CHANGELOG.md index 850dd68..bb72173 100644 --- a/rstar/CHANGELOG.md +++ b/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 diff --git a/rstar/src/node.rs b/rstar/src/node.rs index c126285..6173496 100644 --- a/rstar/src/node.rs +++ b/rstar/src/node.rs @@ -85,7 +85,8 @@ where self.envelope.clone() } - pub(crate) fn new_root() -> Self + /// Creates an empty root ParentNode. + pub fn new_root() -> Self where Params: RTreeParams, { @@ -95,7 +96,8 @@ where } } - pub(crate) fn new_parent(children: Vec>) -> Self { + /// Creates a ParentNode with the specified children. + pub fn new_parent(children: Vec>) -> Self { let envelope = envelope_for_children(&children); ParentNode { envelope, children } diff --git a/rstar/src/rtree.rs b/rstar/src/rtree.rs index 0ea3e2f..3b3c06c 100644 --- a/rstar/src/rtree.rs +++ b/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, size: usize) -> Self { + verify_parameters::(); + RTree { + root: root, + size: size, + _params: Default::default(), + } + } + /// Returns the number of objects in an r-tree. /// /// # Example