Gerenciamento de datas de calendário e horas

A classe Date tem um dos métodos de construtor mais versáteis de todas as classes básicas. É possível chamá-la de quatro formas diferentes.

Primeiro, se não houver nenhum parâmetro, o construtor Date() retornará um objeto de Date que contém data e hora atuais, com base no seu fuso horário local. Eis um exemplo:

var now:Date = new Date();

Segundo, se houver um único parâmetro numérico, o construtor Date() irá tratá-lo como o número de milissegundos desde 1º de janeiro de 1970 e retornará um objeto de Date correspondente. Observe que o valor de milissegundos fornecido é tratado como o número de milissegundos desde 1º de janeiro de 1970, em UTC. No entanto, o objeto Date mostra valores no seu fuso horário local, a não ser que você use métodos específicos de UTC para recuperá-los e exibi-los. Se você criar um novo objeto Date usando um único parâmetro de milissegundos, leve em consideração a diferença de fuso entre o horário local e o UTC. As seguintes instruções criam um objeto Date definido como meia-noite do dia 1º de janeiro de 1970, em 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);

Terceiro, é possível transmitir vários parâmetros numéricos para o construtor Date(). Esses parâmetros são tratados como ano, mês, dia, hora, minuto, segundo e milissegundo, respectivamente, e um objeto Date correspondente é retornado. Supõe-se que esses parâmetros de entrada estão no horário local, não no UTC. As seguintes instruções obtêm um objeto Date definido como meia-noite do dia 1º de janeiro de 2000, no horário local:

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

Quarto, é possível transmitir um parâmetro com uma única string para o construtor Date(). O construtor tentará analisar os componentes de data ou hora dessa string e retornará um objeto Date correspondente. Se você usar essa abordagem, é recomendado colocar o construtor Date() entre um bloco try..catch para detectar qualquer erro de análise. O construtor Date() aceita diversos formatos diferentes de seqüências de caracteres (que estão listados na Referência do ActionScript 3.0 para a plataforma Adobe Flash). A instrução a seguir inicializa um novo objeto Date usando um valor de string:

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

Se o construtor Date() não conseguir analisar o parâmetro de string, não lançará uma exceção. No entanto, o objeto Date resultante terá um valor de data inválido.

Você pode extrair valores para várias unidades de tempo de um objeto Date usando propriedades ou métodos da classe Date. Cada propriedade a seguir fornece o valor de uma unidade de tempo no objeto Date:

• A propriedade fullYear

• A propriedade month, que está em um formato numérico que vai de 0 para janeiro até 11 para dezembro

• A propriedade date, que é o número do calendário do dia do mês, no intervalo de 1 a 31

• A propriedade day, que é o dia da semana em formato numérico, com 0 para domingo

• A propriedade hours, no intervalo de 0 a 23

• A propriedade minutes

• A propriedade seconds

• A propriedade milliseconds

  Na realidade, a classe Date fornece diversas maneiras para obter cada um desses valores. Você pode obter, por exemplo, o valor do mês de um objeto Date de quatro formas diferentes:

• A propriedade month

• O método getMonth()

• A propriedade monthUTC

• O método getMonthUTC()

  Os quatro métodos são praticamente iguais em termos de eficiência, de modo que você pode usar a abordagem mais adequada para seu aplicativo.

  Todas as propriedades listadas acima representam componentes do valor de data total. Por exemplo, a propriedade milliseconds nunca será maior do que 999, pois, quando atingir o número 1000, o valor da propriedade seconds aumentará em uma unidade e a propriedade milliseconds será zerada.

  Se desejar obter o valor do objeto Date em termos de milissegundos desde 1º de janeiro de 1970 (UTC), use o método getTime(). Seu correspondente, o método setTime(), permite alterar o valor de um objeto Date existente usando os milissegundos desde 1º de janeiro de 1970 (UTC).

É possível realizar operações de adição e subtração em datas e horas com a classe Date. Os valores de Date são mantidos internamente em termos de milissegundos, de modo que você deve converter outros valores em milissegundos antes de adicioná-los ou subtraí-los dos objetos Date.

Se o seu aplicativo efetua vários cálculos aritméticos de data e hora, crie constantes que armazenam valores comuns de unidade de tempo em milissegundos, conforme mostrado a seguir:

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

Agora é fácil efetuar cálculos aritméticos de data usando unidades de tempo padrão. O código a seguir define um valor de data como uma hora do horário atual usando os métodos getTime() e setTime():

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

Outra maneira de definir um valor de data é criar um novo objeto Date usando um único parâmetro de milissegundos. Por exemplo, o código a seguir adiciona 30 dias a uma data para calcular outra:

// 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));

Em seguida, a constante millisecondsPerDay é multiplicada por 30 para representar o período de 30 dias e o resultado é adicionado ao valor invoiceDate e usado para definir o valor dueDate.

Cálculos aritméticos de data e hora são úteis quando você deseja converter datas de um fuso horário para outro. O método getTimezoneOffset() serve para isso, pois retorna o valor como a diferença de minutos entre o fuso horário do objeto Date e o UTC. Ele retorna um valor em minutos porque nem todos os fusos horários são definidos como incrementos de horas inteiras - alguns têm diferenças de meia hora em relação às zonas vizinhas.

O exemplo a seguir usa a diferença de fuso para converter uma data do horário local em UTC. Para fazer a conversão, primeiro calcula-se o valor do fuso horário em milissegundos e, depois, ajusta-se o valor de Date de acordo com o resultado:

// 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);