Date.parse()
メソッドは、日時を表す文字列を解釈し、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 からの経過時間を表すミリ秒単位の数値を返します。または、文字列を解釈できなかったり不正な日付 (例えば 2015-02-31) が指定された場合 NaN
を返します。
ES5 に準拠して実装されるまで Date.parse
の使用は推奨されません。文字列の解釈は全体的に実装依存です。これらには多くの異なる実装があり、文字列の解釈が異なることがあるため、日付の文字列は手動で解釈するべきです (多くの異なる書式に対応したライブラリの使用が助けになるでしょう)。
構文
直接呼び出し:
Date.parse(dateString)
省略呼び出し:
new Date(dateString)
引数
dateString
- RFC2822 または ISO 8601 の日付を表す文字列 (他の書式が使用されることがあるため、結果は期待値にならない可能性があります)。
戻り値
"1 January 1970 00:00:00 UTC" からの経過時間をミリ秒単位で表す数値。このメソッドに与えられた日付を表す文字列の解釈により取得される日付。引数に正しい値が与えられない場合、NaN
を返します。
説明
parse
メソッドは、日時の文字列 (例えば "Dec 25, 1995
") を取り、1970 年 1 月 1 日 00:00:00 (UTC) からのミリ秒単位の経過時間を表す数値を返します。この関数は、例えば setTime()
メソッドと Date
オブジェクトを組み合わせて使い、文字列値を基にして日時の値をセットするときに役立ちます。
時刻を表す文字列を与えると、parse()
は time 値を返します。これは、"Mon, 25 Dec 1995 13:30:00 GMT"
のような RFC2822 / IETF 標準の日付構文 (RFC2822 Section 3.3) を受け入れます。また、アメリカ大陸のタイムゾーンの省略形を解釈できますが、一般的な使用にはタイムゾーンオフセットを使用してください。例えば、"Mon, 25 Dec 1995 13:30:00 +0430"
(グリニッジ標準時より 4 時間 30 分東)。
GMT と UTC は等価とみなされます。タイムゾーン情報を含まない文字列は、地方時のタイムゾーンが使用され、RFC2822 Section 3.3 準拠の書式の引数として判断されます。
日付文字列の解釈の多様性により結果の一貫性がないため、文字列は常に手動で解釈することをおすすめします。特に、ECMAScript の実装がエンジンによって異なるため、"2015-10-12 12:00:00"
のような文字列は、NaN
を返したり、UTC または地方時として解釈されたりします。
ECMAScript 5 ISO-8601 書式のサポート
日時の文字列は、ISO 8601 の書式になるでしょう。例えば、"2011-10-10"
(日付のみ) または "2011-10-10T14:48:00"
(日付と時刻) の解釈が可能です。文字列が ISO 8601 の日付のみの場合、UTC タイムゾーンを使用して引数を判断します。文字列が ISO 8601 書式の日付と時刻の場合、地方時として扱われます。
タイムゾーン指定の引数は、日付文字列を解釈して引数を判断するときに使用されます。戻り値は常に、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から引数に指定した時点までの経過時間を表すミリ秒単位の数値、または解釈できない場合 NaN
です。
parse
は Date
の静的メソッドなので、生成した Date
インスタンスのメソッドとしてではなく、常に Date.parse()
のように使います。
想定されるタイムゾーンの違い
"March 7, 2014"
の日付文字列を渡すと、parse()
はタイムゾーンを地方時として想定しますが、"2014-03-07"
のような ISO 書式を与えると UTC のタイムゾーンを想定します (ES5 および ECMAScript 2015 の仕様)。そのため、これらの文字列を使用して生成した Date
オブジェクトは、システムが UTC と同じタイムゾーンに設定されていない限り、サポートされる ECMAScript のバージョンに依存して異なる時刻を表す可能性があります。これは、2 つの同じ日付を表す文字列の結果が、変換される与えた文字列の書式の違いによって、異なる値になる可能性があることを意味します。
実装特有の日付書式へのフォールバック
ECMAScript 仕様の状況: 与えた文字列が標準仕様の書式になっていない場合、この関数は、実装特有のヒューリスティクスまたは実装特有の解釈アルゴリズムにフォールバックします。解釈できない文字列や ISO 書式文字列における不正な要素値を含む日付を渡すと、Date.parse()
は NaN
を返すでしょう。
しかし、日付文字列の不正な値は、ECMA-262 で定義された ISO 書式として理解されず、ブラウザや与えた値に依存して、結果的に NaN
を返すかもしれません。その例:
// 不正な値を持つ 非 ISO 文字列 new Date('23/25/2014');
これは、Firefox 30 では、地方時の 2015 年 11 月 25 日として扱われ、Safari 7 では不正な値として処理されます。しかし、文字列が ISO 書式の文字列として理解され、不正な値を含む場合、ES5 以降の仕様に準拠するすべてのブラウザが 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
例
Date.parse()
を使う
IPOdate
が既存の Date
オブジェクトならば、次のようにして、これを 1995 年 8 月 9 日 (地方時) にセットできます:
IPOdate.setTime(Date.parse('Aug 9, 1995'));
他の非標準の日付文字列の解釈の例:
Date.parse('Aug 9, 1995');
タイムゾーン GMT+0900 では 807894000000
を返し、他のタイムゾーンでは他の値を返します。タイムゾーンが指定されておらず ISO 書式でないため、デフォルトで地方時のタイムゾーンが使用されます。
Date.parse('Wed, 09 Aug 1995 00:00:00 GMT');
GMT (UTC) が指定されているため、地方時のタイムゾーンに関わらず、807926400000
を返します。
Date.parse('Wed, 09 Aug 1995 00:00:00');
タイムゾーン GMT+0900 では 807894000000
を返し、他のタイムゾーンでは他の値を返します。引数にタイムゾーンが指定されておらず、非 ISO 書式であるため、地方時として扱われます。
Date.parse('Thu, 01 Jan 1970 00:00:00 GMT');
GMT (UTC) のタイムゾーンが指定されているため、地方時のタイムゾーンに関わらず 0
を返します。
Date.parse('Thu, 01 Jan 1970 00:00:00');
タイムゾーン GMT+0900 では -32400000
を返し、他のタイムゾーンでは他の値を返します。タイムゾーンが指定されておらず、非 ISO 書式であるため、地方時のタイムゾーンが使用されます。
Date.parse('Thu, 01 Jan 1970 00:00:00 GMT-0400');
GMT (UTC) のタイムゾーンが指定されているため、地方時のタイムゾーンに関わらず 14400000
を返します。
仕様
仕様書 | 策定状況 | 備考 |
---|---|---|
ECMAScript 1st Edition (ECMA-262) | 標準 | 初期定義。JavaScript 1.0 で実装。 |
ECMAScript 5.1 (ECMA-262) Date.parse の定義 |
標準 | ISO 8601 書式が追加された。 |
ECMAScript 2015 (6th Edition, ECMA-262) Date.parse の定義 |
標準 | |
ECMAScript 2017 Draft (ECMA-262) Date.parse の定義 |
ドラフト |
ブラウザの実装状況
機能 | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
基本サポート | (有) | (有) | (有) | (有) | (有) |
ISO 8601 書式 | (有) | 4.0 (2.0) | 9 | (有) | (有) |
機能 | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
基本サポート | ? | (有) | (有) | ? | ? | ? |
ISO 8601 書式 | ? | (有) | (有) | ? | (有) | (有) |
互換性ノート
- Firefox 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46) で、2 桁の「年」の解釈が、Internet Explorer に代わって Google Chrome ブラウザに沿うように変更されました。現在、
50
以下の 2 桁の「年」は 21 世紀の年として解釈されます。例えば04/16/17
は、以前は 1917 年 4 月 16 日と解釈されていましたが、現在は 2017 年 4 月 16 日と解釈されます。これは、相互運用性の問題や不明瞭な年を回避しますが、実装により異なる値を避けるため、"2017-04-16" のような ISO 8601 書式の使用が推奨されます (バグ 1265136)。