O objeto system.date fornece uma coleção de métodos para manipulação de datas e horas. A seguir, uma visão geral das funcionalidades disponíveis.
Métodos Principais
A tabela abaixo resume as funções essenciais para operações com datas.
| Método | Retorno | Descrição |
|---|---|---|
system.date.ehData(valor_data) |
Boolean |
Verifica se o valor fornecido é uma data válida. |
system.date.formatar(data, formato) |
String |
Converte uma data para uma string no formato especificado. |
system.date.entreDatas(data, dataInicio, dataFim) |
Boolean |
Verifica se uma data está dentro de um intervalo inclusivo. |
system.date.paraTimestamp(data, fusoHorario) |
Number |
Converte uma data para um timestamp Unix (em segundos). |
system.date.deTimestamp(timestamp, fusoHorario) |
Date |
Converte um timestamp Unix de volta para um objeto Date. |
system.date.agora() |
Date |
Retorna a data e hora atuais do servidor. |
Exemplo de Uso: Formatação e Validação
// Verificando se um valor é uma data
const entrada = "2023-12-25";
const isValida = system.date.ehData(entrada); // true
// Formatando uma data para um padrão brasileiro
const dataOriginal = new Date();
const dataFormatada = system.date.formatar(dataOriginal, "dd/MM/yyyy HH:mm:ss"); // Ex: "25/12/2023 14:30:00"
// Verificando se uma data está dentro de uma promoção
const inicioPromocao = "2023-12-01";
const fimPromocao = "2023-12-31";
const dataDaCompra = "2023-12-25";
const emPromocao = system.date.entreDatas(dataDaCompra, inicioPromocao, fimPromocao); // true
Extração e Modificação de Componentes
Estes métodos permitem ler e alterar partes específicas de uma data.
| Método | Retorno | Descrição |
|---|---|---|
system.date.obterAno(data) |
Number |
Retorna o ano. |
system.date.obterMes(data) |
Number |
Retorna o mês (1-12). |
system.date.obterDia(data) |
Number |
Retorna o dia do mês. |
system.date.obterDiaSemana(data) |
Number |
Retorna o dia da semana (1=Dom, 2=Seg, ..., 7=Sáb). |
system.date.definirAno(data, novoAno) |
Date |
Retorna uma nova data com o ano alterado. |
system.date.definirMes(data, novoMes) |
Date |
Retorna uma nova data com o mês alterado. |
Exemplo de Uso: Manipulação de Componentes
const evento = system.date.agora();
const anoEvento = system.date.obterAno(evento); // 2023
const mesEvento = system.date.obterMes(evento); // 12
// Criando uma nova data para o próximo ano
const eventoProximoAno = system.date.definirAno(evento, anoEvento + 1);
Cálculos de Diferença e Aritmética de Datas
Funções para calcular diferenças entre datas ou adicionar períodos a elas.
| Método | Retorno | Descrição |
|---|---|---|
system.date.diferencaDias(dataA, dataB) |
Number |
Retorna a diferença em dias. O resultado pode ser negativo. |
system.date.diferencaHoras(dataA, dataB) |
Number |
Retorna a diferença em horas. |
system.date.somarDias(data, quantidade) |
Date |
Retorna uma nova data com dias adicionados (ou subtraídos, se negativo). |
system.date.somarMeses(data, quantidade) |
Date |
Retorna uma nova data com meses adicionados. |
Exemplo de Uso: Cálculo de Diferenças
const dataNascimento = "1990-05-15";
const dataAtual = system.date.agora();
// Calculando a idade aproximada em dias
const diasVividos = system.date.diferencaDias(dataAtual, dataNascimento);
// Adicionando 3 meses a uma data de vencimento
const fatura = "2023-11-01";
const novaDataVencimento = system.date.somarMeses(fatura, 3); // "2024-02-01"
Utilitário: Temporizador de Performance
Para medir o tempo de execução de trechos de código.
// Iniciar a contagem
system.date.iniciarTemporizador("processamentoDados");
// ... Bloco de código cujo desempenho deseja-se medir ...
// Exemplo: processar um grande array de dados
const arrayGrande = [];
for (let i = 0; i < 1000000; i++) {
arrayGrande.push(Math.random());
}
const soma = arrayGrande.reduce((acumulador, valor) => acumulador + valor, 0);
// Finalizar e obter o resultado
const tempoMs = system.date.obterTemporizador("processamentoDados");
console.log(`Operação concluída em ${tempoMs} milissegundos.`);