chore: release 3.0.0-beta.1

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Kiddo Changelog
 
+## [3.0.0-beta.1] - 2023-06-18
+
+### Breaking Changes
+
+* feat!: queries return structs instead of tuples. Query methods have been updated so that they all return
+  either a `NearestNeighbour`, `Vec<NearestNeighbour>`,
+  or `Vec<BestNeighbour>`, for consistency.
+* feat!: use a trait instead of a function pointer for distance metrics (See [SquaredEuclidean](https://docs.rs/kiddo/3.0.0-beta.1/kiddo/float/distance/struct.SquaredEuclidean.html) and [Manhattan](https://docs.rs/kiddo/3.0.0-beta.1/kiddo/float/distance/struct.Manhattan.html))
+* feat: add [within_unsorted_iter](https://docs.rs/kiddo/3.0.0-beta.1/kiddo/float/kdtree/struct.KdTree.html#method.within_unsorted_iter) query
+
+### Performance
+
+* perf: refactor [within](https://docs.rs/kiddo/3.0.0-beta.1/kiddo/float/kdtree/struct.KdTree.html#method.within) to simply sort the result of [within_unsorted](https://docs.rs/kiddo/3.0.0-beta.1/kiddo/float/kdtree/struct.KdTree.html#method.within_unsorted).
+  Previously, `within` was keeping its results in a `BinaryHeap` and calling
+  its `into_sorted_vec` method to, well, return a sorted `Vec`.
+  Whilst a `BinaryHeap` is great if you are frequently adding and removing
+  items, if your use case is to gradually add all your items, and then sort
+  them all at once, its quicker to just put things in a `Vec` and then
+  sort the `Vec` at the end.
+  Benchmarking shows that this change improves performance by anything from
+  5 to 60% in practice.
+
 ## [2.1.1] - 2023-06-07
 
 ### Refactor

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kiddo"
-version = "2.1.1"
+version = "3.0.0-beta.1"
 edition = "2021"
 authors = ["Scott Donnelly <[email protected]>"]
 description = "A high-performance, flexible, ergonomic k-d tree library. Ideal for geo- and astro- nearest-neighbour and k-nearest-neighbor queries"

README.md

@@ -27,7 +27,7 @@ Version 2.x is a complete rewrite, providing:
 Add `kiddo` to `Cargo.toml`
 ```toml
 [dependencies]
-kiddo = "2.1.1"
+kiddo = "3.0.0-beta.1"
 ```
 
 Add points to kdtree and query nearest n points with distance function

src/lib.rs

@@ -3,7 +3,7 @@
 #![warn(missing_docs)]
 #![warn(rustdoc::broken_intra_doc_links)]
 #![warn(rustdoc::private_intra_doc_links)]
-#![doc(html_root_url = "https://docs.rs/kiddo/2.1.1")]
+#![doc(html_root_url = "https://docs.rs/kiddo/3.0.0-beta.1")]
 #![doc(issue_tracker_base_url = "https://github.com/sdd/kiddo/issues/")]
 
 //! # Kiddo
@@ -12,7 +12,7 @@
 //!
 //! Possibly the fastest k-d tree library in the world? [See for yourself](https://sdd.github.io/kd-tree-comparison-webapp/).
 //!
-//! Version 2.x is a complete rewrite, providing:
+//! Version 2 and onwards is a complete rewrite over the previous v0.6.x codebase, providing:
 //! - a new internal architecture for **much-improved performance**;
 //! - Added **integer / fixed point support** via the [`Fixed`](https://docs.rs/fixed/latest/fixed/) library;
 //! - **instant zero-copy deserialization** and serialization via [`Rkyv`](https://docs.rs/rkyv/latest/rkyv/) ([`Serde`](https://docs.rs/serde/latest/serde/) still available).
@@ -29,7 +29,7 @@
 //! Add `kiddo` to `Cargo.toml`
 //! ```toml
 //! [dependencies]
-//! kiddo = "2.1.1"
+//! kiddo = "3.0.0-beta.1"
 //! ```
 //!
 //! ## Usage