From e10efc2b52bd353a3b85b8b526f517df9a088b45 Mon Sep 17 00:00:00 2001 From: IFcoltransG <47414286+IFcoltransG@users.noreply.github.com> Date: Tue, 5 Nov 2024 11:02:40 +1300 Subject: [PATCH 1/7] Format docs for leapers --- src/treefrog.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/treefrog.rs b/src/treefrog.rs index e473436..3e1935c 100644 --- a/src/treefrog.rs +++ b/src/treefrog.rs @@ -365,7 +365,7 @@ 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. pub struct ExtendWith<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -464,7 +464,7 @@ 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. pub struct ExtendAnti<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -543,7 +543,7 @@ pub(crate) mod filter_with { use super::{Leaper, Leapers, Relation}; - /// Wraps a Relation as a leaper. + /// Wraps a `Relation` as a leaper. pub struct FilterWith<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -636,7 +636,7 @@ pub(crate) mod filter_anti { use super::{Leaper, Leapers, Relation}; - /// Wraps a Relation as a leaper. + /// Wraps a `Relation` as a leaper. pub struct FilterAnti<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, From cf8a90bf77f543b5e96500cea8d7e268ede1b45c Mon Sep 17 00:00:00 2001 From: IFcoltransG <47414286+IFcoltransG@users.noreply.github.com> Date: Tue, 5 Nov 2024 11:06:44 +1300 Subject: [PATCH 2/7] Break leaper docs into parts --- src/treefrog.rs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/treefrog.rs b/src/treefrog.rs index 3e1935c..382db82 100644 --- a/src/treefrog.rs +++ b/src/treefrog.rs @@ -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` From bacf48ba9de430c655f9b850d614dded329ce6e8 Mon Sep 17 00:00:00 2001 From: IFcoltransG <47414286+IFcoltransG@users.noreply.github.com> Date: Tue, 5 Nov 2024 12:05:45 +1300 Subject: [PATCH 3/7] Add specific doc comment to each leaper wrapper --- src/treefrog.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/treefrog.rs b/src/treefrog.rs index 382db82..cc9401f 100644 --- a/src/treefrog.rs +++ b/src/treefrog.rs @@ -367,7 +367,7 @@ 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. pub struct ExtendWith<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -466,7 +466,7 @@ 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. pub struct ExtendAnti<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -545,7 +545,7 @@ 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. pub struct FilterWith<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, @@ -638,7 +638,7 @@ 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. pub struct FilterAnti<'leap, Key, Val, Tuple, Func> where Key: Ord + 'leap, From 0ab59063bcdbae7237f3a4bc7a642aeb63edb660 Mon Sep 17 00:00:00 2001 From: IFcoltransG <47414286+IFcoltransG@users.noreply.github.com> Date: Tue, 5 Nov 2024 12:48:02 +1300 Subject: [PATCH 4/7] Add extra intra-doc links in leapers docs --- src/treefrog.rs | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/src/treefrog.rs b/src/treefrog.rs index cc9401f..214b183 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; @@ -367,7 +367,9 @@ pub(crate) mod extend_with { use super::{binary_search, Leaper, Leapers, Relation}; use crate::join::gallop; - /// Wraps a `Relation` as a leaper that maps each source tuple to a key and adds the relation's corresponding values. + /// 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, @@ -466,7 +468,9 @@ pub(crate) mod extend_anti { use super::{binary_search, Leaper, Relation}; use crate::join::gallop; - /// Wraps a `Relation` as a leaper that maps each source tuple to a key and removes the relation's corresponding values. + /// 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, @@ -545,7 +549,9 @@ pub(crate) mod filter_with { use super::{Leaper, Leapers, Relation}; - /// Wraps a `Relation` as a leaper that keeps only source tuples mapping to a key in the relation. + /// 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, @@ -638,7 +644,9 @@ pub(crate) mod filter_anti { use super::{Leaper, Leapers, Relation}; - /// Wraps a `Relation` as a leaper that keeps only source tuples not mapping to a key in the relation. + /// 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, From 6834a41ec6a78b0dda453bf331bbd3203f1ddd16 Mon Sep 17 00:00:00 2001 From: IFcoltransG <47414286+IFcoltransG@users.noreply.github.com> Date: Tue, 5 Nov 2024 13:08:22 +1300 Subject: [PATCH 5/7] Expand docs for leaper constructors on Relation --- src/treefrog.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/treefrog.rs b/src/treefrog.rs index 214b183..ee24a36 100644 --- a/src/treefrog.rs +++ b/src/treefrog.rs @@ -287,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, @@ -295,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, @@ -303,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 all keys found in the relation are added to the source. fn filter_with<'leap, Tuple: Ord, Func: Fn(&Tuple) -> (Key, Val)>( &'leap self, key_func: Func, @@ -311,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, From e2c0d682105936d08d39f65590d7a86ed57cfd6a Mon Sep 17 00:00:00 2001 From: IFcoltransG <47414286+IFcoltransG@users.noreply.github.com> Date: Tue, 5 Nov 2024 13:14:27 +1300 Subject: [PATCH 6/7] Clarify `filter_with` doc comment --- src/treefrog.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/treefrog.rs b/src/treefrog.rs index ee24a36..3cc8a6e 100644 --- a/src/treefrog.rs +++ b/src/treefrog.rs @@ -308,7 +308,7 @@ pub trait RelationLeaper { 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 all keys found in the relation are added to the source. + /// 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, From 29d1f6b8fbe4f7a7fb82465e14c5cd21f64f2815 Mon Sep 17 00:00:00 2001 From: IFcoltransG <47414286+IFcoltransG@users.noreply.github.com> Date: Tue, 5 Nov 2024 13:17:15 +1300 Subject: [PATCH 7/7] Link to leaper constructors from treejoin docs --- src/variable.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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.