eachLeft

Syntax

eachLeft(func, X, Y, [assembleRule|consistent=false])

func:L(X, Y) or X <operator>:L Y, where assembleRule is not specified and the default value is used.

func:LC(X, Y) or X <operator>:LC Y, where assembleRule is specified as C (for "Consistent") as an example.

Arguments

func is a binary function.

X/ Y is a vector/matrix/table/array vector/dictionary.

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

Calculate func(X(i),Y) for each element of X.

  • X(i) is each element when X is a vector.

  • X(i) is each column when X is a matrix.

  • X(i) is each row when X is a table.

  • X(i) is each row when X is an array vector.

  • X(i) is each value when X is a dictionary.

If func supports vector operation and the input is a vector, we should use the vector function/operator directly instead of the eachLeft template for better performance.

Examples

eachLeft with 2 vectors:

x = 4 3 2 1
y = 3 0 6;
x +:L y;
4 3 2 1
7 6 5 4
4 3 2 1
10 9 8 7
eachLeft(pow, x, y);
4 3 2 1
64 27 8 1
1 1 1 1
4096 729 64 1

eachLeft with a vector and a matrix:

x=1..6$2:3;
x;
col1 col2 col3
1 3 5
2 4 6
x ** :L 1 1;
// output: [3,7,11]

eachLeft with 2 matrices:

y=6..1$2:3;
y;
col1 col2 col3
6 4 2
5 3 1
z = x **:L y;
z;

/* output:
(#0 #1 #2
-- -- --
16 10 4
,#0 #1 #2
-- -- --
38 24 10
,#0 #1 #2
-- -- --
60 38 16
)
*/
typestr z;
ANY VECTOR

eachLeft with a dictionary and a vector:

d=dict(`a`b`c, [[1, 2, 3],[4, 5, 6], [7, 8, 9]])
eachLeft(add,d,10 20 30)
/* output:
a->[11,22,33]
b->[14,25,36]
c->[17,28,39]
*/