Date.parse() メソッドは、日時を表す文字列を解釈し、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 からの経過時間を表すミリ秒単位の数値を返します。または、文字列を解釈できなかったり不正な日付 (例えば 2015-02-31) が指定された場合 NaN を返します。
ES5 に準拠して実装されるまで Date.parse の使用は推奨されません。文字列の解釈は全体的に実装依存です。これらには多くの異なる実装があり、文字列の解釈が異なることがあるため、日付の文字列は手動で解釈するべきです (多くの異なる書式に対応したライブラリの使用が助けになるでしょう)。
直接呼び出し:
Date.parse(dateString)
暗黙の呼び出し:
new Date(dateString)
dateString協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 UTC からの経過時間をミリ秒単位で表す数値。このメソッドに与えられた日付を表す文字列の解釈により取得される日付。引数に正しい値が与えられない場合、 {{jsxref("NaN")}} を返します。
parse() メソッドは、日時の文字列 (例えば "2011-10-10T14:48:00") を取り、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 からのミリ秒単位の経過時間を表す数値を返します。
この関数は、例えば {{jsxref("Date.prototype.setTime()", "setTime()")}} メソッドと {{jsxref("Global_Objects/Date", "Date")}} オブジェクトを組み合わせて使う場合など、文字列値を基にして日時の値を設定するときに有用です。。
日時文字列の標準的な文字列表現は、 ISO 8601 のカレンダー日付拡張形式を簡略化したものです。 (詳しくは、 ECMAScript 仕様書の Date Time String Format の章を参照してください。)
例えば, "2011-10-10" (日付のみの形式), "2011-10-10T14:48:00" (日時形式), "2011-10-10T14:48:00.000+09:00" (日時形式にミリ秒とタイムゾーンがついたもの) を渡し、解釈することができます。タイムゾーンのオフセットがない場合は、日付のみの形式では UTC 時刻と解釈され、日時形式では地方時として解釈されます。
タイムゾーン指定子は、日付文字列の解析中に引数を解釈するために使用されますが、返される値は常に、 1970 年 1 月 1 日 00:00:00:00 UTC と、引数で表される時点との間のミリ秒数または NaN です。
parse() は {{jsxref("Date")}} の静的メソッドですので、 {{jsxref("Date")}} のメソッドとしてではなく Date.parse() として呼び出されます。
この節では実装依存の動作を説明しており、実装間で一貫性がない可能性があります。
ECMAScript 仕様書は、文字列が標準の書式に準拠していない場合、この関数は実装固有の検出方法や実装固有の解析アルゴリズムにフォールバックすることがあり、解釈できない文字列や ISO 書式文字列における不正な要素値を含む日付を渡すと、 Date.parse() が {{jsxref("NaN")}} を返すと既定しています。
しかし、 ECMA-262 で定義されている簡略化 ISO 書式として解釈できない日付文字列の無効な値は、ブラウザーや与えられた値に依存して、 {{jsxref("NaN")}} を返したり返さなかったりすることがあります。次の例を参照してください。
// 不正な値を持つ 非 ISO 文字列
new Date('23/25/2014');
これは、 Firefox 30 では、地方時の 2015 年 11 月 25 日として扱われ、 Safari 7 では不正な値として処理されます。
しかし、文字列が ISO 書式の文字列として解釈され、不正な値を含む場合、 ES5 以降の仕様に準拠するすべてのブラウザーが {{jsxref("NaN")}} を返します。
// 不正な値を持つ ISO 文字列
new Date('2014-25-23').toISOString();
// ES5 準拠のすべてのブラウザーが "RangeError: invalid date" を返す
SpiderMonkey の実装特有のヒューリスティックは、jsdate.cpp にあります。 "10 06 2014" の文字列は、非 ISO 書式の例として挙げられており、このようにカスタム処理にフォールバックされます。この解釈の動作を説明するおよそのアウトライン も参照してください。
new Date('10 06 2014');
これは、2014 年 6 月 10 日ではなく、地方時の 2014 年 10 月 6 日 として扱われます。
他の例です。
new Date('foo-bar 2014').toString();
// 返値: "Invalid Date"
Date.parse('foo-bar 2014');
// 返値: NaN
この節では実装依存の動作を説明しており、実装間で一貫性がない可能性があります。
標準外の日付文字列である "March 7, 2014" を渡すと、 parse() はタイムゾーンとして地方時を想定しますが、 "2014-03-07" のような ISO 書式を与えると UTC をタイムゾーンとして想定します (ES5 および ECMAScript 2015 の仕様)。したがって、これらの文字列を使用して生成される {{jsxref("Date")}}} オブジェクトは、システムが UTC の地方時に設定されていない限り、対応している ECMAScript のバージョンによって異なる時刻を表す可能性があります。つまり、同じように見える 2 つの日付文字列が、変換される文字列の形式によって 2 つの異なる値になる可能性があるということです。
Date.parse() の使用以下の呼び出しはすべて 1546300800000 を返します。最初のものは ES5 によれば UTC 時刻を意味し、それ以外は ISO 日付仕様 (Z および +00:00) に従って UTC をタイムゾーンを指定しています。
Date.parse("2019-01-01")
Date.parse("2019-01-01T00:00:00.000Z")
Date.parse("2019-01-01T00:00:00.000+00:00")
以下の呼び出しではタイムゾーンを指定していないので、システムの地方時で 2019-01-01 の 00:00:00 に設定されます。
Date.parse("2019-01-01T00:00:00")
この節では実装依存の動作を説明しており、実装間で一貫性がない可能性があります。
IPOdate が既存の {{jsxref("Date")}} オブジェクトならば、次のようにして、これを 1995 年 8 月 9 日 (地方時) にセットできます:
IPOdate.setTime(Date.parse('Aug 9, 1995'));
それ以外の標準外の日付文字列の解釈の例を示します。
Date.parse('Aug 9, 1995');
GMT-0300 のタイムゾーンでは 807937200000 を返し、他のタイムゾーンでは他の値を返します。タイムゾーンが指定されておらず ISO 書式でないため、既定で地方時のタイムゾーンが使用されます。
Date.parse('Wed, 09 Aug 1995 00:00:00 GMT');
GMT (UTC) が指定されているため、地方時のタイムゾーンに関係なく 807926400000 を返します。
Date.parse('Wed, 09 Aug 1995 00:00:00');
GMT-0300 のタイムゾーンでは 807937200000 を返し、他のタイムゾーンでは他の値を返します。引数にタイムゾーンが指定されておらず、 ISO 書式ではないため、地方時として扱われます。
Date.parse('Thu, 01 Jan 1970 00:00:00 GMT');
GMT (UTC) のタイムゾーンが指定されているため、地方時のタイムゾーンに関係なく 0 を返します。
Date.parse('Thu, 01 Jan 1970 00:00:00');
GMT-0400 のタイムゾーンでは 14400000 を返し、他のタイムゾーンでは他の値を返します。タイムゾーンが指定されておらず、 ISO 書式ではないため、地方時のタイムゾーンが使用されます。
Date.parse('Thu, 01 Jan 1970 00:00:00 GMT-0400');
GMT (UTC) のタイムゾーンが指定されているため、地方時のタイムゾーンに関係なく 14400000 を返します。
| 仕様書 |
|---|
| {{SpecName('ESDraft', '#sec-date.parse', 'Date.parse')}} |
{{Compat("javascript.builtins.Date.parse")}}
50 以下の 2 桁の「年」は 21 世紀の年として解釈されます。例えば 04/16/17 は、以前は 1917 年 4 月 16 日と解釈されていましたが、 2017 年 4 月 16 日と解釈されるようになりました。相互運用性の問題や年があいまいになることを回避するには、 ISO 8601 書式 ("2017-04-16" など) の使用が推奨されます (bug 1265136)。dateString 引数として受け付けます。これは、すなわち、 !!Date.parse("42") は Firefox では false として評価されるのに対して、 Google Chrome では true として評価されます。 "42" は 2042 年 1 月 1 日と解釈されるからです。