diff --git a/src/treefrog.rs b/src/treefrog.rs index e473436..3cc8a6e 100644 --- a/src/treefrog.rs +++ b/src/treefrog.rs @@ -106,7 +106,7 @@ tuple_leapers!(A B C D E); tuple_leapers!(A B C D E F); tuple_leapers!(A B C D E F G); -/// Methods to support treefrog leapjoin. +/// Methods to support [treefrog leapjoin](crate::Variable::from_leapjoin). pub trait Leaper<'leap, Tuple, Val> { /// Estimates the number of proposed values. fn count(&mut self, prefix: &Tuple) -> usize; @@ -121,11 +121,12 @@ pub(crate) mod filters { use super::Leapers; /// A treefrog leaper that tests each of the tuples from the main - /// input (the "prefix"). Use like `PrefixFilter::from(|tuple| - /// ...)`; if the closure returns true, then the tuple is - /// retained, else it will be ignored. This leaper can be used in - /// isolation in which case it just acts like a filter on the - /// input (the "proposed value" will be `()` type). + /// input (the "prefix") against a predicate. + /// + /// Use like `PrefixFilter::from(|tuple| ...)`; if the closure returns + /// true, then the tuple is retained, else it will be ignored. This + /// leaper can be used in isolation in which case it just acts like + /// a filter on the input (the "proposed value" will be `()` type). pub struct PrefixFilter bool> { phantom: ::std::marker::PhantomData, predicate: Func, @@ -238,6 +239,7 @@ pub(crate) mod filters { } /// A treefrog leaper based on a predicate of prefix and value. + /// /// Use like `ValueFilter::from(|tuple, value| ...)`. The closure /// should return true if `value` ought to be retained. The /// `value` will be a value proposed elsewhere by an `extend_with` @@ -285,6 +287,8 @@ pub(crate) mod filters { /// Extension method for relations. pub trait RelationLeaper { /// Extend with `Val` using the elements of the relation. + /// + /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, the key is looked up in this relation, then all corresponding values are added to the source. fn extend_with<'leap, Tuple: Ord, Func: Fn(&Tuple) -> Key>( &'leap self, key_func: Func, @@ -293,6 +297,8 @@ pub trait RelationLeaper { Key: 'leap, Val: 'leap; /// Extend with `Val` using the complement of the relation. + /// + /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, the key is looked up in this relation, then all corresponding values are removed from the source. fn extend_anti<'leap, Tuple: Ord, Func: Fn(&Tuple) -> Key>( &'leap self, key_func: Func, @@ -301,6 +307,8 @@ pub trait RelationLeaper { Key: 'leap, Val: 'leap; /// Extend with any value if tuple is present in relation. + /// + /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, then only keys found in the relation are kept in the source. fn filter_with<'leap, Tuple: Ord, Func: Fn(&Tuple) -> (Key, Val)>( &'leap self, key_func: Func, @@ -309,6 +317,8 @@ pub trait RelationLeaper { Key: 'leap, Val: 'leap; /// Extend with any value if tuple is absent from relation. + /// + /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, then all keys found in the relation are removed from the source. fn filter_anti<'leap, Tuple: Ord, Func: Fn(&Tuple) -> (Key, Val)>( &'leap self, key_func: Func, @@ -365,7 +375,9 @@ pub(crate) mod extend_with { use super::{binary_search, Leaper, Leapers, Relation}; use crate::join::gallop; - /// Wraps a Relation as a leaper. + /// Wraps a `Relation` as a [`Leaper`] that maps each source tuple to a key and adds the relation's corresponding values. + /// + /// This struct is created using the [`extend_with`](`crate::RelationLeaper::extend_with`) method on [`Relation`s](Relation). pub struct ExtendWith<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -464,7 +476,9 @@ pub(crate) mod extend_anti { use super::{binary_search, Leaper, Relation}; use crate::join::gallop; - /// Wraps a Relation as a leaper. + /// Wraps a `Relation` as a [`Leaper`] that maps each source tuple to a key and removes the relation's corresponding values. + /// + /// This struct is created using the [`extend_anti`](`crate::RelationLeaper::extend_anti`) method on [`Relation`s](Relation). pub struct ExtendAnti<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -543,7 +557,9 @@ pub(crate) mod filter_with { use super::{Leaper, Leapers, Relation}; - /// Wraps a Relation as a leaper. + /// Wraps a `Relation` as a [`Leaper`] that keeps only source tuples mapping to a key in the relation. + /// + /// This struct is created using the [`filter_with`](`crate::RelationLeaper::filter_with`) method on [`Relation`s](Relation). pub struct FilterWith<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -636,7 +652,9 @@ pub(crate) mod filter_anti { use super::{Leaper, Leapers, Relation}; - /// Wraps a Relation as a leaper. + /// Wraps a `Relation` as a [`Leaper`] that keeps only source tuples not mapping to a key in the relation. + /// + /// This struct is created using the [`filter_anti`](`crate::RelationLeaper::filter_anti`) method on [`Relation`s](Relation). pub struct FilterAnti<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, diff --git a/src/variable.rs b/src/variable.rs index 537822c..76d89c2 100644 --- a/src/variable.rs +++ b/src/variable.rs @@ -251,13 +251,13 @@ impl Variable { /// You can create a leaper in one of two ways: /// - Extension: In this case, you have a relation of type `(K, Val)` for some /// type `K`. You provide a closure that maps from `SourceTuple` to the key - /// `K`. If you use `relation.extend_with`, then any `Val` values the + /// `K`. If you use [`relation.extend_with`](`crate::RelationLeaper::extend_with`), then any `Val` values the /// relation provides will be added to the set of values; if you use - /// `extend_anti`, then the `Val` values will be removed. + /// [`extend_anti`](`crate::RelationLeaper::extend_anti`), then the `Val` values will be removed. /// - Filtering: In this case, you have a relation of type `K` for some /// type `K` and you provide a closure that maps from `SourceTuple` to /// the key `K`. Filters don't provide values but they remove source - /// tuples. + /// tuples. [`filter_with`](`crate::RelationLeaper::filter_with`) retains matching keys, whereas [`filter_anti`](`crate::RelationLeaper::filter_anti`) removes matching keys. /// - Finally, you get a callback `logic` that accepts each `(SourceTuple, Val)` /// that was successfully joined (and not filtered) and which maps to the /// type of this variable.