From 38bcee9baf1885cdfa3104a3a593e59f642b6b6a Mon Sep 17 00:00:00 2001 From: Nick Guletskii Date: Tue, 3 Jan 2023 12:05:47 +0200 Subject: [PATCH 1/3] Make ParentNode::new_root and ParentNode::new_parent public, add RTree::new_from_root --- rstar/CHANGELOG.md | 2 ++ rstar/src/node.rs | 6 ++++-- rstar/src/rtree.rs | 14 ++++++++++++++ 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/rstar/CHANGELOG.md b/rstar/CHANGELOG.md index 850dd68..38b45b7 100644 --- a/rstar/CHANGELOG.md +++ b/rstar/CHANGELOG.md @@ -12,6 +12,8 @@ ## Added - Added method `RTree::drain()`. - Changed license field to [SPDX 2.1 license expression](https://spdx.dev/spdx-specification-21-web-version/#h.jxpfx0ykyb60) +- `ParentNode::new_root` and `ParentNode::new_parent` are now public. +- Added `RTree::new_from_root`. ## Changed - fixed all clippy lint issues 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..df3760d 100644 --- a/rstar/src/rtree.rs +++ b/rstar/src/rtree.rs @@ -242,6 +242,20 @@ 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. + /// + /// 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 From 8a63e2d0e4ef264f2534cb5ddf6391e6d0d89605 Mon Sep 17 00:00:00 2001 From: Nick Guletskii Date: Sat, 28 Jan 2023 20:06:30 +0200 Subject: [PATCH 2/3] Document the expectations for the parameters of `RTree::new_from_root` --- rstar/src/rtree.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/rstar/src/rtree.rs b/rstar/src/rtree.rs index df3760d..3b3c06c 100644 --- a/rstar/src/rtree.rs +++ b/rstar/src/rtree.rs @@ -245,6 +245,18 @@ where /// 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 { From 14d859da64a210965317c37b500b8fc3888e6184 Mon Sep 17 00:00:00 2001 From: Nick Guletskii Date: Tue, 13 Jun 2023 23:09:40 +0300 Subject: [PATCH 3/3] Changelog update: Move the changes regarding `RTree::new_from_root` into a new release section --- rstar/CHANGELOG.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/rstar/CHANGELOG.md b/rstar/CHANGELOG.md index 38b45b7..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 @@ -12,8 +20,6 @@ ## Added - Added method `RTree::drain()`. - Changed license field to [SPDX 2.1 license expression](https://spdx.dev/spdx-specification-21-web-version/#h.jxpfx0ykyb60) -- `ParentNode::new_root` and `ParentNode::new_parent` are now public. -- Added `RTree::new_from_root`. ## Changed - fixed all clippy lint issues