Revision as of 03:34, 15 April 2017 (view source) C1arkbar (talk | contribs) ← Older edit		Latest revision as of 04:14, 23 March 2020 (view source) WCmore (talk | contribs) m (→‎formatDateTime)
(90 intermediate revisions by 8 users not shown)
Line 1:		Line 1:
−	;Boolean	+	<div style="float: left; clear: both; margin-right: 1em; margin-bottom: 1em;">__TOC__</div>
−	:bool()	+	Functions are extensions to expressions that allow data processing and conversion. Here is a list of all defined functions
−	:boolean()
−	:contains('The quick brown fox jumped over the lazy dog', 'brown') - tests parameter 1 for parameter 2 as any word (case sensitive)
−	:endsWith('The quick brown fox jumped over the lazy dog', 'brown') - tests parameter 1 for parameter 2 as the last word (case sensitive)
−	:eq('123', '321') - checks if both parameters are equal.  This will return false
−	:ge(1000, 900) - Checks if parameter 1 is greater than or equal to parameter 2.  This will return true.
−	:gt(1000, 900) - Checks if parameter 1 is greater than parameter 2.  This will return true.
−	:isEmpty()
−	:le(1000, 900) - Checks if parameter 1 is less than or equal to parameter 2. This will return false.
−	:lt(1000, 900) - Checks if parameter 1 is less than parameter 2. This will return false.
−	:not()
−	:startsWith('The quick brown fox jumped over the lazy dog', 'brown') - tests parameter 1 for parameter 2 as the first word (case sensitive)
−	;Date
−	:date()
−	;datetime	+	=[[Variable_data_types#String|String]] functions=
−	:addDays()
−	:addHours()
−	:addMinutes()
−	:addSeconds()
−	:addWeeks()
−	;Decimal	+	==concat==
−	:avg([Device 1:temperature], [Device2:temperature], [Device 3:temperature]) - Gives you the average temperature of the three devices	+	:Syntax
−	:ceil()	+	::<code>''string'' concat(''dynamic'' value1, ''dynamic'' value2[, .., ''dynamic'' valueN])</code>
−	:ceiling()	+	:Returns
−	:celsius([Sensor:temperature]) - Gives the temperature reading in celsius	+	::Returns a string that is the concatenation of all the supplied values. This function accepts two or more input values.
−	:decimal()
−	:dewPoint([Sensor:temperature], [Sensor:humidity]) - Gives you the dewpoint temperature for that sensor
−	:fahrenheit([Sensor:temperature]) - Gives the temperature reading in fahrenheit
−	:float()
−	:floor()
−	:max([Front Door :temperature], [Back Door :temperature], [test sensor :temperature]) - Returns the max value of selected devices
−	:median([Front Door :temperature], [Back Door :temperature], [test sensor :temperature]) - Returns the median value of selected devices
−	:min([Front Door :temperature], [Back Door :temperature], [test sensor :temperature]) - Returns the min value of selected devices
−	:number()
−	:power(10,3) - Evaluates parameter 1 to the parameter 2 power (e.g. 10*10*10 = 1000)
−	:round(75.6548, 1) -  Rounds a decimal based on value of parameter 2.  This will return 75.7
−	:sqr(100) - Gives the squared value of the parameter. This returns 10000
−	:sqrt(100) - Gives the square root of the parameter. This returns 10.0
−	:stdev()
−	:sum(1,5,6) - Adds all the values
−	:variance()
−	;Dynamic	+	==contains==
−	:if()	+	:Syntax
−	:least()	+	::<code>''boolean'' contains(''string'' haystack, ''string'' needle)</code>
−	:most()	+	:Returns
−	:previousValue()	+	::Returns true if the <code>needle</code> is found anywhere in the <code>haystack</code>
−	;Integers	+	==endsWith==
−	:age([Device:switch) - Gives you the time in MS the device has been on	+	:Syntax
−	:count([Device 1:contact], [Device 2:contact], [Device 3:contact], [Device 4:contact]) - Returns the number of open doors	+	::<code>''boolean'' endsWith(''string'' haystack, ''string'' needle)</code>
−	:int()	+	:Returns
−	:integer()	+	::Returns true if <code>haystack</code> ends with the <code>needle</code>
−	:newer()
−	:older()
−	:previousAge()
−	;String	+	==format==
−	:concat('abc', 'def') - Returns the two strings as 'abcdef'	+	[[File:Format.pdf|page=1|thumb|256px|A very nice article written by Professor Don Colton, at the Brigham Young University of Hawaii]]
−	:format("%.2f", celsius([Sensor:temperature])) - Returns the Celsius temperature formatted with two decimals	+	:Syntax
−	:left('abcdef', 2) - Returns the first two characters in the string value or variable (ex: 'ab')	+	::<code>''string'' format(''string'' formatString[, ''dynamic'' value1[, .., ''dynamic'' valueN]])</code>
−	:lower("HELLO, WORLD") - Returns as "hello, world"	+	:Returns
−	:mid('abcdef', 2, 3) - Skips the first 2 characters and returns the next 3	+	::Returns a string that is built based on the <code>formatString</code> with arguments replaced by their corresponding values. Follows the java syntax for <code>printf()</code>. See a quick reference [https://www.cs.colostate.edu/~cs160/.Summer16/resources/Java_printf_method_quick_reference.pdf here], or a more detailed reference [https://sharkysoft.com/archive/printf/docs/javadocs/lava/clib/stdio/doc-files/specification.htm Reference here].
−	:replace()	+	::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.
−	:right('abcdef', 2) - Returns the last two characters in the string value or variable (ex: 'ef')	+	:Example
−	:sprintf()	+	::<code>format('The temperature outside is %.2f degrees Fahrenheit', [Temp sensor:temperature])</code> outputs <code>The temperature outside is 71.26 degrees Fahrenheit</code>
−	:string()	+	::The <code>%.2f</code> translates to "format as <code>f</code>loat and use <code>.2</code> decimal places.
−	:substring("abcdef", 2, 4) - Skips the first 2 characters and returns the next 4
−	:text()
−	:title("hello, world") - Returns as "Hello, World"
−	:upper("hello, world") - Returns as "HELLO, WORLD"
−	;Time	+	==indexOf==
−	time()	+	:Syntax
		+	::<code>''integer'' indexOf(''string'' haystack, ''string'' needle)</code>
		+	:Returns
		+	::Returns the character index of the first occurrence of <code>needle</code> inside <code>haystack</code>
		+	:Examples
		+	::<code>indexOf("hello world", 'l')</code> outputs <code>2</code>
		+
		+	==json==
		+	:Syntax
		+	::<code>''string'' json(''dynamic'' value[, "boolean" pretty])</code>
		+	:Returns
		+	::Returns the JSON representation of the provided value. If the pretty parameter is true, indentation is added to improve human readability
		+	:Examples
		+	::<code>json(true)</code> outputs <code>"true"</code>
		+	::<code>json(123)</code> outputs <code>"123"</code>
		+	::<code>json('Nicole "Nikki" Sawyer')</code> outputs <code>""Nicole \"Nikki\" Sawyer""</code>
		+	::<code>json(myStringList, true)</code> outputs with pretty formatting
		+	:::<code>"{<br/>&nbsp; "name": "Jaime",<br/>&nbsp; "present": true<br/>}"</code>
		+	::<code>json(myDeviceList)</code> outputs <code>"[":97e051eb6fea489fa7cf1aaa4cb7c171:",":73d68350942e4555a8c47c36f558681e:"]"</code> since device variables are internally a list of device IDs
		+	::<code><nowiki>"\{"device": {json($currentEventDevice)}, "rooms": \[ {json(activeRoom)}, "Basement" \] \}"</nowiki></code> building JSON by hand in a webCoRE expression requires any <code>{}[]</code> characters in the JSON to be escaped with a backslash and all dynamic values must use the <code>json()</code> function to safely represent the value
		+
		+	==lastIndexOf==
		+	:Syntax
		+	::<code>''integer'' lastIndexOf(''string'' haystack, ''string'' needle)</code>
		+	:Returns
		+	::Returns the character index of the last occurrence of <code>needle</code> inside <code>haystack</code>
		+	:Examples
		+	::<code>lastIndexOf("hello world", 'l')</code> outputs <code>9</code>
		+
		+	==left==
		+	:Syntax
		+	::<code>''string'' left(''string'' value, ''integer'' length)</code>
		+	:Returns
		+	::Returns the first <code>length</code> characters in <code>value</code>
		+	:Examples
		+	::<code>left("hello world", 2)</code> outputs <code>he</code>
		+
		+	==lower==
		+	:Syntax
		+	::<code>''string'' lower(''string'' value)</code>
		+	:Returns
		+	::Returns the <code>value</code> but with all lower case letters.
		+	:Examples
		+	::<code>lower("Hello World")</code> outputs <code>hello world</code>
		+
		+	==mid==
		+	:Syntax
		+	::<code>''string'' mid(''string'' value, ''integer'' start[, ''integer'' count = remaining])</code>
		+	:Arguments
		+	::<code>start</code> - provides the 0-based index of the first character to copy. If <code>start</code> is negative, the counting starts from the end of <code>value</code>.
		+	::<code>count</code> - provides the number of characters to copy from <code>value</code>. If not provided, all of the remaining characters from <code>value</code> are returned, starting with character number <code>start</code>. If <code>count</code> is negative, prior characters are returned.
		+	:Returns
		+	::Returns a substring of <code>value</code>, <code>count</code> characters long, starting at character number <code>start</code>. Note that the first character in any string has index 0.
		+	:Examples
		+	::<code>mid("Hello World", 2, 3)</code> outputs <code>llo</code>
		+	::<code>mid("Hello World", 2)</code> outputs <code>llo World</code>
		+	::<code>mid("Hello World", -5, 2)</code> outputs <code>Wo</code>
		+	::<code>mid("Hello World", -1, -3)</code> outputs <code>orl</code>
		+
		+	==random==
		+	:Syntax
		+	::<code>''dynamic'' random([''integer'' range | ''dynamic'' value1, ''dynamic'' value2[, .., ''dynamic'' valueN]])</code>
		+	:Arguments
		+	::<code>range</code> - an integer number representing a range
		+	::<code>value1</code>..<code>valueN</code> - any kind of arguments, one will be randomly returned
		+	:Returns
		+	::Returns a random decimal number between <code>0</code> and <code>1</code> if no arguments are provided, or a number between <code>0</code> and <code>range</code> (inclusive) if a single argument is provided, or a randomly selected argument if two or more arguments are provided.
		+	:Examples
		+	::<code>random()</code> outputs <code>0.483</code> (random decimal)
		+	::<code>random(20)</code> outputs <code>6</code> (random integer)
		+	::<code>random("Hello World", "Good morning", "Hello", "Hi")</code> outputs <code>Hello</code> (randomly selected value)
		+	:Tips
		+	::To output a random integer between 5 and 20 use <code>(5 + random(15))</code>
		+	::To output a random integer between -5 and 20 use <code>(-5 + random(25))</code>
		+
		+	==replace==
		+	:Syntax
		+	::<code>''string'' replace(''string'' haystack, ''string'' needle1, ''string'' replacement1[, .., ''string'' needleN, ''string'' replacementN])</code>
		+	:Returns
		+	::Replaces all the occurrences of <code>needle</code> inside <code>haystack</code> with its respective <code>replacement</code>. Multiple pairs of <code>needle</code>/<code>replacement</code> can be provided in one function call.
		+	:Regular expressions
		+	::Needles support regular expressions when their value starts and ends with a <code>/</code>. For example, <code>'/(\s)/'</code> will match all spaces.
		+	:Examples
		+	::<code>replace("Hello World", 'World', 'Earth')</code> outputs <code>Hello Earth</code>
		+	::<code>replace("Hello World", 'World', 'Earth', 'Hello', 'Hi')</code> outputs <code>Hi Earth</code>
		+	::<code>replace("Hello World", 'World', 'Earth', 'Earth', 'Planet')</code> outputs <code>Hello Planet</code>
		+
		+	==right==
		+	:Syntax
		+	::<code>''string'' right(''string'' value, ''integer'' length)</code>
		+	:Returns
		+	::Returns the last <code>length</code> characters in <code>value</code>
		+	:Examples
		+	::<code>right("hello world", 4)</code> outputs <code>orld</code>
		+
		+	==startsWith==
		+	:Syntax
		+	::<code>''boolean'' startsWith(''string'' haystack, ''string'' needle)</code>
		+	:Returns
		+	::Returns true if <code>haystack</code> starts with the <code>needle</code>
		+
		+	==string==
		+	:Syntax
		+	::<code>''string'' string(''dynamic'' value)</code>
		+	:Returns
		+	::Returns <code>value</code> as a string.
		+
		+	==substr==
		+	:Alias of <code>mid()</code>
		+
		+	==substring==
		+	:Alias of <code>mid()</code>
		+
		+	==title==
		+	:Syntax
		+	::<code>''string'' title(''string'' value)</code>
		+	:Returns
		+	::Returns the <code>value</code> but in its title case format (each word starts with a capitalized letter).
		+	:Examples
		+	::<code>lower("Hello there world")</code> outputs <code>Hello There World</code>
		+
		+	==upper==
		+	:Syntax
		+	::<code>''string'' upper(''string'' value)</code>
		+	:Returns
		+	::Returns the <code>value</code> but with all upper case letters.
		+	:Examples
		+	::<code>upper("Hello World")</code> outputs <code>HELLO WORLD</code>
		+
		+	==text==
		+	:Alias of <code>string()</code>
		+
		+	==trim==
		+	:Syntax
		+	::<code>"string" trim("string" value)</code>
		+	:Returns
		+	::Returns the <code>value</code> with leading and trailing spaces removed
		+	:Examples
		+	::<code>trim(" Hello World ")</code> outputs <code>Hello World</code>
		+
		+	==trimLeft==
		+	:Syntax
		+	::<code>"string" trimLeft("string" value)</code>
		+	:Returns
		+	::Returns the <code>value</code> with leading spaces removed
		+	:Examples
		+	::<code>trimLeft(" Hello World ")</code> outputs <code>"Hello World "</code>
		+
		+	==ltrim==
		+	:Alias of <code>trimLeft()</code>
		+
		+	==trimRight==
		+	:Syntax
		+	::<code>"string" trimRight("string" value)</code>
		+	:Returns
		+	::Returns the <code>value</code> with trailing spaces removed
		+	:Examples
		+	::<code>trimRight(" Hello World ")</code> outputs <code>" Hello World"</code>
		+
		+	==rtrim==
		+	:Alias of <code>trimRight()</code>
		+
		+	==urlEncode==
		+	:Syntax
		+	::<code>''string'' urlEncode(''dynamic'' value)</code>
		+	:Returns
		+	::Returns a string with all characters other than <code>a-z A-Z 0-9 . - * _ +</code> converted to percent encoding for use in a URL
		+	:Examples
		+	::<code>urlEncode("John's iPhone 8+")</code> outputs <code>"John%27s%20iPhone%208+"</code>
		+	::<code><nowiki>"http://webcore.co/sample?device={urlEncode($currentEventDevice)}&attribute={urlEncode($currentEventAttribute)}&value={urlEncode($currentEventValue)}"</nowiki></code> ensures that the generated URL is valid even if the event information includes spaces, & signs, or other problematic characters.
		+
		+	==encodeURIComponent==
		+	:Alias of <code>urlEncode()</code>
		+
		+	=Numeric functions=
		+
		+	==avg==
		+	:Syntax
		+	::<code>''decimal'' avg(''decimal'' value1, ''decimal'' value2[, .., ''decimal'' valueN])</code>
		+	:Returns
		+	::Returns the mean average of all the values provided.
		+
		+	==abs==
		+	:Syntax
		+	::<code>''decimal'' abs(''decimal'' value)</code>
		+	:Returns
		+	::Returns the absolute value of the argument (e.g., remove negative sign for negative values).
		+
		+	==ceil==
		+	:Syntax
		+	::<code>''integer'' ceil(''decimal'' value)</code>
		+	:Returns
		+	::Returns the immediately higher integer, equivalent to rounding the decimal away from zero.
		+	:Examples
		+	::<code>ceil(5.6)</code> outputs <code>6</code>
		+	::<code>ceil(-5.6)</code> outputs <code>-6</code>
		+
		+	==ceiling==
		+	:Alias of <code>ceil</code>
		+
		+	==decimal==
		+	:Syntax
		+	::<code>''decimal'' decimal(''dynamic'' value)</code>
		+	:Returns
		+	::Converts <code>value</code> into a decimal. Returns <code>0</code> if <code>value</code> is not numeric.
		+
		+	==float==
		+	:Alias of <code>decimal</code>
		+
		+	==floor==
		+	:Syntax
		+	::<code>''integer'' ceil(''decimal'' value)</code>
		+	:Returns
		+	::Returns the integer part of a decimal, equivalent to rounding the decimal towards zero.
		+	:Examples
		+	::<code>floor(5.6)</code> outputs <code>5</code>
		+	::<code>floor(-5.6)</code> outputs <code>-5</code>
		+
		+	==max==
		+	:Syntax
		+	::<code>''dynamic'' max(''dynamic'' value1, ''dynamic'' value2[, .., ''dynamic'' valueN])</code>
		+	:Returns
		+	::Returns the maximum of all the values provided. Note: this function works with both numbers and strings.
		+
		+	==median==
		+	:Syntax
		+	::<code>''dynamic'' median(''dynamic'' value1, ''dynamic'' value2[, .., ''dynamic'' valueN])</code>
		+	:Returns
		+	::Returns the median average of all the values provided. Note: this function works with both numbers and strings.
		+
		+	==min==
		+	:Syntax
		+	::<code>''dynamic'' min(''dynamic'' value1, ''dynamic'' value2[, .., ''dynamic'' valueN])</code>
		+	:Returns
		+	::Returns the minimum of all the values provided. Note: this function works with both numbers and strings.
		+
		+	==number==
		+	:Alias of <code>decimal</code>
		+
		+	==power==
		+	:Syntax
		+	::<code>''decimal'' power(''decimal'' value, ''decimal'' exponent)</code>
		+	:Returns
		+	::Returns the <code>value</code> at the power of <code>exponent</code>
		+
		+	==round==
		+	:Syntax
		+	::<code>''decimal'' round(''decimal'' value[, ''integer'' precision = 0])</code>
		+	:Arguments
		+	::<code>precision</code> - the number of decimal places to be retained. If not provided, defaults to <code>0</code>
		+	:Returns
		+	::Returns the rounded <code>value</code> with <code>precision</code> decimal places.
		+
		+	==sqr==
		+	:Syntax
		+	::<code>''decimal'' sqr(''decimal'' value)</code>
		+	:Returns
		+	::Returns the squared <code>value</code>, equivalent to <code>value</code> multiplied by itself.
		+
		+	==sqrt==
		+	:Syntax
		+	::<code>''decimal'' sqrt(''decimal'' value)</code>
		+	:Returns
		+	::Returns the square root of <code>value</code>.
		+
		+	==stdev==
		+	:Syntax
		+	::<code>''decimal'' stdev(''decimal'' value1, ''decimal'' value2[, .., ''decimal'' valueN])</code>
		+	:Returns
		+	::Returns the standard deviation of all the values provided.
		+
		+	==sum==
		+	:Syntax
		+	::<code>''decimal'' sum(''decimal'' value1, ''decimal'' value2[, .., ''decimal'' valueN])</code>
		+	:Returns
		+	::Returns the sum of sum of all the values provided.
		+
		+	==variance==
		+	:Syntax
		+	::<code>''decimal'' variance(''decimal'' value1, ''decimal'' value2[, .., ''decimal'' valueN])</code>
		+	:Returns
		+	::Returns the variance of all the values provided.
		+
		+	=[[Variable_data_types#Boolean|Boolean]] functions=
		+
		+	==bool==
		+	:Syntax
		+	::<code>bool(''dynamic'' value)</code>
		+	:Returns
		+	::Returns the truth value of the input. Accepts anything as input and will return true if <code>value</code> 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
		+
		+	==boolean==
		+	:This is an alias of [[Functions#bool|bool]]
		+
		+	==eq==
		+	:Syntax
		+	::<code>eq(''dynamic'' value1, ''dynamic'' value2)</code>
		+	:Returns
		+	::Returns true if <code>value1</code> is equivalent to <code>value2</code>
		+
		+	==ge==
		+	:Syntax
		+	::<code>ge(''dynamic'' value1, ''dynamic'' value2)</code>
		+	:Returns
		+	::Returns true if <code>value1</code> is greater than or equal to <code>value2</code>
		+
		+	==gt==
		+	:Syntax
		+	::<code>gt(''dynamic'' value1, ''dynamic'' value2)</code>
		+	:Returns
		+	::Returns true if <code>value1</code> is greater than <code>value2</code>
		+
		+	==isBetween==
		+	:Syntax
		+	::<code>isBetween(''dynamic'' value, ''dynamic'' startValue, ''dynamic'' endValue)</code>
		+	:Returns
		+	::Returns true if <code>value</code> is greater then or equal to <code>startValue</code> and less than or equal to <code>endValue</code>
		+
		+	==isEmpty==
		+	:Syntax
		+	::<code>isEmpty(''dynamic'' value)</code>
		+	:Returns
		+	::Returns true if <code>value</code> is not set, an empty string, or zero
		+
		+	==le==
		+	:Syntax
		+	::<code>le(''dynamic'' value1, ''dynamic'' value2)</code>
		+	:Returns
		+	::Returns true if <code>value1</code> is less than or equal to <code>value2</code>
		+
		+	==lt==
		+	:Syntax
		+	::<code>lt(''dynamic'' value1, ''dynamic'' value2)</code>
		+	:Returns
		+	::Returns true if <code>value1</code> is less than <code>value2</code>
		+
		+	==not==
		+	:Syntax
		+	::<code>not(''dynamic'' value)</code>
		+	:Returns
		+	::Returns the negated truth state of <code>value</code>. This is the logical negation of <code>[[Functions#bool|bool]](''dynamic'' value)</code>.
		+
		+	=[[Variable_data_types#Date_and_Time|Date and time]] functions=
		+
		+	==addDays==
		+	:Syntax
		+	::<code>addDays(''datetime'' value, ''integer'' days)</code>
		+	:Returns
		+	::Returns a datetime that is <code>days</code> days after the <code>value</code>. For negative values of <code>days</code>, it returns a datetime that is <code>days</code> days before <code>value</code>.
		+
		+	==addHours==
		+	:Syntax
		+	::<code>addHours(''datetime'' value, ''integer'' hours)</code>
		+	:Returns
		+	::Returns a datetime that is <code>hours</code> hours after the <code>value</code>. For negative values of <code>hours</code>, it returns a datetime that is <code>hours</code> hours before <code>value</code>.
		+
		+	==addMinutes==
		+	:Syntax
		+	::<code>addMinutes(''datetime'' value, ''integer'' minutes)</code>
		+	:Returns
		+	::Returns a datetime that is <code>minutes</code> minutes after the <code>value</code>. For negative values of <code>minutes</code>, it returns a datetime that is <code>minutes</code> minutes before <code>value</code>.
		+
		+	==addSeconds==
		+	:Syntax
		+	::<code>addSeconds(''datetime'' value, ''integer'' seconds)</code>
		+	:Returns
		+	::Returns a datetime that is <code>seconds</code> seconds after the <code>value</code>. For negative values of <code>seconds</code>, it returns a datetime that is <code>seconds</code> seconds before <code>value</code>.
		+
		+	==addWeeks==
		+	:Syntax
		+	::<code>addWeeks(''datetime'' value, ''integer'' weeks)</code>
		+	:Returns
		+	::Returns a datetime that is <code>weeks</code> weeks after the <code>value</code>. For negative values of <code>weeks</code>, it returns a datetime that is <code>weeks</code> weeks before <code>value</code>.
		+
		+	==date==
		+	:Syntax
		+	::<code>date(''datetime'' value)</code>
		+	:Returns
		+	::Returns the date portion of <code>value</code> by stripping off time information.
		+
		+	==datetime==
		+	:Syntax
		+	::<code>''datetime'' datetime(''dynamic'' value)</code>
		+	:Returns
		+	::Tries to convert any value into a datetime. Accepts strings in common date/time formats.
		+
		+
		+	==formatDuration==
		+	:Syntax
		+	::<code>''string'' formatDuration(''datetime'' value[, ''boolean'' friendly = false[, ''string'' granularity = 's'[, ''boolean'' showAdverbs = false]]])</code>
		+	:Arguments
		+	::<code>friendly</code> - <code>false</code> makes the output compact, in the form of <code>0d 00:00:00.000</code>, while <code>true</code> makes the output more human friendly, in the form of <code> 0 days, 0 hours, 0 minutes, and 0 seconds</code>. Defaults to <code>false</code>.
		+	::<code>granularity</code> - represents the smallest time unit to be output. One of <code>d</code> for days, <code>h</code> for hours, <code>m</code> for minutes, <code>s</code> for seconds, or <code>ms</code> for milliseconds. Any time unit below the selected granularity will not be output. Defaults to <code>s</code>
		+	::<code>showAdverbs</code> - only affects the friendly output, when <code>true</code> the words <code>in</code> (for future durations - positive input) or <code>ago</code> (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
		+	::<code>formatDuration(12029)</code> will output <code>00:00:12</code>
		+	::<code>formatDuration(68493, true)</code> will output <code>1 minute and 8 seconds</code>
		+	::<code>formatDuration(68493, false, 'ms')</code> will output <code>00:01:08.493</code>
		+	::<code>formatDuration(68493, true, 'm', true)</code> will output <code>in 1 minute</code>
		+
		+	==formatDateTime==
		+	:Syntax
		+	::<code>formatDateTime(''datetime'' value, string)</code>
		+	:Known Strings (caSe seNsiTivE)
		+	::G, y, M, d, h, H, m, s, S, E, D, F, w, W, a, k, K, z
		+	:Examples
		+
		+	-----
		+
		+	{| class="mw-datatable"
		+	|-
		+	! rowspan="2" | Meaning
		+	! rowspan="2" | String
		+	! rowspan="2" | Sample Code
		+	! rowspan="2" | Sample<br>Output
		+	! rowspan="2" | Format
		+	! rowspan="2" | Range
		+	! rowspan="2" | Notes
		+	|-
		+	!
		+	|-
		+	| Era
		+	| <code>G</code>
		+	| <code>formatDateTime($now, "G")</code>
		+	| <code>AD</code>
		+	| String
		+	| style="text-align:center;" | <code>BC? - AD</code>
		+	| anno Domini
		+	|-
		+	| Year
		+	| <code>y</code>
		+	| <code>formatDateTime($now, "y")</code>
		+	| <code>1992</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1970? - 2???</code>
		+	| Range needs confirmation
		+	|-
		+	| Year (last 2 digits)
		+	| <code>yy</code>
		+	| <code>formatDateTime($now, "yy")</code>
		+	| <code>92</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1970? - 2???</code>
		+	| Range needs confirmation
		+	|-
		+	| Month (integer)
		+	| <code>M</code>
		+	| <code>formatDateTime($now, "M")</code>
		+	| <code>3</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 12</code>
		+	|
		+	|-
		+	| Month (padded)
		+	| <code>MM</code>
		+	| <code>formatDateTime($now, "MM")</code>
		+	| <code>03</code>
		+	| Integer
		+	| style="text-align:center;" | <code>01 - 12</code>
		+	|
		+	|-
		+	| Month (abbr.)
		+	| <code>MMM</code>
		+	| <code>formatDateTime($now, "MMM")</code>
		+	| <code>Mar</code>
		+	| String
		+	| style="text-align:center;" | <code>Jan - Dec</code>
		+	| 3 Letter abbreviation
		+	|-
		+	| Month
		+	| <code>MMMM</code>
		+	| <code>formatDateTime($now, "MMMM")</code>
		+	| <code>March</code>
		+	| String
		+	| style="text-align:center;" | <code>January - December</code>
		+	| Full word
		+	|-
		+	| Day of Month
		+	| <code>d</code>
		+	| <code>formatDateTime($now, "d")</code>
		+	| <code>6?</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 31</code>
		+	|
		+	|-
		+	| Day of Month
		+	| <code>dd</code>
		+	| <code>formatDateTime($now, "dd")</code>
		+	| <code>26</code>
		+	| Integer
		+	| style="text-align:center;" | <code>01 - 31</code>
		+	|
		+	|-
		+	| Hour
		+	| <code>h</code>
		+	| <code>formatDateTime($now, "h")</code>
		+	| <code>7</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 12</code>
		+	|
		+	|-
		+	| Hour (padded)
		+	| <code>hh</code>
		+	| <code>formatDateTime($now, "hh")</code>
		+	| <code>07</code>
		+	| Integer
		+	| style="text-align:center;" | <code>01 - 12</code>
		+	|
		+	|-
		+	| Hour (Military)
		+	| <code>H</code>
		+	| <code>formatDateTime($now, "H")</code>
		+	| <code>22</code>
		+	| Integer
		+	| style="text-align:center;" | <code>0 - 23</code>
		+	|
		+	|-
		+	| Hour (Military padded)
		+	| <code>HH</code>
		+	| <code>formatDateTime($now, "HH")</code>
		+	| <code>07</code>
		+	| Integer
		+	| style="text-align:center;" | <code>00 - 23</code>
		+	|
		+	|-
		+	| Minute
		+	| <code>m</code>
		+	| <code>formatDateTime($now, "m")</code>
		+	| <code>8</code>
		+	| Integer
		+	| style="text-align:center;" | <code>0 - 59</code>
		+	|
		+	|-
		+	| Minute (padded)
		+	| <code>mm</code>
		+	| <code>formatDateTime($now, "mm")</code>
		+	| <code>08</code>
		+	| Integer
		+	| style="text-align:center;" | <code>00? - 59</code>
		+	|
		+	|-
		+	| Second
		+	| <code>s</code>
		+	| <code>formatDateTime($now, "s")</code>
		+	| <code>8</code>
		+	| Integer
		+	| style="text-align:center;" | <code>0 - 59</code>
		+	|
		+	|-
		+	| Second (padded)
		+	| <code>ss</code>
		+	| <code>formatDateTime($now, "ss")</code>
		+	| <code>08</code>
		+	| Integer
		+	| style="text-align:center;" | <code>00? - 59</code>
		+	| "00" needs confirmation
		+	|-
		+	| Millisecond
		+	| <code>S</code>
		+	| <code>formatDateTime($now, "S")</code>
		+	| <code>42</code>
		+	| Integer
		+	| style="text-align:center;" | <code>0 - 999</code>
		+	|
		+	|-
		+	| Millisecond (padded)
		+	| <code>SSS</code>
		+	| <code>formatDateTime($now, "SSS")</code>
		+	| <code>042</code>
		+	| Integer
		+	| style="text-align:center;" | <code>000? - 999</code>
		+	| Good luck trying to capture "000"
		+	|-
		+	| Day of Week (abbr.)
		+	| <code>E</code>
		+	| <code>formatDateTime($now, "E")</code>
		+	| <code>Sat</code>
		+	| String
		+	| style="text-align:center;" | <code>Wed - Tue</code>
		+	|
		+	|-
		+	| Day of Week
		+	| <code>EEEE</code>
		+	| <code>formatDateTime($now, "EEEE")</code>
		+	| <code>Saturday</code>
		+	| String
		+	| style="text-align:center;" | <code>Friday - Thursday</code>
		+	|
		+	|-
		+	| Day of Year
		+	| <code>D</code>
		+	| <code>formatDateTime($now, "D")</code>
		+	| <code>362</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 366</code>
		+	|
		+	|-
		+	| Day of Week in Month
		+	| <code>F</code>
		+	| <code>formatDateTime($now, "F")</code>
		+	| <code>3</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 5?</code>
		+	| IE: 3rd Mon in May
		+	|-
		+	| Week in Year
		+	| <code>w</code>
		+	| <code>formatDateTime($now, "w")</code>
		+	| <code>51</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 54?</code>
		+	| "54" needs confirmation
		+	|-
		+	| Week in Month
		+	| <code>W</code>
		+	| <code>formatDateTime($now, "W")</code>
		+	| <code>2</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 6?</code>
		+	| "6" needs confirmation
		+	|-
		+	| AM/PM
		+	| <code>a</code>
		+	| <code>formatDateTime($now, "a")</code>
		+	| <code>PM</code>
		+	| String
		+	| style="text-align:center;" | <code>AM - PM</code>
		+	|
		+	|-
		+	| Hour (alt version)
		+	| <code>K</code>
		+	| <code>formatDateTime($now, "K")</code>
		+	| <code>7</code>
		+	| Integer
		+	| style="text-align:center;" | <code>0 - 11</code>
		+	|
		+	|-
		+	| Hour (alt Military)
		+	| <code>k</code>
		+	| <code>formatDateTime($now, "k")</code>
		+	| <code>24</code>
		+	| Integer
		+	| style="text-align:center;" | <code>1 - 24</code>
		+	|
		+	|-
		+	| Time Zone (abbr.)
		+	| <code>z</code>
		+	| <code>formatDateTime($now, "z")</code>
		+	| <code>EDT</code>
		+	| String
		+	| style="text-align:center;" | ''Various''
		+	|
		+	|-
		+	| Time Zone
		+	| <code>zzzz</code>
		+	| <code>formatDateTime($now, "zzzz")</code>
		+	| <code>Eastern<br>Daylight<br>Time</code>
		+	| String
		+	| style="text-align:center;" | ''Various''
		+	| Some locations cycle<br>twice a year
		+	|-
		+	|
		+	|}
		+
		+	----
		+
		+	Here are a few combined examples:
		+
		+	{| class="mw-datatable"
		+	|-
		+	! Sample Code
		+	! Sample Output
		+	! Notes
		+	|-
		+	| <code>formatDateTime($now, "H:m")</code>
		+	| <code>23:55</code>
		+	|
		+	|-
		+	| <code>formatDateTime($now, "h:mm a")</code>
		+	| <code>8:01 PM</code>
		+	|
		+	|-
		+	| <code>formatDateTime($now, "EEEE, MMM d, yy")</code>
		+	| <code>Saturday, Mar 21, 20</code>
		+	|
		+	|-
		+	| <code>formatDateTime("August 9, 1995", "EEEE")</code>
		+	| <code>Wednesday</code>
		+	| Note that "datetime value" does not have to be <code>$now</code>
		+	|-
		+	|
		+	|}
		+
		+
		+	:formatDateTime reference - https://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html
		+	:(We are using the term "Strings" here... They call them "Symbols" on that page)
		+
		+
		+	.
		+
		+	==time==
		+	:Syntax
		+	::<code>''time'' time(''datetime'' value)</code>
		+	:Returns
		+	::Returns the time portion of <code>value</code> by stripping off date information.
		+
		+	=Weather related functions=
		+
		+	==celsius==
		+	:Syntax
		+	::<code>''decimal'' celsius(''decimal'' value)</code>
		+	:Returns
		+	::Converts a temperature value from Fahrenheit to Celsius.
		+
		+	==dewPoint==
		+	:Syntax
		+	::<code>''decimal'' dewPoint(''decimal'' temperature, ''decimal'' relativeHumidity[, ''string'' scale = 'F'])</code>
		+	:Parameters
		+	::<code>scale</code> - optional, one of <code>"C"</code> or <code>"F"</code>, corresponding to the temperature range used for <code>temperature</code>. 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
		+	::<code>''decimal'' fahrenheit(''decimal'' value)</code>
		+	:Returns
		+	::Converts a temperature value from Celsius to Fahrenheit.
		+
		+	==convertTemperatureIfNeeded==
		+	:Syntax
		+	::<code>''decimal'' convertTemperatureIfNeeded(''decimal'' value, ''string'' scaleOfValue)</code>
		+	:Parameters
		+	::<code>value</code> - the numeric temperature value in units specified by the <code>scaleOfValue</code> parameter
		+	::<code>scaleOfValue</code> - one of <code>"C"</code> or <code>"F"</code>, 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 <code>$temperatureScale</code>). If the provided unit matches the location's temperature scale the value is returned as-is.
		+
		+	= [[Variable_data_types#Dynamic|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
		+
		+	= [[Variable_data_types#Number_.28Integer.29|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 <code>604800000</code>, which corresponds to 7 days.
		+	:Use <code>previousAge([device﹕attribute]) - age([device﹕attribute])</code> to determine the length of time that the device attribute had the previous value.
		+
		+	= [[Variable_data_types#Time|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

---

Latest revision as of 04:14, 23 March 2020

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 the haystack

endsWith

Syntax

boolean endsWith(string haystack, string needle)

Returns

Returns true if haystack ends with the needle

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 for printf(). 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.

Example

format('The temperature outside is %.2f degrees Fahrenheit', [Temp sensor:temperature]) outputs The temperature outside is 71.26 degrees Fahrenheit

The %.2f translates to "format as float and use .2 decimal places.

indexOf

Syntax

integer indexOf(string haystack, string needle)

Returns

Returns the character index of the first occurrence of needle inside haystack

Examples

indexOf("hello world", 'l') outputs 2

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 the json() 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 inside haystack

Examples

lastIndexOf("hello world", 'l') outputs 9

left

Syntax

string left(string value, integer length)

Returns

Returns the first length characters in value

Examples

left("hello world", 2) outputs he

lower

Syntax

string lower(string value)

Returns

Returns the value but with all lower case letters.

Examples

lower("Hello World") outputs hello 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. If start is negative, the counting starts from the end of value.

count - provides the number of characters to copy from value. If not provided, all of the remaining characters from value are returned, starting with character number start. If count is negative, prior characters are returned.

Returns

Returns a substring of value, count characters long, starting at character number start. Note that the first character in any string has index 0.

Examples

mid("Hello World", 2, 3) outputs llo

mid("Hello World", 2) outputs llo World

mid("Hello World", -5, 2) outputs Wo

mid("Hello World", -1, -3) outputs orl

random

Syntax

dynamic random([integer range | dynamic value1, dynamic value2[, .., dynamic valueN]])

Arguments

range - an integer number representing a range

value1..valueN - any kind of arguments, one will be randomly returned

Returns

Returns a random decimal number between 0 and 1 if no arguments are provided, or a number between 0 and range (inclusive) if a single argument is provided, or a randomly selected argument if two or more arguments are provided.

Examples

random() outputs 0.483 (random decimal)

random(20) outputs 6 (random integer)

random("Hello World", "Good morning", "Hello", "Hi") outputs Hello (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))

replace

Syntax

string replace(string haystack, string needle1, string replacement1[, .., string needleN, string replacementN])

Returns

Replaces all the occurrences of needle inside haystack with its respective replacement. Multiple pairs of needle/replacement can be provided in one function call.

Regular expressions

Needles support regular expressions when their value starts and ends with a /. For example, '/(\s)/' will match all spaces.

Examples

replace("Hello World", 'World', 'Earth') outputs Hello Earth

replace("Hello World", 'World', 'Earth', 'Hello', 'Hi') outputs Hi Earth

replace("Hello World", 'World', 'Earth', 'Earth', 'Planet') outputs Hello Planet

right

Syntax

string right(string value, integer length)

Returns

Returns the last length characters in value

Examples

right("hello world", 4) outputs orld

startsWith

Syntax

boolean startsWith(string haystack, string needle)

Returns

Returns true if haystack starts with the needle

string

Syntax

string string(dynamic value)

Returns

Returns value as a string.

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).

Examples

lower("Hello there world") outputs Hello There World

upper

Syntax

string upper(string value)

Returns

Returns the value but with all upper case letters.

Examples

upper("Hello World") outputs HELLO WORLD

text

Alias of string()

trim

Syntax

"string" trim("string" value)

Returns

Returns the value with leading and trailing spaces removed

Examples

trim(" Hello World ") outputs Hello World

trimLeft

Syntax

"string" trimLeft("string" value)

Returns

Returns the value with leading spaces removed

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

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

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) outputs 6

ceil(-5.6) outputs -6

ceiling

Alias of ceil

decimal

Syntax

decimal decimal(dynamic value)

Returns

Converts value into a decimal. Returns 0 if value is not numeric.

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) outputs 5

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 of exponent

round

Syntax

decimal round(decimal value[, integer precision = 0])

Arguments

precision - the number of decimal places to be retained. If not provided, defaults to 0

Returns

Returns the rounded value with precision decimal places.

sqr

Syntax

decimal sqr(decimal value)

Returns

Returns the squared value, equivalent to value multiplied by itself.

sqrt

Syntax

decimal sqrt(decimal value)

Returns

Returns the square root of value.

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

boolean

This is an alias of bool

eq

Syntax

eq(dynamic value1, dynamic value2)

Returns

Returns true if value1 is equivalent to value2

ge

Syntax

ge(dynamic value1, dynamic value2)

Returns

Returns true if value1 is greater than or equal to value2

gt

Syntax

gt(dynamic value1, dynamic value2)

Returns

Returns true if value1 is greater than value2

isBetween

Syntax

isBetween(dynamic value, dynamic startValue, dynamic endValue)

Returns

Returns true if value is greater then or equal to startValue and less than or equal to endValue

isEmpty

Syntax

isEmpty(dynamic value)

Returns

Returns true if value is not set, an empty string, or zero

le

Syntax

le(dynamic value1, dynamic value2)

Returns

Returns true if value1 is less than or equal to value2

lt

Syntax

lt(dynamic value1, dynamic value2)

Returns

Returns true if value1 is less than value2

not

Syntax

not(dynamic value)

Returns

Returns the negated truth state of value. This is the logical negation of bool(dynamic value).

Date and time functions

addDays

Syntax

addDays(datetime value, integer days)

Returns

Returns a datetime that is days days after the value. For negative values of days, it returns a datetime that is days days before value.

addHours

Syntax

addHours(datetime value, integer hours)

Returns

Returns a datetime that is hours hours after the value. For negative values of hours, it returns a datetime that is hours hours before value.

addMinutes

Syntax

addMinutes(datetime value, integer minutes)

Returns

Returns a datetime that is minutes minutes after the value. For negative values of minutes, it returns a datetime that is minutes minutes before value.

addSeconds

Syntax

addSeconds(datetime value, integer seconds)

Returns

Returns a datetime that is seconds seconds after the value. For negative values of seconds, it returns a datetime that is seconds seconds before value.

addWeeks

Syntax

addWeeks(datetime value, integer weeks)

Returns

Returns a datetime that is weeks weeks after the value. For negative values of weeks, it returns a datetime that is weeks weeks before value.

date

Syntax

date(datetime value)

Returns

Returns the date portion of value by stripping off time information.

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 of 0d 00:00:00.000, while true makes the output more human friendly, in the form of 0 days, 0 hours, 0 minutes, and 0 seconds. Defaults to false.

granularity - represents the smallest time unit to be output. One of d for days, h for hours, m for minutes, s for seconds, or ms for milliseconds. Any time unit below the selected granularity will not be output. Defaults to s

showAdverbs - only affects the friendly output, when true the words in (for future durations - positive input) or ago (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 output 00:00:12

formatDuration(68493, true) will output 1 minute and 8 seconds

formatDuration(68493, false, 'ms') will output 00:01:08.493

formatDuration(68493, true, 'm', true) will output in 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	BC? - AD	anno Domini
Year	y	formatDateTime($now, "y")	1992	Integer	1970? - 2???	Range needs confirmation
Year (last 2 digits)	yy	formatDateTime($now, "yy")	92	Integer	1970? - 2???	Range needs confirmation
Month (integer)	M	formatDateTime($now, "M")	3	Integer	1 - 12
Month (padded)	MM	formatDateTime($now, "MM")	03	Integer	01 - 12
Month (abbr.)	MMM	formatDateTime($now, "MMM")	Mar	String	Jan - Dec	3 Letter abbreviation
Month	MMMM	formatDateTime($now, "MMMM")	March	String	January - December	Full word
Day of Month	d	formatDateTime($now, "d")	6?	Integer	1 - 31
Day of Month	dd	formatDateTime($now, "dd")	26	Integer	01 - 31
Hour	h	formatDateTime($now, "h")	7	Integer	1 - 12
Hour (padded)	hh	formatDateTime($now, "hh")	07	Integer	01 - 12
Hour (Military)	H	formatDateTime($now, "H")	22	Integer	0 - 23
Hour (Military padded)	HH	formatDateTime($now, "HH")	07	Integer	00 - 23
Minute	m	formatDateTime($now, "m")	8	Integer	0 - 59
Minute (padded)	mm	formatDateTime($now, "mm")	08	Integer	00? - 59
Second	s	formatDateTime($now, "s")	8	Integer	0 - 59
Second (padded)	ss	formatDateTime($now, "ss")	08	Integer	00? - 59	"00" needs confirmation
Millisecond	S	formatDateTime($now, "S")	42	Integer	0 - 999
Millisecond (padded)	SSS	formatDateTime($now, "SSS")	042	Integer	000? - 999	Good luck trying to capture "000"
Day of Week (abbr.)	E	formatDateTime($now, "E")	Sat	String	Wed - Tue
Day of Week	EEEE	formatDateTime($now, "EEEE")	Saturday	String	Friday - Thursday
Day of Year	D	formatDateTime($now, "D")	362	Integer	1 - 366
Day of Week in Month	F	formatDateTime($now, "F")	3	Integer	1 - 5?	IE: 3rd Mon in May
Week in Year	w	formatDateTime($now, "w")	51	Integer	1 - 54?	"54" needs confirmation
Week in Month	W	formatDateTime($now, "W")	2	Integer	1 - 6?	"6" needs confirmation
AM/PM	a	formatDateTime($now, "a")	PM	String	AM - PM
Hour (alt version)	K	formatDateTime($now, "K")	7	Integer	0 - 11
Hour (alt Military)	k	formatDateTime($now, "k")	24	Integer	1 - 24
Time Zone (abbr.)	z	formatDateTime($now, "z")	EDT	String	Various
Time Zone	zzzz	formatDateTime($now, "zzzz")	Eastern Daylight Time	String	Various	Some locations cycle twice a year

---

Here are a few combined examples:

Sample Code	Sample Output	Notes
formatDateTime($now, "H:m")	23:55
formatDateTime($now, "h:mm a")	8:01 PM
formatDateTime($now, "EEEE, MMM d, yy")	Saturday, Mar 21, 20
formatDateTime("August 9, 1995", "EEEE")	Wednesday	Note that "datetime value" does not have to be $now

formatDateTime reference - https://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html

(We are using the term "Strings" here... They call them "Symbols" on that page)

.

time

Syntax

time time(datetime value)

Returns

Returns the time portion of value by stripping off date information.

Weather related functions

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 for temperature. 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 the scaleOfValue parameter

scaleOfValue - 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.

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