W3cubDocs

/date-fns

parse

Parse the date.

Description

Return the date parsed from string using the given format string.

⚠️ Please note that the format tokens differ from Moment.js and other libraries. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

The characters in the format string 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.

Format of the format 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 5 below the table).

Not all tokens are compatible. Combinations that don't make sense or could lead to bugs are prohibited and will throw RangeError. For example usage of 24-hour format token with AM/PM token will throw an exception:

parse('23 AM', 'HH a', new Date())
//=> RangeError: The format string mustn't contain `HH` and `a` at the same time

See the compatibility table: https://docs.google.com/spreadsheets/d/e/2PACX-1vQOPU3xUhplll6dyoMmVUXHKl_8CRDs6_ueLmex3SoqwhuolkuN3O05l4rqx5h1dKX8eb46Ul-CCSrq/pubhtml?gid=0&single=true

Accepted format string patterns:

Unit Prior Pattern Result examples Notes
Era 140 G..GGG AD, BC
GGGG Anno Domini, Before Christ 2
GGGGG A, B
Calendar year 130 y 44, 1, 1900, 2017, 9999 4
yo 44th, 1st, 1900th, 9999999th 4,5
yy 44, 01, 00, 17 4
yyy 044, 001, 123, 999 4
yyyy 0044, 0001, 1900, 2017 4
yyyyy ... 2,4
Local week-numbering year 130 Y 44, 1, 1900, 2017, 9000 4
Yo 44th, 1st, 1900th, 9999999th 4,5
YY 44, 01, 00, 17 4,6
YYY 044, 001, 123, 999 4
YYYY 0044, 0001, 1900, 2017 4,6
YYYYY ... 2,4
ISO week-numbering year 130 R -43, 1, 1900, 2017, 9999, -9999 4,5
RR -43, 01, 00, 17 4,5
RRR -043, 001, 123, 999, -999 4,5
RRRR -0043, 0001, 2017, 9999, -9999 4,5
RRRRR ... 2,4,5
Extended year 130 u -43, 1, 1900, 2017, 9999, -999 4
uu -43, 01, 99, -99 4
uuu -043, 001, 123, 999, -999 4
uuuu -0043, 0001, 2017, 9999, -9999 4
uuuuu ... 2,4
Quarter (formatting) 120 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, ... 2
QQQQQ 1, 2, 3, 4 4
Quarter (stand-alone) 120 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, ... 2
qqqqq 1, 2, 3, 4 3
Month (formatting) 110 M 1, 2, ..., 12
Mo 1st, 2nd, ..., 12th 5
MM 01, 02, ..., 12
MMM Jan, Feb, ..., Dec
MMMM January, February, ..., December 2
MMMMM J, F, ..., D
Month (stand-alone) 110 L 1, 2, ..., 12
Lo 1st, 2nd, ..., 12th 5
LL 01, 02, ..., 12
LLL Jan, Feb, ..., Dec
LLLL January, February, ..., December 2
LLLLL J, F, ..., D
Local week of year 100 w 1, 2, ..., 53
wo 1st, 2nd, ..., 53th 5
ww 01, 02, ..., 53
ISO week of year 100 I 1, 2, ..., 53 5
Io 1st, 2nd, ..., 53th 5
II 01, 02, ..., 53 5
Day of month 90 d 1, 2, ..., 31
do 1st, 2nd, ..., 31st 5
dd 01, 02, ..., 31
Day of year 90 D 1, 2, ..., 365, 366 7
Do 1st, 2nd, ..., 365th, 366th 5
DD 01, 02, ..., 365, 366 7
DDD 001, 002, ..., 365, 366
DDDD ... 2
Day of week (formatting) 90 E..EEE Mon, Tue, Wed, ..., Sun
EEEE Monday, Tuesday, ..., Sunday 2
EEEEE M, T, W, T, F, S, S
EEEEEE Mo, Tu, We, Th, Fr, Sa, Su
ISO day of week (formatting) 90 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 2,5
iiiii M, T, W, T, F, S, S 5
iiiiii Mo, Tu, We, Th, Fr, Sa, Su 5
Local day of week (formatting) 90 e 2, 3, 4, ..., 1
eo 2nd, 3rd, ..., 1st 5
ee 02, 03, ..., 01
eee Mon, Tue, Wed, ..., Sun
eeee Monday, Tuesday, ..., Sunday 2
eeeee M, T, W, T, F, S, S
eeeeee Mo, Tu, We, Th, Fr, Sa, Su
Local day of week (stand-alone) 90 c 2, 3, 4, ..., 1
co 2nd, 3rd, ..., 1st 5
cc 02, 03, ..., 01
ccc Mon, Tue, Wed, ..., Sun
cccc Monday, Tuesday, ..., Sunday 2
ccccc M, T, W, T, F, S, S
cccccc Mo, Tu, We, Th, Fr, Sa, Su
AM, PM 80 a..aaa AM, PM
aaaa a.m., p.m. 2
aaaaa a, p
AM, PM, noon, midnight 80 b..bbb AM, PM, noon, midnight
bbbb a.m., p.m., noon, midnight 2
bbbbb a, p, n, mi
Flexible day period 80 B..BBB at night, in the morning, ...
BBBB at night, in the morning, ... 2
BBBBB at night, in the morning, ...
Hour [1-12] 70 h 1, 2, ..., 11, 12
ho 1st, 2nd, ..., 11th, 12th 5
hh 01, 02, ..., 11, 12
Hour [0-23] 70 H 0, 1, 2, ..., 23
Ho 0th, 1st, 2nd, ..., 23rd 5
HH 00, 01, 02, ..., 23
Hour [0-11] 70 K 1, 2, ..., 11, 0
Ko 1st, 2nd, ..., 11th, 0th 5
KK 01, 02, ..., 11, 00
Hour [1-24] 70 k 24, 1, 2, ..., 23
ko 24th, 1st, 2nd, ..., 23rd 5
kk 24, 01, 02, ..., 23
Minute 60 m 0, 1, ..., 59
mo 0th, 1st, ..., 59th 5
mm 00, 01, ..., 59
Second 50 s 0, 1, ..., 59
so 0th, 1st, ..., 59th 5
ss 00, 01, ..., 59
Seconds timestamp 40 t 512969520
tt ... 2
Fraction of second 30 S 0, 1, ..., 9
SS 00, 01, ..., 99
SSS 000, 001, ..., 999
SSSS ... 2
Milliseconds timestamp 20 T 512969520900
TT ... 2
Timezone (ISO-8601 w/ Z) 10 X -08, +0530, Z
XX -0800, +0530, Z
XXX -08:00, +05:30, Z
XXXX -0800, +0530, Z, +123456 2
XXXXX -08:00, +05:30, Z, +12:34:56
Timezone (ISO-8601 w/o Z) 10 x -08, +0530, +00
xx -0800, +0530, +0000
xxx -08:00, +05:30, +00:00 2
xxxx -0800, +0530, +0000, +123456
xxxxx -08:00, +05:30, +00:00, +12:34:56
Long localized date NA P 05/29/1453 5,8
PP May 29, 1453
PPP May 29th, 1453
PPPP Sunday, May 29th, 1453 2,5,8
Long localized time NA p 12:00 AM 5,8
pp 12:00:00 AM
Combination of date and time NA Pp 05/29/1453, 12:00 AM
PPpp May 29, 1453, 12:00:00 AM
PPPpp May 29th, 1453 at ...
PPPPpp Sunday, May 29th, 1453 at ... 2,5,8

