Date: qué es, tipo de tiempo y TimeInterval en Foundation

¿Qué es Date en Foundation?

Date es un tipo valor del framework Foundation que captura un único momento absoluto en el tiempo. A diferencia de las representaciones de calendario (año, mes, día), Date no depende de la zona horaria ni del sistema de calendario — es un valor de marca de tiempo puramente numérico.

La representación interna de Date es TimeInterval (un alias de tipo para Double), que almacena el número de segundos relativos a la fecha de referencia — 1 de enero de 2001, 00:00:00 UTC. Apple eligió esta fecha en lugar de la época Unix (1970) por compatibilidad con los sistemas heredados NeXTSTEP, sobre los cuales se construyeron iOS y macOS.

Date se utiliza como el tipo de tiempo estándar en todas las API de Apple: UIDatePicker, DatePicker, UserDefaults, Codable, Core Data, CloudKit. Sin Date, es imposible trabajar con horarios, temporizadores, eventos de calendario, serialización de datos y cualquier operación relacionada con el tiempo.

Date frente a otros tipos de tiempo

Date se diferencia de los tipos de calendario en que representa una marca de tiempo física en lugar de un valor legible por humanos. El mismo Date puede corresponder a diferentes fechas de calendario en diferentes zonas horarias. Para extraer componentes (año, mes, día), Date se convierte a través de Calendar y DateComponents.

Date también se diferencia de DispatchTime, que se utiliza para el envío de tareas en Grand Central Dispatch. DispatchTime es relativo al momento de inicio del sistema, mientras que Date es una marca de tiempo absoluta que se puede guardar, transmitir y restaurar.

Crear Date en Swift

Date() es la forma más sencilla de crear un objeto con el momento actual. El inicializador sin parámetros devuelve la hora exacta de la llamada. Para crear una fecha en el pasado o futuro, use TimeInterval y el método addingTimeInterval, o la inicialización desde un Date existente.

Para crear una fecha arbitraria a partir de componentes, use el par Calendar y DateComponents. Calendar convierte componentes legibles por humanos (año, mes, día, hora, minuto) en Date. También puede inicializar Date a través de ISO8601DateFormatter desde una cadena ISO 8601, o a través de DateFormatter desde una representación de cadena arbitraria.

Date.distantPast y Date.distantFuture son dos propiedades estáticas que representan momentos infinitamente distantes en el pasado y el futuro. Se utilizan como valores límite para filtrar y ordenar fechas en algoritmos.

import Foundation

// Crear Date con la hora actual
let now = Date()
print("Current time: \(now)")

// Fecha en 1 hora (3600 segundos)
let inOneHour = now.addingTimeInterval(3600)

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

El ejemplo muestra tres formas de crear un Date: hora actual, agregando un intervalo y creando a través de DateComponents. Los tres enfoques devuelven un valor de tipo Date con precisión de milisegundos. Calendar.current utiliza el calendario del sistema del usuario — en dispositivos Apple, este suele ser el calendario gregoriano.

TimeInterval y comparación de fechas

TimeInterval es un alias de tipo para Double que representa el número de segundos entre dos momentos en el tiempo. La precisión de TimeInterval alcanza fracciones de milisegundo, suficiente para la mayoría de las tareas prácticas. Un TimeInterval negativo indica el pasado en relación con el punto de referencia.

Date admite todos los operadores de comparación estándar: ==, <, >, <=, >=. Swift compara automáticamente los valores internos de TimeInterval. El método compare devuelve ComparisonResult con las opciones .orderedSame, .orderedAscending, .orderedDescending para una comparación más explícita.

Date.distance(to:) es un método que devuelve el TimeInterval hasta la fecha especificada. Si la fecha objetivo está en el pasado, el resultado es negativo. advanced(by:) crea una nueva fecha agregando el TimeInterval especificado a la actual. Estos métodos implementan el protocolo Strideable, permitiendo usar Date en Range y ClosedRange.

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

// Comparación usando operadores
if start < end {
    print("start is earlier")
}

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

// Usar Date en un rango
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 un día. Para intervalos más complejos — semanas, meses, años — use Calendar y DateComponents, ya que estas unidades tienen longitud variable (años bisiestos, cambio de horario de verano). TimeInterval solo es aplicable para intervalos fijos en segundos.

