Dates

library

Formats, shifts and compares dates that are passed around as text. Patterns use Joda-Time letters: `yyyy` year, `MM` month, `dd` day, `HH` hour (0-23), `hh` hour (1-12) with `a` for AM/PM, `mm` minutes, `ss` seconds, `EEEE` day name, `MMMM` month name, `Z` zone offset; put literal letters in single quotes (`yyyy-MM-dd'T'HH:mm`). A date without a time is midnight in the time zone of the agent. Day and month names follow the language set with `Dates.locale`, by default that of the agent. When dates are shifted the order is days, weeks, months, years, and a day that does not exist in the target month moves to the end of that month (31-01-2024 plus one month is 29-02-2024). A date that does not fit its pattern, or does not exist (31-02-2024), throws.

Kind Library, a global in every script
Category Utilities
Functions 7

Functions

today string Returns today's date, and optionally the time, formatted as text, in the time zone of the agent.
format string Converts a date from one pattern to another, optionally shifting it on the way.
yearsBetween number Returns the number of complete years from the first date to the second.
monthsBetween number Returns the number of complete months from the first date to the second.
daysBetween number Returns the number of complete days from the first date to the second.
locale self Sets the language used for day and month names, when parsing and when formatting, for all later calls of this library.
with string Sets parts of a date to fixed values and returns the date in the same pattern.

`today()`

Dates.today()→stringDates.today(pattern: string)→stringDates.today(pattern: string, day: number, week: number, month: number, year: number)→string

Returns today's date, and optionally the time, formatted as text, in the time zone of the agent. Without arguments the pattern is `dd-MM-yyyy`. Five arguments shift the date by a number of days, weeks, months and years (negative numbers go back; pass 0 to skip one). Use exactly 0, 1 or 5 arguments: with 2, 3 or 4 arguments only the pattern is used and the shifts are silently ignored.

Parameters

pattern string optional: Output pattern, for example `yyyy-MM-dd HH:mm`
day number optional: Days to add (negative to subtract)
week number optional: Weeks to add (negative to subtract)
month number optional: Months to add (negative to subtract)
year number optional: Years to add (negative to subtract)

Returns

string Today's date in the requested pattern

Example runs in CI

print(Dates.today("yyyy-MM-dd"))
print(Dates.format("31-12-2024", "dd-MM-yyyy", "yyyy/MM/dd"))
print(Dates.daysBetween("01-01-2024", "31-01-2024"))

`format()`

Dates.format(date: string, from: string, to: string)→stringDates.format(date: string, from: string, to: string, day: number, week: number, month: number, year: number)→string

Converts a date from one pattern to another, optionally shifting it on the way. Seven arguments shift the date by days, weeks, months and years (negative numbers go back; 0 skips one). Use exactly 3 or 7 arguments: with 4, 5 or 6 arguments the shifts are silently ignored. Throws when the date does not fit the `from` pattern.

Parameters

date string: The date as text
from string: Pattern the date is written in
to string: Pattern of the result
day number optional: Days to add (negative to subtract)
week number optional: Weeks to add (negative to subtract)
month number optional: Months to add (negative to subtract)
year number optional: Years to add (negative to subtract)

Returns

string The date in the `to` pattern

Example runs in CI

print(Dates.format("31-01-2024", "dd-MM-yyyy", "yyyy/MM/dd"))
print(Dates.format("31-01-2024", "dd-MM-yyyy", "dd-MM-yyyy", 0, 0, 1, 0))

`yearsBetween()`

Dates.yearsBetween(date1: string, date2: string)→number

Returns the number of complete years from the first date to the second. The result is negative when the second date is earlier. Both dates must be written as `dd-MM-yyyy`; other formats throw.

Parameters

date1 string: First date as `dd-MM-yyyy`
date2 string: Second date as `dd-MM-yyyy`

Returns

number Whole years, negative when the second date is earlier

`monthsBetween()`

Dates.monthsBetween(date1: string, date2: string)→number

Returns the number of complete months from the first date to the second. The result is negative when the second date is earlier. Both dates must be written as `dd-MM-yyyy`; other formats throw.

Parameters

date1 string: First date as `dd-MM-yyyy`
date2 string: Second date as `dd-MM-yyyy`

Returns

number Whole months, negative when the second date is earlier

`daysBetween()`

Dates.daysBetween(date1: string, date2: string)→number

Returns the number of complete days from the first date to the second. The result is negative when the second date is earlier. Both dates must be written as `dd-MM-yyyy`; other formats throw.

Parameters

date1 string: First date as `dd-MM-yyyy`
date2 string: Second date as `dd-MM-yyyy`

Returns

number Whole days, negative when the second date is earlier

`locale()`

Dates.locale(value: string)→self

Sets the language used for day and month names, when parsing and when formatting, for all later calls of this library. Only a plain language code works (`nl`, `en`, `de`, `fr`): a value like `nl-NL` or `nl_NL` is accepted but does not select a language, so names stay in English. An empty value goes back to the language of the agent.

Parameters

value string: Language code, like `nl` or `en`

Returns

self chainable The library itself, so calls can be chained.

Example runs in CI

Dates.locale("nl")
print(Dates.format("01-03-2024", "dd-MM-yyyy", "EEEE d MMMM yyyy"))

`with()`

Dates.with(pattern: string, date: string, day: number, week: number, month: number, year: number)→string

Sets parts of a date to fixed values and returns the date in the same pattern. Unlike the shifting arguments of `Dates.format`, the numbers here are the new values (day 1 means the first of the month); 0 keeps the current value. The parts are applied in this order: day of the month, ISO week of the year, month, year. A part that does not exist for the date at that moment (day 31 in a 30-day month, month 13) throws, and a day that is valid when set can still move to the end of the month when the month is changed afterwards. All six arguments are required. Throws when the date does not fit the pattern.

Parameters

pattern string: Pattern of the date, also used for the result, for example `dd-MM-yyyy`
date string: The date as text
day number: Day of the month to set (1-31), 0 to keep it
week number: ISO week of the year to set (1-53), 0 to keep it
month number: Month to set (1-12), 0 to keep it
year number: Year to set, 0 to keep it

Returns

string The changed date, written in `pattern`

Example runs in CI

print(Dates.with("dd-MM-yyyy", "15-03-2024", 1, 0, 0, 0))   -- first of the month
print(Dates.with("dd-MM-yyyy", "15-03-2024", 0, 0, 12, 2030))