Notes: 1. "Formatting" units (e.g. formatting quarter) in the default en-US locale are the same as "stand-alone" units, but are different in some languages. "Formatting" units are declined according to the rules of the language in the context of a date. "Stand-alone" units are always nominative singular. In format function, they will produce different result:

format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'

format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'

parse will try to match both formatting and stand-alone units interchangably.

  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:

    • for numerical units (yyyyyyyy) parse will try to match a number as wide as the sequence
    • for text units (MMMMMMMM) parse will try to match the widest variation of the unit. These variations are marked with "2" in the last column of the table.

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

  3. 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 will try to guess the century of two digit year by proximity with referenceDate:

parse('50', 'yy', new Date(2018, 0, 1)) //=> Sat Jan 01 2050 00:00:00

parse('75', 'yy', new Date(2018, 0, 1)) //=> Wed Jan 01 1975 00:00:00

while uu will just assign the year as is:

parse('50', 'uu', new Date(2018, 0, 1)) //=> Sat Jan 01 0050 00:00:00

parse('75', 'uu', new Date(2018, 0, 1)) //=> Tue Jan 01 0075 00:00:00

The same difference is true for local and ISO week-numbering years (Y and R), except local week-numbering years are dependent on options.weekStartsOn and options.firstWeekContainsDate (compare [setISOWeekYear]{@link https://date-fns.org/docs/setISOWeekYear} and [setWeekYear]{@link https://date-fns.org/docs/setWeekYear}).

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

    • i: ISO day of week
    • I: ISO week of year
    • R: ISO week-numbering year
    • o: ordinal number modifier
    • P: long localized date
    • p: long localized time

  2. YY and YYYY tokens represent week-numbering years but they are often confused with years. You should enable options.useAdditionalWeekYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

  3. D and DD tokens represent days of the year but they are ofthen confused with days of the month. You should enable options.useAdditionalDayOfYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

  4. P+ tokens do not have a defined priority since they are merely aliases to other tokens based on the given locale.

using en-US locale: P => MM/dd/yyyy using en-US locale: p => hh:mm a using pt-BR locale: P => dd/MM/yyyy using pt-BR locale: p => HH:mm

Values will be assigned to the date in the descending order of its unit's priority. Units of an equal priority overwrite each other in the order of appearance.

If no values of higher priority are parsed (e.g. when parsing string 'January 1st' without a year), the values will be taken from 3rd argument referenceDate which works as a context of parsing.

referenceDate must be passed for correct work of the function. If you're not sure which referenceDate to supply, create a new instance of Date: parse('02/11/2014', 'MM/dd/yyyy', new Date()) In this case parsing will be done in the context of the current date. If referenceDate is Invalid Date or a value not convertible to valid Date, then Invalid Date will be returned.

The result may vary by locale.

If formatString matches with dateString but does not provides tokens, referenceDate will be returned.

If parsing failed, Invalid Date will be returned. Invalid Date is a Date, whose time value is NaN. Time value of Date: http://es5.github.io/#x15.9.1.1

Usage

// CommonJS
var parse = require('date-fns/parse')
// ES 2015
import parse from 'date-fns/parse'
// ESM
import { parse } from 'date-fns'

Syntax

parse(dateString, formatString, referenceDate, [options])

Arguments

Name Description
dateString

the string to parse
formatString

the string of tokens
referenceDate

defines values missing from the parsed dateString
options

an object with options.
options.locale

the locale object. See [Locale]{@link https://date-fns.org/docs/Locale}
options.weekStartsOn

the index of the first day of the week (0 - Sunday)
options.firstWeekContainsDate

the day of January, which is always in the first week of the year
options.useAdditionalWeekYearTokens

if true, allows usage of the week-numbering year tokens YY and YYYY; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
options.useAdditionalDayOfYearTokens

if true, allows usage of the day of year tokens D and DD; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

Returns

Description

the parsed date

Exceptions

Type Description
TypeError

3 arguments required
RangeError

options.weekStartsOn must be between 0 and 6
RangeError

options.firstWeekContainsDate must be between 1 and 7
RangeError

options.locale must contain match property
RangeError

use yyyy instead of YYYY for formatting years using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
RangeError

use yy instead of YY for formatting years using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
RangeError

use d instead of D for formatting days of the month using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
RangeError

use dd instead of DD for formatting days of the month using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
RangeError

format string contains an unescaped latin alphabet character

Examples

// Parse 11 February 2014 from middle-endian format:
var result = parse('02/11/2014', 'MM/dd/yyyy', new Date())
//=> Tue Feb 11 2014 00:00:00
// Parse 28th of February in Esperanto locale in the context of 2010 year:
import eo from 'date-fns/locale/eo'
var result = parse('28-a de februaro', "do 'de' MMMM", new Date(2010, 0, 1), {
  locale: eo
})
//=> Sun Feb 28 2010 00:00:00

© 2021 Sasha Koss and Lesha Koss
Licensed under the MIT License.
https://date-fns.org/v2.29.2/docs/parse