A few new functions have worked their way into Reactor's expression language over the last couple of months, and while they are documented in the change logs and documentation, it seems some of you are not aware of them, so I'm going to pick one out and highlight it, maybe do others later...
A lot of you build strings in expressions by simple concatenation, and there's nothing wrong with that, but there's a new function in the expression language that can help you clean things up, in particular when handling numeric values.
I've noticed many of you will round your results either on the calculation, or in some cases, in a separate variable. For example, say we have a pair of expressions that retrieves the indoor and outdoor temperature from a sensor and the weather service:
indoor = getEntity( 'hubitat>144' ).attributes.temperature_sensor.value' )
outdoor = getEntity( 'weather>home' ).attributes.wx.temperature
The weather service, since it converts from degrees K in its reporting to degrees C, may have an irrational or repeating value (e.g. 8.233333333...). As a result, when you compute the difference, it, too, may have an irrational or repeating result, so you decide to round it to one decimal:
tempDiff = round( outdoor - indoor, 1 )
Then, perhaps you have a rule that if the differential is greater than 10 degrees, you send a notification, and the notification uses all three variables in the message string:
${{ 'The outdoor temperature is ' + outdoor + 'C and the indoor temperature is ' + indoor + 'C; the difference is ' + tempDiff + 'C' }}
This is fine, except that the outdoor temperature isn't rounded, so you decide to fix that. There are at least three ways: add a round() to the outdoor variable expression, or create a third variable like outdoorRounded = round( outdoor, 1 ), or, use the round() function into the substitution expression
${{ 'The outdoor temperature is ' + round( outdoor, 1 ) + 'C and the indoor temperature is ' + indoor + 'C; the difference is ' + tempDiff + 'C' }}
It's all getting very messy... Let's use format() instead of string concatenation, and not worry about rounding the difference, so we keep the maximum precision possible for any calcs or tests that use it. We go back to:
indoor = getEntity( 'hubitat>144' ).attributes.temperature_sensor.value' )
outdoor = getEntity( 'weather>home' ).attributes.wx.temperature
tempDiff = outdoor - indoor
Now our string substitution:
${{ format( "The outdoor temperature is {0:.1f}C and the indoor temperature is {1:.1f}C; the difference is {2:.1f}C", outdoor, indoor, tempDiff ) }}
Here, format() is building the message string. Each {} (curly-brace) pair denotes the substitution of a parameter to follow. The number first inside the opening curly brace is the parameter number, starting from 0 as the first parameter. So parameter 0 in this example refers to the variable outdoor, and 1 is indoor, and 2 is tempDiff. Using the numbers, parameters can be inserted in any order.
Each of these substitutions in the example includes an optional format specification. If no format specification is given (e.g. {0}), then the parameter is converted to a string with no special formatting, but since we can get numbers like 8.233333... it's desirable to use some formatting to make it pretty. The format is separated from the parameter number by the : (colon) in the substitution. The format we're using for all three parameters is .1f, which is <width>.<precision>f. Any number before the dot is a fixed field width, but since we want no extra spaces, we just don't specify a width (it's blank for our example), and the value will take as much space as it needs. The f at the end tells format() that the value is going to be formatted as a floating point number, and the .1 before the f tells the formatter to display a single decimal digit. So our 8.23333333 value would be displayed as 8.2, without using extra functions or variables, or dropping precision in a calculation. For clarity, 10.875 would be displayed/inserted as 10.9 in this example, because the formatter will round the displayed result to the specified number of decimal digits.
Tip: for simple string insertions that require no special formatting, format() will let you skip the parameter numbers if the parameters are in the same order as the substitutions, and the default format is (generic) string (s), so format( "{} x {} = {}", "alpha", "beta", "gamma" ) produces the string alpha x beta = gamma.
Docs for format are in the Reactor documentation under the heading Special Reactor Functions.
