# Formula Language You can compute values derived from raw tag values by writing formulae similar to JavaScript expressions. The formulae are continuously evaluated as input tag values change. Currently, Clarity supports using formulae for notification conditions, but it may support them for more uses in the future. ## Examples Test if either `tag1` or `tag2` is not available (`null`):

tagValue("tag1") === null || tagValue("tag2") === null

Test if `flow` is less than 10 (in whatever units the tag has) while pumping, assmuing that the `pumping` tag is a `boolean`: ``` tagValue("pumping") && tagValue("flow") < 10 ``` Test if `flow` has been above 10 (in whatever units the tag has) for at least an hour: ``` conditionHoldsFor(tagValue("flow") > 10, 1h) ``` Test if the max of three tags is above another tag: ``` max( tagValue("pressure1"), tagValue("pressure2"), tagValue("pressure3") ) > tagValue("pressureLimit") ``` ## Language Reference ### Data Types Formulae support JavaScript `number`, `boolean`, and `string` data types, as well as `null` (used when a value isn't available for a tag or an expression on that tag). Numbers are represented as 64-bit floating point values, although when performing bitwise operations, they are first converted to 32-bit integer values, then the result is converted back to a 64-bit floating point value. #### No Coercion to Number or Boolean Unlike JavaScript, formula won't automatically coerce other data types to `number` or `boolean` values, and any operation on mismatched data types (except for string concatenation with `+`) will be flagged as an error. #### `null` propagation Unlike JavaScript, the result of an arithmetic, bitwise, or comparison operation will be `null` if one of the operands is `null`. For example the expression `tagValue("a") + tagValue("b")` will be `null` if the value of either of the two tags is `null` (not available). #### No `NaN` Unlike JavaScript, there is no `NaN` constant; `null` is returned instead, for example from `0 / 0`. ### Keywords `true`, `false`, and `null` have the same values as in JSON. ### Number Literals As in JSON, a number may consist of decimal digits `0`-`9`, optional digits after a decimal place `.`, and and optional positive or negative exponent `e8` or `e-8`. ### String Literals As in JSON, a string literal consists of text between double quotes (`"`), for example: ``` "hello world" ``` The backslash (`\`) allows you to escape special characters: | Escape sequence | Actual Value | | ----------------------------------------- | ----------------- | | `\\` | `\` | | `\"` | `"` | | `\n` | newline | | `\r` | carriage return | | `\t` | horizontal tab | | `\b` | backspace | | `\f` | form feed | | `\u0000` (any hex digits, up to `\uffff`) | unicode character | ### Time Intervals Some functions accept time intervals as arguments; a time interval is a number with a time unit suffix, for example: | Literal | Meaning | | ------- | -------------- | | `3s` | 3 seconds | | `5ms` | 5 milliseconds | | `10m` | 10 minutes | | `1h` | 1 hour | | `3d` | 3 days | ### Built-in Functions #### `tagValue()` Gets the value of the given `` at the current time. `` must be a string literal, for example: ``` tagValue("Site 1/battery/1/lifetimeWh") ``` `tagValue()` may evaluate to a `number`, `string`, `boolean`, depending on the data type of the given tag, or `null` if a value for the given tag is not available at the current time. #### `tagIsNAFor(, )` Evaluates to `true` if the given `` has been unavailable for at least the given amount of time. If there is or was a value available for the tag more recently than the given amount of time before the present, evaluates to `false`. `` must be a string literal and `` must be a [time interval](#time-intervals), for example: ``` tagIsNAFor("Site 1/battery/1/lifetimeWh", 5m) ``` #### `maxChange(, )` Evaluates to the maximum amount the given `` has changed over the given `` of time since the present. Always evaluates to a positive number, the absolute difference between the minimum and maximum values of `` over the past ``. `` can be any expression that evaluates to a `number` or `null`. `` must be a [time interval](#time-intervals) no greater than one day. #### `conditionHoldsFor(, )` Evaluates to `true` if the given `` has remained `true` over the given `` of time since the present. Otherwise, evaluates to `false`. `` can be any expression that evaluates to a `boolean` or `null`. `` must be a [time interval](#time-intervals) no greater than one day. #### Math functions The following JavaScript `Math` functions are available:

