The temporal contract (roadmap 02, B1).
Two vocabularies, deliberately separate:
Domains are the internal representation. Everything internal is UTC:
a point in time is a java.time.Instant, a span is a java.time.Duration,
and :local-date is a civil date that is deliberately not a point in time.
Zone-bearing and wall-clock types (:local-date-time, :zoned-date-time,
:offset-date-time) are ingress formats only — they are resolved to an
Instant at the boundary and never travel internally (D10).
Dialects are the encodings used at a boundary. A dialect is a named
value, chosen explicitly, never inferred (D6). :epoch-ms is the platform
default (D3b) and is narrow: it can only carry :instant, at millisecond
resolution.
Nothing here guesses. A number without a dialect is an error, a zone-less datetime is an error (D11), and a value a dialect cannot represent is an error rather than a silent narrowing (D5).
The temporal contract (roadmap 02, B1). Two vocabularies, deliberately separate: - **Domains** are the *internal* representation. Everything internal is UTC: a point in time is a `java.time.Instant`, a span is a `java.time.Duration`, and `:local-date` is a civil date that is deliberately *not* a point in time. Zone-bearing and wall-clock types (`:local-date-time`, `:zoned-date-time`, `:offset-date-time`) are **ingress formats only** — they are resolved to an `Instant` at the boundary and never travel internally (D10). - **Dialects** are the *encodings* used at a boundary. A dialect is a named value, chosen explicitly, never inferred (D6). `:epoch-ms` is the platform default (D3b) and is narrow: it can only carry `:instant`, at millisecond resolution. Nothing here guesses. A number without a dialect is an error, a zone-less datetime is an error (D11), and a value a dialect cannot represent is an error rather than a silent narrowing (D5).
(->instant value)(->instant value opts)Decodes a boundary value into an Instant (the internal UTC representation).
(->instant 1704067200000 {:dialect :epoch-ms})
(->instant "2024-01-01T00:00:00Z" {:dialect :rfc3339})
(->instant (LocalDateTime/parse "2024-01-01T00:00:00") {:zone "America/Sao_Paulo"})
:dialect-required rather than guessing seconds vs millis vs nanos.LocalDateTime needs :zone; a local time that does not
exist because of a DST spring-forward throws unless :dst-gap :shift-forward
is supplied.{:dialect :local-date} is an ingress directive returning a LocalDate — a
civil date that deliberately never becomes midnight UTC.Decodes a boundary value into an `Instant` (the internal UTC representation).
```clojure
(->instant 1704067200000 {:dialect :epoch-ms})
(->instant "2024-01-01T00:00:00Z" {:dialect :rfc3339})
(->instant (LocalDateTime/parse "2024-01-01T00:00:00") {:zone "America/Sao_Paulo"})
```
- A **number requires an explicit dialect** (D6); omitting it throws
`:dialect-required` rather than guessing seconds vs millis vs nanos.
- A **zone-less string is rejected**, never assumed UTC (D11).
- A **wall-clock `LocalDateTime` needs `:zone`**; a local time that does not
exist because of a DST spring-forward throws unless `:dst-gap :shift-forward`
is supplied.
- `{:dialect :local-date}` is an ingress directive returning a `LocalDate` — a
civil date that deliberately never becomes midnight UTC.(->wire value dialect)(->wire value dialect opts)Encodes an internal value into the given dialect.
Refuses lossy encodings by default (D5/D13); pass {:truncating? true} to accept
a documented narrowing.
Encodes an internal value into the given dialect.
Refuses lossy encodings by default (D5/D13); pass `{:truncating? true}` to accept
a documented narrowing.Domains that exist only as ingress/egress representations, never internally.
Domains that exist only as ingress/egress representations, never internally.
The platform's de-facto wire encoding for points in time (D3b).
The platform's de-facto wire encoding for points in time (D3b).
(default-dialect-for domain)The default encoding for a domain.
:instant defaults to :epoch-ms — the platform's existing contract, preserved
so no current consumer sees a format change (D3b). The other internal domains
have no epoch encoding at all: a date-only fact cannot be an integer without
silently acquiring a zone, so :local-date and :duration default to their
natural textual forms.
The default encoding for a domain. `:instant` defaults to `:epoch-ms` — the platform's existing contract, preserved so no current consumer sees a format change (D3b). The other internal domains have no epoch encoding at all: a date-only fact cannot be an integer without silently acquiring a zone, so `:local-date` and `:duration` default to their natural textual forms.
(dialect-supports? dialect domain)True when dialect can carry domain without losing information (§4.1 lattice).
True when `dialect` can carry `domain` without losing information (§4.1 lattice).
Named boundary encodings. A dialect is data, never inferred from a value.
:domains answers the honest question "can this encoding carry this domain?".
Note that :local-date-time and :zoned-date-time appear here — they are
representable on a text wire — but they are boundary-only: domains (above)
lists what may exist internally, and that set excludes them (D10).
Named boundary encodings. A dialect is data, never inferred from a value. `:domains` answers the honest question "can this encoding carry this domain?". Note that `:local-date-time` and `:zoned-date-time` appear here — they *are* representable on a text wire — but they are boundary-only: `domains` (above) lists what may exist internally, and that set excludes them (D10).
(domain-of value)Returns the internal domain of a value, or nil if it is not an internal representation. Boundary-only java.time types return nil by design (D10).
Returns the internal domain of a value, or nil if it is not an internal representation. Boundary-only java.time types return nil by design (D10).
The internal domain vocabulary (D10). Everything internal is UTC.
The internal domain vocabulary (D10). Everything internal is UTC.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |