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 (likeIso.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
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
Name | Type | Description |
---|---|---|
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
an Iso.ZonedDateTime
string representing the current system date, time, time zone, and time zone offset.
Defined in
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
fromEpochMilliseconds
โธ fromEpochMilliseconds(epochMilliseconds
, timeZone
): ZonedDateTime
Parameters
Name | Type |
---|---|
epochMilliseconds | number |
timeZone | string |
Returns
Defined in
isValid
โธ isValid(zonedDateTime
): zonedDateTime is ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | unknown |
Returns
zonedDateTime is ZonedDateTime
Defined in
assertIsValid
โธ assertIsValid(zonedDateTime
): asserts zonedDateTime is ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | unknown |
Returns
asserts zonedDateTime is ZonedDateTime
Defined in
getTimeZone
โธ getTimeZone(zonedDateTime
): string
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
string
Defined in
getYear
โธ getYear(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getMonth
โธ getMonth(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getDay
โธ getDay(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getHour
โธ getHour(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getMinute
โธ getMinute(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getSecond
โธ getSecond(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getMillisecond
โธ getMillisecond(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getEpochSeconds
โธ getEpochSeconds(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getEpochMilliseconds
โธ getEpochMilliseconds(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getDayOfWeek
โธ getDayOfWeek(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getDayOfYear
โธ getDayOfYear(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getWeekOfYear
โธ getWeekOfYear(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getHoursInDay
โธ getHoursInDay(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getDaysInMonth
โธ getDaysInMonth(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
getDaysInYear
โธ getDaysInYear(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
inLeapYear
โธ inLeapYear(zonedDateTime
): boolean
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
boolean
Defined in
getOffset
โธ getOffset(zonedDateTime
): string
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
string
Defined in
getOffsetMilliseconds
โธ getOffsetMilliseconds(zonedDateTime
): number
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
number
Defined in
with
โธ with(zonedDateTime
, zonedDateTimeLike
, options?
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
zonedDateTimeLike | Object |
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
Defined in
withDate
โธ withDate(zonedDateTime
, date
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
date | Date | DateSlots |
Returns
Defined in
withTime
โธ withTime(zonedDateTime
, time
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
time | Time | Partial <TimeSlots > |
Returns
Defined in
withTimeZone
โธ withTimeZone(zonedDateTime
, timeZone
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
timeZone | string |
Returns
Defined in
add
โธ add(zonedDateTime
, temporalDurationLike
, options?
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
temporalDurationLike | Duration | { years? : number ; months? : number ; weeks? : number ; days? : number ; hours? : number ; minutes? : number ; seconds? : number ; milliseconds? : number } |
options? | Object |
options.overflow? | TemporalOverflow |
Returns
Defined in
subtract
โธ subtract(zonedDateTime
, temporalDurationLike
, options?
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
temporalDurationLike | Duration | { years? : number ; months? : number ; weeks? : number ; days? : number ; hours? : number ; minutes? : number ; seconds? : number ; milliseconds? : number } |
options? | Object |
options.overflow? | TemporalOverflow |
Returns
Defined in
until
โธ until(zonedDateTime
, other
, options?
): Duration
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
other | ZonedDateTime |
options? | Object |
options.largestUnit? | TemporalSingularUnit | TemporalPluralUnit | "auto" |
options.smallestUnit? | TemporalSingularUnit | TemporalPluralUnit |
options.roundingIncrement? | number |
options.roundingMode? | TemporalRoundingMode |
Returns
Defined in
since
โธ since(zonedDateTime
, other
, options?
): Duration
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
other | ZonedDateTime |
options? | Object |
options.largestUnit? | TemporalSingularUnit | TemporalPluralUnit | "auto" |
options.smallestUnit? | TemporalSingularUnit | TemporalPluralUnit |
options.roundingIncrement? | number |
options.roundingMode? | TemporalRoundingMode |
Returns
Defined in
types/IZonedDateTimeFns.ts:109
round
โธ round(zonedDateTime
, options
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
options | Object |
options.smallestUnit | "day" | "hour" | "minute" | "second" | "millisecond" |
options.roundingIncrement? | number |
options.roundingMode? | TemporalRoundingMode |
Returns
Defined in
types/IZonedDateTimeFns.ts:119
equals
โธ equals(zonedDateTime
, other
): boolean
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
other | ZonedDateTime |
Returns
boolean
Defined in
types/IZonedDateTimeFns.ts:127
startOfDay
โธ startOfDay(zonedDateTime
): ZonedDateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Defined in
types/IZonedDateTimeFns.ts:128
toInstant
โธ toInstant(zonedDateTime
): Instant
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Defined in
types/IZonedDateTimeFns.ts:129
toDate
โธ toDate(zonedDateTime
): Date
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Defined in
types/IZonedDateTimeFns.ts:130
toTime
โธ toTime(zonedDateTime
): Time
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Defined in
types/IZonedDateTimeFns.ts:131
toDateTime
โธ toDateTime(zonedDateTime
): DateTime
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Defined in
types/IZonedDateTimeFns.ts:132
toYearMonth
โธ toYearMonth(zonedDateTime
): YearMonth
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Defined in
types/IZonedDateTimeFns.ts:133
toMonthDay
โธ toMonthDay(zonedDateTime
): MonthDay
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Defined in
types/IZonedDateTimeFns.ts:134
getFields
โธ getFields(zonedDateTime
): Object
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
Object
Name | Type |
---|---|
day | number |
hour | number |
millisecond | number |
minute | number |
month | number |
second | number |
year | number |
offset | string |
timeZone | string |
Defined in
types/IZonedDateTimeFns.ts:135
from
โธ from(item
, options?
): ZonedDateTime
Parameters
Name | Type |
---|---|
item | any |
options? | Object |
options.overflow? | TemporalOverflow |
options.disambiguation? | TemporalDisambiguation |
options.offset? | TemporalOffset |
Returns
Defined in
types/IZonedDateTimeFns.ts:146
compare
โธ compare(one
, two
): number
Parameters
Name | Type |
---|---|
one | ZonedDateTime |
two | ZonedDateTime |
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:
Unit | Pattern | Result examples | Notes |
---|---|---|---|
Era | G..GGG | AD, BC | |
GGGG | Anno Domini, Before Christ | 1 | |
GGGGG | A, B | ||
Calendar year | y | 44, 1, 1900, 2017 | 4 |
yo | 44th, 1st, 0th, 17th | 4,5 | |
yy | 44, 01, 00, 17 | 4 | |
yyy | 044, 001, 1900, 2017 | 4 | |
yyyy | 0044, 0001, 1900, 2017 | 4 | |
yyyyy | ... | 2,4 | |
Extended year | u | -43, 0, 1, 1900, 2017 | 4 |
uu | -43, 01, 1900, 2017 | 4 | |
uuu | -043, 001, 1900, 2017 | 4 | |
uuuu | -0043, 0001, 1900, 2017 | 4 | |
uuuuu | ... | 2,4 | |
Quarter | Q | 1, 2, 3, 4 | |
Qo | 1st, 2nd, 3rd, 4th | 5 | |
01, 02, 03, 04 | |||
QQQ | Q1, Q2, Q3, Q4 | ||
QQQQ | 1st quarter, 2nd quarter, ... | 1 | |
QQQQQ | 1, 2, 3, 4 | 3 | |
Month | M | 1, 2, ..., 12 | |
Mo | 1st, 2nd, ..., 12th | 5 | |
MM | 01, 02, ..., 12 | ||
MMM | Jan, Feb, ..., Dec | ||
MMMM | January, February, ..., December | 1 | |
MMMMM | J, F, ..., D | ||
ISO week of year | I | 1, 2, ..., 53 | 5 |
Io | 1st, 2nd, ..., 53th | 5 | |
II | 01, 02, ..., 53 | 5 | |
Day of month | d | 1, 2, ..., 31 | |
do | 1st, 2nd, ..., 31st | 5 | |
dd | 01, 02, ..., 31 | ||
ISO day of week | i | 1, 2, 3, ..., 7 | 5 |
io | 1st, 2nd, ..., 7th | 5 | |
ii | 01, 02, ..., 07 | 5 | |
iii | Mon, Tue, Wed, ..., Sun | 5 | |
iiii | Monday, Tuesday, ..., Sunday | 1,5 | |
iiiii | M, T, W, T, F, S, S | 5 | |
iiiiii | Mo, Tu, We, Th, Fr, Sa, Su | 5 | |
AM, PM | a..aa | AM, PM | |
aaa | am, pm | ||
aaaa | a.m., p.m. | 1 | |
aaaaa | a, p | ||
AM, PM, noon, midnight | b..bb | AM, PM, noon, midnight | |
bbb | am, pm, noon, midnight | ||
bbbb | a.m., p.m., noon, midnight | 1 | |
bbbbb | a, p, n, mi | ||
Flexible day period | B..BBB | at night, in the morning, ... | |
BBBB | at night, in the morning, ... | 1 | |
BBBBB | at night, in the morning, ... | ||
Hour [1-12] | h | 1, 2, ..., 11, 12 | |
ho | 1st, 2nd, ..., 11th, 12th | 5 | |
hh | 01, 02, ..., 11, 12 | ||
Hour [0-23] | H | 0, 1, 2, ..., 23 | |
Ho | 0th, 1st, 2nd, ..., 23rd | 5 | |
HH | 00, 01, 02, ..., 23 | ||
Hour [0-11] | K | 1, 2, ..., 11, 0 | |
Ko | 1st, 2nd, ..., 11th, 0th | 5 | |
KK | 01, 02, ..., 11, 00 | ||
Hour [1-24] | k | 24, 1, 2, ..., 23 | |
ko | 24th, 1st, 2nd, ..., 23rd | 5 | |
kk | 24, 01, 02, ..., 23 | ||
Minute | m | 0, 1, ..., 59 | |
mo | 0th, 1st, ..., 59th | 5 | |
mm | 00, 01, ..., 59 | ||
Second | s | 0, 1, ..., 59 | |
so | 0th, 1st, ..., 59th | 5 | |
ss | 00, 01, ..., 59 | ||
Fraction of second | S | 0, 1, ..., 9 | |
SS | 00, 01, ..., 99 | ||
SSS | 000, 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, +123456 | 1 | |
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:00 | 1 | |
xxxx | -0800, +0530, +0000, +123456 | ||
xxxxx | -08:00, +05:30, +00:00, +12:34:56 | ||
Timezone (GMT) | O...OOO | GMT-8, GMT+5:30, GMT+0 | |
OOOO | GMT-08:00, GMT+05:30, GMT+00:00 | 1 | |
Timezone (specific non-locat.) | z...zzz | CST, CST, CST | |
zzzz | Central Standard Time | 1 | |
Long localized date | P | 04/29/1453 | 5 |
PP | Apr 29, 1453 | 5 | |
PPP | April 29th, 1453 | 5 | |
PPPP | Friday, April 29th, 1453 | 1,5 | |
Long localized time | p | 12:00 AM | 5 |
pp | 12:00:00 AM | 5 | |
ppp | 12:00:00 AM CDT | 5 | |
pppp | 12:00:00 AM Central Daylight Time | 1,5 | |
Combination of date and time | Pp | 04/29/1453, 12:00 AM | 5 |
PPpp | Apr 29, 1453, 12:00:00 AM | 5 | |
PPPppp | April 29th, 1453 at ... | 5 | |
PPPPpppp | Friday, April 29th, 1453 at ... | 1,5 |
Notes:
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'
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'
QQQQQ
could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.The main difference between
y
andu
patterns are B.C. years:Year y
u
AC 1 1 1 BC 1 1 0 BC 2 2 -1 Also
yy
always returns the last two digits of a year, whileuu
pads single digit years to 2 characters and returns other years unchanged:Year yy
uu
1 01 01 14 14 14 376 76 376 1453 53 1453 These patterns are not in the Unicode Technical Standard #35:
i
: ISO day of weekI
: ISO week of yearo
: ordinal number modifierP
: long localized datep
: 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
Name | Type | Description |
---|---|---|
zonedDateTime | ZonedDateTime | the original date |
format | string | the string of tokens |
Returns
string
the formatted date string
Defined in
types/IZonedDateTimeFns.ts:335
chain
โธ chain(zonedDateTime
): IZonedDateTimeChain
Parameters
Name | Type |
---|---|
zonedDateTime | ZonedDateTime |
Returns
IZonedDateTimeChain