Skip to main content

ZonedDateTime

ฦฌ ZonedDateTime: Format["YYYY-MM-DDThh:mm-ss[.sss]+00:00[TimeZoneName]"] & string

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.

Defined in

iso-types.ts:57

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

NameTypeDescription
timeZone?stringThe 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.

Defined in

types/IZonedDateTimeFns.ts:18


currentTimeZone

โ–ธ currentTimeZone(): 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.

Defined in

types/IZonedDateTimeFns.ts:24


fromEpochMilliseconds

โ–ธ fromEpochMilliseconds(epochMilliseconds, timeZone): ZonedDateTime

Parameters

NameType
epochMillisecondsnumber
timeZonestring

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:25


isValid

โ–ธ isValid(zonedDateTime): zonedDateTime is ZonedDateTime

Parameters

NameType
zonedDateTimeunknown

Returns

zonedDateTime is ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:26


assertIsValid

โ–ธ assertIsValid(zonedDateTime): asserts zonedDateTime is ZonedDateTime

Parameters

NameType
zonedDateTimeunknown

Returns

asserts zonedDateTime is ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:27


getTimeZone

โ–ธ getTimeZone(zonedDateTime): string

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

string

Defined in

types/IZonedDateTimeFns.ts:28


getYear

โ–ธ getYear(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:29


getMonth

โ–ธ getMonth(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:30


getDay

โ–ธ getDay(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:31


getHour

โ–ธ getHour(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:32


getMinute

โ–ธ getMinute(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:33


getSecond

โ–ธ getSecond(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:34


getMillisecond

โ–ธ getMillisecond(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:35


getEpochSeconds

โ–ธ getEpochSeconds(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:36


getEpochMilliseconds

โ–ธ getEpochMilliseconds(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:37


getDayOfWeek

โ–ธ getDayOfWeek(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:38


getDayOfYear

โ–ธ getDayOfYear(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:39


getWeekOfYear

โ–ธ getWeekOfYear(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:40


getHoursInDay

โ–ธ getHoursInDay(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:41


getDaysInMonth

โ–ธ getDaysInMonth(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:42


getDaysInYear

โ–ธ getDaysInYear(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:43


inLeapYear

โ–ธ inLeapYear(zonedDateTime): boolean

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

boolean

Defined in

types/IZonedDateTimeFns.ts:44


getOffset

โ–ธ getOffset(zonedDateTime): string

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

string

Defined in

types/IZonedDateTimeFns.ts:45


getOffsetMilliseconds

โ–ธ getOffsetMilliseconds(zonedDateTime): number

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:46


with

โ–ธ with(zonedDateTime, zonedDateTimeLike, options?): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime
zonedDateTimeLikeObject
zonedDateTimeLike.day?number
zonedDateTimeLike.hour?number
zonedDateTimeLike.millisecond?number
zonedDateTimeLike.minute?number
zonedDateTimeLike.month?number
zonedDateTimeLike.second?number
zonedDateTimeLike.year?number
options?Object
options.overflow?TemporalOverflow
options.disambiguation?TemporalDisambiguation
options.offset?TemporalOffset

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:47


withDate

โ–ธ withDate(zonedDateTime, date): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime
dateDate | DateSlots

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:64


withTime

โ–ธ withTime(zonedDateTime, time): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime
timeTime | Partial<TimeSlots>

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:65


withTimeZone

โ–ธ withTimeZone(zonedDateTime, timeZone): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime
timeZonestring

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:66


add

โ–ธ add(zonedDateTime, temporalDurationLike, options?): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime
temporalDurationLikeDuration | { years?: number ; months?: number ; weeks?: number ; days?: number ; hours?: number ; minutes?: number ; seconds?: number ; milliseconds?: number }
options?Object
options.overflow?TemporalOverflow

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:67


subtract

โ–ธ subtract(zonedDateTime, temporalDurationLike, options?): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime
temporalDurationLikeDuration | { years?: number ; months?: number ; weeks?: number ; days?: number ; hours?: number ; minutes?: number ; seconds?: number ; milliseconds?: number }
options?Object
options.overflow?TemporalOverflow

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:83


until

โ–ธ until(zonedDateTime, other, options?): Duration

Parameters

NameType
zonedDateTimeZonedDateTime
otherZonedDateTime
options?Object
options.largestUnit?TemporalSingularUnit | TemporalPluralUnit | "auto"
options.smallestUnit?TemporalSingularUnit | TemporalPluralUnit
options.roundingIncrement?number
options.roundingMode?TemporalRoundingMode

Returns

Duration

Defined in

types/IZonedDateTimeFns.ts:99


since

โ–ธ since(zonedDateTime, other, options?): Duration

Parameters

NameType
zonedDateTimeZonedDateTime
otherZonedDateTime
options?Object
options.largestUnit?TemporalSingularUnit | TemporalPluralUnit | "auto"
options.smallestUnit?TemporalSingularUnit | TemporalPluralUnit
options.roundingIncrement?number
options.roundingMode?TemporalRoundingMode

Returns

Duration

Defined in

types/IZonedDateTimeFns.ts:109


round

โ–ธ round(zonedDateTime, options): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime
optionsObject
options.smallestUnit"day" | "hour" | "minute" | "second" | "millisecond"
options.roundingIncrement?number
options.roundingMode?TemporalRoundingMode

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:119


equals

โ–ธ equals(zonedDateTime, other): boolean

Parameters

NameType
zonedDateTimeZonedDateTime
otherZonedDateTime

Returns

boolean

Defined in

types/IZonedDateTimeFns.ts:127


startOfDay

โ–ธ startOfDay(zonedDateTime): ZonedDateTime

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:128


toInstant

โ–ธ toInstant(zonedDateTime): Instant

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

Instant

Defined in

types/IZonedDateTimeFns.ts:129


toDate

โ–ธ toDate(zonedDateTime): Date

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

Date

Defined in

types/IZonedDateTimeFns.ts:130


toTime

โ–ธ toTime(zonedDateTime): Time

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

Time

Defined in

types/IZonedDateTimeFns.ts:131


toDateTime

โ–ธ toDateTime(zonedDateTime): DateTime

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

DateTime

Defined in

types/IZonedDateTimeFns.ts:132


toYearMonth

โ–ธ toYearMonth(zonedDateTime): YearMonth

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

YearMonth

Defined in

types/IZonedDateTimeFns.ts:133


toMonthDay

โ–ธ toMonthDay(zonedDateTime): MonthDay

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

MonthDay

Defined in

types/IZonedDateTimeFns.ts:134


getFields

โ–ธ getFields(zonedDateTime): Object

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

Object

NameType
daynumber
hournumber
millisecondnumber
minutenumber
monthnumber
secondnumber
yearnumber
offsetstring
timeZonestring

Defined in

types/IZonedDateTimeFns.ts:135


from

โ–ธ from(item, options?): ZonedDateTime

Parameters

NameType
itemany
options?Object
options.overflow?TemporalOverflow
options.disambiguation?TemporalDisambiguation
options.offset?TemporalOffset

Returns

ZonedDateTime

Defined in

types/IZonedDateTimeFns.ts:146


compare

โ–ธ compare(one, two): number

Parameters

NameType
oneZonedDateTime
twoZonedDateTime

Returns

number

Defined in

types/IZonedDateTimeFns.ts:154


format

โ–ธ format(zonedDateTime, format): string

summary Format the ZonedDateTime.

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'

Parameters

NameTypeDescription
zonedDateTimeZonedDateTimethe original date
formatstringthe string of tokens

Returns

string

the formatted date string

Defined in

types/IZonedDateTimeFns.ts:335


chain

โ–ธ chain(zonedDateTime): IZonedDateTimeChain

Parameters

NameType
zonedDateTimeZonedDateTime

Returns

IZonedDateTimeChain

Defined in

types/IZonedDateTimeFns.ts:336