Implement tie breaker handler and distance retrieving

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 **This is the changelog for the core Rust library**. There's a [separate changelog](./python/CHANGELOG.md) for the Python bindings.
 
+## Unreleased
+
+### Breaking
+
+- BREAKING: Introduce `NeighborsOptions` struct and change signatures of `neighbors_with_simple_distance`, `neighbors_with_distance`, `neighbors_coord_with_distance`, and `neighbors_geometry` to accept `NeighborsOptions` instead of separate `max_results`/`max_distance` parameters, and return `Vec<(u32, N)>` instead of `Vec<u32>` to include distances with results. `NeighborsOptions` also adds support for tie breaker inclusion at rank k. by @Kontinuation in https://github.com/georust/geo-index/pull/154
+
 ## [0.3.3] - 2026-02-11
 
 ## Bug fixes

benches/distance.rs

@@ -5,7 +5,7 @@ use geo_index::rtree::distance::{
     DistanceMetric, EuclideanDistance, HaversineDistance, SliceGeometryAccessor,
 };
 use geo_index::rtree::sort::HilbertSort;
-use geo_index::rtree::{RTreeBuilder, RTreeIndex, SimpleDistanceMetric};
+use geo_index::rtree::{NeighborsOptions, RTreeBuilder, RTreeIndex, SimpleDistanceMetric};
 use geo_index::IndexableNum;
 use rand::rngs::StdRng;
 use rand::{Rng, SeedableRng};
@@ -116,8 +116,7 @@ fn benchmark_distance_metrics(c: &mut Criterion) {
                 tree.neighbors_with_distance(
                     query_point.x(),
                     query_point.y(),
-                    Some(10),
-                    None,
+                    NeighborsOptions::k(10),
                     &euclidean,
                 )
             })
@@ -128,8 +127,7 @@ fn benchmark_distance_metrics(c: &mut Criterion) {
                 tree.neighbors_with_distance(
                     query_point.x(),
                     query_point.y(),
-                    Some(10),
-                    None,
+                    NeighborsOptions::k(10),
                     &haversine,
                 )
             })
@@ -144,7 +142,14 @@ fn benchmark_distance_metrics(c: &mut Criterion) {
         geom_group.bench_with_input(BenchmarkId::new("euclidean", size), &size, |b, _| {
             let metric = SimpleMetric;
             let accessor = SliceGeometryAccessor::new(&geometries);
-            b.iter(|| tree.neighbors_geometry(&query_geometry, Some(10), None, &metric, &accessor))
+            b.iter(|| {
+                tree.neighbors_geometry(
+                    &query_geometry,
+                    NeighborsOptions::k(10),
+                    &metric,
+                    &accessor,
+                )
+            })
         });
 
         geom_group.finish();
@@ -209,8 +214,7 @@ fn benchmark_comparison_with_baseline(c: &mut Criterion) {
             tree.neighbors_with_distance(
                 query_point.x(),
                 query_point.y(),
-                Some(10),
-                None,
+                NeighborsOptions::k(10),
                 &euclidean,
             )
         })

src/rtree/mod.rs

@@ -66,5 +66,5 @@ pub mod util;
 
 pub use builder::{RTreeBuilder, DEFAULT_RTREE_NODE_SIZE};
 pub use index::{RTree, RTreeMetadata, RTreeRef};
-pub use r#trait::{RTreeIndex, SimpleDistanceMetric};
+pub use r#trait::{NeighborsOptions, RTreeIndex, SimpleDistanceMetric};
 pub use traversal::Node;