Date
Checked immutable Gregorian calendar dates, exact day arithmetic, recoverable parsing and time and space complexity.
Date is an import free immutable calendar date in the proleptic Gregorian calendar. It stores a day independently of a time of day, offset, or timezone. Supported years are 0001 through 9999; invalid dates fail rather than rolling into another month.
Construction and representation
let observed: Date = Date(year: 2026, month: 10, day: 12)
let next = observed.add_days(1)
print(observed.str())
print(next.str())
print(observed.days_until(next)) // 1Date(year: Int64, month: Int64, day: Int64) validates the complete date, including Gregorian leap years. Date.parse(text: String) accepts the exact YYYY-MM-DD representation. str() produces the same fixed width format. These formats use ASCII digits and have no locale dependency.
Date.from_epoch_days(days: Int64) interprets an exact day count from January 1, 1970. epoch_days() returns that count. Both retain the supported calendar bounds. An epoch day is a calendar conversion; it does not assign a timezone or a midnight instant.
Methods and arithmetic
| Method or factory | Result | Contract |
|---|---|---|
Date.parse(text: String) | Date | Parse one complete calendar date. |
Date.try_parse(text: String) | Result<Date, String> | Return a date or a recoverable validation error. |
Date.from_epoch_days(days: Int64) | Date | Convert a bounded day count from January 1, 1970. |
year() | Int64 | Calendar year. |
month() | Int64 | Month from 1 through 12. |
day() | Int64 | Valid day within the month. |
weekday() | Int64 | Monday is 1; Sunday is 7. |
epoch_days() | Int64 | Signed calendar days from January 1, 1970. |
add_days(count: Int64) | Date | Return a date offset by an exact signed day count. |
days_until(other: Date) | Int64 | Return other minus this date in days. |
str() | String | Format YYYY-MM-DD. |
Arithmetic checks overflow and calendar bounds before returning a value. No month addition or year addition rule is inferred: those operations require an explicit policy for dates such as February 29.
Two Dates compare by calendar day. Equality does not imply equality with a String containing the same spelling or a DateTime on that date. Values copied through bindings remain independent immutable values. type(value) reports Date; dtype(value) is undefined for calendar values and reports the normal unsupported datatype error.
Errors and limits
An invalid calendar date, an out of range day result, or a checked arithmetic overflow produces a located runtime error R3401. Wrong static argument types or arities produce E1002. The corresponding documented try_ conversions represent expected validation failure as Result.err with a String payload rather than halting execution. A runtime failure retains the normal program or persistent session error contract.
Time and space complexity
Every Date stores O(1) native data. Construction, accessors, comparisons, add_days, and days_until take O(1) time and O(1) additional space. Parsing accepts a fixed width input and takes O(1) time and space; formatting returns a bounded ten byte String in O(1) time and space. Calendar conversion uses arithmetic rather than traversing intervening days. Evaluating an owned String argument can add its existing copy cost.
See DateTime for explicit instants and offsets, and run the complete Date example.