Functions
From webCoRE Wiki - Web-enabled Community's own Rule Engine
Contents
- 1 String functions
- 1.1 concat
- 1.2 contains
- 1.3 endsWith
- 1.4 format
- 1.5 indexOf
- 1.6 json
- 1.7 lastIndexOf
- 1.8 left
- 1.9 lower
- 1.10 mid
- 1.11 random
- 1.12 replace
- 1.13 right
- 1.14 startsWith
- 1.15 string
- 1.16 substr
- 1.17 substring
- 1.18 title
- 1.19 upper
- 1.20 text
- 1.21 trim
- 1.22 trimLeft
- 1.23 ltrim
- 1.24 trimRight
- 1.25 rtrim
- 1.26 urlEncode
- 1.27 encodeURIComponent
- 2 Numeric functions
- 3 Boolean functions
- 4 Date and time functions
- 5 Weather related functions
- 6 Dynamic
- 7 Integers
- 8 Time
Functions are extensions to expressions that allow data processing and conversion. Here is a list of all defined functions
String functions
concat
- Syntax
string concat(dynamic value1, dynamic value2[, .., dynamic valueN])
- Returns
- Returns a string that is the concatenation of all the supplied values. This function accepts two or more input values.
contains
- Syntax
boolean contains(string haystack, string needle)
- Returns
- Returns true if the
needle
is found anywhere in thehaystack
- Returns true if the
endsWith
- Syntax
boolean endsWith(string haystack, string needle)
- Returns
- Returns true if
haystack
ends with theneedle
- Returns true if
format
- Syntax
string format(string formatString[, dynamic value1[, .., dynamic valueN]])
- Returns
- Returns a string that is built based on the
formatString
with arguments replaced by their corresponding values. Follows the java syntax forprintf()
. See a quick reference here, or a more detailed reference Reference here. - Each % in the format string represents an argument and corresponds to a value (in order of appearance) in the value list. Each argument can have formatting settings, according to the reference provided.
- Returns a string that is built based on the
- Example
format('The temperature outside is %.2f degrees Fahrenheit', [Temp sensor:temperature])
outputsThe temperature outside is 71.26 degrees Fahrenheit
- The
%.2f
translates to "format asf
loat and use.2
decimal places.
indexOf
- Syntax
integer indexOf(string haystack, string needle)
- Returns
- Returns the character index of the first occurrence of
needle
insidehaystack
- Returns the character index of the first occurrence of
- Examples
indexOf("hello world", 'l')
outputs2
json
- Syntax
string json(dynamic value[, "boolean" pretty])
- Returns
- Returns the JSON representation of the provided value. If the pretty parameter is true, indentation is added to improve human readability
- Examples
json(true)
outputs"true"
json(123)
outputs"123"
json('Nicole "Nikki" Sawyer')
outputs""Nicole \"Nikki\" Sawyer""
json(myStringList, true)
outputs with pretty formatting"{
"name": "Jaime",
"present": true
}"
json(myDeviceList)
outputs"[":97e051eb6fea489fa7cf1aaa4cb7c171:",":73d68350942e4555a8c47c36f558681e:"]"
since device variables are internally a list of device IDs"\{"device": {json($currentEventDevice)}, "rooms": \[ {json(activeRoom)}, "Basement" \] \}"
building JSON by hand in a webCoRE expression requires any{}[]
characters in the JSON to be escaped with a backslash and all dynamic values must use thejson()
function to safely represent the value
lastIndexOf
- Syntax
integer lastIndexOf(string haystack, string needle)
- Returns
- Returns the character index of the last occurrence of
needle
insidehaystack
- Returns the character index of the last occurrence of
- Examples
lastIndexOf("hello world", 'l')
outputs9
left
- Syntax
string left(string value, integer length)
- Returns
- Returns the first
length
characters invalue
- Returns the first
- Examples
left("hello world", 2)
outputshe
lower
- Syntax
string lower(string value)
- Returns
- Returns the
value
but with all lower case letters.
- Returns the
- Examples
lower("Hello World")
outputshello world
mid
- Syntax
string mid(string value, integer start[, integer count = remaining])
- Arguments
start
- provides the 0-based index of the first character to copy. Ifstart
is negative, the counting starts from the end ofvalue
.count
- provides the number of characters to copy fromvalue
. If not provided, all of the remaining characters fromvalue
are returned, starting with character numberstart
. Ifcount
is negative, prior characters are returned.
- Returns
- Returns a substring of
value
,count
characters long, starting at character numberstart
. Note that the first character in any string has index 0.
- Returns a substring of
- Examples
mid("Hello World", 2, 3)
outputsllo
mid("Hello World", 2)
outputsllo World
mid("Hello World", -5, 2)
outputsWo
mid("Hello World", -1, -3)
outputsorl
random
- Syntax
dynamic random([integer range | dynamic value1, dynamic value2[, .., dynamic valueN]])
- Arguments
range
- an integer number representing a rangevalue1
..valueN
- any kind of arguments, one will be randomly returned
- Returns
- Returns a random decimal number between
0
and1
if no arguments are provided, or a number between0
andrange
(inclusive) if a single argument is provided, or a randomly selected argument if two or more arguments are provided.
- Returns a random decimal number between
- Examples
random()
outputs0.483
(random decimal)random(20)
outputs6
(random integer)random("Hello World", "Good morning", "Hello", "Hi")
outputsHello
(randomly selected value)
- Tips
- To output a random integer between 5 and 20 use
(5 + random(15))
- To output a random integer between -5 and 20 use
(-5 + random(25))
- To output a random integer between 5 and 20 use
replace
- Syntax
string replace(string haystack, string needle1, string replacement1[, .., string needleN, string replacementN])
- Returns
- Replaces all the occurrences of
needle
insidehaystack
with its respectivereplacement
. Multiple pairs ofneedle
/replacement
can be provided in one function call.
- Replaces all the occurrences of
- Regular expressions
- Needles support regular expressions when their value starts and ends with a
/
. For example,'/(\s)/'
will match all spaces.
- Needles support regular expressions when their value starts and ends with a
- Examples
replace("Hello World", 'World', 'Earth')
outputsHello Earth
replace("Hello World", 'World', 'Earth', 'Hello', 'Hi')
outputsHi Earth
replace("Hello World", 'World', 'Earth', 'Earth', 'Planet')
outputsHello Planet
right
- Syntax
string right(string value, integer length)
- Returns
- Returns the last
length
characters invalue
- Returns the last
- Examples
right("hello world", 4)
outputsorld
startsWith
- Syntax
boolean startsWith(string haystack, string needle)
- Returns
- Returns true if
haystack
starts with theneedle
- Returns true if
string
- Syntax
string string(dynamic value)
- Returns
- Returns
value
as a string.
- Returns
substr
- Alias of
mid()
substring
- Alias of
mid()
title
- Syntax
string title(string value)
- Returns
- Returns the
value
but in its title case format (each word starts with a capitalized letter).
- Returns the
- Examples
lower("Hello there world")
outputsHello There World
upper
- Syntax
string upper(string value)
- Returns
- Returns the
value
but with all upper case letters.
- Returns the
- Examples
upper("Hello World")
outputsHELLO WORLD
text
- Alias of
string()
trim
- Syntax
"string" trim("string" value)
- Returns
- Returns the
value
with leading and trailing spaces removed
- Returns the
- Examples
trim(" Hello World ")
outputsHello World
trimLeft
- Syntax
"string" trimLeft("string" value)
- Returns
- Returns the
value
with leading spaces removed
- Returns the
- Examples
trimLeft(" Hello World ")
outputs"Hello World "
ltrim
- Alias of
trimLeft()
trimRight
- Syntax
"string" trimRight("string" value)
- Returns
- Returns the
value
with trailing spaces removed
- Returns the
- Examples
trimRight(" Hello World ")
outputs" Hello World"
rtrim
- Alias of
trimRight()
urlEncode
- Syntax
string urlEncode(dynamic value)
- Returns
- Returns a string with all characters other than
a-z A-Z 0-9 . - * _ +
converted to percent encoding for use in a URL
- Returns a string with all characters other than
- Examples
urlEncode("John's iPhone 8+")
outputs"John%27s%20iPhone%208+"
"http://webcore.co/sample?device={urlEncode($currentEventDevice)}&attribute={urlEncode($currentEventAttribute)}&value={urlEncode($currentEventValue)}"
ensures that the generated URL is valid even if the event information includes spaces, & signs, or other problematic characters.
encodeURIComponent
- Alias of
urlEncode()
Numeric functions
avg
- Syntax
decimal avg(decimal value1, decimal value2[, .., decimal valueN])
- Returns
- Returns the mean average of all the values provided.
abs
- Syntax
decimal abs(decimal value)
- Returns
- Returns the absolute value of the argument (e.g., remove negative sign for negative values).
ceil
- Syntax
integer ceil(decimal value)
- Returns
- Returns the immediately higher integer, equivalent to rounding the decimal away from zero.
- Examples
ceil(5.6)
outputs6
ceil(-5.6)
outputs-6
ceiling
- Alias of
ceil
decimal
- Syntax
decimal decimal(dynamic value)
- Returns
- Converts
value
into a decimal. Returns0
ifvalue
is not numeric.
- Converts
float
- Alias of
decimal
floor
- Syntax
integer ceil(decimal value)
- Returns
- Returns the integer part of a decimal, equivalent to rounding the decimal towards zero.
- Examples
floor(5.6)
outputs5
floor(-5.6)
outputs-5
max
- Syntax
dynamic max(dynamic value1, dynamic value2[, .., dynamic valueN])
- Returns
- Returns the maximum of all the values provided. Note: this function works with both numbers and strings.
median
- Syntax
dynamic median(dynamic value1, dynamic value2[, .., dynamic valueN])
- Returns
- Returns the median average of all the values provided. Note: this function works with both numbers and strings.
min
- Syntax
dynamic min(dynamic value1, dynamic value2[, .., dynamic valueN])
- Returns
- Returns the minimum of all the values provided. Note: this function works with both numbers and strings.
number
- Alias of
decimal
power
- Syntax
decimal power(decimal value, decimal exponent)
- Returns
- Returns the
value
at the power ofexponent
- Returns the
round
- Syntax
decimal round(decimal value[, integer precision = 0])
- Arguments
precision
- the number of decimal places to be retained. If not provided, defaults to0
- Returns
- Returns the rounded
value
withprecision
decimal places.
- Returns the rounded
sqr
- Syntax
decimal sqr(decimal value)
- Returns
- Returns the squared
value
, equivalent tovalue
multiplied by itself.
- Returns the squared
sqrt
- Syntax
decimal sqrt(decimal value)
- Returns
- Returns the square root of
value
.
- Returns the square root of
stdev
- Syntax
decimal stdev(decimal value1, decimal value2[, .., decimal valueN])
- Returns
- Returns the standard deviation of all the values provided.
sum
- Syntax
decimal sum(decimal value1, decimal value2[, .., decimal valueN])
- Returns
- Returns the sum of sum of all the values provided.
variance
- Syntax
decimal variance(decimal value1, decimal value2[, .., decimal valueN])
- Returns
- Returns the variance of all the values provided.
Boolean functions
bool
- Syntax
bool(dynamic value)
- Returns
- Returns the truth value of the input. Accepts anything as input and will return true if
value
is either a non-zero number, a non-empty string (with some exceptions, see below), a non-empty device list, a non-empty date/time/datetime
- Returns the truth value of the input. Accepts anything as input and will return true if
boolean
- This is an alias of bool
eq
- Syntax
eq(dynamic value1, dynamic value2)
- Returns
- Returns true if
value1
is equivalent tovalue2
- Returns true if
ge
- Syntax
ge(dynamic value1, dynamic value2)
- Returns
- Returns true if
value1
is greater than or equal tovalue2
- Returns true if
gt
- Syntax
gt(dynamic value1, dynamic value2)
- Returns
- Returns true if
value1
is greater thanvalue2
- Returns true if
isBetween
- Syntax
isBetween(dynamic value, dynamic startValue, dynamic endValue)
- Returns
- Returns true if
value
is greater then or equal tostartValue
and less than or equal toendValue
- Returns true if
isEmpty
- Syntax
isEmpty(dynamic value)
- Returns
- Returns true if
value
is not set, an empty string, or zero
- Returns true if
le
- Syntax
le(dynamic value1, dynamic value2)
- Returns
- Returns true if
value1
is less than or equal tovalue2
- Returns true if
lt
- Syntax
lt(dynamic value1, dynamic value2)
- Returns
- Returns true if
value1
is less thanvalue2
- Returns true if
not
- Syntax
not(dynamic value)
- Returns
- Returns the negated truth state of
value
. This is the logical negation ofbool(dynamic value)
.
- Returns the negated truth state of
Date and time functions
addDays
- Syntax
addDays(datetime value, integer days)
- Returns
- Returns a datetime that is
days
days after thevalue
. For negative values ofdays
, it returns a datetime that isdays
days beforevalue
.
- Returns a datetime that is
addHours
- Syntax
addHours(datetime value, integer hours)
- Returns
- Returns a datetime that is
hours
hours after thevalue
. For negative values ofhours
, it returns a datetime that ishours
hours beforevalue
.
- Returns a datetime that is
addMinutes
- Syntax
addMinutes(datetime value, integer minutes)
- Returns
- Returns a datetime that is
minutes
minutes after thevalue
. For negative values ofminutes
, it returns a datetime that isminutes
minutes beforevalue
.
- Returns a datetime that is
addSeconds
- Syntax
addSeconds(datetime value, integer seconds)
- Returns
- Returns a datetime that is
seconds
seconds after thevalue
. For negative values ofseconds
, it returns a datetime that isseconds
seconds beforevalue
.
- Returns a datetime that is
addWeeks
- Syntax
addWeeks(datetime value, integer weeks)
- Returns
- Returns a datetime that is
weeks
weeks after thevalue
. For negative values ofweeks
, it returns a datetime that isweeks
weeks beforevalue
.
- Returns a datetime that is
date
- Syntax
date(datetime value)
- Returns
- Returns the date portion of
value
by stripping off time information.
- Returns the date portion of
datetime
- Syntax
datetime datetime(dynamic value)
- Returns
- Tries to convert any value into a datetime. Accepts strings in common date/time formats.
formatDuration
- Syntax
string formatDuration(datetime value[, boolean friendly = false[, string granularity = 's'[, boolean showAdverbs = false]]])
- Arguments
friendly
-false
makes the output compact, in the form of0d 00:00:00.000
, whiletrue
makes the output more human friendly, in the form of0 days, 0 hours, 0 minutes, and 0 seconds
. Defaults tofalse
.granularity
- represents the smallest time unit to be output. One ofd
for days,h
for hours,m
for minutes,s
for seconds, orms
for milliseconds. Any time unit below the selected granularity will not be output. Defaults tos
showAdverbs
- only affects the friendly output, whentrue
the wordsin
(for future durations - positive input) orago
(for past durations - negative input) are prepended or appended respectively to the output
- Returns
- Returns a string that represents the duration in a human readable format
- Examples
formatDuration(12029)
will output00:00:12
formatDuration(68493, true)
will output1 minute and 8 seconds
formatDuration(68493, false, 'ms')
will output00:01:08.493
formatDuration(68493, true, 'm', true)
will outputin 1 minute
formatDateTime
- Syntax
formatDateTime(datetime value, string)
- Known Strings (caSe seNsiTivE)
- G, y, M, d, h, H, m, s, S, E, D, F, w, W, a, k, K, z
- Examples
Meaning | String | Sample Code | Sample Output | Format | Range | Notes |
---|---|---|---|---|---|---|
Era | G
|
formatDateTime($now, "G")
|
AD
|
String | ||
Year | y
|
formatDateTime($now, "y")
|
1992
|
Integer | 1970? - ?? | Needs confirmation |
Year | yy
|
formatDateTime($now, "yy")
|
92
|
Integer | 1970? - ?? | Needs confirmation |
Month | M
|
formatDateTime($now, "M")
|
3
|
Integer | 1 - 12 | |
Month | MM
|
formatDateTime($now, "MM")
|
03
|
Integer | 01 - 12 | |
Month | MMM
|
formatDateTime($now, "MMM")
|
Mar
|
String | 3 Letter abbreviation | |
Month | MMMM
|
formatDateTime($now, "MMMM")
|
March
|
String | Full word | |
Day of Month | d
|
formatDateTime($now, "d")
|
29
|
Integer | 1 - 31 | |
Day of Month | dd
|
formatDateTime($now, "dd")
|
??
|
Integer | 01 - 31 | |
Hour | h
|
formatDateTime($now, "h")
|
7
|
Integer | 1 - 12 | |
Hour | hh
|
formatDateTime($now, "hh")
|
07
|
Integer | 01 - 12 | |
Hour (Military) | H
|
formatDateTime($now, "H")
|
22
|
Integer | 0 - 23 | |
Hour (Military) | HH
|
formatDateTime($now, "HH")
|
07
|
Integer | 00 - 23 | |
Minute | m
|
formatDateTime($now, "m")
|
59
|
Integer | 0 - 59 | |
Minute | mm
|
formatDateTime($now, "mm")
|
08?
|
Integer | 00? - 59 | Needs confirmation |
Second | s
|
formatDateTime($now, "s")
|
8
|
Integer | 0 - 59 | |
Second | ss
|
formatDateTime($now, "ss")
|
08
|
Integer | 00? - 59 | Needs confirmation |
Millisecond | S
|
formatDateTime($now, "S")
|
42
|
Integer | 0 - 999 | |
Millisecond | SSS
|
formatDateTime($now, "SSS")
|
042
|
Integer | 000? - 999 | Needs confirmation |
Day of Week | E
|
formatDateTime($now, "E")
|
Sat
|
String | ||
Day of Week | EEEE
|
formatDateTime($now, "EEEE")
|
Saturday
|
String | ||
Day of Year | D
|
formatDateTime($now, "D")
|
362
|
Integer | ||
Day of Week in Month | F
|
formatDateTime($now, "F")
|
3
|
Integer | IE: 3rd Mon in May | |
Week in Year | w
|
formatDateTime($now, "w")
|
51
|
Integer | 1 - 54? | Needs confirmation |
Week in Month | W
|
formatDateTime($now, "W")
|
2
|
Integer | 1 - 6? | Needs confirmation |
AM/PM | a
|
formatDateTime($now, "a")
|
PM
|
String | ||
Hour (alt version) | K
|
formatDateTime($now, "K")
|
7
|
Integer | 0 - 11 | |
Hour (alt Military) | k
|
formatDateTime($now, "k")
|
24
|
Integer | 1 - 24 | |
Time Zone | z
|
formatDateTime($now, "z")
|
EDT
|
String | ||
Time Zone | zzzz
|
formatDateTime($now, "zzzz")
|
Eastern Daylight Time
|
String | ||
formatDateTime reference doc is here - https://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html
Here are a few combined examples:
Sample Code | Sample Output | Notes |
---|---|---|
formatDateTime("August 9, 1995", "EEEE")
|
Wednesday
|
Note that "datetime value" does not have to be $now
|
formatDateTime($now, "h:mm a")
|
8:01 PM
|
|
formatDateTime($now, "H:m")
|
23:55
|
|
formatDateTime($now, "EEEE, MMM d, yy")
|
Saturday, Mar 21, '20
|
|
.
time
- Syntax
time time(datetime value)
- Returns
- Returns the time portion of
value
by stripping off date information.
- Returns the time portion of
celsius
- Syntax
decimal celsius(decimal value)
- Returns
- Converts a temperature value from Fahrenheit to Celsius.
dewPoint
- Syntax
decimal dewPoint(decimal temperature, decimal relativeHumidity[, string scale = 'F'])
- Parameters
scale
- optional, one of"C"
or"F"
, corresponding to the temperature range used fortemperature
. The result will be provided in the same scale. If no scale is provided, the Fahrenheit scale will be used.
- Returns
- Returns the due temperature for a given temperature and relative humidity
fahrenheit
- Syntax
decimal fahrenheit(decimal value)
- Returns
- Converts a temperature value from Celsius to Fahrenheit.
convertTemperatureIfNeeded
- Syntax
decimal convertTemperatureIfNeeded(decimal value, string scaleOfValue)
- Parameters
value
- the numeric temperature value in units specified by thescaleOfValue
parameterscaleOfValue
- one of"C"
or"F"
, corresponding to the known unit of the value parameter
- Returns
- Converts the temperature value from Celsius to Fahrenheit or vice versa if the scale does not match the location's temperature scale (see
$temperatureScale
). If the provided unit matches the location's temperature scale the value is returned as-is.
- Converts the temperature value from Celsius to Fahrenheit or vice versa if the scale does not match the location's temperature scale (see
Dynamic
- if(condition, valueIfTrue, valueIfFalse)
- evaluates a boolean and returns value1 if true, or value2 otherwise
- least(values)
- returns the value that is least found a series of numeric values
- most(values)
- returns the value that is most found a series of numeric values
- previousValue([device;attribute])
- returns the previous value of the attribute
Integers
- age([device﹕attribute])
- returns the number of milliseconds an attribute had the current value
- count(values)
- calculates the number of true/non-zero/non-empty items in a series of numeric values
- int()
- //todo
- integer(decimal or string)
- converts a decimal value to it's integer value
- newer([device﹕attribute],[...], [device﹕attribute], threshold)
- returns the number of devices whose attribute had the current value for less than the specified number of milliseconds
- older([device﹕attribute],[...], [device﹕attribute], threshold)
- returns the number of devices whose attribute had the current value for more than the specified number of milliseconds
- previousAge([device﹕attribute])
- returns the number of milliseconds that have elapsed since an attribute changed to the previous value. If there is no previous value recorded returns
604800000
, which corresponds to 7 days. - Use
previousAge([device﹕attribute]) - age([device﹕attribute])
to determine the length of time that the device attribute had the previous value.
Time
- time(value)
- returns the value as a time type
- addSeconds(dateTime, seconds)
- adds seconds to time, returns the value as a time type
- addMinutes(dateTime, minutes)
- adds minutes to time, returns the value as a time type
- addHours(dateTime, hours)
- adds hours to time, returns the value as a time type
- addDays(dateTime, days)
- adds days to time, returns the value as a time type
- addWeeks(dateTime, weeks)
- adds weeks to time, returns the value as a time type