Date Functions in Rule Expressions

In additional to traditional math expressions like addition, multiplication, division, and averaging, rule expressions provide a variety of date and time related features. For more details on how to use expressions, check out the Introduction to Expressions article. 

Time Input

• now()  Return: current unix timestamp (millis)

• date(input[, format])  

  Accepts an input  date value and optional format  string. The default parser expects unix timestamps and ISO formatted date strings when a format string is not provided. The optional format  string can use the reference format values.
  Return: the parsed unix timestamp (millis)

date($myTimestamp)
date('2022-09-23', 'YYYY-MM-DD')

Date Math

• addDays(date, value)  Adds the value number of days to the base date ¹ Return: unix timestamp (millis)
• addHours(date, value)  Adds the value number of hours to the base date ¹ Return: unix timestamp (millis)
• addMinutes(date, value)  Adds the value number of minutes to the base date ¹ Return: unix timestamp (millis)
• addSeconds(date, value)  Adds the value number of seconds to the base date ¹ Return: unix timestamp (millis)
• addWeeks(date, value)  Adds the value number of weeks to the base date ¹ Return: unix timestamp (millis)
• startOfDate(date, unit='day')  Return: timestamp at the beginning of the specified date unit ² (default: day)
• endOfDate(date, unit='day')  Return: timestamp at the end of the specified date unit ² (default: day)
• setDatePart(date, unit, value)  Return: timestamp with the adjusted date unit ^{2, 3} updated to the supplied value
• getDatePart(date, unit)  Return: numeric value indicating the specified date unit ^{2, 3}

addDays(now(), 1)              //tomorrow (at the current time)
startOfDate(addDays(now(), 1)) //midnight tonight (eg. 00:00 tomorrow)
endOfDate(now(), 1)            //23:59 tonight
setDatePart(startOfDate(now()), 'hour', 4) //4:00 AM today
getDatePart(now(), 'hour')     //the current numeric hour (eg. 19 at 7:00 PM)

Sunset and Sunrise

You can calculate sunset and sunrise times within expressions for the current day or any date you specify.

• sunrise(date)  Calculates the time of sunrise; optionally accepts a date  parameter
• sunset(date)  Calculates the time of sunset; optionally accepts a date  parameter

The sunrise or sunset is calculated using the first location on the account which contains a valid geolocation and outputs the time of the event as a unix timestamp (millis).

By default, each method outputs the current day's sunset/sunrise, but each method also accepts an optional date  parameter which accepts a unix timestamp (millis) to adjust which date the sunrise/sunset is calculated for.

formatDate(sunrise(), "LT")      //today's sunrise (eg. 6:31 AM)
formatDate(sunset(), "LT")       //today's sunset (eg. 8:18 PM)

tomorrow = addDays(now(), 1)         //calculate tomorrow by adding 1 day
formatDate(sunrise(tomorrow), "LT")  //tomorrow's sunrise (eg. 6:30 AM)

Note that you can combine other logic for cases where you want specific sunrise or sunset values. For example, a common use-case is to get the next sunrise. The following reads as "if it’s currently after today’s sunrise, then use tomorrow’s sunrise, otherwise use today’s"

tomorrow = addDays(now(), 1)
time = now() > sunrise() ? 
  sunrise(tomorrow) : 
  sunrise()
formatDate(time, "LT")

Date Formatting

• formatDate(date, format, locale)  The format   string can use the reference format values. The locale  string should be a valid locale key.
• humanizeDuration(millis, showAdverbs=false)  
• durationAs(millis, units)  
• formatDuration(millis, format)  

formatDate(now(), 'YYYY-MM-DD')        //2022-09-23 (en-US locale default)
formatDate(now(), 'LLL', 'pl')         //23 września 2022 17:58
humanizeDuration(60 * 1000)            // "a minute"
humanizeDuration(60 * 60 * 1000, true) // "in an hour"
humanizeDuration(-60 * 1000, true)     // "a minute ago"
durationAs(60 * 60 * 1000, 'hours')    //1
formatDuration((60 * 60 * 1000) + (2 * 60 * 1000), "HH:mm") //01:02 (one hour, 2 minutes)

Date Logic

• isBetweenDates(start, end)  Returns true  if the current date is between the provided start  and end  dates. The provided dates should either be in YYYY-MM-DD  , MM-DD  , or millisecond format as is common with the result of other date functions. Note that the year portion is always ignored to ensure the expression will continue to work year after year.