From 83ddde4f87ee3642ce1f5de43e9e57c3be6e87a9 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Mon, 29 Jun 2020 16:23:11 -0400 Subject: distance: Expand the Distance docs --- src/distance.rs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/distance.rs b/src/distance.rs index 070bac7..e44ed03 100644 --- a/src/distance.rs +++ b/src/distance.rs @@ -14,8 +14,8 @@ impl Value for T {} /// /// An implementation may be an actual numerical distance, or an [order embedding] of the true /// distance. This allows for optimizations whenever distances can be compared more efficiently -/// than their exact values can be computed, as is the case for [Euclidean distance]. Implementors -/// must satisfy, for all distances `$x$` and `$y$`: +/// than their exact values can be computed. Implementors must satisfy, for all distances `$x$` and +/// `$y$`: /// /// ```math /// \begin{aligned} @@ -25,8 +25,14 @@ impl Value for T {} /// \end{aligned} /// ``` /// +/// Any monotonically increasing function can be used to create an order embedding. For example, +/// [`EuclideanDistance`] holds a squared distance, rather than the distance itself. Comparisons +/// still behave correctly because `$x \mapsto x^2$` is an increasing function. This lets us avoid +/// computing relatively expensive square roots until we need the `value()` itself, at which point +/// the inverse function `$x \mapsto \sqrt{x}$` must be applied. +/// /// [order embedding]: https://en.wikipedia.org/wiki/Order_embedding -/// [Euclidean distance]: crate::euclid::EuclideanDistance +/// [`EuclideanDistance`]: crate::euclid::EuclideanDistance pub trait Distance where Self: Copy, -- cgit v1.2.3