Skip to main content

Module datetime

Module datetime 

Source
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 DuckDB decomposes a DATE.
Decimal
A DECIMAL value: an unscaled i128 plus its declared width and scale.
Time
A wall-clock time, as DuckDB decomposes a TIME.
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 DATE value DuckDB uses for infinity, in days since 1970-01-01.
DATE_NEGATIVE_INFINITY_DAYS
The DATE value DuckDB uses for -infinity, in days since 1970-01-01.
DECIMAL_MAX_WIDTH
The widest DECIMAL DuckDB supports (Decimal::MAX_WIDTH_INT128).
MICROS_PER_DAY
Microseconds in a day (Interval::MICROS_PER_DAY).
TIMESTAMP_INFINITY_MICROS
The TIMESTAMP value DuckDB uses for infinity, in microseconds since the epoch.
TIMESTAMP_NEGATIVE_INFINITY_MICROS
The TIMESTAMP value DuckDB uses for -infinity, in microseconds since the epoch.
TIME_TZ_MAX_OFFSET_SECONDS
The largest TIME WITH TIME ZONE offset DuckDB can 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 DECIMAL to f64 the way DuckDB does.
f64_to_decimal⚠
Converts an f64 into a DECIMAL of the given width and scale.
f64_to_hugeint⚠
Converts an f64 to HUGEINT the way DuckDB does, truncating toward zero.
f64_to_uhugeint⚠
Converts an f64 to UHUGEINT the way DuckDB does, truncating toward zero.
hugeint_to_f64⚠
Converts a HUGEINT to f64 the way DuckDB does.
is_finite_date⚠
Returns false for DuckDB’s infinity / -infinity DATE sentinels.
is_finite_timestamp⚠
Returns false for DuckDB’s infinity / -infinity TIMESTAMP sentinels.
is_finite_timestamp_ms⚠
TIMESTAMP_MS variant of is_finite_timestamp.
is_finite_timestamp_ns⚠
TIMESTAMP_NS variant of is_finite_timestamp.
is_finite_timestamp_s⚠
TIMESTAMP_S variant of is_finite_timestamp.
is_valid_date
Returns true if DuckDB can represent date as a DATE.
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’s TIME WITH TIME ZONE bit representation.
time_tz_from_bits⚠
Unpacks DuckDB’s TIME WITH TIME ZONE bit 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 f64 into a DECIMAL(width, scale) like f64_to_decimal, or None when it cannot.
try_f64_to_hugeint⚠
Converts an f64 to HUGEINT like f64_to_hugeint, or None when DuckDB cannot convert it: NaN, an infinity, or a value outside (-2^127, 2^127).
try_f64_to_uhugeint⚠
Converts an f64 to UHUGEINT like f64_to_uhugeint, or None when DuckDB cannot convert it: NaN, an infinity, a negative value, or one at or above 2^128.
uhugeint_to_f64⚠
Converts a UHUGEINT to f64 the way DuckDB does.