xtr.datetime¶

The datetime module leverages the ISO-8601 offset date-time format for representing and manipulating date and time, and the ISO-8601 duration format for temporal amounts. The ISO format is the recommendation of the IETF through RFC 3339: Date and Time on the Internet.

atBeginningOfDay¶

atBeginningOfDay(datetime: String): String

Returns the given datetime at midnight.

Example

xtr.datetime.atBeginningOfDay('2020-12-31T23:19:35Z')

'2020-12-31T00:00:00Z'

atBeginningOfHour¶

atBeginningOfHour(datetime: String): String

Returns the given datetime with the minutes and seconds set to zero.

Example

xtr.datetime.atBeginningOfHour('2020-12-31T23:19:35Z')

'2020-12-31T23:00:00Z'

atBeginningOfMonth¶

atBeginningOfMonth(datetime: String): String

Returns the given datetime with the day set to first of the month, and the time set to midnight.

Example

xtr.datetime.atBeginningOfMonth('2020-12-31T23:19:35Z')

'2020-12-01T00:00:00Z'

atBeginningOfWeek¶

atBeginningOfWeek(datetime: String): String

Returns the given datetime with the day set to first of the current week, and the time set to midnight. The week is taken to start on Sunday.

Example

xtr.datetime.atBeginningOfWeek('2020-12-31T23:19:35Z')

'2020-12-27T00:00:00Z'

atBeginningOfYear¶

atBeginningOfYear(datetime: String): String

Returns the given datetime with the day/month set to January 1st, and the time set to midnight.

Example

xtr.datetime.atBeginningOfYear('2020-12-31T23:19:35Z')

'2020-01-01T00:00:00Z'

inOffset¶

inOffset(datetime: String, offset: String): String

Returns the given datetime in the given timezone offset, changing the date and time as appropriate.

Example

xtr.datetime.inOffset('2020-12-31T23:19:35Z', '-08:00')

'2020-12-31T15:19:35-08:00'

compare¶

compare(datetime: String, datetwo: String): Number

Returns:

1 if datetime is after datetwo

-1 if datetime is before datetwo

0 if datetime and datetwo are the same

Example

xtr.datetime.compare('2020-12-31T23:19:35Z','2020-01-01T00:00:00Z')

1

of¶

of(obj: Object[Number|String]): String

Returns the String representation of the date and time given in obj, an Object of the form:

{
    year: Number, month: Number, day: Number,
    hour: Number, minute: Number, second: Number,
    nanosecond: Number, offset: String
}

where all elements are optional; keys outside this form are an error, except dayOfWeek, which is accepted and ignored so that of(toParts(x)) round-trips.

Example

local parts = {
    'year': 2021,
    'offset': '-08:00'
};

xtr.datetime.of(parts)

'2021-01-01T00:00:00-08:00'

between¶

between(datetimeone: String, datetimetwo: String): String

Returns the ISO-8601 duration between datetime1 and datetime2.

Example

local date1 = '2019-09-20T18:53:41.425Z';
local date2 = '2019-09-14T18:53:41.425Z';

xtr.datetime.between(date1, date2)

'-P6D'

format¶

format(datetime: String, outputFormat: String): String

Returns the given datetime formatted in the requested format.

Example

xtr.datetime.format('2019-09-20T18:53:41.425Z', 'yyyy/MM/dd')

'2019/09/20'

isLeapYear¶

isLeapYear(datetime: String): Boolean

Returns a true if datetime is in a leap year, otherwise false.

Example

xtr.datetime.isLeapYear('2019-09-14T18:53:41.425Z')

false

minus¶

minus(datetime: String, duration: String): String

Returns the result of subtracting the specified ISO-8601 duration from the given datetime. Accepts any duration xtr.duration.of can produce, including time-only forms like 'PT2H'; a leading minus sign negates every part of the duration.

Example

xtr.datetime.minus('2019-09-20T18:53:41Z', 'P2D')

'2019-09-18T18:53:41Z'

now¶

now(): String

Returns the current datetime.

Example

xtr.datetime.now()

'2021-01-05T13:09:45.476375-05:00'

parse¶

parse(datetime: String|Number, inputFormat: String): String

Returns an ISO-8601 extended offset date-time from the given datetime using the specified format.

Example

xtr.datetime.parse('12/31/1990 10:10:10', 'MM/dd/yyyy HH:mm:ss')

'1990-12-31T10:10:10Z'

Additionally, developers can parse Unix timestamps by passing 'unix' as the format.

plus¶

plus(datetime: String, duration: String): String

Returns the result of adding the specified ISO-8601 duration to the given datetime. Accepts any duration xtr.duration.of can produce, including time-only forms like 'PT2H'; a leading minus sign negates every part of the duration.

Example

xtr.datetime.plus('2019-09-18T18:53:41Z', 'P2D')

'2019-09-20T18:53:41Z'

toLocalDate¶

toLocalDate(datetime: String): String

Returns the given datetime without time or offset.

Example

xtr.datetime.toLocalDate('2019-07-04T18:53:41Z')

'2019-07-04'

toLocalDateTime¶

toLocalDateTime(datetime: String): String

Returns the given datetime without an offset.

Example

xtr.datetime.toLocalDateTime('2019-07-04T21:00:00Z')

'2019-07-04T21:00:00'

toLocalTime¶

toLocalTime(datetime: String): String

Returns the given datetime without date or offset.

Example

xtr.datetime.toLocalTime('2019-07-04T21:00:00Z')

'21:00:00'

toParts¶

toParts(datetime: String): Object[Number|String]

Returns the constituent parts of the given datetime, as an Object of the form:

{
    year: Number, month: Number, day: Number, dayOfWeek: Number,
    hour: Number, minute: Number, second: Number, nanosecond: Number,
    offset: String
}

day is the day of the month, so that of(toParts(x)) round-trips — of reads the day key as the day of the month. The day of the week is dayOfWeek, 1 (Monday) through 7 (Sunday).

Example

xtr.datetime.toParts('2019-07-10T21:00:00Z')

{
    year: 2019, month: 7, day: 10, dayOfWeek: 3,
    hour: 21, minute: 0, second: 0, nanosecond: 0,
    offset: 'Z'
}

today¶

today(): String

Returns the current day at midnight.

Example

xtr.datetime.today()

Result

'2021-01-05T00:00:00-05:00'

tomorrow¶

tomorrow(): String

Returns the next day at midnight.

Example

xtr.datetime.tomorrow()

Result

'2021-01-06T00:00:00-05:00'

yesterday¶

yesterday(): String

Returns the previous day at midnight.

Example

xtr.datetime.yesterday()

Result

'2021-01-04T00:00:00-05:00'