From 31e713e4700a20cce3a8691cd128cf7a072af960 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Mon, 29 Jun 2020 14:24:08 -0400 Subject: distance: Expand the Proximity docs --- src/distance.rs | 55 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 49 insertions(+), 6 deletions(-) (limited to 'src') diff --git a/src/distance.rs b/src/distance.rs index 0fc1c2a..070bac7 100644 --- a/src/distance.rs +++ b/src/distance.rs @@ -51,15 +51,58 @@ impl Distance for T { /// A space with some notion of distance between points. /// -/// Distances in this space don't need to obey any particular rules like symmetry or the [triangle -/// inequality]. However, spaces that satisfy those rules, at least approximately, often allow for -/// more accurate and efficient searches. +/// There are no restrictions on the distances returned by spaces that implement only `Proximity`. +/// In particular, they may be asymmetric or even negative. If a space meets the restrictions of +/// the [`Metric`] trait, it should be implemented as well. Spaces that satisfy those rules, at +/// least approximately, often allow for more accurate and efficient searches. /// -/// Type parameters: +/// `Proximity` is generic, to allow comparisons between objects of related but distinct types. +/// For example: /// -/// * `T`: The type to compare against. +/// ``` +/// # use acap::cos::{angular_distance, AngularDistance}; +/// # use acap::distance::Proximity; +/// // A GPS coordinate +/// struct Gps { +/// lat: f64, +/// long: f64, +/// } +/// # type HaversineDistance = f64; +/// # fn haversine_distance(a: &Gps, b: &Gps) -> HaversineDistance { +/// # 0.0 +/// # } /// -/// [triangle inequality]: https://en.wikipedia.org/wiki/Triangle_inequality +/// // For computing distances between GPS coordinates +/// impl Proximity for Gps { +/// type Distance = HaversineDistance; +/// +/// fn distance(&self, other: &Self) -> Self::Distance { +/// haversine_distance(self, other) +/// } +/// } +/// +/// // A point of interest with a known location, name, ... +/// struct PointOfInterest { +/// location: Gps, +/// name: String, +/// // ... +/// } +/// +/// // Compute the distance between a GPS coordinate and a point of interest, +/// // by delegating to the Proximity impl for Gps +/// impl Proximity for Gps { +/// type Distance = ::Distance; +/// +/// fn distance(&self, other: &PointOfInterest) -> Self::Distance { +/// self.distance(&other.location) +/// } +/// } +/// ``` +/// +/// With those implementations available, you could use a [`NearestNeighbors`] +/// instance to find the closest point(s) of interest to any GPS location. +/// +/// [`NearestNeighbors`]: super::NearestNeighbors pub trait Proximity { /// The type that represents distances. type Distance: Distance; -- cgit v1.2.3