Calendar y DateComponents

Calendar es el puente entre Date y los componentes legibles por humanos. Calendar convierte Date en DateComponents (año, mes, día, hora, minuto, segundo) teniendo en cuenta la zona horaria y la configuración regional. Sin Calendar, es imposible extraer el año o el mes de Date — Date no contiene esta información debido a su naturaleza absoluta.

El método Calendar.component extrae un solo componente de Date: año, mes, día, hora, minuto, segundo, día de la semana, trimestre. El método Calendar.dateComponents extrae un conjunto de componentes en una sola llamada — esto es más eficiente que llamar a component para cada campo por separado.

Calendar.isDateInToday, isDateInTomorrow, isDateInYesterday son métodos convenientes para verificar fechas relativas. Calendar.dateInterval devuelve el inicio y el final del período especificado (día, semana, mes, año). Calendar.compare compara fechas con precisión hasta el componente especificado — por ejemplo, año sin considerar mes y día.

let calendar = Calendar.current

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

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

// Inicio y fin del día
let dayInterval = calendar.dateInterval(of: .day, for: Date())!
print("Day start: \(dayInterval.start)")
print("Day end: \(dayInterval.end)")

Calendar.current utiliza la configuración del sistema del usuario — calendario, zona horaria y configuración regional. Para pruebas o cálculos específicos, puede crear un Calendar con parámetros específicos a través de Calendar(identifier: .gregorian) y configurar la zona horaria deseada mediante la propiedad timeZone.

DateFormatter y visualización de fechas

DateFormatter es un componente obligatorio si Date necesita mostrarse al usuario. DateFormatter convierte Date en una cadena según el formato y la configuración regional especificados. Convertir Date directamente a cadena mediante String(describing:) devuelve una representación técnica con la fecha de referencia y TimeInterval — no está destinada a los usuarios.

El enfoque básico es usar los estilos predefinidos dateStyle y timeStyle. iOS admite cuatro estilos: .short, .medium, .long, .full. La combinación de estilos de fecha y hora permite una configuración flexible de visualización. DateFormatter aplica automáticamente la localización: para la configuración regional rusa, la fecha se mostrará en el formato “21 de julio de 2026”.

ISO8601DateFormatter es un formateador especializado para ISO 8601, el formato más común para API e intercambio de datos. Este formateador funciona más rápido que DateFormatter y no depende de la configuración regional, lo que lo hace preferible para serializar fechas en 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álisis desde cadena
let parsed = isoFormatter.date(from: "2026-07-21T10:30:00Z")!

Al trabajar con DateFormatter, es importante recordar el rendimiento: crear un nuevo formateador es una operación costosa. Se recomienda almacenar en caché el formateador o crearlo una vez y reutilizarlo. Las propiedades del formateador permiten configurar timeZone — por defecto se usa la zona horaria del sistema, pero para fechas de servidor a menudo se requiere TimeZone(identifier: “UTC”).

Ejemplos de uso de Date

Consideremos escenarios típicos para trabajar con Date en una aplicación iOS. El primer escenario es calcular la edad a partir de la fecha de nacimiento del usuario. El segundo es un temporizador de cuenta regresiva para un evento. El tercero es agrupar registros por fecha para mostrarlos como secciones de tabla.

Calcular la edad a partir de la fecha de nacimiento

Calendar.dateComponents con el indicador [.year] calcula la diferencia entre dos fechas. Establecer la zona horaria correcta es crítico — si no se especifica timeZone en Calendar, el resultado puede diferir en un día debido al cruce de la medianoche en otra zona horaria.

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 cuenta regresiva se implementa usando TimeInterval. Calcule la diferencia entre la fecha objetivo y la fecha actual, obtenga el resto en segundos y conviértalo a días, horas, minutos. Para actualizaciones periódicas, use Timer con un intervalo de 1 segundo. Un ObservableObject con una propiedad @Published permite que SwiftUI actualice automáticamente la interfaz.

Agrupar por fecha se implementa usando un diccionario con Date como clave. Calendar.dateInterval(of: .day, for:) normaliza la fecha al inicio del día, lo que le permite agrupar registros que pertenecen al mismo día. El mismo enfoque funciona para semanas, meses y años — simplemente cambie el componente en dateInterval a .weekOfYear o .month.