Function	Description
`abs(x)`	Returns the absolute value of `x`.
`acos(x)`	Returns the arccosine of `x`.
`acosh(x)`	Returns the hyperbolic arccosine of `x`.
`asin(x)`	Returns the arcsine of `x`.
`asinh(x)`	Returns the hyperbolic arcsine of `x`.
`atan(x)`	Returns the arctangent of `x`.
`atan2(y, x)`	Returns the arctangent of the quotient of its arguments.
`atanh(x)`	Returns the hyperbolic arctangent of `x`.
`cbrt(x)`	Returns the cube root of `x`.
`ceil(x)`	Returns the smallest integer greater than or equal to `x`.
`cos(x)`	Returns the cosine of `x`.
`exp(x)`	Returns ex, where x is the argument, and e is Euler's number (`2.718`…, the base of the natural logarithm).
`expm1(x)`	Returns subtracting `1` from `exp(x)`.
`floor(x)`	Returns the largest integer less than or equal to `x`.
`fround(x)`	Returns the nearest single precision float representation of `x`.
`hypot(value1, ...values)`	Returns the square root of the sum of squares of its arguments.
`imul(x, y)`	Returns the result of the 32-bit integer multiplication of `x` and `y`.
`log(x)`	Returns the natural logarithm (㏒e; also, ㏑) of `x`.
`log10(x)`	Returns the base-10 logarithm of `x`.
`log1p(x)`	Returns the natural logarithm (㏒e; also ㏑) of `1 + x` for the number `x`.
`max(value1, ...values)`	Returns the largest of zero or more numbers.
`min(value1, ...values)`	Returns the smallest of zero or more numbers.
`pow(x, y)`	Returns base `x` to the exponent power `y`.
`round(x)`	Returns the value of the number `x` rounded to the nearest integer.
`sign(x)`	Returns the sign of the `x`, indicating whether `x` is positive, negative, or zero.
`sin(x)`	Returns the sine of `x`.
`sinh(x)`	Returns the hyperbolic sine of `x`.
`sqrt(x)`	Returns the positive square root of `x`.
`tan(x)`	Returns the tangent of `x`.
`trunc(x)`	Returns the integer portion of `x`, removing any fractional digits.

### Operators All operators are computed as in JavaScript, except that [no coercion to number or boolean is supported](#no-coercion-to-number-or-boolean). When performing bitwise operations, the operands are first converted to 32-bit integer values, then the result of the operation is converted back to a 64-bit floating point value. #### Equality and Strict Equality Unlike JavaScript, the non-strict `==` and `!=` operators evaluate to `null` if either operand is `null`. That is, whereas in JavaScript, `null == null` is `true`, in Clarity formulae, `null == null` is `null`. If you want to test for `null`, use the `===` and `!==` operators; `null === null` is true.

Precedence	Associativity	Individual Operators
grouping	n/a	`(x)`
prefix operators	n/a	Logical NOT `!x` Bitwise NOT `~x` Negation `-x`
exponentiation	right-to-left	`x ** y`
multiplicative	left-to-right	Multiplication `x * y` Division `x / y` Remainder `x % y`
additive	left-to-right	Addition `x + y` Subtraction `x - y`
bitwise shift	left-to-right	Left shift `x << y` Right shift `x >> y` Unsigned right shift `x >>> y`
comparison	left-to-right	Less than `x < y` Less than or equal `x <= y` Greater than `x > y` Greater than or equal `x >= y`
equality	left-to-right	Equality `x == y` Inequality `x != y` Strict Equality `x === y` Strict Inequality `x !== y`
bitwise AND	left-to-right	`x & y`
bitwise XOR	left-to-right	`x ^ y`
bitwise OR	left-to-right	`x \| y`
logical AND	left-to-right	`x && y`
logical OR, nullish coalescing	left-to-right	Logical OR `x \|\| y` Nullish coalescing operator `x ?? y`
conditional (ternary) operator	right-to-left	`x ? y : z`

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.jcore.io/clarity/formula-language.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.