Docs updates

editions/prerelease/tiddlers/Release 5.1.20.tid

@@ -9,7 +9,7 @@ type: text/vnd.tiddlywiki
 
 !! Major Improvements
 
-[[Added|https://github.com/Jermolene/TiddlyWiki5/commit/0ea00b59b0dcd3de003e92a6bc0b27814fd0ec81]] support for mathematical operations within filters.
+Added several new [[Mathematics Operators]] for working with numbers.
 
 !! Plugin Improvements
 

editions/tw5.com/tiddlers/filters/Filter Operators.tid

@@ -1,5 +1,5 @@
 created: 20140410103123179
-modified: 20161017154031883
+modified: 20190206140446821
 tags: Filters
 title: Filter Operators
 type: text/vnd.tiddlywiki
@@ -30,19 +30,21 @@ The following table lists all core operators, the most common ones marked ✓. T
 <th align="center">✓</th>
 <th align="center">`!`</th>
 </tr>
-<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[Mathematics Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
 <<.group-heading "Order Operators">>
-<<.operator-rows "[tag[Filter Operators]tag[Order Operators]!tag[Listops Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.operator-rows "[tag[Filter Operators]tag[Order Operators]!tag[Listops Operators]!tag[Mathematics Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
 <<.group-heading "Listops Operators">>
-<<.operator-rows "[tag[Filter Operators]tag[Listops Operators]tag[Order Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.operator-rows "[tag[Filter Operators]tag[Listops Operators]tag[Order Operators]!tag[Mathematics Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
 <<.group-heading "String Operators">>
-<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[Mathematics Operators]tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.group-heading "Mathematics Operators">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]tag[Mathematics Operators]!tag[String Operators]!tag[Tag Operators]!tag[Special Operators]sort[]]">>
 <<.group-heading "Tag Operators">>
-<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[String Operators]tag[Tag Operators]!tag[Special Operators]sort[]]">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[Mathematics Operators]!tag[String Operators]tag[Tag Operators]!tag[Special Operators]sort[]]">>
 <<.group-heading "Special Operators">>
-<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[String Operators]!tag[Tag Operators]tag[Special Operators]sort[]]">>
+<<.operator-rows "[tag[Filter Operators]!tag[Order Operators]!tag[Mathematics Operators]!tag[String Operators]!tag[Tag Operators]tag[Special Operators]sort[]]">>
 </table>
 
 A typical step is written as `[operator[parameter]]`, although not all of the operators need a [[parameter|Filter Parameter]].
 
-Most steps process the [[selection of titles|Title Selection]] that are supplied as their input, but a few [[construct an entirely new selection|Selection Constructors]] instead. For the exact rules, see [[Filter Syntax]].
+Most steps process the [[selection of titles|Title Selection]] that are supplied as their input, but a few [[construct an entirely new selection|Selection Constructors]] instead. For the exact rules, see [[Filter Syntax]].

editions/tw5.com/tiddlers/filters/Mathematics Operators.tid

@@ -0,0 +1,40 @@
+created: 20190206140446821
+modified: 20190206140446821
+title: Mathematics Operators
+tags: Filters
+
+<<.from-version "5.1.20">>The mathematics filter operators allow numerical calculations to be performed within filters.
+
+The mathematics operators interpret their arguments as numbers according to the following rules:
+
+* Any non-numeric characters after a valid number are ignored (e.g. `28px` is interpreted as the number 28)
+* If the argument cannot be interpreted as a number, the value 0 is used (e.g. `foo` is interpreted as the number 0)
+* The special values `Infinity` and `-Infinity` can be used to represent positive and negative infinity respectively
+
+The mathematics operators take three different forms:
+
+* ''Unary operators'' apply an operation to each number in the input list (e.g. negate, truncate, sign)
+** <<.inline-operator-example "1 2 3 4 +[negate[]]">>
+** <<.inline-operator-example "1.2 2.4 3.6 4.8 +[trunc[]]">>
+** <<.inline-operator-example "1.2 2.4 3.6 4.8 +[round[]]">>
+* ''Binary operators'' apply an operation and operand to each number in the input list (e.g. add, multiply, remainder) 
+** <<.inline-operator-example "1 2 3 4 +[add[3]]">>
+** <<.inline-operator-example "1 2 3 4 +[multiply[8]]">>
+* ''Array operators'' apply an operation to all of the numbers in the input list, returning a single result (e.g. sum, product)
+** <<.inline-operator-example "1 2 3 4 +[sum[]]">>
+** <<.inline-operator-example "1 2 3 4 +[product[]]">>
+
+Operators can be combined:
+
+* <<.inline-operator-example "[[355]divide[113]fixed[5]]">>
+* <<.inline-operator-example "[range[100]sum[]divide[100]]">>
+* <<.inline-operator-example "[tag[HelloThere]get[text]length[]sum[]]">>
+
+Complex operations will sometimes need to be split up into separate filters. For example, to compute the average length of the text field of tiddlers tagged "~HelloThere":
+
+<$macrocall $name='wikitext-example-without-html'
+src="""<$set name="number-of-tiddlers" value={{{ [tag[HelloThere]count[]] }}}>
+Average length of <$text text=<<number-of-tiddlers>>/> tiddlers tagged <<tag "HelloThere">>: <$text text={{{ [tag[HelloThere]get[text]length[]sum[]divide<number-of-tiddlers>fixed[3]] }}}/>
+</$set>""" />
+
+<<list-links "[tag[Mathematics Operators]]">>

editions/tw5.com/tiddlers/filters/add.tid

@@ -0,0 +1,15 @@
+created: 20190206140446821
+modified: 20190206140446821
+tags: [[Filter Operators]] [[Mathematics Operators]] [[Binary Mathematics Operators]]
+title: add Operator
+type: text/vnd.tiddlywiki
+caption: add
+op-purpose: treating each input title as a number, add to each the numeric value of the operand
+op-input: a [[selection of titles|Title Selection]]
+op-parameter: a number
+op-parameter-name: N
+op-output: the input as numbers, but with <<.place N>> added to each one
+
+<<.from-version "5.1.20">>
+
+<<.operator-examples "add">>

editions/tw5.com/tiddlers/system/operator-macros.tid

@@ -28,6 +28,10 @@ tags: $:/tags/Macro
 </$list>
 \end
 
+\define .inline-operator-example(eg)
+<code><$text text=<<__eg__>>/></code> evaluates to <$list filter=<<__eg__>> emptyMessage="(empty)"> <code><$text text=<<currentTiddler>>/></code> </$list>
+\end
+
 \define .this-is-operator-example() This example tiddler is used to illustrate some of the [[Filter Operators]].
 \define .using-days-of-week() These examples make use of the [[Days of the Week]] tiddler.
 \define .s-matching-is-case-sensitive() In looking for matches for <<.place S>>, capital and lowercase letters are treated as different.