//! [Soft deletion](https://en.wiktionary.org/wiki/soft_deletion) for nearest neighbor search. use super::forest::{KdForest, VpForest}; use super::kd::KdTree; use super::vp::VpTree; use super::{Metric, NearestNeighbors, Neighborhood}; use std::iter; use std::iter::FromIterator; use std::mem; /// A trait for objects that can be soft-deleted. pub trait SoftDelete { /// Check whether this item is deleted. fn is_deleted(&self) -> bool; } /// Blanket [SoftDelete] implementation for references. impl<'a, T: SoftDelete> SoftDelete for &'a T { fn is_deleted(&self) -> bool { (*self).is_deleted() } } /// [Neighborhood] wrapper that ignores soft-deleted items. #[derive(Debug)] struct SoftNeighborhood(N); impl Neighborhood for SoftNeighborhood where T: SoftDelete, U: Metric, N: Neighborhood, { fn target(&self) -> U { self.0.target() } fn contains(&self, distance: f64) -> bool { self.0.contains(distance) } fn contains_distance(&self, distance: U::Distance) -> bool { self.0.contains_distance(distance) } fn consider(&mut self, item: T) -> U::Distance { if item.is_deleted() { self.target().distance(&item) } else { self.0.consider(item) } } } /// A [NearestNeighbors] implementation that supports [soft deletes](https://en.wiktionary.org/wiki/soft_deletion). #[derive(Debug)] pub struct SoftSearch(T); impl SoftSearch where T: SoftDelete, U: FromIterator + IntoIterator, { /// Create a new empty soft index. pub fn new() -> Self { Self(iter::empty().collect()) } /// Push a new item into this index. pub fn push(&mut self, item: T) where U: Extend, { self.0.extend(iter::once(item)); } /// Rebuild this index, discarding deleted items. pub fn rebuild(&mut self) { let items = mem::replace(&mut self.0, iter::empty().collect()); self.0 = items.into_iter().filter(|e| !e.is_deleted()).collect(); } } impl Default for SoftSearch where T: SoftDelete, U: FromIterator + IntoIterator, { fn default() -> Self { Self::new() } } impl> Extend for SoftSearch { fn extend>(&mut self, iter: I) { self.0.extend(iter); } } impl> FromIterator for SoftSearch { fn from_iter>(iter: I) -> Self { Self(U::from_iter(iter)) } } impl IntoIterator for SoftSearch { type Item = T::Item; type IntoIter = T::IntoIter; fn into_iter(self) -> Self::IntoIter { self.0.into_iter() } } impl NearestNeighbors for SoftSearch where T: SoftDelete, U: Metric, V: NearestNeighbors, { fn search<'a, 'b, N>(&'a self, neighborhood: N) -> N where T: 'a, U: 'b, N: Neighborhood<&'a T, &'b U>, { self.0.search(SoftNeighborhood(neighborhood)).0 } } /// A k-d forest that supports soft deletes. pub type SoftKdForest = SoftSearch>; /// A k-d tree that supports soft deletes. pub type SoftKdTree = SoftSearch>; /// A VP forest that supports soft deletes. pub type SoftVpForest = SoftSearch>; /// A VP tree that supports soft deletes. pub type SoftVpTree = SoftSearch>; #[cfg(test)] mod tests { use super::*; use crate::metric::kd::Cartesian; use crate::metric::tests::Point; use crate::metric::Neighbor; #[derive(Debug, PartialEq)] struct SoftPoint { point: Point, deleted: bool, } impl SoftPoint { fn new(x: f64, y: f64, z: f64) -> Self { Self { point: Point([x, y, z]), deleted: false, } } fn deleted(x: f64, y: f64, z: f64) -> Self { Self { point: Point([x, y, z]), deleted: true, } } } impl SoftDelete for SoftPoint { fn is_deleted(&self) -> bool { self.deleted } } impl Metric for SoftPoint { type Distance = ::Distance; fn distance(&self, other: &Self) -> Self::Distance { self.point.distance(&other.point) } } impl Metric<[f64]> for SoftPoint { type Distance = ::Distance; fn distance(&self, other: &[f64]) -> Self::Distance { self.point.distance(other) } } impl Cartesian for SoftPoint { fn dimensions(&self) -> usize { self.point.dimensions() } fn coordinate(&self, i: usize) -> f64 { self.point.coordinate(i) } } impl Metric for Point { type Distance = ::Distance; fn distance(&self, other: &SoftPoint) -> Self::Distance { self.distance(&other.point) } } fn test_index(index: &T) where T: NearestNeighbors, { let target = Point([0.0, 0.0, 0.0]); assert_eq!( index.nearest(&target), Some(Neighbor::new(&SoftPoint::new(1.0, 2.0, 2.0), 3.0)) ); assert_eq!(index.nearest_within(&target, 2.0), None); assert_eq!( index.nearest_within(&target, 4.0), Some(Neighbor::new(&SoftPoint::new(1.0, 2.0, 2.0), 3.0)) ); assert_eq!( index.k_nearest(&target, 3), vec![ Neighbor::new(&SoftPoint::new(1.0, 2.0, 2.0), 3.0), Neighbor::new(&SoftPoint::new(3.0, 4.0, 0.0), 5.0), Neighbor::new(&SoftPoint::new(2.0, 3.0, 6.0), 7.0), ] ); assert_eq!( index.k_nearest_within(&target, 3, 6.0), vec![ Neighbor::new(&SoftPoint::new(1.0, 2.0, 2.0), 3.0), Neighbor::new(&SoftPoint::new(3.0, 4.0, 0.0), 5.0), ] ); assert_eq!( index.k_nearest_within(&target, 3, 8.0), vec![ Neighbor::new(&SoftPoint::new(1.0, 2.0, 2.0), 3.0), Neighbor::new(&SoftPoint::new(3.0, 4.0, 0.0), 5.0), Neighbor::new(&SoftPoint::new(2.0, 3.0, 6.0), 7.0), ] ); } fn test_soft_index(index: &mut SoftSearch) where T: Extend, T: FromIterator, T: IntoIterator, T: NearestNeighbors, { let points = vec![ SoftPoint::deleted(0.0, 0.0, 0.0), SoftPoint::new(3.0, 4.0, 0.0), SoftPoint::new(5.0, 0.0, 12.0), SoftPoint::new(0.0, 8.0, 15.0), SoftPoint::new(1.0, 2.0, 2.0), SoftPoint::new(2.0, 3.0, 6.0), SoftPoint::new(4.0, 4.0, 7.0), ]; for point in points { index.push(point); } test_index(index); index.rebuild(); test_index(index); } #[test] fn test_soft_kd_forest() { test_soft_index(&mut SoftKdForest::new()); } #[test] fn test_soft_vp_forest() { test_soft_index(&mut SoftVpForest::new()); } }