summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorTavian Barnes <tavianator@tavianator.com>2020-06-29 14:24:08 -0400
committerTavian Barnes <tavianator@tavianator.com>2020-06-29 16:07:49 -0400
commit31e713e4700a20cce3a8691cd128cf7a072af960 (patch)
tree53d24f3e35528be4c8a05589460c800fe892f1d1 /src
parent5aa0fd44535faa0ea1c0522b089e16d4b57e4e6f (diff)
downloadacap-31e713e4700a20cce3a8691cd128cf7a072af960.tar.xz
distance: Expand the Proximity docs
Diffstat (limited to 'src')
-rw-r--r--src/distance.rs55
1 files changed, 49 insertions, 6 deletions
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<T: Value> 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<T>` 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<PointOfInterest> for Gps {
+/// type Distance = <Gps as Proximity>::Distance;
+///
+/// fn distance(&self, other: &PointOfInterest) -> Self::Distance {
+/// self.distance(&other.location)
+/// }
+/// }
+/// ```
+///
+/// With those implementations available, you could use a [`NearestNeighbors<Gps, PointOfInterest>`]
+/// instance to find the closest point(s) of interest to any GPS location.
+///
+/// [`NearestNeighbors<Gps, PointOfInterest>`]: super::NearestNeighbors
pub trait Proximity<T: ?Sized = Self> {
/// The type that represents distances.
type Distance: Distance;