Expand description
Pure calendar arithmetic on epoch seconds — the date-arithmetic stone (R4a’s last engine-side gap). Time columns stay declared i64 (epoch seconds; units belong to the caller, the WINDOW philosophy) — this crate is the query-side arithmetic that turns a human bound into that i64, never a new column type.
Everything here is a pure function: now is always an argument,
the stone never touches a clock. Proleptic Gregorian, UTC only
(zone conversion is the application’s — refused by name at the
surface, not silently guessed here).
The civil conversion is the standard integer-arithmetic algorithm (era/year-of-era/day-of-year decomposition over 400-year cycles), exact over the whole i64 day range the epoch can reach.
use kevy_time::{Civil, add_months};
// Epoch seconds in, calendar out, and back again.
let c = Civil::from_epoch(1_700_000_000);
assert_eq!((c.year(), c.month(), c.day()), (2023, 11, 14));
assert_eq!((c.hour(), c.minute(), c.second()), (22, 13, 20));
assert_eq!(c.to_epoch(), 1_700_000_000);
// Month arithmetic clamps rather than spilling into the next month:
// 31 January plus one month is the last day of February, and 2024 is
// a leap year.
let jan31 = Civil::from_date(2024, 1, 31).ok_or("not a date")?.to_epoch();
let feb = Civil::from_epoch(add_months(jan31, 1));
assert_eq!((feb.month(), feb.day()), (2, 29));Structs§
- Civil
- One civil timestamp: year, month (1-12), day (1-31), hour, minute, second — UTC, proleptic Gregorian.
Functions§
- add_
months - Add
ncalendar months (negative subtracts), clamping the day to the target month’s end — Jan 31 + 1mo = Feb 28 (29 in a leap year), the convention every calendar API converges on. - checked_
add_ months add_months, answeringNoneinstead of saturating when the result leaves the range ani64epoch can hold.- eval
- Evaluate one
@query-bound expression against the caller’snow.Noneon anything malformed — the surface refuses by name, this stone never guesses.