User Tools

  • (equal to forum credentials)

Site Tools


functions

Table of Contents

Functions

RANDOM

Version
Available since pilight v7.0

Description
Generate a random number.

Examples

IF RANDOM(0, 10) == 5 THEN ...
IF RANDOM(1, 100) == 10 THEN ...
IF RANDOM(randomLow.dimlevel, randomHigh.dimlevel) == 10 THEN ...

Parameters
The random function takes two arguments and generates a number in between the two the lower and higher boundary. The function can also accept device parameters like shown above to dynamically change its behavior.

DATE_ADD

Version
Available since pilight v7.0

Description
Allows calculations with date and time values.

Examples

IF DATE_ADD(datetime, +1 HOUR) == ...
IF DATE_ADD(datetime, -1 DAY) == ...
IF DATE_ADD(2015-12-31, 23:59:59, +1 SECOND) == ...
IF DATE_ADD(datetime, RANDOM(-3, +3) DAY) == ...
IF DATE_FORMAT(DATE_ADD(2015-01-01 21:00:00, RANDOM(0, 120) MINUTE), \"%Y-%m-%d %H:%M:%S\", %H.%M) == ...

Parameters
The first argument can be either a datetime device or a datetime string. The datetime string must be in the format YYYY-MM-DD HH:MM:SS. The last argument contains a number and unit. The number can be either positive or negative. The unit can be SECOND, MINUTE, HOUR, DAY, MONTH, or YEAR.

Return value
The return format is always in the format ”%Y-%m-%d %H:%M:%S”. So in case of the third example, the output will be “2016-01-01 00:00:00”.

DATE_FORMAT

Version
Available since pilight v7.0

Description
Allows easy reformatting of date and time values

Examples

IF DATE_FORMAT(datetime, %H%M%S) == ...
Will translate as 122144 if it's 12:21:44.
IF DATE_FORMAT(datetime, %Y-%m-%d) == ...
Will translate as 2015-04-29
IF DATE_FORMAT(2015-04-29, %Y-%m-%d, %d-%m-%Y) == ...
Will translate as 29-04-2015
IF DATE_FORMAT(DATE_ADD(datetime, +1 HOUR), \"%Y-%m-%d %H:%M:%S\", %H.%M)
Will translate the input 29-04-2015 12:21:44 to 13.21

Parameters
The function takes either two or three parameters. When a datetime protocol is given as the first parameter, the function only requires two parameters. The second parameter will then contain the formatted string to output. When a datetime string is given as the first parameter, an additional second parameter is given to tell the function in what format the inputted date time string was offered. So to properly format an input string like 29-04-2015 12:12:12 we need to know what number is the date, month, hour, minute or second. All these numbers except the year could be a valid other number. 29 could well be the day, but also an hour, minute, or second. That's why we need an additional formatting parameter when a datetime string is given as the first parameter.

When you use DATE_ADD as the first parameter, you should consider the return value of DATE_ADD, because that's what DATE_FORMAT will eventually receive. The output format of DATE_ADD is ”%Y-%m-%d %H:%M:%S”, so the input format for DATE_FORMAT should be the same.

Also consider that the flexibility of the function depends on the input. If you input just %H:%M:%S, the DATE_FORMAT can't output a format like this %Y-%m-%d, because the function didn't receive any date information. It only received time information. So, DATE_FORMAT can't be used to exterpolate information that's not present.

The formatting parameters are the same as used by the C function strtime. For documentation, best refer to the C manual.

Return value
The function will output the exact format as requested in the last (second or third argument). There are a few things you must consider when working with the DATE_FORMAT function. The types of operators you can use with DATE_FORMAT depends on the output format requested. If you want to compare the output format %c you can only use the IS operator, because the final output will be interpreted as a string value. If you want to compare %H.%M, you will need numeric operators like ==, >, or <, because the output will be evaluated as a number.

Also consider the usage of quotes. The flexibility in which DATE_FORMAT can format date and time values isn't always accepted by pilight. For example: DATE_FORMAT(datetime, %c) outputs Fri Apr 24 11:35:36 2015 which pilight subsequently can't handle. If you want to output string like this, use quotes DATE_FORMAT(datetime, ”%c”), which will output as “Fri Apr 24 11:35:36 2015”.

functions.txt · Last modified: 2015/11/27 22:09 (external edit)