Skip to main content

date

title: Date sidebar_position: 6​

Date

Part of the function and operator catalog. Every example shown below is executed as an assertion by the engine's own test suite (examples.test.ts), so a result shown here is a result the engine actually produces for that input.

NOW​

NOW() -> a date/time

Returns the current instant, supplied by the caller through the evaluation's present-instant option — never the host clock — interpreted in the ruleset's declared timezone.

Examples:

  • NOW()
    • now: 1798804800000
    • timezone: UTC
    • result: "2027-01-01T12:00:00.000Z[UTC]"
  • NOW()
    • fails with EXPR_MISSING_PRESENT_INSTANT

TODAY​

TODAY() -> a date/time

Returns the start of the current instant's local calendar day, in the ruleset's declared timezone. The current instant is supplied by the caller — never the host clock — exactly as NOW does.

Examples:

  • TODAY()
    • now: 1798804800000
    • timezone: UTC
    • result: "2027-01-01T00:00:00.000Z[UTC]"
  • TODAY()
    • fails with EXPR_MISSING_PRESENT_INSTANT

DATE​

DATE(year: a number, month: a number, day: a number) -> a date/time

Constructs the start of the local calendar day named by year, month (one to twelve) and day, in the ruleset's declared timezone. A month outside one to twelve, or a day outside one to the target month's length — including a non-existent date such as the thirty-first of February — fails rather than rolling over into the next month.

Examples:

  • DATE(2027, 1, 31)
    • result: "2027-01-31T00:00:00.000Z[UTC]"
  • DATE(2027, 2, 31)
    • fails with EXPR_TYPE_MISMATCH
  • DATE(2027, 13, 1)
    • fails with EXPR_TYPE_MISMATCH

YEAR​

YEAR(date: a date/time) -> a number

Returns a date/time's local calendar year, in its own timezone.

Examples:

  • YEAR(DATE(2027, 6, 15))
    • result: "2027"

MONTH​

MONTH(date: a date/time) -> a number

Returns a date/time's local calendar month (one to twelve), in its own timezone.

Examples:

  • MONTH(DATE(2027, 6, 15))
    • result: "6"

DAY​

DAY(date: a date/time) -> a number

Returns a date/time's local calendar day of the month, in its own timezone.

Examples:

  • DAY(DATE(2027, 6, 15))
    • result: "15"

ADD_DAYS​

ADD_DAYS(date: a date/time, count: a number) -> a date/time

Adds a whole number of calendar days to a date/time's own local calendar day, keeping the same local time of day — including across a daylight-saving transition. A negative count moves backwards. A fractional count is a type error: a fractional day has no calendar meaning.

Examples:

  • ADD_DAYS(DATE(2027, 6, 15), 5)
    • result: "2027-06-20T00:00:00.000Z[UTC]"
  • ADD_DAYS(DATE(2027, 6, 15), input.count)
    • context: {"count":-5}
    • result: "2027-06-10T00:00:00.000Z[UTC]"
  • ADD_DAYS(DATE(2027, 6, 15), 1.5)
    • fails with EXPR_TYPE_MISMATCH

ADD_MONTHS​

ADD_MONTHS(date: a date/time, count: a number) -> a date/time

Adds a whole number of calendar months to a date/time's own local calendar month, clamping the day to the target month's last day when the source day does not exist there: the thirty-first of January plus one month is the twenty-eighth or twenty-ninth of February by year, never a rollover into March. A negative count moves backwards with the same clamping.

Examples:

  • ADD_MONTHS(DATE(2027, 1, 31), 1)
    • result: "2027-02-28T00:00:00.000Z[UTC]"
  • ADD_MONTHS(DATE(2028, 1, 31), 1)
    • result: "2028-02-29T00:00:00.000Z[UTC]"
  • ADD_MONTHS(DATE(2027, 3, 31), input.count)
    • context: {"count":-1}
    • result: "2027-02-28T00:00:00.000Z[UTC]"

DIFF_DAYS​

DIFF_DAYS(from: a date/time, to: a date/time) -> a number

Counts whole calendar-day boundaries from the first date/time to the second, in the first date/time's own timezone — negative when the second is earlier than the first. Never computed by subtracting instants and dividing by a day's worth of milliseconds, so it is correct across a daylight-saving transition.

Examples:

  • DIFF_DAYS(DATE(2027, 6, 1), DATE(2027, 6, 10))
    • result: "9"
  • DIFF_DAYS(DATE(2027, 6, 10), DATE(2027, 6, 1))
    • result: "-9"

START_OF_DAY​

START_OF_DAY(date: a date/time) -> a date/time

Returns the local midnight of a date/time's own local calendar day, in its own timezone.

Examples:

  • START_OF_DAY(DATE(2027, 6, 15))
    • result: "2027-06-15T00:00:00.000Z[UTC]"

END_OF_DAY​

END_OF_DAY(date: a date/time) -> a date/time

Returns the last representable instant within a date/time's own local calendar day, in its own timezone — inclusive of the day itself (the last instant at the value type's declared millisecond precision), not the first instant of the next day.

Examples:

  • END_OF_DAY(DATE(2027, 6, 15))
    • result: "2027-06-15T23:59:59.999Z[UTC]"

PARSEDATE​

PARSEDATE(text: text, pattern: text) -> a date/time

Parses text into a date/time using an enumerated pattern (yyyy, MM, dd, HH, mm, ss and literal separators), in the ruleset's declared timezone. Missing time fields default to the start of the local day. Fails if the text does not match the pattern, if the pattern uses anything outside the token set, or if the parsed fields do not name a calendar date and a time of day that both exist — an hour outside zero to twenty-three, or a minute or second outside zero to fifty-nine, fails rather than rolling the date forward.

Examples:

  • FORMATDATE(PARSEDATE('31.01.2027', 'dd.MM.yyyy'), 'dd.MM.yyyy')
    • result: "31.01.2027"
  • PARSEDATE('31-01-2027', 'dd.MM.yyyy')
    • fails with EXPR_DATE_PARSE_FAILED
  • PARSEDATE('31.02.2027', 'dd.MM.yyyy')
    • fails with EXPR_DATE_PARSE_FAILED
  • PARSEDATE('2027', 'QQQQ')
    • fails with EXPR_INVALID_DATE_PATTERN
  • PARSEDATE('01.01.2027 24:00:00', 'dd.MM.yyyy HH:mm:ss')
    • fails with EXPR_DATE_PARSE_FAILED
  • PARSEDATE('01.01.2027 00:60:00', 'dd.MM.yyyy HH:mm:ss')
    • fails with EXPR_DATE_PARSE_FAILED
  • PARSEDATE('01.01.2027 00:00:60', 'dd.MM.yyyy HH:mm:ss')
    • fails with EXPR_DATE_PARSE_FAILED
  • FORMATDATE(PARSEDATE('01.01.2027 23:59:59', 'dd.MM.yyyy HH:mm:ss'), 'dd.MM.yyyy HH:mm:ss')
    • result: "01.01.2027 23:59:59"

FORMATDATE​

FORMATDATE(date: a date/time, pattern: text) -> text

Renders a date/time as text using an enumerated pattern (yyyy, MM, dd, HH, mm, ss and literal separators), in the date/time's own timezone. Fails if the pattern uses anything outside the token set.

Examples:

  • FORMATDATE(DATE(2027, 1, 31), 'dd.MM.yyyy')
    • result: "31.01.2027"
  • FORMATDATE(DATE(2027, 1, 31), 'QQQQ')
    • fails with EXPR_INVALID_DATE_PATTERN