Module red

source code

red -r [BINARY_FUNCTION ...]

Aggregates (reduces) objects from the input stream in a simpler but less general way than the agg command.

A BINARY_FUNCTION takes two inputs and produces one output. Binary operators and user-defined functions can be used as BINARY_FUNCTIONs. Given a sequence of inputs such as (1,), (2,), (3,), red can be used to find the sum:

   ... ^ red +

yields (6,). If each input sequence contains multiple values, then multiple BINARY_FUNCTIONs can be provided. For example, to find the sums of the first 10 integers, the sum of their squares, and the sum of their cubes:

   osh gen 10 ^ f 'x: (x, x**2, x**3)' ^ red + + + $

which yields the output (45, 285, 2025).

If . is provided as one of the BINARY_FUNCTIONs, then that value is not aggregated. Instead, aggregation is done for the groups defined by the indicated elements. For example, suppose the input sequence is:

   (1, 10, 5, 100)
   (1, 10, 6, 200)
   (1, 11, 4, 100)
   (1, 11, 3, 200)
   (2, 20, 8, 100)
   (2, 20, 9, 200)
   (2, 20, 10, 300)
   (3, 30, 5, 100)

If this sequence is piped to this invocation of red:

   red . . + +

Then the output sequence would be:

   (1, 10, 11, 300)
   (1, 11, 7, 300)
   (2, 20, 17, 300)
   (3, 30, 5, 100)

The two .s, in the first two positions, mean that the groups used for aggregation are (1, 10), (1, 11), (2, 20), and (3, 30). The (1, 10) group has two rows, (1, 10, 5, 100), and (1, 10, 6, 200). The two +s mean that the items in the last two fields should be summed. Adding the items in the third position, 5 + 6 = 11; and in the last position, 100 + 200 = 300.

If the -r flag is specified, then one output object is generated for each input object; the output object contains the current accumulated values. The accumulator appears in the output row before the inputs. For example, if the input stream contains (1,), (2,), (3,), then the running total can be computed as follows:

   ... ^ red -r + ^ ...

The output stream would be (1, 1), (3, 2), (6, 3). In the last output object, 6 is the sum of the current input (3) and all preceding inputs (1, 2).

The -r flag can also be used with grouping. For example, if the input objects are ('a', 1), ('a', 2), ('b', 3), ('b', 4), then the running totals for the strings would be computed as follows:

   ... ^ red -r -g 'x, y: x' 0 'sum, x, y: sum + y' ^ ...

The output stream would be (1, 'a', 1), (3, 'a', 2), (3, 'b', 3), (7, 'b', 4).