Custom Expressions
Custom Expressions
Expressions allow complex Tag-based logic to set a property. Expressions can be broken down into two phases: the math phase and the formatting phase. In the math phase, users can use tags to compute mathematical operations to get a single value. The formatting phase is intended for display purposes. Formatting options include specifying the number of decimals for a number date, time string format, etc.
Math
The math phase will always return a single numeric value. This phase is similar to a calculator where the only allowed inputs are tag values, constants, and operations on those values.
All constants are treated as doubles, including boolean values (1.0/0.0)
Format
The format phase will always return a single string value. This phase will convert the math value from the math phase into a string value.
Built-in Operators
Math Operators
Here are the Math operations in Tag Expressions.
Tag ( [] )
Constants ( pi , epsilon , inf )
Basic math operators ( + , - , * , / , % )
Functions ( min , max , avg , sum , abs , ceil, floor, round, exp, log, log10, log , pow, root, sqrt, clamp )
Trigonometry ( sin , cos , tan , acos , asin , atan , atan2 , cosh , cot , csc , sec , sinh , tanh )
Equalities ( == , != , < , <= , > , >= )
Control ( if, then, else )
Format Operators
| Item | Description |
|---|---|
| round(decimalPlaces) | Returns a number rounded to the nearest decimalPlaces decimal places. |
| base(base) | Returns a string equivalent of the input number according to the specified base. |
| numericFormat(format) | Returns a string formatted by the pattern described in the format. Invalid formats will return an empty string. |
| # | Denotes a basic decimal character. If used past a decimal point, it will specify the minimum number of decimal values to show. Not compatible with hexadecimal formats. |
| H | Denotes a hexadecimal character. This is not compatible with decimal formats. |
| 0 | Denotes a zero-fill character. The index of this character will be used as a minimum number of digits to display before a decimal point. There should be at most one. |
| . | Denotes a decimal point. There should only be one at most. Not compatible with hexadecimal format. |
| , | Denotes a group separator. The index of this character will be used as the number of digits to group up. There should be at most one, and it cannot be used past a decimal point. |
| datetimeFormat(format) | Returns the UNIX timestamp as a string in the form described in format. |
| h | An hour without a leading zero. It can be either 0 to 23 or 1 to 12. |
| hh | An hour with a leading zero. It can be either 00 to 23 or 01 to 12. |
| H | An hour without a leading zero. It can be either 0 to 23, even with AM/PM display. |
| HH | An hour with a leading zero. It can be either 0 to 23, even with AM/PM display. |
| m | A minute without a leading zero (0 to 59) |
| mm | Minute with a leading zero (00 to 59) |
| s | The whole second, without any leading zero (0 to 59) |
| ss | The entire second, with a leading zero where applicable (00 to 59) |
| z | The fractional part of the second, to go after a decimal point, without trailing zeroes (0 to 999). |
| zzz | The fractional part of the second, to millisecond precision, including trailing zeroes where applicable (000 to 999). |
| AP or A | Use AM/PM display. |
| ap or a | Use am/pm display. |
| t | The timezone. |
| d | The day as a number without a leading zero. |
| dd | The day with a leading zero. |
| ddd | The abbreviated localized day name. It uses the system to localize the name. |
| dddd | The long localized day name. It uses the system to localize the name. |
| M | The month as a number without a leading zero. |
| MM | The month as a number with a leading zero. |
| MMM | The abbreviated localized month name. It uses the system to localize the name. |
| MMMM | The long localized month name. It uses the system to localize the name. |
| yy | The year as a two-digit number. |
| yyyy | The year as a four-digit number. |
| map(format) | Returns the value that falls in the range provided in the format based on the input value. The following is the expected syntax of the format: - A list of range values separated by a comma. - A range value is defined as: - Starts with { - A pair of a range and a value. - A range is defined as: - Starts with [ or ( - A [ implies inclusive. - A ( implies exclusive. - A pair of numeric values separated by a comma - An empty numeric valuye implies either positive infinity or negative infinity depending on which side of the pair it is on - "inf," "+inf" resolves to infinity" - "-inf" resolves to negative infinity - Ends with ] or ) - A ] implies inclusive - A ) implies exclusive - Ends with } - A default value may be specified with a | character. |
| hasPermission(permission) | Returns whether or not the currently signed-in user has permission. This is the expression equivalent to the script with the same name. System.hasExpression. |
Examples
| Item | Description |
|---|---|
| Get Tag | {[TAG1]} |
| Add two tags together | {[TAG1] + [TAG2]} |
| Add two tags together, then return value as binary | {[TAG1] + [TAG2]|base(2)} |
| Conditional Value | {if ([TAG1] % 2) [TAG2]; else [TAG3];} |
| Convert C to F | {([CelsiusTag] * 9 / 5) + 32} |
| Embed values into a string | Temp: {[TAG1]} | Pressure: {[TAG2]} |
| Map values from a range | {[TAG1]|map("{,0),-1},{[0,10),0},{[10,20),1},{[20,30),2},|nan")} |