Skip to main content

An Iso.ZonedDateTime is a timezone-aware date/time type that represents a real event that has happened (or will happen) at a particular instant from the perspective of a particular region on Earth. As the broadest Iso type, Iso.ZonedDateTime can be considered a combination of a Iso.TimeZone, Iso.Instant, and Iso.DateTime.

As the only Iso type that persists a time zone, Iso.ZonedDateTime is optimized for use cases that require a time zone:

  • Arithmetic automatically adjusts for Daylight Saving Time, using the rules defined in RFC 5545 (iCalendar) and adopted in other libraries like moment.js.
  • Creating derived values (e.g. change time to 2:30AM) can avoid worrying that the result will be invalid due to the time zone's DST rules.
  • Functions are available to easily measure attributes like "length of day" or "starting time of day" which may not be the same on all days in all time zones due to DST transitions or political changes to the definitions of time zones.
  • It's easy to flip back and forth between a human-readable representation (like Iso.DateTime) and the UTC timeline (like Iso.Instant) without having to do any work to keep the two in sync.
  • A date/time, an offset, and a time zone are represented in a single string that can be sorted alphabetically by the exact time they happened. This behavior is also helpful for developers who are not sure which of those components will be needed by later readers of this data.
  • Multiple time-zone-sensitive operations can be performed in a chain without having to repeatedly provide the same time zone.

An Iso.ZonedDateTime can be losslessly converted into every other Iso type except Iso.Duration. Iso.Instant, Iso.DateTime, Iso.Date, Iso.Time, Iso.YearMonth, and Iso.MonthDay all carry less information and can be used when complete information is not required.

The Iso.ZonedDateTime functions are a superset of Iso.DateTime functions, which makes it easy to port code back and forth between the two types as needed. Because Iso.DateTime is not aware of time zones, in use cases where the time zone is known it's recommended to use Iso.ZonedDateTime which will automatically adjust for DST and can convert easily to Iso.Instant without having to re-specify the time zone.

now()​

now(timeZone?): ZonedDateTime

This method gets the current date, time, time zone, and time zone offset according to the system settings. Optionally a time zone can be given in which the time is computed, instead of the current system time zone.

Parameters​

timeZone?​

string

The time zone to get the current date and time in as a string. If not given, the current system time zone will be used.

Returns​

ZonedDateTime

an Iso.ZonedDateTime string representing the current system date, time, time zone, and time zone offset.

currentTimeZoneId()​

currentTimeZoneId(): string

This method gets the current system time zone. This will usually be a named IANA time zone, as that is how most people configure their computers.

Returns​

string

a string representing the time zone according to the current system settings.

fromEpochMilliseconds()​

fromEpochMilliseconds(epochMilliseconds, timeZone): ZonedDateTime

Parameters​

epochMilliseconds​

number

timeZone​

string

Returns​

ZonedDateTime

isValid()​

isValid(zonedDateTime): zonedDateTime is ZonedDateTime

Parameters​

zonedDateTime​

unknown

Returns​

zonedDateTime is ZonedDateTime

assertIsValid()​

assertIsValid(zonedDateTime): asserts zonedDateTime is ZonedDateTime

Parameters​

zonedDateTime​

unknown

Returns​

asserts zonedDateTime is ZonedDateTime

getTimeZoneId()​

getTimeZoneId(zonedDateTime): string

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

string

getYear()​

