La méthode Date.parse() analyse la représentation textuelle d'une date, et renvoie le nombre de millisecondes depuis le 1er janvier 1970, 00:00:00 UTC jusqu'à cette date ou NaN si la chaîne n'est pas reconnue ou décrit une date invalide (par exemple 2015-02-31).
Note : Pour les anciennes implémentations (avant ES5), le résultat de Date.parse variait d'une implémentation à l'autre. Attention donc à la compatibilité avec ces anciennes versions.
Syntaxe
Appel direct :
Date.parse(dateString)
Appel implicite :
new Date(dateString)
Paramètres
dateString- Une chaine de caractères représentant une date RFC2822 ou ISO 8601 (d'autres formats peuvent être utilisés mais les résultats ne sont pas garantis).
Description
La méthode parse prend en argument une chaine de caractères contenant une date en paramètre (comme "Dec 25, 1995") et renvoie le nombre de millièmes de secondes depuis le 1er janvier 1970, 00:00:00 UTC. Cette fonction est utile pour définir des valeurs de dates à partir de représentations textuelles, par exemple en conjonction avec la méthode {{jsxref("Objets_globaux/Date/setTime", "setTime()")}} et l'objet {{jsxref("Objets_globaux/Date", "Date")}}.
À partir d'une chaine de caractères représentant une date, parse renvoie une valeur de temps. Elle accepte la syntaxe de date standard RFC2822 / IETF : "Mon, 25 Dec 1995 13:30:00 GMT" (RFC2822 Section 3.3). Elle comprend les abréviations de fuseaux horaires continentaux des États-Unis, mais en général on utilisera plutôt un décalage horaire, par exemple "Mon, 25 Dec 1995 13:30:00 +0430" (4 heures 30 minutes à l'est du méridien de Greenwich). Si aucun fuseau horaire n'est spécifié et que la chaîne est dans une format ISO reconnu par ES5, on suppose qu'il s'agit de l'heure UTC. En revanche, avec ECMAScript 2015 (ES6), les dates au format ISO sans fuseau sont traitées comme des dates locales.
Les indicateurs GMT et UTC sont considérés comme équivalents. Le fuseau horaire local est utilisé afin d'interpréter des arguments au format décrit par la Section 3.3 de la RFC2822 qui ne comportent pas d'informations sur le fuseau à utiliser (de même pour les formats non ISO 8601 supportés par ES5).
ECMAScript 5 et support du format ISO-8601
Il est aussi possible d'écrire la date au format ISO 8601. Par exemple, "2011-10-10" (seulement la date) ou "2011-10-10T14:48:00" (la date et l'heure) peuvent être interprétées. Le fuseau horaire local est utilisé pour interpréter les arguments au format ISO 8601 qui ne contiennent pas un fuseau horaire. Il est à noter que ECMAScript 2015 définit qu'une chaîne de date/heure sans fuseau doit être traitée comme une date/heure locale (et non comme une date/heure UTC).
On notera quen bien que les indications de fuseau horaire soient utilisées lors de l'interprétation de la chaine de caractères pour l'interpréter correctement, elles n'affectent pas la valeur renvoyée, qui est toujours le nombre de millisecondes depuis le 1er janvier 1970, 00:00:00 UTC et l'instant dans le temps représenté par dateString.
Comme parse est une méthode statique de Date, on l'utilise toujours sous la forme Date.parse(), plutôt que comme une méthode d'un objet Date qui aurait été créé en script.
Différences entre les fuseaux horaires supposés
Avec une chaîne comme "March 7, 2014", parse() supposera un fuseau horaire local, avec une chaîne au format ISO comme "2014-03-07", la méthode supposera un fuseau horaire UTC en ES5 et un fuseau horaire local pour ECMAScript 2015. Ainsi les objets {{jsxref("Date")}} construits avec ces chaînes représenteront des instants différents, sauf si le fuseau horaire local du système utilisé correspond à UTC. Cela signifie que deux dates représentées de façon textuelles semblables peuvent donner des dates différentes (ce comportement doit être corrigé avec ECMAScript 6 afin que les deux dates soient traitées de façon locale).
Traitement laissé libre à l'implémentation
Le standard ECMAScript dicte que si la chaîne utilisée n'est pas conforme au format standard, alors la fonction peut utiliser une heuristique et/ou un algorithme d'analyse de texte propre à l'implémentation. Les chaînes impossibles à décoder et/ou qui contiennent des éléments non-conformes aux formats ISO doivent renvoyer {{jsxref("NaN")}} lors de l'appel à Date.parse().
Cependant, les valeurs invalides qui ne sont pas reconnues dans un format ISO pris en charge par ECMA-262 peuvent ou non engendrer la valeur {{jsxref("NaN")}} selon le navigateur et les valeurs utilisées. Par exemple :
// Chaîne non ISO avec des valeurs invalides
new Date('23/25/2014');
sera traitée comme la date locale du 25 novembre 2015 avec Firefox 30 et comme invalide avec Safari 7. Cependant, si la chaîne est reconnue dans un format ISO mais contient des valeurs invalides, la méthode renverra {{jsxref("NaN")}} pour tous les navigateurs conformes à ES5 (ou aux versions ultérieures) :
// Chaîne ISO avec des valeurs invalides new
Date('2014-25-23').toISOString();
// renvoie "RangeError: invalid date" pour les navigateurs ES5
L'implémentation spécifique de SpiderMonkey peut être trouvée dans le fichier jsdate.cpp. La chaîne "10 06 2014" est un exemple de chaîne non ISO, utiliser parse() sur cette chaîne entraînera le moteur JavaScript à utiliser son implémentation de recours. Voir ce bug pour une explication rapide de la façon dont est faite l'analyse de la chaîne.
new Date('10 06 2014');
sera traitée comme la date locale du 6 octobre 2014 et non comme le 10 juin 2014. D'autres exemples :
new Date('toto-truc 2014').toString();
// renvoie : "Invalid Date"
Date.parse('toto-truc 2014');
// renvoie : NaN
Exemples
Utiliser Date.parse()
Si IPOdate est un objet {{jsxref("Date")}} existant, vous pouvez le positionner au 9 août 1995 comme suit :
IPOdate.setTime(Date.parse("Aug 9, 1995"));
D'autres exemples :
// Renvoie 807937200000 dans le fuseau horaire GMT-0300, et d'autres valeurs dans d'autres
// fuseaux horaires, puisque il n'y a aucun fuseau horaire indiqué.
Date.parse("Aug 9, 1995");
// Renvoie 807926400000 quel que soit le fuseau horaire local.
Date.parse("Wed, 09 Aug 1995 00:00:00 GMT");
// Renvoie 807937200000 dans le fuseau horaire GMT-0300, et d'autres valeurs dans d'autres
// fuseaux horaires, puisque il n'y a aucun fuseau horaire indiqué.
Date.parse("Wed, 09 Aug 1995 00:00:00");
// Renvoie 0 quel que soit le fuseau horaire local.
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT");
// Renvoie 14400000 dans le fuseau horaire GMT-0400, et d'autres valeurs dans d'autres
// fuseaux horaires, puisque il n'y a aucun fuseau horaire indiqué.
Date.parse("Thu, 01 Jan 1970 00:00:00");
// Renvoie 14400000 quel que soit le fuseau horaire local.
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT-0400");
Spécifications
| Spécification | Statut | Commentaires |
|---|---|---|
| {{SpecName('ES1')}} | {{Spec2('ES1')}} | Définition initiale. Implémentée avec JavaScript 1.0. |
| {{SpecName('ES5.1', '#sec-15.9.4.2', 'Date.parse')}} | {{Spec2('ES5.1')}} | Ajout du format ISO 8601. |
| {{SpecName('ES6', '#sec-date.parse', 'Date.parse')}} | {{Spec2('ES6')}} | |
| {{SpecName('ESDraft', '#sec-date.parse', 'Date.parse')}} | {{Spec2('ESDraft')}} |
Compatibilité des navigateurs
| Fonctionnalité | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|
| Support simple | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
| Format ISO 8601 | {{CompatVersionUnknown}} | {{CompatGeckodesktop("2.0")}} | {{CompatIE("9")}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
| Fonctionnalité | Android | Chrome pour Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|---|
| Support simple | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
| Format ISO 8601 | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
Voir aussi
- {{jsxref("Date.UTC()")}}