# time.dkh: cálculos con fechas y zonas horarias `time.dkh` suma y resta tiempo a fechas, calcula diferencias, da el inicio y el fin de un día, semana, mes o año, convierte a ISO 8601 y a tiempo Unix, y trabaja con zonas horarias IANA (`America/Mexico_City`). Viene con la distribución de Devkron 2.0 (`Devkron.Ext.Base.dll`). ## Cuándo usarla - Rangos de reportes: del primer al último día del mes, esta semana. - Vencimientos: fecha de pago a 30 días, días de atraso. - Integraciones: las API usan ISO 8601 (`2026-10-27T14:30:05Z`) o tiempo Unix (los JWT). - Servidores en UTC que atienden clientes en varias zonas (México, Colombia, Venezuela). ```dkl #include "time.dkh" ``` ## Fechas en DKL Las fechas en DKL son **números** con el formato `AAAAMMDD.HHMMSS` (`20261027.143005` = 27 de octubre de 2026, 14:30:05), las mismas de `ndatetime.*`. No llevan zona horaria. Una fecha inválida da error (`date.add: fecha inválida …`). Unidades: `s` (segundos), `m` (minutos), `h` (horas), `d` (días), `sem` (semanas), `mes`, `a` (años). También se aceptan `seg`, `min`, `hora`, `dia`, `semanas`, `meses`, `año` y sus plurales. ## Funciones date.* | Función | Devuelve | Descripción | |---|---|---| | `date.now()` / `date.utc_now()` | fecha | Ahora, en la hora del servidor / en UTC | | `date.add(fecha, cantidad, unidad)` | fecha | Suma (con cantidad negativa, resta). Fin de mes ajustado: 31-ene + 1 mes = 28 o 29-feb | | `date.diff(fecha1, fecha2, unidad)` | número | `fecha1 - fecha2` en unidades completas; `mes` y `a` se cuentan por calendario (15-ene a 14-mar = 1 mes) | | `date.start(fecha, unidad)` | fecha | Inicio del día (`d`), semana (`sem`, el lunes), mes, año (`a`) u hora (`h`) | | `date.end(fecha, unidad)` | fecha | Último segundo de ese periodo | | `date.weekday(fecha)` | número | 0 = domingo … 6 = sábado | | `date.iso(fecha)` | cadena | `2026-10-27T14:30:05` | | `date.from_iso(cadena)` | fecha | Lee ISO 8601; si trae `Z` o desfase (`-06:00`), la convierte a la hora del servidor | | `date.unix(fecha)` / `date.from_unix(segundos)` | número / fecha | Segundos desde 1970, con la fecha en la hora del servidor | | `date.unix_utc(fecha)` / `date.from_unix_utc(segundos)` | número / fecha | Igual, con la fecha en UTC (lo que usan los JWT) | Atención al orden de `date.diff`: es la **primera menos la segunda**. Los días de atraso son `date.diff(hoy, vencimiento, "d")`. ## Funciones tz.* | Función | Devuelve | Descripción | |---|---|---| | `tz.now(zona)` | fecha | Hora actual en esa zona | | `tz.convert(fecha, origen, destino)` | fecha | Convierte una fecha de una zona a otra | | `tz.offset(zona, fecha)` | número | Minutos respecto de UTC en esa fecha (`-360` = UTC−6), con horario de verano si aplica | `zona` es un nombre IANA: `America/Mexico_City`, `America/Tijuana`, `America/Cancun`, `America/Bogota`, `America/Caracas`, `UTC`. Funcionan igual en Linux y en Windows. ## Ejemplo ```dkl #include "dkli.dkh" #! program "fechas" { #include "functions.dkh" #include "time.dkh" f = 20261027.143005 do print("Inicio de mes: " + str(date.start(f, "mes")) + " fin: " + str(date.end(f, "mes"))) do print("Semana (lunes a domingo): " + str(date.start(f, "sem")) + " - " + str(date.end(f, "sem"))) vence = date.add(f, 30, "d") do print("Vence a 30 días: " + str(vence) + " 31-ene + 1 mes: " + str(date.add(20260131, 1, "mes"))) do print("Días de atraso al 15-dic: " + str(date.diff(20261215, vence, "d")) + " meses: " + str(date.diff(20270314, 20270115, "mes"))) do print("Día de la semana: " + str(date.weekday(f))) do print("ISO: " + date.iso(f) + " desde ISO con Z: " + str(date.from_iso("2026-10-27T20:30:05Z"))) do print("Unix UTC: " + str(date.unix_utc(f)) + " de vuelta: " + str(date.from_unix_utc(1793111405))) do print("En Bogotá: " + str(tz.convert(f, "America/Mexico_City", "America/Bogota")) + " desfase CDMX: " + str(tz.offset("America/Mexico_City", f)) + " min") do print("Tijuana en julio: " + str(tz.offset("America/Tijuana", 20260715)) + " min") x = date.add(f, 1, "quincena") exception { do print(last_error()) } } ``` Salida en un servidor con la zona `America/Mexico_City`: ``` Inicio de mes: 20261001.000000 fin: 20261031.235959 Semana (lunes a domingo): 20261026.000000 - 20261101.235959 Vence a 30 días: 20261126.143005 31-ene + 1 mes: 20260228.000000 Días de atraso al 15-dic: 18 meses: 1 Día de la semana: 2 ISO: 2026-10-27T14:30:05 desde ISO con Z: 20261027.143005 Unix UTC: 1793111405 de vuelta: 20261027.143005 En Bogotá: 20261027.153005 desfase CDMX: -360 min Tijuana en julio: -420 min {1} Error en 'date.add. (date.add: unidad no reconocida 'quincena' (use s, m, h, d, sem, mes, a)Exception has been thrown by the target of an invocation.) [time.dkl][Ln= 18] ``` En un servidor en UTC, `date.from_iso("2026-10-27T20:30:05Z")` da `20261027.203005`: el resultado depende de la zona del servidor. ## Errores | Mensaje | Causa | |---|---| | `date.add: fecha inválida …` | El número no es una fecha `AAAAMMDD.HHMMSS` válida (también en las demás `date.*`) | | `date.add: unidad no reconocida '…' (use s, m, h, d, sem, mes, a)` | Unidad desconocida (también en `date.diff`) | | `date.start: use d, sem, mes, a o h` / `date.end: …` | Unidad no válida para un periodo | | `date.from_iso: fecha ISO 8601 inválida '…'` | Cadena mal formada | | `tz.now: zona horaria desconocida '…'` / `… no se indicó la zona horaria` | Nombre IANA inválido o vacío | | `tz.convert: la hora … no existe en … (cambio de horario)` | La hora cae en el salto del horario de verano | ## Advertencias - **La fecha DKL no guarda zona horaria.** Decida una convención (por ejemplo, guardar en UTC en la base y convertir al mostrar con `tz.convert`) y úsela en todo el sistema. - México dejó de aplicar el horario de verano en 2022, salvo en la franja fronteriza (Tijuana aparece con `-420` en julio). Use siempre el nombre IANA, no un desfase fijo. - Los resultados de `date.unix`, `date.from_unix` y `date.from_iso` dependen de la zona del servidor. Para tokens y API use `date.unix_utc` y `date.from_unix_utc`.