Expand description
Calendar conversions for DuckDB’s temporal types.
VectorReader/VectorWriter move DATE, TIME and TIMESTAMP as the raw
integers DuckDB stores: days since 1970-01-01, microseconds since midnight,
microseconds since the epoch. Turning those into year/month/day means
implementing the proleptic Gregorian calendar — including DuckDB’s
infinity sentinels — which is exactly the kind of thing an extension should
not be reimplementing.
DuckDB already exposes the conversions (duckdb_from_date,
duckdb_to_date, duckdb_from_time, duckdb_from_timestamp, …) and they
sit in the stable prefix of the C extension API, so they work on every
release from v1.2.0 onwards and need no feature flag. This module wraps them
in plain Rust structs.
Using DuckDB’s own routines also means the results agree with DuckDB’s
SQL semantics exactly, rather than approximately.
§Example
use quack_rs::datetime;
// Inside a callback, given a DATE read as days-since-epoch:
let date = unsafe { datetime::date_from_days(days) };
assert_eq!((date.year, date.month, date.day), (1970, 1, 1));
// …and back again. Composing can fail (a month of 13, a 30th of
// February), so it returns an `Option`.
assert_eq!(unsafe { datetime::date_to_days(date) }, Some(days));§Invalid input returns None, never aborts
Several of DuckDB’s conversions throw a C++ exception on bad input — a
DATE of 2026-13-01, decomposing the infinity TIMESTAMP — and the C API
does not catch it, so it would abort the whole process. The wrappers here
check first, mirroring DuckDB’s own conditions, and return None:
date_to_days, time_from_micros, time_tz_from_bits,
timestamp_from_micros, timestamp_to_micros, time_tz_bits and
decimal_to_f64. is_valid_date exposes the date check on its own.
Two of those (time_from_micros, time_tz_from_bits) guard a debug
assertion rather than an exception: a release build of DuckDB returns
nonsense fields there, and a build with assertions aborts.
§Infinity
DuckDB reserves two values of DATE and of TIMESTAMP for infinity and
-infinity. Decomposing one of those into a calendar date is meaningless, so
check with is_finite_date / is_finite_timestamp first, or compare
against the constants below.
Note the exact values: negative infinity is -i32::MAX / -i64::MAX, not
i32::MIN / i64::MIN. i32::MIN is an ordinary (if absurd) finite date.
Structs§
- Date
- A calendar date, as
DuckDBdecomposes aDATE. - Decimal
- A
DECIMALvalue: an unscaledi128plus its declared width and scale. - Time
- A wall-clock time, as
DuckDBdecomposes aTIME. - TimeTz
- A
TIME WITH TIME ZONE, decomposed into wall-clock time plus UTC offset. - Timestamp
- A
TIMESTAMP, decomposed into date and time parts.
Constants§
- DATE_
INFINITY_ DAYS - The
DATEvalueDuckDBuses forinfinity, in days since 1970-01-01. - DATE_
NEGATIVE_ INFINITY_ DAYS - The
DATEvalueDuckDBuses for-infinity, in days since 1970-01-01. - DECIMAL_
MAX_ WIDTH - The widest
DECIMALDuckDBsupports (Decimal::MAX_WIDTH_INT128). - MICROS_
PER_ DAY - Microseconds in a day (
Interval::MICROS_PER_DAY). - TIMESTAMP_
INFINITY_ MICROS - The
TIMESTAMPvalueDuckDBuses forinfinity, in microseconds since the epoch. - TIMESTAMP_
NEGATIVE_ INFINITY_ MICROS - The
TIMESTAMPvalueDuckDBuses for-infinity, in microseconds since the epoch. - TIME_
TZ_ MAX_ OFFSET_ SECONDS - The largest
TIME WITH TIME ZONEoffsetDuckDBcan encode, in seconds:+15:59:59(dtime_tz_t::MAX_OFFSET = 16 * 60 * 60 - 1). The smallest is its negation.
Functions§
- date_
from_ ⚠days - Decomposes a
DATE(days since 1970-01-01) into a calendar date. - date_
to_ ⚠days - Composes a calendar date into a
DATE(days since 1970-01-01). - decimal_
to_ ⚠f64 - Converts a
DECIMALtof64the wayDuckDBdoes. - f64_
to_ ⚠decimal - Converts an
f64into aDECIMALof the given width and scale. - f64_
to_ ⚠hugeint - Converts an
f64toHUGEINTthe wayDuckDBdoes, truncating toward zero. - f64_
to_ ⚠uhugeint - Converts an
f64toUHUGEINTthe wayDuckDBdoes, truncating toward zero. - hugeint_
to_ ⚠f64 - Converts a
HUGEINTtof64the wayDuckDBdoes. - is_
finite_ ⚠date - Returns
falseforDuckDB’sinfinity/-infinityDATEsentinels. - is_
finite_ ⚠timestamp - Returns
falseforDuckDB’sinfinity/-infinityTIMESTAMPsentinels. - is_
finite_ ⚠timestamp_ ms TIMESTAMP_MSvariant ofis_finite_timestamp.- is_
finite_ ⚠timestamp_ ns TIMESTAMP_NSvariant ofis_finite_timestamp.- is_
finite_ ⚠timestamp_ s TIMESTAMP_Svariant ofis_finite_timestamp.- is_
valid_ date - Returns
trueifDuckDBcan representdateas aDATE. - time_
from_ ⚠micros - Decomposes a
TIME(microseconds since midnight) into a wall-clock time. - time_
to_ ⚠micros - Composes a wall-clock time into a
TIME(microseconds since midnight). - time_
tz_ ⚠bits - Packs a wall-clock time and UTC offset into
DuckDB’sTIME WITH TIME ZONEbit representation. - time_
tz_ ⚠from_ bits - Unpacks
DuckDB’sTIME WITH TIME ZONEbit representation. - timestamp_
from_ ⚠micros - Decomposes a
TIMESTAMP(microseconds since the epoch) into date and time. - timestamp_
to_ ⚠micros - Composes date and time into a
TIMESTAMP(microseconds since the epoch). - try_
f64_ ⚠to_ decimal - Converts an
f64into aDECIMAL(width, scale)likef64_to_decimal, orNonewhen it cannot. - try_
f64_ ⚠to_ hugeint - Converts an
f64toHUGEINTlikef64_to_hugeint, orNonewhenDuckDBcannot convert it: NaN, an infinity, or a value outside(-2^127, 2^127). - try_
f64_ ⚠to_ uhugeint - Converts an
f64toUHUGEINTlikef64_to_uhugeint, orNonewhenDuckDBcannot convert it: NaN, an infinity, a negative value, or one at or above2^128. - uhugeint_
to_ ⚠f64 - Converts a
UHUGEINTtof64the wayDuckDBdoes.