Skip to main content

An Iso.Date represents a calendar date. "Calendar date" refers to the concept of a date as expressed in everyday usage, independent of any time zone. For example, it could be used to represent an event on a calendar which happens during the whole day no matter which time zone it's happening in.

Iso.Date refers to the whole of a specific day; if you need to refer to a specific time on that day, use Iso.DateTime. An Iso.Date can be converted into a Iso.ZonedDateTime by combining it with a Iso.Time and Iso.TimeZone using the toZonedDateTime() function. It can also be combined with a Iso.Time to yield a "zoneless" Iso.DateTime using the toDateTime() method.

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

now()​

now(timeZone?): Date

This method gets the current calendar date 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​

Date

an Iso.Date string representing the date.

fromNumbers()​

fromNumbers(year, month, day): Date

Parameters​

year​

number

month​

number

day​

number

Returns​

Date

isValid()​

isValid(date): date is Date

Parameters​

date​

unknown

Returns​

date is Date

assertIsValid()​

assertIsValid(date): asserts date is Date

Parameters​

date​

unknown

Returns​

asserts date is Date

getYear()​

getYear(date): number

Parameters​

date​

Date

Returns​

number

getMonth()​

getMonth(date): number

Parameters​

date​

Date

Returns​

number

getDay()​

getDay(date): number

Parameters​

date​

Date

Returns​

number

getDayOfWeek()​

getDayOfWeek(date): number

Parameters​

date​

Date

Returns​

number

getDayOfYear()​

getDayOfYear(date): number

Parameters​

date​

Date

Returns​

number

getWeekOfYear()​

getWeekOfYear(date): number

Parameters​

date​

Date

Returns​

number

getDaysInMonth()​

getDaysInMonth(date): number

Parameters​

date​

Date

Returns​

number

getDaysInYear()​

getDaysInYear(date): number

Parameters​

date​

Date

Returns​

number

inLeapYear()​

inLeapYear(date): boolean

Parameters​

date​

Date

Returns​

boolean

with()​

with(dateTime, temporalDateLike, options?): Date

Parameters​

dateTime​

Date

temporalDateLike​

day?​

number

month?​

number

year?​

number

options?​

overflow?​

"constrain" | "reject"

Returns​

Date

add()​

add(date, temporalDurationLike, options?): Date

Parameters​

date​

Date

temporalDurationLike​

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

options?​

overflow?​

"constrain" | "reject"

Returns​

Date

subtract()​

subtract(date, temporalDurationLike, options?): Date

Parameters​

date​

Date

temporalDurationLike​

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

options?​

overflow?​

"constrain" | "reject"

Returns​

Date

until()​

until(date, other, options?): Duration

Parameters​

date​

Date

other​

Date

options?​

largestUnit?​

LargestUnit\<"day" | "week" | "month" | "year">

smallestUnit?​

SmallestUnit\<"day" | "week" | "month" | "year">

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

Duration

since()​

since(date, other, options?): Duration

Parameters​

date​

Date

other​

Date

options?​

largestUnit?​

LargestUnit\<"day" | "week" | "month" | "year">

smallestUnit?​

SmallestUnit\<"day" | "week" | "month" | "year">

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

Duration

equals()​

equals(date, other): boolean

Parameters​

date​

Date

other​

Date

Returns​

boolean

isEqual()​

isEqual(date, other): boolean

alias for equals

Parameters​

date​

Date

other​

Date

Returns​

boolean

isBefore()​

isBefore(date, other): boolean

Parameters​

date​

Date

other​

Date

Returns​

boolean

isAfter()​

isAfter(date, other): boolean

Parameters​

date​

Date

other​

Date

Returns​

boolean

isEqualOrBefore()​

isEqualOrBefore(date, other): boolean

Parameters​

date​

Date

other​

Date

Returns​

boolean

isEqualOrAfter()​

isEqualOrAfter(date, other): boolean

Parameters​

date​

Date

other​

Date

Returns​

boolean

toDateTime()​

toDateTime(date, time?): DateTime

Parameters​

date​

Date

time?​

Time

Returns​

DateTime

toZonedDateTime()​

toZonedDateTime(date, item): ZonedDateTime

Parameters​

date​

Date

item​

timeZone​

string

time?​

Time

Returns​

ZonedDateTime

toYearMonth()​

toYearMonth(date): YearMonth

Parameters​

date​

Date

Returns​

YearMonth

toMonthDay()​

toMonthDay(date): MonthDay

Parameters​

date​

Date

Returns​

MonthDay

getFields()​

getFields(date): DateSlots

Parameters​

date​

Date

Returns​

DateSlots

from()​

from(item, options?): Date

Parameters​

item​

string | Partial\<DateSlots>

options?​

overflow​

"constrain" | "reject"

Returns​

Date

compare()​

compare(one, two): number

Parameters​

one​

Date

two​

Date

Returns​

number

format()​

format(date, format, options?): string

Parameters​

date​

Date

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
Long localized dateP04/29/14535
PPApr 29, 14535
PPPApril 29th, 14535
PPPPFriday, April 29th, 14531,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-11", 'MM/dd/yyyy')
//=> '02/11/2014'

chain()​

chain(date): IDateChain

Parameters​

date​

Date

Returns​

IDateChain