Skip to content

DateTime

Type

The DateTime type is used to represent variables that represent date and time with mandatory timezone.

A DateTime variable can be initialized or mutated by assigning it a DateTime literal represented according to the ISO 8601 standard (format yyyy-mm-ddThh:MM[:ss[.mmm]]Z or yyyy-mm-ddThh:MM[:ss[.mmm]‌‌‌‌‌‌‌‌‌‌‌‌‌]{+|-}hh:MM, e.g.

var newYearInSwitzerland = 2019-01-01T00:00+01:00;
var newYearInLondon = 2019-01-01T00:00:00.000Z;

Alternatively a DateTime value can be constructed using dateTimeOf.

Methods

nano

<function> Gets the nano-of-second.

Receiver

DateTime

Returns

Number - the nano-of-second

Usage
2019-07-01T13:04:05.678+01:00.nano() == 678000000

second

<function> Gets the second-of-minute.

Receiver

DateTime

Returns

Number - the second-of-minute (0-59)

Usage
2019-07-01T13:04:05.678+01:00.second() == 5

minute

<function> Gets the minute-of-hour.

Receiver

DateTime

Returns

Number - the minute-of-hour(0-59)

Usage
2019-07-01T13:04:05.678+01:00.minute() == 4

day

<function> Gets the day-of-month.

Receiver

DateTime

Returns

Number - day-of-month (1-31)

Usage
2019-07-01T13:04:05.678+01:00.day() == 1

hour

<function> Gets the hour-of-day.

Receiver

DateTime

Returns

Number - the hour-of-day (0-23)

Usage
2019-07-01T13:04:05.678+01:00.hour() == 13

month

<function> Gets the month-of-year.

Receiver

DateTime

Returns

Number - month-of-year (1-12)

Usage
2019-07-01T13:04:05.678+01:00.month() == 7

year

<function> Gets the year.

Receiver

DateTime

Returns

Number - the year (e.g., 1999)

Usage
2019-07-01T13:04:05.678+01:00.year() == 2019

startOfDay

<function> Returns a copy of this DateTime with the time set to the first occurrence of midnight. Retains the date and time zone.

Receiver

DateTime

Returns

DateTime - a copy of this DateTime with the time set to the first occurrence of midnight

Usage
2018-02-28T15:30:00Z.startOfDay() == 2018-02-28T00:00:00Z

firstDayOfMonth

<function> Returns a DateTime value with the date set to the first day of the month. Retains the time and time zone.

Receiver

DateTime

Returns

DateTime - a DateTime value with the date set to the first day of the month

Usage
2018-02-28T15:30:00Z.firstDayOfMonth() == 2018-02-01T15:30:00Z

firstDayOfYear

<function> Returns a DateTime value with the date set to the first day of the year. Retains the time and time zone.

Receiver

DateTime

Returns

DateTime - a DateTime value with the date set to the first day of the year

Usage
2018-02-28T15:30:00Z.firstDayOfYear() == 2018-01-01T15:30:00Z

lastDayOfMonth

<function> Returns a DateTime value with the date set to the last day of the month. Retains the time and time zone.

Receiver

DateTime

Returns

DateTime - a DateTime value with the date set to the last day of the month

Usage
2020-02-10T15:30:00Z.lastDayOfMonth() == 2020-02-29T15:30:00Z

lastDayOfYear

<function> Returns a DateTime value with the date set to the last day of the year. Retains the time and time zone.

Receiver

DateTime

Returns

DateTime - a DateTime value with the date set to the first day of the year

Usage
2018-02-28T15:30:00Z.lastDayOfYear() == 2018-12-31T15:30:00Z

durationUntil

<function> Returns the Duration until another DateTime. The result will be negative if the other date is in the past.

Receiver

DateTime

Arguments

date - DateTime - other DateTime to compare against

Returns

Duration - duration until the provided other DateTime

Usage
2018-01-01T12:00:00Z.durationUntil(2018-01-01T13:00:00Z) == hours(1)

isAfter

<function> Determine whether this DateTime is after another DateTime (or equal if inclusive is true).

Receiver

DateTime

Arguments

date - DateTime - other DateTime to compare against

inclusive - Boolean - return true if both are at the same point in time

Returns

Boolean - whether this date is after the provided date

Usage

(2019-01-01T00:00Z).isAfter(2018-12-01T00:00Z, false) == true

(2019-07-01T00:00Z).isAfter(2019-07-01T00:00+01:00, false) == true

(2019-07-02T01:00+01:00).isAfter(2019-07-02T00:00Z, true) == true

isBefore

<function> Determine whether this DateTime is before another DateTime (or equal if inclusive is true).

Receiver

DateTime

Arguments

date - DateTime - other DateTime to compare against

inclusive - Boolean - return true if both are at the same point in time

Returns

Boolean - whether this date is before the provided date

Usage

(2019-07-01T00:00Z).isBefore(2018-12-01T00:00Z, false) == false

(2019-07-01T00:00Z).isBefore(2019-07-01T00:00+01:00, false) == false

(2019-07-02T00:00Z).isBefore(2019-07-02T01:00+01:00, true) == true

isBetween

<function> Determine whether this DateTime falls within the range of a lower and upper bound (or equal to either if inclusive is true).

Receiver

DateTime

Arguments

low - DateTime - lower bound of the range

high - DateTime - upper bound of the range

inclusive - Boolean - return true if equal to either

Returns

Boolean - whether this date is before the provided date

Usage

(2019-07-01T00:00Z).isBetween(2018-12-01T00:00Z, 2019-05-31T00:00+02:00, false) == false

(2019-07-01T00:00Z).isBetween(2019-07-01T01:00+01:00, 2020-01-01T00:00Z, false) == false

(2019-07-02T00:00Z).isBetween(2019-07-02T01:00+01:00, 2020-01-01T00:00Z, true) == true

plus

<function> Returns a date with the Duration or Period added to it. Particularly care needs to be taken regarding the difference between Period and Duration when dealing with daylight saving time, in which cases adding a duration of hours(24) and a period of days(1) will have different results.

Receiver

DateTime

Arguments

delta - Temporal - the Period or Duration to add

Returns

DateTime - a date with the Duration or Period added to it

Usage

2018-01-01T12:00:00Z.plus(hours(1)) == 2018-01-01T13:00:00Z

// Period and Duration behave differently in situations involving daylight saving.
var paris = dateTimeOf(2019, 3, 30, 15, 0, valueOfZoneId(ZoneId.EUROPE_PARIS));

var parisD = paris + hours(24);
var parisP = paris + days(1);

// You might expect `parisP.hour()` and`parisD.hour()`
// to both return 15, i.e. the same hour value as used when
// creating the original `paris` value. However, France
// switched to summer time on the morning of March 31st,
// So adding a day won't affect the hour value but adding
// 24 hours will (as the clocks skipped forward an hour on the
// morning of the 31st):
test.assertTrue(
    parisP.hour() == 15 && parisD.hour() == 16
);

// This method is also available as an infix operator, `+`:
2018-01-01T12:00:00Z + hours(1) == 2018-01-01T13:00:00Z

minus

<function> Returns a date with the Duration or Period subtracted from it. Particularly care needs to be taken regarding the difference between Period and Duration when dealing with daylight saving time, in which cases adding a duration of hours(24) and a period of days(1) will have different results.

Receiver

DateTime

Arguments

delta - Temporal - the Period or Duration to subtract

Returns

DateTime - a date with the Duration or Period subtracted from it

Usage

2018-01-01T12:00:00Z.minus(hours(1)) == 2018-01-01T11:00:00Z

//  This method is also available as an infix operator `-`:
2018-01-01T12:00:00Z - hours(1) == 2018-01-01T11:00:00Z

toLocalDate

<function> Returns the date part of a DateTime.

Receiver

DateTime

Returns

LocalDate - a LocalDate that represents the date part of the DateTime

Usage
2021-02-08T15:34:00Z.toLocalDate() == localDateOf(2021, 02, 08)

withZoneSameInstant

<function> Returns a DateTime value that corresponds to the same instant in time in the given time zone. This means the wall clock times are different, but they represent the same instance in time.

Receiver

DateTime

Arguments

zoneId - Text - the time zone

Returns

DateTime - a DateTime value that corresponds to the same instant in time in the given time zone

Usage

var paris = dateTimeOf(2019, 1, 1, 15, 0, valueOfZoneId(ZoneId.EUROPE_PARIS));
var ny = paris.withZoneSameInstant(valueOfZoneId(ZoneId.AMERICA_NEW_YORK));
// Note that `ny.hour()` will be 9, i.e. 6 hours earlier that in Paris:
test.assertEquals(9, ny.hour());
// While `ny` and `paris` correspond to the same instant in time,
// `ny != paris` as they have different time zones.
test.assertTrue(isSameInstant(paris, ny));
test.assertEquals(valueOfZoneId(ZoneId.AMERICA_NEW_YORK), ny.zoneId());

// You can use `isBefore` and `isAfter` with `DateTime` values in different
// time zones but if you want to determine if two `DateTime` values correspond
// to the same instant in time then you need to compare them using
// the same time zone for both, e.g. like so:
function isSameInstant(d1: DateTime, d2: DateTime) ->
    d1 == d2.withZoneSameInstant(d1.zoneId());

withZoneSameLocal

<function> Returns a DateTime value that corresponds to the same time of day in the given time zone. This means the wall clock times are the same, but they represent different instances in time.

Receiver

DateTime

Arguments

zoneId - Text - the time zone

Returns

DateTime - a DateTime value that corresponds to the same time of day in the given time zone

Usage
var paris = dateTimeOf(2019, 1, 1, 15, 0, valueOfZoneId(ZoneId.EUROPE_PARIS));
var ny = paris.withZoneSameLocal(valueOfZoneId(ZoneId.AMERICA_NEW_YORK));
// Note that `ny.hour()` will be 15, i.e. the same wall clock time as in Paris,
// but the times `ny` and `paris` do not correspond to the same instant in time.
test.assertEquals(15, ny.hour());
test.assertEquals(valueOfZoneId(ZoneId.AMERICA_NEW_YORK), ny.zoneId());

zoneId

<function> Gets the zoneId.

Receiver

DateTime

Returns

Text - the zoneId (e.g., "Z")

Usage

(2019-07-01T00:00Z).zoneId() == "Z"

2019-07-01T13:04:05.678+01:00.zoneId() == "+01:00"

Inherited methods

toText

<function> Obtain the Text representation of this.

Receiver

T

Type Arguments

T

Returns

Text - the Text representation of this

Usage

Converts a DateTime to Text. 

(2019-07-01T00:00Z).toText() == "2019-07-01T00:00:00Z"

(2019-07-01T13:04:05.678+01:00).toText() == "2019-07-01T13:04:05.678+01:00"