Instantly share code, notes, and snippets.

# terrancesnyder/datemath.md

Last active May 30, 2016 16:50
Show Gist options
• Save terrancesnyder/95f79ad585f9ee55caac16d5db7f8a56 to your computer and use it in GitHub Desktop.
Date Math

# Date Support

The dates used within the platform support more than simple date/time constraints. Almost all dates within the platform are strings and have special semantics when dealing with periodicity as well as general date/math functions that make it much easier to specify effective start/stop period and work within date ranges.

## Basic Date Format

The basic date format is defined as `YYYY-MM-DDThh:mm:ssZ` where:

• YYYY is the year.
• MM is the month.
• DD is the day of the month.
• hh is the hour of the day as on a 24-hour clock.
• mm is minutes.
• ss is seconds.
• Z is a literal 'Z' character indicating that this string representation of the date is in UTC

Note that no time zone can be specified; the String representations of dates is always expressed in Coordinated Universal Time (UTC).

Here is an example value:

• 1972-05-20T17:33:18Z

## Date Math Syntax

Date math expressions consist either adding some quantity of time in a specified unit, or rounding the current time by a specified unit. expressions can be chained and are evaluated left to right.

For example: this represents a point in time two months from now:

• NOW+2MONTHS

This is one day ago:

• NOW-1DAY

A slash is used to indicate rounding. This represents the beginning of the current hour:

• NOW/HOUR

The following example computes (with millisecond precision) the point in time six months and three days into the future and then rounds that time to the beginning of that day:

• NOW+6MONTHS+3DAYS/DAY

Note that while date math is most commonly used relative to NOW it can be applied to any fixed moment in time as well:

• 1972-05-20T17:33:18.772Z+6MONTHS+3DAYS/DAY

You can optionally include fractional seconds if you wish, although any precision beyond milliseconds will be ignored. Here are example values with sub-seconds:

• 1972-05-20T17:33:18.772Z
• 1972-05-20T17:33:18.77Z
• 1972-05-20T17:33:18.7Z