Improve documentation for reduce operator (#4936)

editions/tw5.com/tiddlers/filters/examples/reduce Operator (Examples).tid

@@ -6,14 +6,19 @@ type: text/vnd.tiddlywiki
 
 \define add-price() [get[price]multiply{!!quantity}add<accumulator>]
 \define num-items() [get[quantity]add<accumulator>]
+\define join-with-commas() [<index>compare:number:gt[0]then<accumulator>addsuffix[, ]addsuffix<currentTiddler>else<currentTiddler>]
 \define display-variable(name)
 ''<$text text=<<__name__>>/>'': <code><$text text={{{ [<__name__>getvariable[]] }}}/></code>
 \end
+\define reduce-tip()
+Remember that <<.op reduce>> always produces output, so <<.op else>> will never trigger after <<.op reduce>>.
+\end
 
 These examples use the following predefined variables:
 
 * <<display-variable add-price>>
 * <<display-variable num-items>>
+* <<display-variable join-with-commas>>
 
 They also use the following data tiddlers:
 
@@ -32,3 +37,25 @@ Number of items:
 Total price:
 
 <<.operator-example 2 "[tag[shopping]reduce<add-price>]">>
+
+Using `<index>` to act differently on the first item than the rest:
+
+<<.operator-example 3 "[tag[shopping]reduce<join-with-commas>]">>
+
+Empty input, no suffix:
+
+<<.operator-example 4 "[tag[non-existent]reduce<add-price>]">>
+
+Note how the output contains a single item with no text. This is not "empty output" for the purposes of the <<.op else>> operator.
+
+<$macrocall $name=".tip" _=<<reduce-tip>> />
+
+Empty input, no suffix, followed by <<.op else>>:
+
+<<.operator-example 5 "[tag[non-existent]reduce<add-price>else[0]]">>
+
+Note how the output still contains a single item with no text: <<.op else>> did not trigger. If you want the value to be 0 when <<.op reduce>> has no items to process, you need to specify 0 as the initial value by passing it as a suffix to <<.op reduce>>.
+
+Empty input, suffix provided:
+
+<<.operator-example 6 "[tag[non-existent]reduce:0<add-price>]">>

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

@@ -12,6 +12,10 @@ tags: [[Filter Operators]]
 title: reduce Operator
 type: text/vnd.tiddlywiki
 
+\define reduce-tip()
+The <<.op reduce>> operator will always produce output, even if its input was empty. If its input is empty, the output of <<.op reduce>> will be the initial value of the accumulator, i.e. the value of the suffix. One result of this fact is that the <<.op else>> operator will never be triggered if it follows a <<.op reduce>>. The "Empty input" examples show what happens when <<.op reduce>> receives no input.
+\end
+
 <<.from-version "5.1.23">> The <<.op reduce>> operator runs a subfilter for each input title, passing the result of the previous subfilter run as a variable. The initial value of the accumulator can optionally be specified. It returns the result of the final subfilter run.
 
 The <<.op reduce>> operator is used to flatten a list of items down to a single item by repeatedly applying a formula. A typical use is to add up the values in a given field of a list of tiddlers.
@@ -24,4 +28,6 @@ The following variables are available within the subfilter:
 * ''revIndex'' - the reverse numeric index of the current list item (with zero being the last item in the list)
 * ''length'' - the total length of the input list
 
+<$macrocall $name=".tip" _=<<reduce-tip>> />
+
 <<.operator-examples "reduce">>