getYear(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getMonth()​

getMonth(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getDay()​

getDay(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getHour()​

getHour(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getMinute()​

getMinute(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getSecond()​

getSecond(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getMillisecond()​

getMillisecond(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getEpochSeconds()​

getEpochSeconds(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getEpochMilliseconds()​

getEpochMilliseconds(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getDayOfWeek()​

getDayOfWeek(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getDayOfYear()​

getDayOfYear(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getWeekOfYear()​

getWeekOfYear(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getHoursInDay()​

getHoursInDay(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getDaysInMonth()​

getDaysInMonth(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

getDaysInYear()​

getDaysInYear(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

inLeapYear()​

inLeapYear(zonedDateTime): boolean

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

boolean

getOffset()​

getOffset(zonedDateTime): string

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

string

getOffsetMilliseconds()​

getOffsetMilliseconds(zonedDateTime): number

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

number

with()​

with(zonedDateTime, zonedDateTimeLike, options?): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

zonedDateTimeLike​

day?​

number

hour?​

number

millisecond?​

number

minute?​

number

month?​

number

second?​

number

year?​

number

options?​

overflow?​

"constrain" | "reject"

disambiguation?​

"reject" | "compatible" | "earlier" | "later"

offset?​

"reject" | "use" | "prefer" | "ignore"

Returns​

ZonedDateTime

withDate()​

withDate(zonedDateTime, date): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

date​

Date | DateSlots

Returns​

ZonedDateTime

withTime()​

withTime(zonedDateTime, time): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

time​

Time | Partial\<TimeSlots>

Returns​

ZonedDateTime

withTimeZone()​

withTimeZone(zonedDateTime, timeZone): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

timeZone​

string

Returns​

ZonedDateTime

add()​

add(zonedDateTime, temporalDurationLike, options?): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

temporalDurationLike​

Duration | { years?: number; months?: number; weeks?: number; days?: number; hours?: number; minutes?: number; seconds?: number; milliseconds?: number; }

options?​

overflow?​

"constrain" | "reject"

Returns​

ZonedDateTime

subtract()​

subtract(zonedDateTime, temporalDurationLike, options?): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

temporalDurationLike​

Duration | { years?: number; months?: number; weeks?: number; days?: number; hours?: number; minutes?: number; seconds?: number; milliseconds?: number; }

options?​

overflow?​

"constrain" | "reject"

Returns​

ZonedDateTime

until()​

until(zonedDateTime, other, options?): Duration

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

options?​

largestUnit?​

LargestUnit\<DateTimeUnit>

smallestUnit?​

SmallestUnit\<DateTimeUnit>

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

Duration

since()​

since(zonedDateTime, other, options?): Duration

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

options?​

largestUnit?​

LargestUnit\<DateTimeUnit>

smallestUnit?​

SmallestUnit\<DateTimeUnit>

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

Duration

round()​

round(zonedDateTime, options): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

options​

smallestUnit​

"day" | TimeUnit

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

ZonedDateTime

equals()​

equals(zonedDateTime, other): boolean

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

Returns​

boolean

isEqual()​

isEqual(zonedDateTime, other): boolean

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

Returns​

boolean

isBefore()​

isBefore(zonedDateTime, other): boolean

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

Returns​

boolean

isAfter()​

isAfter(zonedDateTime, other): boolean

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

Returns​

boolean

isEqualOrBefore()​

isEqualOrBefore(zonedDateTime, other): boolean

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

Returns​

boolean

isEqualOrAfter()​

isEqualOrAfter(zonedDateTime, other): boolean

Parameters​

zonedDateTime​

ZonedDateTime

other​

ZonedDateTime

Returns​

boolean

startOfDay()​

startOfDay(zonedDateTime): ZonedDateTime

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

ZonedDateTime

toInstant()​

toInstant(zonedDateTime): Instant

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

Instant

toDate()​

toDate(zonedDateTime): Date

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

Date

toTime()​

toTime(zonedDateTime): Time

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

Time

toDateTime()​

toDateTime(zonedDateTime): DateTime

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

DateTime

toYearMonth()​

toYearMonth(zonedDateTime): YearMonth

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

YearMonth

toMonthDay()​

toMonthDay(zonedDateTime): MonthDay

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

MonthDay

getFields()​

getFields(zonedDateTime): object

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

object

day​

day: number

hour​

hour: number

millisecond​

millisecond: number

minute​

minute: number

month​

month: number

second​

second: number

year​

year: number

offset​

offset: string

timeZone​

timeZone: string

epochMilliseconds​

epochMilliseconds: number

from()​

from(item, options?): ZonedDateTime

Parameters​

item​

string | Partial\<DateTimeSlots & object>

options?​

overflow?​

"constrain" | "reject"

disambiguation?​

"reject" | "compatible" | "earlier" | "later"

offset?​

"reject" | "use" | "prefer" | "ignore"

Returns​

ZonedDateTime

compare()​

compare(one, two): number

Parameters​

one​

ZonedDateTime

two​

ZonedDateTime

Returns​

number

format()​

format(zonedDateTime, format, options?): string

Parameters​

zonedDateTime​

ZonedDateTime

the original date

format​

string

the string of tokens

options?​

FormatOptions

Returns​

string

the formatted date string

Description​

Return the formatted ZonedDateTime string in the given format.

The characters wrapped between two single quotes characters (') are escaped. Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote. (see the last example)

Format of the string is based on Unicode Technical Standard #35: https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table with a few additions (see note 7 below the table).

Accepted patterns:

UnitPatternResult examplesNotes
EraG..GGGAD, BC
GGGGAnno Domini, Before Christ1
GGGGGA, B
Calendar yeary44, 1, 1900, 20174
yo44th, 1st, 0th, 17th4,5
yy44, 01, 00, 174
yyy044, 001, 1900, 20174
yyyy0044, 0001, 1900, 20174
yyyyy...2,4
Extended yearu-43, 0, 1, 1900, 20174
uu-43, 01, 1900, 20174
uuu-043, 001, 1900, 20174
uuuu-0043, 0001, 1900, 20174
uuuuu...2,4
QuarterQ1, 2, 3, 4
Qo1st, 2nd, 3rd, 4th5
QQ01, 02, 03, 04
QQQQ1, Q2, Q3, Q4
QQQQ1st quarter, 2nd quarter, ...1
QQQQQ1, 2, 3, 43
MonthM1, 2, ..., 12
Mo1st, 2nd, ..., 12th5
MM01, 02, ..., 12
MMMJan, Feb, ..., Dec
MMMMJanuary, February, ..., December1
MMMMMJ, F, ..., D
ISO week of yearI1, 2, ..., 535
Io1st, 2nd, ..., 53th5
II01, 02, ..., 535
Day of monthd1, 2, ..., 31
do1st, 2nd, ..., 31st5
dd01, 02, ..., 31
ISO day of weeki1, 2, 3, ..., 75
io1st, 2nd, ..., 7th5
ii01, 02, ..., 075
iiiMon, Tue, Wed, ..., Sun5
iiiiMonday, Tuesday, ..., Sunday1,5
iiiiiM, T, W, T, F, S, S5
iiiiiiMo, Tu, We, Th, Fr, Sa, Su5
AM, PMa..aaAM, PM
aaaam, pm
aaaaa.m., p.m.1
aaaaaa, p
AM, PM, noon, midnightb..bbAM, PM, noon, midnight
bbbam, pm, noon, midnight
bbbba.m., p.m., noon, midnight1
bbbbba, p, n, mi
Flexible day periodB..BBBat night, in the morning, ...
BBBBat night, in the morning, ...1
BBBBBat night, in the morning, ...
Hour [1-12]h1, 2, ..., 11, 12
ho1st, 2nd, ..., 11th, 12th5
hh01, 02, ..., 11, 12
Hour [0-23]H0, 1, 2, ..., 23
Ho0th, 1st, 2nd, ..., 23rd5
HH00, 01, 02, ..., 23
Hour [0-11]K1, 2, ..., 11, 0
Ko1st, 2nd, ..., 11th, 0th5
KK01, 02, ..., 11, 00
Hour [1-24]k24, 1, 2, ..., 23
ko24th, 1st, 2nd, ..., 23rd5
kk24, 01, 02, ..., 23
Minutem0, 1, ..., 59
mo0th, 1st, ..., 59th5
mm00, 01, ..., 59
Seconds0, 1, ..., 59
so0th, 1st, ..., 59th5
ss00, 01, ..., 59
Fraction of secondS0, 1, ..., 9
SS00, 01, ..., 99
SSS000, 001, ..., 999
SSSS...2
Timezone (ISO-8601 w/ Z)X-08, +0530, Z
XX-0800, +0530, Z
XXX-08:00, +05:30, Z
XXXX-0800, +0530, Z, +1234561
XXXXX-08:00, +05:30, Z, +12:34:56
Timezone (ISO-8601 w/o Z)x-08, +0530, +00
xx-0800, +0530, +0000
xxx-08:00, +05:30, +00:001
xxxx-0800, +0530, +0000, +123456
xxxxx-08:00, +05:30, +00:00, +12:34:56
Timezone (GMT)O...OOOGMT-8, GMT+5:30, GMT+0
OOOOGMT-08:00, GMT+05:30, GMT+00:001
Timezone (specific non-locat.)z...zzzCST, CST, CST
zzzzCentral Standard Time1
Long localized dateP04/29/14535
PPApr 29, 14535
PPPApril 29th, 14535
PPPPFriday, April 29th, 14531,5
Long localized timep12:00 AM5
pp12:00:00 AM5
ppp12:00:00 AM CDT5
pppp12:00:00 AM Central Daylight Time1,5
Combination of date and timePp04/29/1453, 12:00 AM5
PPppApr 29, 1453, 12:00:00 AM5
PPPpppApril 29th, 1453 at ...5
PPPPppppFriday, April 29th, 1453 at ...1,5

Notes:

  1. Any sequence of the identical letters is a pattern, unless it is escaped by the single quote characters (see below). If the sequence is longer than listed in table (e.g. EEEEEEEEEEE) the output will be the same as default pattern for this unit, usually the longest one (in case of ISO weekdays, EEEE). Default patterns for units are marked with "2" in the last column of the table.

    format("2017-11-06", 'MMM') //=> 'Nov'

    format("2017-11-06", 'MMMM') //=> 'November'

    format("2017-11-06", 'MMMMM') //=> 'N'

    format("2017-11-06", 'MMMMMM') //=> 'November'

    format("2017-11-06", 'MMMMMMM') //=> 'November'

  2. Some patterns could be unlimited length (such as yyyyyyyy). The output will be padded with zeros to match the length of the pattern.

    format("2017-11-06", 'yyyyyyyy') //=> '00002017'

  3. QQQQQ could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.

  4. The main difference between y and u patterns are B.C. years:

    Yearyu
    AC 111
    BC 110
    BC 22-1

    Also yy always returns the last two digits of a year, while uu pads single digit years to 2 characters and returns other years unchanged:

    Yearyyuu
    10101
    141414
    37676376
    1453531453

  5. These patterns are not in the Unicode Technical Standard #35:

    • i: ISO day of week
    • I: ISO week of year
    • o: ordinal number modifier
    • P: long localized date
    • p: long localized time
  • Characters are escaped using single quote symbols (').

Example​

// Represent 11 February 2014 in middle-endian format:
var result = format("2014-02-11T00:00:00+00:00[UTC]", 'MM/dd/yyyy')
//=> '02/11/2014'

chain()​

chain(zonedDateTime): IZonedDateTimeChain

Parameters​

zonedDateTime​

ZonedDateTime

Returns​

IZonedDateTimeChain