# Expressions

Expressions are used in dispatch displays, charts and tables. In the dispatch context they access data attributes through the `values` object.

Expression can include function and any other path values.

Example, calculate BMI from metric weight and height.

``````values.weight / (values.height) ^ 2
``````

## Data

Pick and apply are passed objects that can be accessed from the expression.

Pick is passed: 1. `values` - dispatch data 2. `dispatch` - other attributes on the dispatch

Apply is passed: 1. `ls` - an array of values that are the result of pick

## Syntax

Operator Name Syntax Associativity Example Result
`(, )` Grouping `(x)` None `2 * (3 + 4)` `14`
`[, ]` Matrix, Index `[...]` None `[[1,2],[3,4]]` `[[1,2],[3,4]]`
`{, }` Object `{...}` None `{a: 1, b: 2}` `{a: 1, b: 2}`
`,` Parameter separator `x, y` L🡒R `max(2, 1, 5)` `5`
`.` Property accessor `obj.prop` L🡒R `obj={a: 12}; obj.a` `12`
`;` Statement separator `x; y` L🡒R `a=2; b=3; a*b` ``
`;` Row separator `[x; y]` L🡒R `[1,2;3,4]` `[[1,2],[3,4]]`
`\n` Statement separator `x \n y` L🡒R `a=2 \n b=3 \n a*b` `[2,3,6]`
`+` Add `x + y` L🡒R `4 + 5` `9`
`+` Unary plus `+y` L🡐R `+4` `4`
`-` Subtract `x - y` L🡒R `7 - 3` `4`
`-` Unary minus `-y` L🡐R `-4` `-4`
`*` Multiply `x * y` L🡒R `2 * 3` `6`
`.*` Element-wise multiply `x .* y` L🡒R `[1,2,3] .* [1,2,3]` `[1,4,9]`
`/` Divide `x / y` L🡒R `6 / 2` 3
`./` Element-wise divide `x ./ y` L🡒R `[9,6,4] ./ [3,2,2]` `[3,3,2]`
`%`, `mod` Modulus `x % y` L🡒R `8 % 3` `2`
`^` Power `x ^ y` L🡐R `2 ^ 3` `8`
`.^` Element-wise power `x .^ y` L🡐R `[2,3] .^ [3,3]` `[8,27]`
`'` Transpose `y'` L🡒R `[[1,2],[3,4]]'` `[[1,3],[2,4]]`
`!` Factorial `y!` L🡒R `5!` `120`
`&` Bitwise and `x & y` L🡒R `5 & 3` `1`
`~` Bitwise not `~x` L🡐R `~2` `-3`
`\|` Bitwise or `x \| y` L🡒R `5 \| 3` `7`
`^\|` Bitwise xor `x ^\| y` L🡒R `5 ^\| 2` `7`
`<<` Left shift `x << y` L🡒R `4 << 1` `8`
`>>` Right arithmetic shift `x >> y` L🡒R `8 >> 1` `4`
`>>>` Right logical shift `x >>> y` L🡒R `-8 >>> 1` `2147483644`
`and` Logical and `x and y` L🡒R `true and false` `false`
`not` Logical not `not y` L🡐R `not true` `false`
`or` Logical or `x or y` L🡒R `true or false` `true`
`xor` Logical xor `x xor y` L🡒R `true xor true` `false`
`=` Assignment `x = y` L🡐R `a = 5` `5`
`? :` Conditional expression `x ? y : z` L🡐R `15 > 100 ? 1 : -1` `-1`
`:` Range `x : y` L🡐R `1:4` `[1,2,3,4]`
`to`, `in` Unit conversion `x to y` L🡒R `2 inch to cm` `5.08 cm`
`==` Equal `x == y` L🡒R `2 == 4 - 2` `true`
`!=` Unequal `x != y` L🡒R `2 != 3` `true`
`<` Smaller `x < y` L🡒R `2 < 3` `true`
`>` Larger `x > y` L🡒R `2 > 3` `false`
`<=` Smallereq `x <= y` L🡒R `4 <= 3` `false`
`>=` Largereq `x >= y` L🡒R `2 + 4 >= 6` `true`

## Functions

Both pick and apply support functions. These can be part of the

1. `mad(..)` - Median absolute deviation
2. `max(..)` - Maximum value
3. `mean(..)` - Mean value
4. `median(..)` - Median value
5. `min(..)` - Minimum value
6. `mode(..)` - Mode
7. `prod(..)` - Product
8. `std(..)` - Standard deviation
9. `sum(..)` - Compute the sum
10. `variance(..)` - Provide a Maximum value
11. `time(metric)` - Compute the delta in a time range metric
12. `timeStart(metric)` - Provide the start time of a time range metric
13. `timeEnd(metric)` - Provide the end time of a time range metric
14. `at(ls, n)` - Access a specific value in the list; 0 is the first, -1 the last.
15. `isDefined(n)` - check if a variable has a value and return values based on that
16. `toNumber(n, str, left, right)` - turn a string into a value with the expression n === str ? left : right
17. `ifNull(n, default=0)` - if N is not defined then replace with default
18. `ifNaN(n, default=0)` - if N is not number than replace with a default value
19. `symbol(...)` - Returns the referenced attribute as a symbol

## Some examples

### Example 1

pick = `1` apply = `sum(ls)`

The value 1 would be generated for each dispatch and ls would be [1, 1, 1, ..] with a 1 for each dispatch.

### Example 2

pick = `values.size * 2` apply = `mean(ls)`

Sized times two would be generated for each dispatch, based on the data, and then that array of values would be passed to mean. The result would be the mean of size * 2 for every dispatch in the series.

### Example 3

pick = `values.status == values.goal ? 3 : values.status == 0 ? 1 : values.status > 0 ? 2 : nil` apply = `mean(ls)`

In this example we have three outcomes: 3 if we hit the goal, 1 if status is zero and 2 if between the goal and zero. This is then passed to mean though presumably this would

This can then use conditional formatting to display different symbols, for example:

``````"rules": [
{
"rule": "values.result == 3",
"value": "◎"
},
{
"rule": "values.result == 2",
"value": "◯"
},
{
"rule": "values.result == 1",
"value": "✕"
}
]
``````