eachPre

Syntax

eachPre(func, X, [pre], [consistent=false])

[pre] <operator>:P X or func:P([pre], X), where assembleRule is not specified and the default value is used.

[pre] <operator>:PC X or func:PC([pre], X), where assembleRule is specified as C (for "Consistent") as an example.

Arguments

func is a binary function.

X is a vector/matrix/table. When X is a matrix, pre must be a scalar or vector; when X is a table, pre must be a scalar or table. When pre is absent, the first element in the result would be NULL.

pre (optional) provides an initial pre-value for the calculation. Its data form depends on the data form of X.

assembleRule (optional) indicates how the results of sub-tasks are merged into the final result. It accepts either an integer or a string, with the following options:

  • 0 (or "D"): The default value, which indicates the DolphinDB rule. This means the data type and form of the final result are determined by all sub results. If all sub results have the same data type and form, scalars will be combined into a vector, vectors into a matrix, matrices into a tuple, and dictionaries into a table. Otherwise, all sub results are combined into a tuple.

  • 1 (or "C"): The Consistent rule, which assumes all sub results match the type and form of the first sub result. This means the first sub result determines the data type and form of the final output. The system will attempt to convert any subsequent sub results that don't match the first sub result. If conversion fails, an exception is thrown. This rule should only be used when the sub results' types and forms are known to be consistent. This rule avoids having to cache and check each sub result individually, improving performance.

  • 2 (or "U"): The Tuple rule, which directly combines all sub results into a tuple without checking for consistency in their types or forms.

  • 3 (or "K"): The kdb+ rule. Like the DolphinDB rule, it checks all sub results to determine the final output. However, under the kdb+ rule, if any sub result is a vector, the final output will be a tuple. In contrast, under the DolphinDB rule, if all sub results are vectors of the same length, the final output will be a matrix. In all other cases, the output of the kdb+ rule is the same as the DolphinDB rule.

Note:

  • Starting from version 2.00.15/3.00.3, the new assembleRule parameter has been introduced. This parameter not only incorporates all the functionality of the original consistent parameter but also offers additional options for combining results.

    The consistent parameter is a boolean value that defaults to false, which is equivalent to setting assembleRule="D". When set to true, it’s equivalent to assembleRule="C". For backward compatibility, users can still use the consistent parameter. If both assembleRule and consistent are specified in the same operation, the value of consistent takes precedence.

  • assembleRule can also be specified after a function pattern symbol, represented by characters D/C/U/K (e.g., sub:PU(X). If not specified, the default value D will be used.

Details

Apply func over all pairs of consecutive elements of X. It is equivalent to: F(X[0], pre), F(X[1], X[0]), ..., F(X[n], X[n-1]).

The built-in functions ratios and deltas are also implemented by the eachPre template. They are defined as:

  • function deltas(a){return a[0] -:P a}

  • function ratios(a){return a[0] :P a}

Examples

x=1..10;

eachPre(sub, x);
// output: [,1,1,1,1,1,1,1,1,1]
// equivalent to [NULL, 2-1, ..., 10-9]

eachPre(sub, x,,assembleRule="U");
// output: (,1,1,1,1,1,1,1,1,1)

-:P x;
// output: [,1,1,1,1,1,1,1,1,1]
// same as above

eachPre(+, x);
// output: [,3,5,7,9,11,13,15,17,19]
// equivalent to [NULL, 2+1, ..., ]

0 +:P x;
// output: [1,3,5,7,9,11,13,15,17,19]
// equivalent to [1+0, 2+1, ..., ]

x=1..12$3:4;
x;
col1 col2 col3 col4
1 4 7 10
2 5 8 11
3 6 9 12 
- :P x;
col1 col2 col3 col4
3 3 3
3 3 3
3 3 3 
eachPre(\, x, x[0]);
col1 col2 col3 col4
1 4 1.75 1.428571
1 2.5 1.6 1.375
1 2 1.5 1.333333 
def f1(a,b){
    return (a[`x])+(a[`y])+(b[`x])+(b[`y])
}

t = table(1 2 3 as x,2 3 4 as y)
t1 = table(1 as x,2 as y)
eachPre(f1,t,t1)

// output: ([6],8,12)
Compare two result combining rules.
tab = table(til(5) as a,`a`a`b`b`c as b)
select *, contextby({x,y->isNull(y) ? [x] : [y,x]}:P,a,b) as c from tab
// Use the DolphinDB rule
a b c    
- - -----
0 a [0]  
1 a [0,1]
2 b [2]  
3 b [2,3]
4 c 4    

select *, contextby({x,y->isNull(y) ? [x] : [y,x]}:PU,a,b) as c from tab
// Use the Tuple rule to output - the c column in the last row is output as a vector
a b c    
- - -----
0 a [0]  
1 a [0,1]
2 b [2]  
3 b [2,3]
4 c [4]