From da5d12d6fb09254396909aafc427aed5d2e1c66b Mon Sep 17 00:00:00 2001 From: Saq Imtiaz Date: Wed, 9 Dec 2020 12:11:14 +0100 Subject: [PATCH] Docs for :reduce filter run prefix (#5238) --- editions/tw5.com/tiddlers/filters/reduce.tid | 17 ++++++++++++++- .../filters/syntax/Filter Expression.tid | 8 +++++-- .../syntax/Filter Run Prefix (Examples).tid | 21 ++++++++++++++++++- 3 files changed, 42 insertions(+), 4 deletions(-) diff --git a/editions/tw5.com/tiddlers/filters/reduce.tid b/editions/tw5.com/tiddlers/filters/reduce.tid index debd28c9f..153fe463c 100644 --- a/editions/tw5.com/tiddlers/filters/reduce.tid +++ b/editions/tw5.com/tiddlers/filters/reduce.tid @@ -1,6 +1,6 @@ caption: reduce created: 20201004154131193 -modified: 20201204130601564 +modified: 20201208185109549 op-input: a [[selection of titles|Title Selection]] passed as input to the filter op-output: the final result of running the subfilter <<.place S>> op-parameter: a [[filter expression|Filter Expression]]. Optional second parameter for initial value for accumulator @@ -28,4 +28,19 @@ The following variables are available within the subfilter: <$macrocall $name=".tip" _=<> /> + +<<.tip "Compare with the analagous named filter run prefix `:reduce`">> + +``` +\define num-items() [get[quantity]add] + +[tag[shopping]reduce] +``` + +is equivalent to: + +``` +[tag[shopping]] :reduce[get[quantity]add] +``` + <<.operator-examples "reduce">> diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid index fb2a1704e..0b3835373 100644 --- a/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid +++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Expression.tid @@ -1,5 +1,5 @@ created: 20150124182421000 -modified: 20201102224444831 +modified: 20201208185257875 tags: [[Filter Syntax]] title: Filter Expression type: text/vnd.tiddlywiki @@ -24,9 +24,13 @@ If a run has: * named prefixes for filter runs are available. <<.from-version "5.1.23">> * named prefix `:filter`, it receives the filter output so far as its input. The next run is evaluated for each title of the input, removing every input title for which the output is an empty list. <<.from-version "5.1.23">> * named prefix `:intersection` replaces all filter output so far with titles that are present in the output of this run, as well as the output from previous runs. Forms the input for the next run. <<.from-version "5.1.23">> +* named prefix `:reduce` replaces all filter output so far with a single item by repeatedly applying a formula to each input title. A typical use is to add up the values in a given field of each input title. <<.from-version "5.1.23">> +** [[Examples|Filter Run Prefix (Examples)]] <<.tip "Compare named filter run prefix `:filter` with [[filter Operator]] which applies a subfilter to every input title, removing the titles that return an empty result from the subfilter">> +<<.tip "Compare named filter run prefix `:reduce` with [[reduce Operator]] which is used to used to flatten a list of items down to a single item by repeatedly applying a subfilter.">> + In technical / logical terms: |!Run |!Equivalent named prefix |!Interpretation |!Output | @@ -43,7 +47,7 @@ The input of a run is normally a list of all the non-[[shadow|ShadowTiddlers]] t |Prefix|Input|h |`-`, `~`, `=`, `:intersection` or none| <$link to="all Operator">`[all[]]` tiddler titles, unless otherwise determined by the first [[filter operator|Filter Operators]]| -|`+`, `:filter`|the filter output of all previous runs so far| +|`+`, `:filter`, `:reduce`|the filter output of all previous runs so far| Precisely because of varying inputs, be aware that both prefixes `-` and `+` do not behave inverse to one another! diff --git a/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid b/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid index eb88c339b..f40cc7356 100644 --- a/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid +++ b/editions/tw5.com/tiddlers/filters/syntax/Filter Run Prefix (Examples).tid @@ -1,7 +1,8 @@ created: 20201117073343969 -modified: 20201117074106350 +modified: 20201208185546667 tags: [[Filter Syntax]] title: Filter Run Prefix (Examples) +type: text/vnd.tiddlywiki !! Difference between `+` and `:intersection` @@ -23,3 +24,21 @@ The following examples use the [[field Operator]] and [[compare Operator]] tiddl <<.operator-example 3 "[[field Operator]tags[]] +[[compare Operator]tags[]]" """The "field Operator" tiddler's tags are lost, so only the "compare Operator" tiddler's tags are returned""">> <<.operator-example 4 "[[field Operator]tags[]] :intersection[[compare Operator]tags[]]" """Returns the tags that both tiddlers have in common""">> + +!! `:reduce` examples + +``` +[tag[shopping]] :reduce[get[quantity]add] +``` + +is equivalent to: + +``` +\define num-items() [get[quantity]add] + +[tag[shopping]reduce] +``` + +Specifying a default value: + +`[tag[non-existent]] :reduce[get[price]multiply{!!quantity}add] :else[[0]]`