Should the APL DATETIME type include explicit time‑zone metadata?

Answer

The built‑in DATETIME scalar in Dyalog APL should not be changed to embed time‑zone data by default. Instead, an opt‑in aware type or an optional zone attribute preserves existing semantics while providing reliable cross‑regional conversions.

Why this matters

Existing DATETIME values represent a local‑time snapshot without any offset. When projects need to convert between regions, they typically store a separate UTC offset or use third‑party libraries. Those approaches differ in how they treat daylight‑saving transitions, leading to inconsistent behavior.

Adding a mandatory zone field would silently alter the meaning of every existing local‑time value. Code that assumes the old semantics would now produce different results, breaking downstream logic that relies on the original interpretation.

Interaction with primitives

• DATE and TIME remain zoneless; they continue to represent calendar dates and clock times only.
• TIMESTAMP is the anchor for absolute instants. A time‑zone‑aware DATETIME can be resolved to a TIMESTAMP by applying the stored zone rules.

Offset vs. IANA zone

Storing a numeric offset is inadequate because it cannot encode daylight‑saving rules or historical changes. An IANA zone identifier (e.g., Europe/London) is the preferred primary representation. The offset can be derived on demand for display or interop, but the zone must be stored to preserve future‑proof semantics.

Implications for existing code

• Unmodified DATETIME values keep their current meaning; no runtime changes are required.
• Functions that accept or produce DATETIME must be updated to either reject mixed aware/unaware values or explicitly require a zone parameter.
• Conversion helpers (e.g., localize, convert-to-zone, to-UTC-instant) should be added as library functions rather than altering the core type.

Recommended migration shape

1. Keep the existing DATETIME scalar unchanged.
2. Introduce a new DATETIME‑ATZ (or similar) type that stores local fields plus an IANA zone identifier.
3. Provide conversion functions that map DATETIME‑ATZ to TIMESTAMP and back.
4. Deprecate any implicit mixing of aware and unaware values; raise a runtime error if a conversion is attempted without an explicit zone.
5. Document the need to pin the tzdata version used for tests and production; verify conversions across known DST boundaries.

Next step – diagnostic detail needed

To tailor the recommendation for your environment, please provide:

• The exact Dyalog APL release you are using.
• The tzdata version installed on your target systems.

These details affect how the new DATETIME‑ATZ type will be implemented and how existing code will interoperate.