Gestion des dates calendaires et des heures

La classe Date compte l’une des méthodes constructeur les plus polyvalentes de toutes les classes de base. Vous pouvez l’invoquer de quatre manières différentes.

Primo, si aucun paramètre n’est fourni, le constructeur Date() renvoie un objet Date contenant la date et l’heure locale actuelle de votre fuseau horaire. Exemple :

var now:Date = new Date();

Secundo, si un paramètre numérique unique est fourni, le constructeur Date() le considère comme le nombre de millisecondes écoulées depuis le 1er janvier 1970 et renvoie l’objet Date correspondant. Notez que la valeur en millisecondes que vous transmettez est considérée comme le nombre de millisecondes depuis le 1er janvier 1970 en temps UTC. Toutefois, l’objet Date affiche des valeurs dans votre fuseau horaire local, sauf si vous utilisez des méthodes UTC uniquement pour les extraire et les afficher. Si vous créez un nouvel objet Date à l’aide du paramètre en millisecondes, veillez à tenir compte du décalage horaire entre votre fuseau local et le temps UTC. Les instructions ci-après créent un objet Date défini à minuit le 1er janvier 1970 en temps UTC :

var millisecondsPerDay:int = 1000 * 60 * 60 * 24; 
// gets a Date one day after the start date of 1/1/1970 
var startTime:Date = new Date(millisecondsPerDay);

Tertio, vous pouvez transmettre plusieurs paramètres numériques au constructeur Date() . Celui-ci les traite respectivement comme la date, le mois, le jour, les heures, les minutes, les secondes et les millisecondes, et renvoie un objet Date correspondant. Les paramètres indiqués sont considérés comme correspondant à l’heure locale plutôt qu’au temps UTC. Les instructions suivantes établissent un objet Date défini à minuit le 1er janvier 2000, dans le fuseau horaire local :

var millenium:Date = new Date(2000, 0, 1, 0, 0, 0, 0);

Quarto, vous pouvez transmettre un paramètre numérique unique au constructeur Date() . Celui-ci essaiera d’analyser cette chaîne en composants de date et heure, et de renvoyer un objet Date correspondant. Si vous choisissez cette approche, il est recommandé d’inclure le constructeur Date() dans un bloc try..catch afin d’intercepter toute erreur d’analyse. Le constructeur Date() gère plusieurs formats de chaîne (dont la liste figure dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash ). L’instruction suivante initialise un nouvel objet Date à l’aide d’une valeur chaîne :

var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM");

Si le constructeur Date() ne peut analyser le paramètre chaîne, il ne déclenche pas d’exception. Cependant, l’objet Date résultant contiendra une valeur date incorrecte.

Vous pouvez extraire les valeurs de plusieurs unités temporelles au sein de l’objet Date grâce à des propriétés ou des méthodes de la classe Date. Chacune des propriétés suivantes fournit la valeur d’une unité temporelle de l’objet Date :

• La propriété fullYear

• La propriété month au format numérique : de 0 pour janvier à 11 pour décembre

• La propriété date , qui correspond au numéro calendaire du jour du mois, de 1 à 31

• La propriété day , qui correspond au jour de la semaine au format numérique, 0 représentant dimanche

• La propriété hours , de 0 à 23

• La propriété minutes

• La propriété seconds

• La propriété milliseconds

  La classe Date offre en fait plusieurs manières d’obtenir ces valeurs. Vous pouvez par exemple obtenir la valeur month de l’objet Date de quatre manières :

• La propriété month

• La méthode getMonth()

• La propriété monthUTC

• La méthode getMonthUTC()

  Ces quatre solutions sont d’une efficacité équivalente, vous pouvez donc adopter celle qui convient le mieux à votre application.

  Les propriétés répertoriées ci-dessus représentent toutes des composants de la valeur date totale. Par exemple, la propriété milliseconds ne sera jamais supérieure à 999, puisque si elle atteint 1000, la valeur seconds augmente de 1, la propriété milliseconds se remet à zéro.

  Si vous voulez obtenir la valeur de l’objet Date en millisecondes depuis le 1er janvier 1970 (UTC), vous pouvez utiliser la méthode getTime() . La méthode setTime() , quant à elle, vous permet de modifier la valeur d’un objet Date existant en millisecondes depuis le 1er janvier 1970 (UTC).

La classe Date permet d’additionner et de soustraire des dates et heures. Les valeurs Date sont conservées en interne sous forme de millisecondes. Il est donc nécessaire de convertir les autres valeurs en millisecondes avant de les ajouter ou de les soustraire aux objets Date.

Si votre application doit effectuer de nombreuses opérations arithmétiques sur les dates et heures, il peut s’avérer utile de créer des constantes qui conservent les valeurs d’unités temporelles courantes en millisecondes, comme illustré ci-après :

public static const millisecondsPerMinute:int = 1000 * 60; 
public static const millisecondsPerHour:int = 1000 * 60 * 60; 
public static const millisecondsPerDay:int = 1000 * 60 * 60 * 24;

Il devient alors simple d’effectuer des opérations arithmétiques à l’aide des unités temporelles standard. Le code ci-après décale la valeur date d’une heure par rapport à l’heure actuelle à l’aide des méthodes getTime() et setTime() :

var oneHourFromNow:Date = new Date(); 
oneHourFromNow.setTime(oneHourFromNow.getTime() + millisecondsPerHour);

Une autre manière de définir une valeur date consiste à créer un objet Date à l’aide d’un seul paramètre en millisecondes. Par exemple, le code suivant ajoute 30 jours à une date pour en calculer une autre :

// sets the invoice date to today's date 
var invoiceDate:Date = new Date(); 
 
// adds 30 days to get the due date 
var dueDate:Date = new Date(invoiceDate.getTime() + (30 * millisecondsPerDay));

La constante millisecondsPerDay est ensuite multipliée par 30 pour représenter la période de 30 jours et le résultat est ajouté à la valeur invoiceDate afin de définir la valeur dueDate .

Les opérations arithmétiques sur les dates et heures sont particulièrement pratiques lorsque vous devez convertir des dates d’un fuseau horaire à un autre. Tel est le rôle de la méthode getTimezoneOffset() , qui renvoie la valeur (en minutes) de décalage entre le fuseau horaire de l’objet Date et le temps UTC. La valeur renvoyée s’exprime en minutes parce que tous les fuseaux horaires ne correspondent pas à une heure ; certains sont décalés d’une demi-heure par rapport aux fuseaux voisins.

L’exemple suivant utilise le décalage de fuseau horaire pour convertir une date à partir de l’heure locale en temps UTC. La conversion s’effectue tout d’abord par calcul de la valeur du fuseau horaire en millisecondes, puis par ajustement de la valeur Date selon ce montant :

// creates a Date in local time 
var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM"); 
 
// converts the Date to UTC by adding or subtracting the time zone offset 
var offsetMilliseconds:Number = nextDay.getTimezoneOffset() * 60 * 1000; 
nextDay.setTime(nextDay.getTime() + offsetMilliseconds);