DateTime

Ƭ DateTime: Format["YYYY-MM-DDThh:mm-ss[.sss]"] & string

An Iso.DateTime represents a calendar date and wall-clock time, with a precision in milliseconds, and without any time zone.

For use cases that require a time zone, especially using arithmetic or other derived values, consider using Iso.ZonedDateTime instead because that type automatically adjusts for Daylight Saving Time. A Iso.DateTime can be converted to a Iso.ZonedDateTime using a Iso.TimeZone.

Iso.Date, Iso.Time, Iso.YearMonth, and Iso.MonthDay all carry less information and should be used when complete information is not required.

A Iso.DateTime can be converted into any of the types mentioned above using conversion methods like toZonedDateTime or toDate.

Because Iso.DateTime does not represent an exact point in time, most date/time use cases are better handled using exact time types like Iso.ZonedDateTime and Iso.Instant. But there are cases where Iso.DateTime is the correct type to use:

Representing timezone-specific events where the time zone is not stored together with the date/time data. In this case, Iso.DateTime is an intermediate step before converting to/from Iso.ZonedDateTime or Iso.Instant using the separate time zone. Examples:
- When the time zone is stored separately in a separate database column or a per-user setting.
- Implicit time zones, e.g. stock exchange data that is always America/New_York
- Interacting with poorly-designed legacy systems that record data in the server's non-UTC time zone.
Passing data to/from a component that is unaware of time zones, e.g. a UI date/time picker.
Modeling events that happen at the same local time in every time zone. For example, the British Commonwealth observes a two minute silence every November 11th at 11:00AM in local time.
When time zone is irrelevant, e.g. a sleep tracking device that only cares about the local time you went to sleep and woke up, regardless of where in the world you are.
Parsing local time from ISO 8601 strings like 2020-04-09T16:08-08:00 that have a numeric offset without an IANA time zone like America/Los_Angeles. These strings can also be parsed by Iso.Instant, but to parse the local date and time then dateTimeFns.from is required.
Performing arithmetic that deliberately ignores DST. Example: in a day-planner UI, the visual height of a meeting may be the same even if DST skips or repeats an hour. To learn more about time zones and DST best practices, visit Time Zones and Resolving Ambiguity.

Defined in

iso-types.ts:97

now

▸ now(timeZone?): DateTime

This method gets the current calendar date and wall-clock time 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

DateTime

an Iso.DateTime string representing the date and time.

Defined in

types/IDateTimeFns.ts:17

fromNumbers

▸ fromNumbers(year, month, day, hour?, minute?, second?, millisecond?): DateTime

Parameters

Name	Type
`year`	`number`
`month`	`number`
`day`	`number`
`hour?`	`number`
`minute?`	`number`
`second?`	`number`
`millisecond?`	`number`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:18

isValid

▸ isValid(dateTime): dateTime is DateTime

Parameters

Name	Type
`dateTime`	`unknown`

Returns

dateTime is DateTime

Defined in

types/IDateTimeFns.ts:27

assertIsValid

▸ assertIsValid(dateTime): asserts dateTime is DateTime

Parameters

Name	Type
`dateTime`	`unknown`

Returns

asserts dateTime is DateTime

Defined in

types/IDateTimeFns.ts:28

getYear

