summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/chebyshev.rs8
-rw-r--r--src/coords.rs12
-rw-r--r--src/cos.rs22
-rw-r--r--src/distance.rs8
-rw-r--r--src/euclid.rs10
-rw-r--r--src/exhaustive.rs2
-rw-r--r--src/hamming.rs6
-rw-r--r--src/kd.rs14
-rw-r--r--src/lib.rs44
-rw-r--r--src/taxi.rs10
10 files changed, 73 insertions, 63 deletions
diff --git a/src/chebyshev.rs b/src/chebyshev.rs
index 335b6f1..bddbd5e 100644
--- a/src/chebyshev.rs
+++ b/src/chebyshev.rs
@@ -9,8 +9,8 @@ use num_traits::{zero, Signed};
///
/// This wrapper equips any [coordinate space] with the [Chebyshev distance] metric.
///
-/// [coordinate space]: [Coordinates]
-/// [Chebyshev distance]: https://en.wikipedia.org/wiki/Chebyshev_distance
+/// [coordinate space]: Coordinates
+/// [Chebyshev distance]: chebyshev_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Chebyshev<T>(pub T);
@@ -43,7 +43,7 @@ impl<T: Coordinates> Coordinates for Chebyshev<T> {
}
}
-/// Compute the Chebyshev distance between two points.
+/// Compute the [Chebyshev distance] between two points.
///
/// ```math
/// \begin{aligned}
@@ -51,6 +51,8 @@ impl<T: Coordinates> Coordinates for Chebyshev<T> {
/// &= \max_i |x_i - y_i|
/// \end{aligned}
/// ```
+///
+/// [Chebyshev distance]: https://en.wikipedia.org/wiki/Chebyshev_distance
pub fn chebyshev_distance<T, U>(x: T, y: U) -> T::Value
where
T: Coordinates,
diff --git a/src/coords.rs b/src/coords.rs
index 08e807c..a95e378 100644
--- a/src/coords.rs
+++ b/src/coords.rs
@@ -24,7 +24,7 @@ pub trait Coordinates {
}
}
-/// [Coordinates] implementation for slices.
+/// [`Coordinates`] implementation for slices.
impl<T: Value> Coordinates for [T] {
type Value = T;
@@ -37,7 +37,7 @@ impl<T: Value> Coordinates for [T] {
}
}
-/// [Coordinates] implementation for arrays.
+/// [`Coordinates`] implementation for arrays.
macro_rules! array_coordinates {
($n:expr) => (
impl<T: Value> Coordinates for [T; $n] {
@@ -63,7 +63,7 @@ array_coordinates!(6);
array_coordinates!(7);
array_coordinates!(8);
-/// [Coordinates] implemention for vectors.
+/// [`Coordinates`] implemention for vectors.
impl<T: Value> Coordinates for Vec<T> {
type Value = T;
@@ -76,7 +76,7 @@ impl<T: Value> Coordinates for Vec<T> {
}
}
-/// Blanket [Coordinates] implementation for references.
+/// Blanket [`Coordinates`] implementation for references.
impl<T: ?Sized + Coordinates> Coordinates for &T {
type Value = T::Value;
@@ -97,7 +97,7 @@ pub trait CoordinateProximity<T> {
fn distance_to_coords(&self, coords: &[T]) -> Self::Distance;
}
-/// Blanket [CoordinateProximity] implementation for references.
+/// Blanket [`CoordinateProximity`] implementation for references.
impl<T: CoordinateProximity<U>, U> CoordinateProximity<U> for &T {
type Distance = T::Distance;
@@ -109,5 +109,5 @@ impl<T: CoordinateProximity<U>, U> CoordinateProximity<U> for &T {
/// Marker trait for coordinate proximities that are [metrics][crate::distance::Metric].
pub trait CoordinateMetric<T>: CoordinateProximity<T> {}
-/// Blanket [CoordinateMetric] implementation for references.
+/// Blanket [`CoordinateMetric`] implementation for references.
impl<T: CoordinateMetric<U>, U> CoordinateMetric<U> for &T {}
diff --git a/src/cos.rs b/src/cos.rs
index 5d8f73f..99a08f4 100644
--- a/src/cos.rs
+++ b/src/cos.rs
@@ -10,7 +10,7 @@ use std::cmp::Ordering;
/// Compute the [cosine *similarity*] between two points.
///
-/// Use [cosine_distance] instead if you are implementing [Proximity::distance()].
+/// Use [cosine_distance] instead if you are implementing [`Proximity::distance()`].
///
/// ```math
/// \begin{aligned}
@@ -21,7 +21,7 @@ use std::cmp::Ordering;
/// ```
///
/// [cosine *similarity*]: https://en.wikipedia.org/wiki/Cosine_similarity
-/// [Proximity::distance()]: Proximity#tymethod.distance
+/// [`Proximity::distance()`]: Proximity#tymethod.distance
pub fn cosine_similarity<T, U>(x: T, y: U) -> T::Value
where
T: Coordinates,
@@ -69,8 +69,8 @@ where
/// Equips any [coordinate space] with the [cosine distance] function.
///
-/// [coordinate space]: [Coordinates]
-/// [cosine distance]: https://en.wikipedia.org/wiki/Cosine_similarity
+/// [coordinate space]: Coordinates
+/// [cosine distance]: cosine_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Cosine<T>(pub T);
@@ -112,7 +112,7 @@ where
/// Compute the [cosine *similarity*] between two pre-normalized (unit magnitude) points.
///
-/// Use [prenorm_cosine_distance] instead if you are implementing [Proximity::distance()].
+/// Use [`prenorm_cosine_distance()`] instead if you are implementing [`Proximity::distance()`].
///
/// ```math
/// \begin{aligned}
@@ -166,8 +166,8 @@ where
/// Equips any [coordinate space] with the [cosine distance] function for pre-normalized (unit
/// magnitude) points.
///
-/// [coordinate space]: [Coordinates]
-/// [cosine distance]: https://en.wikipedia.org/wiki/Cosine_similarity
+/// [coordinate space]: Coordinates
+/// [cosine distance]: prenorm_cosine_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PrenormCosine<T>(pub T);
@@ -230,8 +230,8 @@ where
/// Equips any [coordinate space] with the [angular distance] metric.
///
-/// [coordinate space]: [Coordinates]
-/// [angular distance]: https://en.wikipedia.org/wiki/Cosine_similarity#Angular_distance_and_similarity
+/// [coordinate space]: Coordinates
+/// [angular distance]: angular_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Angular<T>(pub T);
@@ -322,8 +322,8 @@ where
/// Equips any [coordinate space] with the [angular distance] metric for pre-normalized (unit
/// magnitude) points.
///
-/// [coordinate space]: [Coordinates]
-/// [angular distance]: https://en.wikipedia.org/wiki/Cosine_similarity#Angular_distance_and_similarity
+/// [coordinate space]: Coordinates
+/// [angular distance]: prenorm_angular_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PrenormAngular<T>(pub T);
diff --git a/src/distance.rs b/src/distance.rs
index 20d862b..0fc1c2a 100644
--- a/src/distance.rs
+++ b/src/distance.rs
@@ -7,7 +7,7 @@ use num_traits::{Num, NumAssign, Signed};
/// This trait is automatically implemented for all types that support the required operations.
pub trait Value: Copy + Num + NumAssign + Signed + PartialOrd {}
-/// Blanket [Value] implementation.
+/// Blanket [`Value`] implementation.
impl<T: Num + NumAssign + Signed + Copy + PartialOrd> Value for T {}
/// A distance between two points.
@@ -44,7 +44,7 @@ where
}
}
-/// Any numerical distance value can be a [Distance].
+/// Any numerical distance value can be a [`Distance`].
impl<T: Value> Distance for T {
type Value = T;
}
@@ -72,7 +72,7 @@ pub trait Proximity<T: ?Sized = Self> {
/// Shorthand for `K::Distance::Value`.
pub type DistanceValue<K, V = K> = <<K as Proximity<V>>::Distance as Distance>::Value;
-/// Blanket [Proximity] implementation for references.
+/// Blanket [`Proximity`] implementation for references.
impl<'k, 'v, K: Proximity<V>, V> Proximity<&'v V> for &'k K {
type Distance = K::Distance;
@@ -110,5 +110,5 @@ impl<'k, 'v, K: Proximity<V>, V> Proximity<&'v V> for &'k K {
/// [pseudometric spaces]: https://en.wikipedia.org/wiki/Pseudometric_space
pub trait Metric<T: ?Sized = Self>: Proximity<T> {}
-/// Blanket [Metric] implementation for references.
+/// Blanket [`Metric`] implementation for references.
impl<'k, 'v, K: Metric<V>, V> Metric<&'v V> for &'k K {}
diff --git a/src/euclid.rs b/src/euclid.rs
index 0f2281e..c1d88ae 100644
--- a/src/euclid.rs
+++ b/src/euclid.rs
@@ -12,8 +12,8 @@ use std::convert::TryFrom;
///
/// This wrapper equips any [coordinate space] with the [Euclidean distance] metric.
///
-/// [coordinate space]: [Coordinates]
-/// [Euclidean distance]: https://en.wikipedia.org/wiki/Euclidean_distance
+/// [coordinate space]: Coordinates
+/// [Euclidean distance]: euclidean_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Euclidean<T>(pub T);
@@ -46,7 +46,7 @@ impl<T: Coordinates> Coordinates for Euclidean<T> {
}
}
-/// Compute the Euclidean distance between two points.
+/// Compute the [Euclidean distance] between two points.
///
/// ```math
/// \begin{aligned}
@@ -54,6 +54,8 @@ impl<T: Coordinates> Coordinates for Euclidean<T> {
/// &= \sqrt{\sum_i (x_i - y_i)^2}
/// \end{aligned}
/// ```
+///
+/// [Euclidean distance]: https://en.wikipedia.org/wiki/Euclidean_distance
pub fn euclidean_distance<T, U>(x: T, y: U) -> EuclideanDistance<T::Value>
where
T: Coordinates,
@@ -175,7 +177,7 @@ impl<T: Value> EuclideanDistance<T> {
}
}
-/// Error type for failed conversions from negative numbers to [EuclideanDistance].
+/// Error type for failed conversions from negative numbers to [`EuclideanDistance`].
#[derive(Debug)]
pub struct NegativeDistanceError;
diff --git a/src/exhaustive.rs b/src/exhaustive.rs
index 909edda..221641c 100644
--- a/src/exhaustive.rs
+++ b/src/exhaustive.rs
@@ -5,7 +5,7 @@ use crate::{ExactNeighbors, NearestNeighbors, Neighborhood};
use std::iter::FromIterator;
-/// A [NearestNeighbors] implementation that does exhaustive search.
+/// A [`NearestNeighbors`] implementation that does exhaustive search.
#[derive(Debug)]
pub struct ExhaustiveSearch<T>(Vec<T>);
diff --git a/src/hamming.rs b/src/hamming.rs
index da959b4..b3a7e78 100644
--- a/src/hamming.rs
+++ b/src/hamming.rs
@@ -8,7 +8,7 @@ use num_traits::PrimInt;
///
/// This wrapper equips any integer with the [Hamming distance] metric.
///
-/// [Hamming distance]: https://en.wikipedia.org/wiki/Hamming_distance
+/// [Hamming distance]: hamming_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Hamming<T>(pub T);
@@ -24,7 +24,7 @@ impl<T> Hamming<T> {
}
}
-/// Compute the Hamming distance between two integers.
+/// Compute the [Hamming distance] between two integers.
///
/// ```math
/// \begin{aligned}
@@ -32,6 +32,8 @@ impl<T> Hamming<T> {
/// &= \mathrm{popcount}(x \wedge y)
/// \end{aligned}
/// ```
+///
+/// [Hamming distance]: https://en.wikipedia.org/wiki/Hamming_distance
pub fn hamming_distance<T: PrimInt>(x: T, y: T) -> i32 {
(x ^ y).count_ones() as i32
}
diff --git a/src/kd.rs b/src/kd.rs
index 69c72bf..2a9ecb4 100644
--- a/src/kd.rs
+++ b/src/kd.rs
@@ -81,7 +81,7 @@ impl<T: Coordinates> KdNode<T> {
}
}
-/// Marker trait for [Proximity] implementations that are compatible with k-d trees.
+/// Marker trait for [`Proximity`] implementations that are compatible with k-d trees.
pub trait KdProximity<V: ?Sized = Self>
where
Self: Coordinates<Value = V::Value>,
@@ -90,7 +90,7 @@ where
V: Coordinates,
{}
-/// Blanket [KdProximity] implementation.
+/// Blanket [`KdProximity`] implementation.
impl<K, V> KdProximity<V> for K
where
K: Coordinates<Value = V::Value>,
@@ -99,7 +99,7 @@ where
V: Coordinates,
{}
-/// Marker trait for [Metric] implementations that are compatible with k-d tree.
+/// Marker trait for [`Metric`] implementations that are compatible with k-d tree.
pub trait KdMetric<V: ?Sized = Self>
where
Self: KdProximity<V>,
@@ -108,7 +108,7 @@ where
V: Coordinates,
{}
-/// Blanket [KdMetric] implementation.
+/// Blanket [`KdMetric`] implementation.
impl<K, V> KdMetric<V> for K
where
K: KdProximity<V>,
@@ -240,7 +240,7 @@ impl<T: Coordinates> KdTree<T> {
/// Push a new item into the tree.
///
- /// Inserting elements individually tends to unbalance the tree. Use [KdTree::balanced] if
+ /// Inserting elements individually tends to unbalance the tree. Use [`KdTree::balanced()`] if
/// possible to create a balanced tree from a batch of items.
pub fn push(&mut self, item: T) {
if let Some(root) = &mut self.root {
@@ -413,8 +413,8 @@ where
/// A [k-d tree] stored as a flat array.
///
-/// A FlatKdTree is always balanced and usually more efficient than a [KdTree], but doesn't support
-/// dynamic updates.
+/// A FlatKdTree is always balanced and usually more efficient than a [`KdTree`], but doesn't
+/// support dynamic updates.
///
/// [k-d tree]: https://en.wikipedia.org/wiki/K-d_tree
#[derive(Debug)]
diff --git a/src/lib.rs b/src/lib.rs
index e6ca957..346e9e9 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,18 +2,19 @@
//!
//! # Overview
//!
-//! The notion of distances between points is captured by the [Proximity] trait. Its [`distance()`]
-//! method returns a [Distance], from which the actual numerical distance may be retrieved with
-//! [`value()`]. These layers of abstraction allow `acap` to work with generically with different
-//! distance functions over different types.
+//! The notion of distances between points is captured by the [`Proximity`] trait. Its
+//! [`distance()`] method returns a [`Distance`], from which the actual numerical distance may be
+//! retrieved with [`value()`]. These layers of abstraction allow `acap` to work with generically
+//! with different distance functions over different types.
//!
-//! There are no restrictions on the distances computed by a [Proximity]. For example, they don't
+//! There are no restrictions on the distances computed by a [`Proximity`]. For example, they don't
//! have to be symmetric, subadditive, or even positive. Implementations that do have these
-//! desirable properties will additionally implement the [Metric] marker trait. This distinction
+//! desirable properties will additionally implement the [`Metric`] marker trait. This distinction
//! allows `acap` to support a wide variety of useful metric and non-metric distances.
//!
-//! As a concrete example, consider `Euclidean<[i32; 2]>`. The [Euclidean] wrapper equips any type
-//! that has [coordinates] with the [Euclidean distance] function as its Proximity implementation:
+//! As a concrete example, consider `Euclidean<[i32; 2]>`. The [`Euclidean`] wrapper equips any
+//! type that has [coordinates] with the [Euclidean distance] function as its [`Proximity`]
+//! implementation:
//!
//! use acap::distance::Proximity;
//! use acap::euclid::Euclidean;
@@ -23,7 +24,7 @@
//! assert_eq!(a.distance(&b), 5);
//!
//! In this case, `distance()` doesn't return a number directly; as an optimization, it returns a
-//! [EuclideanDistance] wrapper. This wrapper stores the squared value of the distance, to avoid
+//! [`EuclideanDistance`] wrapper. This wrapper stores the squared value of the distance, to avoid
//! computing square roots until absolutely necessary. Still, it transparently supports comparisons
//! with numerical values:
//!
@@ -38,9 +39,10 @@
//! assert_eq!(d, 5);
//! assert_eq!(d.value(), 5.0f32);
//!
-//! For finding the nearest neighbors to a point from a set of other points, the [NearestNeighbors]
-//! trait provides a uniform interface to [many different similarity search data structures]. One
-//! such structure is the [vantage-point tree], available in `acap` as [VpTree]:
+//! For finding the nearest neighbors to a point from a set of other points, the
+//! [`NearestNeighbors`] trait provides a uniform interface to [many different similarity search
+//! data structures]. One such structure is the [vantage-point tree], available in `acap` as
+//! [`VpTree`]:
//!
//! # use acap::euclid::Euclidean;
//! use acap::vp::VpTree;
@@ -53,9 +55,9 @@
//! Euclidean([7, 24]),
//! ]);
//!
-//! [VpTree] implements [NearestNeighbors], which has a [`nearest()`] method that returns an
-//! optional [Neighbor]. The [Neighbor] struct holds the actual neighbor it found, and the distance
-//! it was from the target:
+//! [`VpTree`] implements [`NearestNeighbors`], which has a [`nearest()`] method that returns an
+//! optional [`Neighbor`]. The [`Neighbor`] struct holds the actual neighbor it found, and the
+//! distance it was from the target:
//!
//! # use acap::euclid::Euclidean;
//! # use acap::vp::VpTree;
@@ -67,15 +69,15 @@
//! assert_eq!(nearest.item, &Euclidean([3, 4]));
//! assert_eq!(nearest.distance, 5);
//!
-//! [NearestNeighbors] also provides the [`nearest_within()`], [`k_nearest()`], and
+//! [`NearestNeighbors`] also provides the [`nearest_within()`], [`k_nearest()`], and
//! [`k_nearest_within()`] methods which find up to `k` neighbors within a possible threshold.
//!
//! It can be expensive to compute nearest neighbors exactly, especially in high dimensions.
-//! For performance reasons, [NearestNeighbors] implementations are allowed to return approximate
+//! For performance reasons, [`NearestNeighbors`] implementations are allowed to return approximate
//! results. Many implementations have a speed/accuracy tradeoff which can be tuned. Those
-//! implementations which always return exact results will also implement the [ExactNeighbors]
-//! marker trait. For example, a [VpTree] will be exact when the [Proximity] function is a
-//! [Metric].
+//! implementations which always return exact results will also implement the [`ExactNeighbors`]
+//! marker trait. For example, a [`VpTree`] will be exact when the [`Proximity`] function is a
+//! [`Metric`].
//!
//! [nearest neighbor search]: https://en.wikipedia.org/wiki/Nearest_neighbor_search
//! [`distance()`]: Proximity#tymethod.distance
@@ -84,7 +86,7 @@
//! [Euclidean distance]: https://en.wikipedia.org/wiki/Euclidean_distance
//! [many different similarity search data structures]: NearestNeighbors#implementors
//! [vantage-point tree]: https://en.wikipedia.org/wiki/Vantage-point_tree
-//! [VpTree]: vp::VpTree
+//! [`VpTree`]: vp::VpTree
//! [`nearest()`]: NearestNeighbors#method.nearest
//! [`k_nearest()`]: NearestNeighbors#method.k_nearest
//! [`nearest_within()`]: NearestNeighbors#method.nearest_within
diff --git a/src/taxi.rs b/src/taxi.rs
index f22afb0..8bbe2f3 100644
--- a/src/taxi.rs
+++ b/src/taxi.rs
@@ -7,10 +7,10 @@ use num_traits::{zero, Signed};
/// A point in taxicab space.
///
-/// This wrapper equips any [coordinate space] with the [taxicab distance metric].
+/// This wrapper equips any [coordinate space] with the [taxicab distance] metric.
///
-/// [coordinate space]: [Coordinates]
-/// [taxicab distance metric]: https://en.wikipedia.org/wiki/Taxicab_geometry
+/// [coordinate space]: Coordinates
+/// [taxicab distance]: taxicab_distance
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Taxicab<T>(pub T);
@@ -43,7 +43,7 @@ impl<T: Coordinates> Coordinates for Taxicab<T> {
}
}
-/// Compute the taxicab distance between two points.
+/// Compute the [taxicab distance] between two points.
///
/// ```math
/// \begin{aligned}
@@ -51,6 +51,8 @@ impl<T: Coordinates> Coordinates for Taxicab<T> {
/// &= \sum_i |x_i - y_i|
/// \end{aligned}
/// ```
+///
+/// [taxicab distance]: https://en.wikipedia.org/wiki/Taxicab_geometry
pub fn taxicab_distance<T, U>(x: T, y: U) -> T::Value
where
T: Coordinates,
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-22 03:43:27 +0000