datahike.pg.datetime.in — org.replikativ/pg-datahike 0.1.313

The five input functions: date_in, time_in, timetz_in, timestamp_in, timestamptz_in.

Each is the same three steps -- lex, decode, convert -- differing in the work-buffer size, which decoder it calls, whether it accepts a zone, and what it does with the parts it does not want. Those differences are small and every one of them is observable, so the five are written out rather than generated from a table.

date_in is the one that surprises: it runs the WHOLE timestamp decoder and then discards the time. So the time is still validated and '2001-02-03 25:00:00'::date is an error, not 2001-02-03 (date.c:117-170).

ALL FIVE pass a non-NULL tzp, so all five ACCEPT a zone -- date_in at date.c:134 and time_in at date.c:1399. The ones that have nowhere to put it parse it and discard it, which is why '2000-01-01 12:00:00 PST'::date is 2000-01-01 and ::time is 12:00:00 rather than errors. I had both refusing, on the assumption that a type with no zone would not take one; tzp == NULL is for other internal callers, not for the input functions.

ERRORS. Every dterr becomes the SQLSTATE DateTimeParseError gives it (datetime.c:4063-4120):

bad-format 22007 invalid input syntax for type … field-overflow 22008 date/time field value out of range md-field-overflow 22008 …plus a "datestyle" HINT tzdisp-overflow 22009 time zone displacement out of range bad-timezone 22023 time zone "…" not recognized

The three overflow codes are distinct and are routinely got wrong: a zone past ±15 is 22009, not 22008.

->fields clj

(->fields {:keys [kind jd usec]})

A canonical value back to {:year :mon :mday :hour :min :sec :usec}, which is j2date plus the division timestamp2tm does. For a :timetz the fields are the LOCAL time; :west carries the rest.

date-in clj

(date-in s {:keys [date-order now] :as _ctx})

date_in (date.c:117-170). Returns {:kind :date :jd …} with :jd in days from 2000-01-01, or {:kind :infinity|:-infinity}.

It decodes a whole TIMESTAMP and then throws the time away, so the time is validated first: '2001-02-03 25:00:00'::date is an error. A zone is likewise parsed and discarded -- '2000-01-01 12:00:00 PST'::date is 2000-01-01 -- because date_in passes a non-NULL tzp (date.c:134) like every other input function.

end-timestamp clj

END_TIMESTAMP (timestamp.h): just past 294277-01-09 AD.

min-timestamp clj

MIN_TIMESTAMP (timestamp.h): 4714-11-24 BC.

pg-epoch-jdate clj

POSTGRES_EPOCH_JDATE: the Julian day of 2000-01-01.

time-in clj

(time-in s {:keys [date-order now] :as _ctx})

time_in (date.c:1368-1404). Microseconds since midnight. 86400000000 is legal and renders as 24:00:00 -- there is no day to carry into. No zone.

timestamp-in clj

(timestamp-in s {:keys [date-order now] :as _ctx})

timestamp_in (timestamp.c:160-220). No zone is kept -- the literal may CARRY one and it is parsed and then ignored, which is why '2001-02-03 04:05:06+05:30:30'::timestamp is 04:05:06 unshifted.

timestamptz-in clj

(timestamptz-in s {:keys [date-order now session-zone] :as _ctx})

timestamptz_in (timestamp.c:412-470). As timestamp-in, and the zone IS kept -- resolved here, after the date is known, and folded into the value so that what comes back is a UTC instant.

timetz-in clj

(timetz-in s {:keys [date-order now session-zone] :as _ctx})

timetz_in (date.c:2266-2302). As time-in, plus the offset.

A zone whose offset depends on the date can only be used when the literal supplies the date, or when the zone is a FIXED offset -- which is why '12:00 UTC'::timetz works and '12:00 America/New_York'::timetz does not.

usecs-per-day clj