Date: o que é, tipo de tempo e TimeInterval em Foundation

O que é Date no Foundation?

Date é um tipo valor do framework Foundation que captura um único momento absoluto no tempo. Ao contrário das representações de calendário (ano, mês, dia), Date não depende de fuso horário ou sistema de calendário — é um valor de timestamp puramente numérico.

A representação interna de Date é TimeInterval (um alias de tipo para Double), armazenando o número de segundos relativos à data de referência — 1º de janeiro de 2001, 00:00:00 UTC. A Apple escolheu esta data em vez da época Unix (1970) para compatibilidade com sistemas legados NeXTSTEP, sobre os quais iOS e macOS foram construídos.

Date é usado como o tipo de tempo padrão em todas as APIs da Apple: UIDatePicker, DatePicker, UserDefaults, Codable, Core Data, CloudKit. Sem Date, é impossível trabalhar com agendas, temporizadores, eventos de calendário, serialização de dados e qualquer operação relacionada ao tempo.

Date vs outros tipos de tempo

Date difere dos tipos de calendário por representar um timestamp físico em vez de um valor legível por humanos. O mesmo Date pode corresponder a diferentes datas de calendário em diferentes fusos horários. Para extrair componentes (ano, mês, dia), Date é convertido através de Calendar e DateComponents.

Date também difere de DispatchTime, que é usado para despacho de tarefas no Grand Central Dispatch. DispatchTime é relativo ao momento de inicialização do sistema, enquanto Date é um timestamp absoluto que pode ser salvo, transmitido e restaurado.

Criar Date em Swift

Date() é a maneira mais simples de criar um objeto com o momento atual. O inicializador sem parâmetros retorna a hora exata da chamada. Para criar uma data no passado ou futuro, use TimeInterval e o método addingTimeInterval, ou inicialização a partir de um Date existente.

Para criar uma data arbitrária a partir de componentes, use o par Calendar e DateComponents. Calendar converte componentes legíveis por humanos (ano, mês, dia, hora, minuto) em Date. Você também pode inicializar Date através de ISO8601DateFormatter a partir de uma string ISO 8601, ou através de DateFormatter a partir de uma representação de string arbitrária.

Date.distantPast e Date.distantFuture são duas propriedades estáticas que representam momentos infinitamente distantes no passado e no futuro. Elas são usadas como valores limite para filtrar e ordenar datas em algoritmos.

import Foundation

// Criar Date com a hora atual
let now = Date()
print("Current time: \(now)")

// Data em 1 hora (3600 segundos)
let inOneHour = now.addingTimeInterval(3600)

// Data a partir de componentes
var components = DateComponents()
components.year = 2025
components.month = 12
components.day = 25
let christmas = Calendar.current.date(from: components)!

O exemplo mostra três maneiras de criar um Date: hora atual, adicionando um intervalo e criando via DateComponents. Todas as três abordagens retornam um valor do tipo Date com precisão de milissegundos. Calendar.current usa o calendário do sistema do usuário — em dispositivos Apple, este é tipicamente o calendário gregoriano.

TimeInterval e comparação de datas

TimeInterval é um alias de tipo para Double que representa o número de segundos entre dois momentos no tempo. A precisão do TimeInterval atinge frações de milissegundo, suficiente para a maioria das tarefas práticas. Um TimeInterval negativo indica o passado em relação ao ponto de referência.

Date suporta todos os operadores de comparação padrão: ==, <, >, <=, >=. Swift compara automaticamente os valores internos de TimeInterval. O método compare retorna ComparisonResult com as opções .orderedSame, .orderedAscending, .orderedDescending para uma comparação mais explícita.

Date.distance(to:) é um método que retorna o TimeInterval até a data especificada. Se a data alvo está no passado, o resultado é negativo. advanced(by:) cria uma nova data adicionando o TimeInterval especificado à atual. Esses métodos implementam o protocolo Strideable, permitindo usar Date em Range e ClosedRange.

let start = Date()
let end = start.addingTimeInterval(86400)

// Comparação usando operadores
if start < end {
    print("start is earlier")
}

// TimeInterval entre duas datas
let interval: TimeInterval = end.timeIntervalSince(start)
print("Seconds: \(Int(interval / 60)) minutes")

// Usar Date em um intervalo
let range = start...end
let mid = start.addingTimeInterval(43200)
if range.contains(mid) {
    print("mid is between start and end")
}

TimeInterval de 86400 corresponde a um dia. Para intervalos mais complexos — semanas, meses, anos — use Calendar e DateComponents, pois essas unidades têm comprimento variável (anos bissextos, horário de verão). TimeInterval é aplicável apenas para intervalos fixos em segundos.

Calendar e DateComponents

Calendar é a ponte entre Date e componentes legíveis por humanos. Calendar converte Date em DateComponents (ano, mês, dia, hora, minuto, segundo) levando em conta fuso horário e localidade. Sem Calendar, é impossível extrair o ano ou mês de Date — Date não contém esta informação devido à sua natureza absoluta.

O método Calendar.component extrai um único componente de Date: ano, mês, dia, hora, minuto, segundo, dia da semana, trimestre. O método Calendar.dateComponents extrai um conjunto de componentes em uma única chamada — isto é mais eficiente do que chamar component para cada campo separadamente.

Calendar.isDateInToday, isDateInTomorrow, isDateInYesterday são métodos convenientes para verificar datas relativas. Calendar.dateInterval retorna o início e o fim do período especificado (dia, semana, mês, ano). Calendar.compare compara datas com precisão até o componente especificado — por exemplo, ano sem considerar mês e dia.

let calendar = Calendar.current

// Extrair componentes
let year = calendar.component(.year, from: Date())
let month = calendar.component(.month, from: Date())

// Verificar data relativa
if calendar.isDateInToday(someDate) {
    print("Today!")
}

// Início e fim do dia
let dayInterval = calendar.dateInterval(of: .day, for: Date())!
print("Day start: \(dayInterval.start)")
print("Day end: \(dayInterval.end)")

Calendar.current usa as configurações do sistema do usuário — calendário, fuso horário e localidade. Para testes ou cálculos específicos, você pode criar um Calendar com parâmetros específicos através de Calendar(identifier: .gregorian) e definir o fuso horário desejado através da propriedade timeZone.

DateFormatter e exibição de datas

DateFormatter é um componente obrigatório se Date precisa ser exibido ao usuário. DateFormatter converte Date em uma string de acordo com o formato e localidade especificados. Converter Date diretamente para string via String(describing:) retorna uma representação técnica com a data de referência e TimeInterval — não é destinada a usuários.

A abordagem básica é usar os estilos predefinidos dateStyle e timeStyle. iOS suporta quatro estilos: .short, .medium, .long, .full. A combinação de estilos de data e hora permite configuração flexível de exibição. DateFormatter aplica localização automaticamente: para a localidade russa, a data será exibida no formato “21 de julho de 2026”.

ISO8601DateFormatter é um formatador especializado para ISO 8601, o formato mais comum para API e troca de dados. Este formatador funciona mais rápido que DateFormatter e não depende de localidade, tornando-o preferível para serializar datas em JSON.

// Estilos predefinidos
let formatter = DateFormatter()
formatter.dateStyle = .medium
formatter.timeStyle = .short
let userString = formatter.string(from: Date())

// ISO 8601 para API
let isoFormatter = ISO8601DateFormatter()
let apiString = isoFormatter.string(from: Date())

// Análise a partir de string
let parsed = isoFormatter.date(from: "2026-07-21T10:30:00Z")!

Ao trabalhar com DateFormatter, é importante lembrar do desempenho: criar um novo formatador é uma operação cara. Recomenda-se armazenar em cache o formatador ou criá-lo uma vez e reutilizá-lo. As propriedades do formatador permitem configurar timeZone — por padrão, o fuso horário do sistema é usado, mas para datas de servidor, TimeZone(identifier: “UTC”) é frequentemente necessário.

Exemplos de uso do Date

Vamos considerar cenários típicos para trabalhar com Date em um aplicativo iOS. O primeiro cenário é calcular a idade a partir da data de nascimento do usuário. O segundo é um temporizador de contagem regressiva para um evento. O terceiro é agrupar registros por data para exibição como seções de tabela.

Calcular a idade a partir da data de nascimento

Calendar.dateComponents com a flag [.year] calcula a diferença entre duas datas. Definir o fuso horário correto é crítico — se você não especificar timeZone em Calendar, o resultado pode diferir em um dia devido à passagem da meia-noite em outro fuso horário.

func calculateAge(from birthDate: Date) -> Int {
    let calendar = Calendar.current
    let now = Date()
    let components = calendar.dateComponents(
        [.year], from: birthDate, to: now
    )
    return components.year ?? 0
}

Temporizador de contagem regressiva é implementado usando TimeInterval. Calcule a diferença entre a data alvo e a data atual, obtenha o resto em segundos e converta em dias, horas, minutos. Para atualizações regulares, use Timer com intervalo de 1 segundo. Um ObservableObject com uma propriedade @Published permite que SwiftUI atualize automaticamente a interface.

Agrupar por data é implementado usando um dicionário com Date como chave. Calendar.dateInterval(of: .day, for:) normaliza a data para o início do dia, permitindo agrupar registros pertencentes ao mesmo dia. A mesma abordagem funciona para semanas, meses e anos — basta alterar o componente em dateInterval para .weekOfYear ou .month.