▸ getYear(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:29

getMonth

▸ getMonth(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:30

getDay

▸ getDay(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:31

getHour

▸ getHour(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:32

getMinute

▸ getMinute(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:33

getSecond

▸ getSecond(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:34

getMillisecond

▸ getMillisecond(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:35

getDayOfWeek

▸ getDayOfWeek(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:36

getDayOfYear

▸ getDayOfYear(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:37

getWeekOfYear

▸ getWeekOfYear(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:38

getDaysInYear

▸ getDaysInYear(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:39

getDaysInMonth

▸ getDaysInMonth(dateTime): number

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:40

getInLeapYear

▸ getInLeapYear(dateTime): boolean

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

boolean

Defined in

types/IDateTimeFns.ts:41

with

▸ with(dateTime, temporalDateTimeLike, options?): DateTime

Parameters

Name	Type
`dateTime`	`DateTime`
`temporalDateTimeLike`	`Object`
`temporalDateTimeLike.day?`	`number`
`temporalDateTimeLike.hour?`	`number`
`temporalDateTimeLike.millisecond?`	`number`
`temporalDateTimeLike.minute?`	`number`
`temporalDateTimeLike.month?`	`number`
`temporalDateTimeLike.second?`	`number`
`temporalDateTimeLike.year?`	`number`
`options?`	`Object`
`options.overflow?`	`TemporalOverflow`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:42

withTime

▸ withTime(dateTime, time?): DateTime

Parameters

Name	Type
`dateTime`	`DateTime`
`time?`	`Time`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:57

withDate

▸ withDate(dateTime, temporalDate): DateTime

Parameters

Name	Type
`dateTime`	`DateTime`
`temporalDate`	`Date`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:58

add

▸ add(dateTime, temporalDurationLike, options?): DateTime

Parameters

Name	Type
`dateTime`	`DateTime`
`temporalDurationLike`	`Duration` \| { `years?`: `number` ; `months?`: `number` ; `weeks?`: `number` ; `days?`: `number` ; `hours?`: `number` ; `minutes?`: `number` ; `seconds?`: `number` ; `milliseconds?`: `number` }
`options?`	`Object`
`options.overflow?`	`TemporalOverflow`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:59

subtract

▸ subtract(dateTime, temporalDurationLike, options?): DateTime

Parameters

Name	Type
`dateTime`	`DateTime`
`temporalDurationLike`	`Duration` \| { `years?`: `number` ; `months?`: `number` ; `weeks?`: `number` ; `days?`: `number` ; `hours?`: `number` ; `minutes?`: `number` ; `seconds?`: `number` ; `milliseconds?`: `number` }
`options?`	`Object`
`options.overflow?`	`TemporalOverflow`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:75

until

▸ until(from, until, options?): Duration

Parameters

Name	Type
`from`	`DateTime`
`until`	`DateTime`
`options?`	`Object`
`options.largestUnit?`	`TemporalSingularUnit` \| `TemporalPluralUnit` \| `"auto"`
`options.smallestUnit?`	`TemporalSingularUnit` \| `TemporalPluralUnit`
`options.roundingIncrement?`	`number`
`options.roundingMode?`	`TemporalRoundingMode`

Returns

Duration

Defined in

types/IDateTimeFns.ts:91

since

▸ since(dateTime, other, options?): Duration

Parameters

Name	Type
`dateTime`	`DateTime`
`other`	`DateTime`
`options?`	`Object`
`options.largestUnit?`	`TemporalSingularUnit` \| `TemporalPluralUnit` \| `"auto"`
`options.smallestUnit?`	`TemporalSingularUnit` \| `TemporalPluralUnit`
`options.roundingIncrement?`	`number`
`options.roundingMode?`	`TemporalRoundingMode`

Returns

Duration

Defined in

types/IDateTimeFns.ts:101

round

▸ round(dateTime, options): DateTime

Parameters

Name	Type
`dateTime`	`DateTime`
`options`	`Object`
`options.smallestUnit`	`"day"` \| `"hour"` \| `"minute"` \| `"second"` \| `"millisecond"` \| `TemporalPluralUnit`
`options.roundingIncrement?`	`number`
`options.roundingMode?`	`TemporalRoundingMode`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:111

equals

▸ equals(dateTime, other): boolean

Parameters

Name	Type
`dateTime`	`DateTime`
`other`	`DateTime`

Returns

boolean

Defined in

types/IDateTimeFns.ts:119

isEqual

▸ isEqual(dateTime, other): boolean

alias for equals

Parameters

Name	Type
`dateTime`	`DateTime`
`other`	`DateTime`

Returns

boolean

Defined in

types/IDateTimeFns.ts:123

isBefore

▸ isBefore(dateTime, other): boolean

Parameters

Name	Type
`dateTime`	`DateTime`
`other`	`DateTime`

Returns

boolean

Defined in

types/IDateTimeFns.ts:124

isAfter

▸ isAfter(dateTime, other): boolean

Parameters

Name	Type
`dateTime`	`DateTime`
`other`	`DateTime`

Returns

boolean

Defined in

types/IDateTimeFns.ts:125

isEqualOrBefore

▸ isEqualOrBefore(dateTime, other): boolean

Parameters

Name	Type
`dateTime`	`DateTime`
`other`	`DateTime`

Returns

boolean

Defined in

types/IDateTimeFns.ts:126

isEqualOrAfter

▸ isEqualOrAfter(dateTime, other): boolean

Parameters

Name	Type
`dateTime`	`DateTime`
`other`	`DateTime`

Returns

boolean

Defined in

types/IDateTimeFns.ts:127

toZonedDateTime

▸ toZonedDateTime(dateTime, timeZone, options?): ZonedDateTime

Parameters

Name	Type
`dateTime`	`DateTime`
`timeZone`	`string`
`options?`	`Object`
`options.disambiguation`	`TemporalDisambiguation`

Returns

ZonedDateTime

Defined in

types/IDateTimeFns.ts:128

toDate

▸ toDate(dateTime): Date

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

Date

Defined in

types/IDateTimeFns.ts:133

toYearMonth

▸ toYearMonth(dateTime): YearMonth

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

YearMonth

Defined in

types/IDateTimeFns.ts:134

toMonthDay

▸ toMonthDay(dateTime): MonthDay

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

MonthDay

Defined in

types/IDateTimeFns.ts:135

toTime

▸ toTime(dateTime): Time

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

Time

Defined in

types/IDateTimeFns.ts:136

getFields

▸ getFields(dateTime): DateTimeSlots

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

DateTimeSlots

Defined in

types/IDateTimeFns.ts:137

from

▸ from(item, options?): DateTime

Parameters

Name	Type
`item`	`any`
`options?`	`Object`
`options.overflow`	`TemporalOverflow`

Returns

DateTime

Defined in

types/IDateTimeFns.ts:138

compare

▸ compare(one, two): number

Parameters

Name	Type
`one`	`DateTime`
`two`	`DateTime`

Returns

number

Defined in

types/IDateTimeFns.ts:139

format

▸ format(dateTime, formatString): 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
	QQ	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
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
Combination of date and time	Pp	04/29/1453, 12:00 AM	5
	PPpp	Apr 29, 1453, 12:00:00 AM	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 and u 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, while uu 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 week
- I: ISO week of year
- o: ordinal number modifier
- P: long localized date
- p: long localized time

Year	`y`	`u`
AC 1	1	1
BC 1	1	0
BC 2	2	-1

Year	`yy`	`uu`
1	01	01
14	14	14
376	76	376
1453	53	1453

Characters are escaped using single quote symbols (').

example

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

example

// Escape string by single quote characters:
var result = format("2014-02-11T15:00:00.000", "h 'o''clock'")
//=> "3 o'clock"

Parameters

Name	Type	Description
`dateTime`	`DateTime`	the original date
`formatString`	`string`	-

Returns

string

the formatted date string

Defined in

types/IDateTimeFns.ts:309

chain

▸ chain(dateTime): IDateTimeChain

Parameters

Name	Type
`dateTime`	`DateTime`

Returns

IDateTimeChain

Defined in

types/IDateTimeFns.ts:310

Defined in​

now​

Parameters​

Returns​

Defined in​

fromNumbers​

Parameters​

Returns​

Defined in​

isValid​

Parameters​

Returns​

Defined in​

assertIsValid​

Parameters​

Returns​

Defined in​

getYear​

Parameters​

Returns​

Defined in​

getMonth​

Parameters​

Returns​

Defined in​

getDay​

Parameters​

Returns​

Defined in​

getHour​

Parameters​

Returns​

Defined in​

getMinute​

Parameters​

Returns​

Defined in​

getSecond​

Parameters​

Returns​

Defined in​

getMillisecond​

Parameters​

Returns​

Defined in​

getDayOfWeek​

Parameters​

Returns​

Defined in​

getDayOfYear​

Parameters​

Returns​

Defined in​

getWeekOfYear​

Parameters​

Returns​

Defined in​

getDaysInYear​

Parameters​

Returns​

Defined in​

getDaysInMonth​

Parameters​

Returns​

Defined in​

getInLeapYear​

Parameters​

Returns​

Defined in​

with​

Parameters​

Returns​

Defined in​

withTime​

Parameters​

Returns​

Defined in​

withDate​

Parameters​

Returns​

Defined in

now

Parameters

Returns

Defined in

fromNumbers

Parameters

Returns

Defined in

isValid

Parameters

Returns

Defined in

assertIsValid

Parameters

Returns

Defined in

getYear

Parameters

Returns

Defined in

getMonth

Parameters

Returns

Defined in

getDay

Parameters

Returns

Defined in

getHour

Parameters

Returns

Defined in

getMinute

Parameters

Returns

Defined in

getSecond

Parameters

Returns

Defined in

getMillisecond

Parameters

Returns

Defined in

getDayOfWeek

Parameters

Returns

Defined in

getDayOfYear

Parameters

Returns

Defined in

getWeekOfYear

Parameters

Returns

Defined in

getDaysInYear

Parameters

Returns

Defined in

getDaysInMonth

Parameters

Returns

Defined in

getInLeapYear

Parameters

Returns

Defined in

with

Parameters

Returns

Defined in

withTime

Parameters

Returns

Defined in

withDate

Parameters

Returns