Proposal proposal-uniform-interchange-date-parsing

Stage 1 Draft / March 17, 2019

Uniform parsing of quasi-standard Date.parse input

1Date.parse ( string )

The parse function applies the ToString operator to its argument. If ToString results in an abrupt completion the Completion Record is immediately returned. Otherwise, parse interprets the resulting Stringinterprets its argument as a date and time; it returns a Number, the UTC time value corresponding to the date and time. The String may be interpreted as a local time, a UTC time, or a time in some other time zone, depending on the contents of the String. The function first attempts to parse the String according to the format described in Date Time String Format (20.3.1.16), including expanded years. If the String does not conform to that format the function may fall back to any implementation-specific heuristics or implementation-specific date formats. Strings that are unrecognizable or contain out-of-bounds format field values shall cause Date.parse to return NaN.

If the String conforms to the Date Time String Format, substitute values take the place of absent format elements. When the MM or DD elements are absent, "01" is used. When the HH, mm, or ss elements are absent, "00" is used. When the sss element is absent, "000" is used. When the time zone designator is absent, date-only forms are interpreted as a UTC time and date-time forms are interpreted as a local time.

If x is any Date object whose milliseconds amount is zero within a particular implementation of ECMAScript, then all of the following expressions should produce the same numeric value in that implementation, if all the properties referenced have their initial values:

x.valueOf()
Date.parse(x.toString())
Date.parse(x.toUTCString())
Date.parse(x.toISOString())

However, the expression

Date.parse(x.toLocaleString())

is not required to produce the same Number value as the preceding three expressions and, in general, the value produced by Date.parse is implementation-dependent when given any String value that does not conform to the Date Time String Format (20.3.1.16) and that could not be produced in that implementation by the toString or toUTCString method.

When the parse function is called, the following steps are taken:

  1. Let inputString be ? ToString(string).
  2. Let extendedDecimalInputString be the String value that is the same as inputString except that each sequence of the code unit 0x002E (FULL STOP) followed by one or more consecutive DecimalDigits has been replaced with . followed by the first three code units of the string-concatenation of the DecimalDigits of the sequence and "00".
  3. Let msInputString be the String value that is the same as extendedDecimalInputString except that each sequence of the code unit 0x002E (FULL STOP) followed by four or more consecutive DecimalDigits has been replaced with . followed by the first three DecimalDigits of the sequence.
  4. Let inBoundsInputString be the String value that is the same as msInputString except that each occurrence of DecimalDigit has been replaced with 1.
  5. If inBoundsInputString conforms to the interchange format described in Date Time String Format (20.3.1.16), including expanded years, then
    1. Assert: The YYYY format element is present in msInputString.
    2. If the YYYY format element of msInputString represents a year exceeding the bounds of a time value, return NaN.
    3. If the MM format element is present in msInputString and its value is "00" or its value is greater than "12" or the combination of the YYYY and MM format elements of msInputString represents a year and month exceeding the bounds of a time value, return NaN.
    4. If the DD format element is present in msInputString and the combination of the YYYY, MM, and DD format elements of msInputString represents a nonexistent date or a date exceeding the bounds of a time value, return NaN.
    5. Assert: The combination of the YYYY, MM, and DD format elements of msInputString (substituting "01" for any absent MM or DD element) represents a date that is part of the proleptic Gregorian calendar.
    6. If the HH format element is present in msInputString and its value is greater than "24" or its value is equal to "24" and one or more of the mm, ss, and sss format elements are present in msInputString with a value including any code unit other than 0, return NaN.
    7. If the mm format element is present in msInputString and its value is greater than "59", return NaN.
    8. If the ss format element is present in msInputString and its value is greater than "59", return NaN.
    9. Assert: The combination of the HH, mm, and ss format elements of msInputString (substituting "00" for any absent element) represents either a valid time of day that is at most "23:59:59" or a special end-of-day "24:00:00".
    10. If the Z format element is present in msInputString and its HH component is greater than "23" or its mm component is greater than "59", return NaN.
    11. Assert: The Z format element is either absent from msInputString or represents a UTC offset of magnitude less than 24 hours.
    12. If the date and time represented by msInputString exceeds the bounds of a time value, return NaN.
    13. Return the time value corresponding with the date and time represented by msInputString.
  6. Assert: inputString does not conform to the Date Time String Format (20.3.1.16).
  7. Let tv be NaN.
  8. If there is a nonempty set of finite time values such that invoking the initial value of Date.prototype.toString (20.3.4.41) with a Date instance having a [[DateValue]] internal slot equal to any of them would return inputString, then
    1. Let tv be the lowest-valued member of the set.
  9. Else if there is a nonempty set of finite time values such that invoking the initial value of Date.prototype.toUTCString (20.3.4.43) with a Date instance having a [[DateValue]] internal slot equal to any of them would return inputString, then
    1. Let tv be the lowest-valued member of the set.
  10. Else if the implementation includes a further facility for parsing dates and times, then
    1. Let tv be the implementation-dependent time value returned from using that facility to attempt parsing inputString.
  11. Assert: tv is NaN or abs(tv) ≤ 8.64 × 1015.
  12. Return tv.

ACopyright & Software License

Copyright Notice

© 2019 Richard Gibson

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.