std.date

Date is an immutable proleptic Gregorian calendar date from 0001-01-01 through 9999-12-31. It contains no time of day, time zone, or locale. The same calendar rules apply before and after 1582.

Date.fromYmd accepts years from 1 through 9999 and months from 1 through 12. The day must be a real day of the selected month and year. All range endpoints are included.

A year divisible by 4 is a leap year except a century year that is not divisible by 400. February has 29 days in a leap year and 28 otherwise. April, June, September, and November have 30 days. The other months have 31.

Valid components return Ok containing that date. Year zero, a year outside the supported range, an invalid month, and an invalid day return Err containing a descriptive nonempty string. Components are not normalized into another date.

The error string describes the failed construction and has no stable machine readable format. Callers branch on Ok or Err.

Date.year, Date.month, and Date.day are calls with no arguments. They return the validated components of the receiver. A valid Date makes these observations total and leaves the receiver unchanged.

Arguments are evaluated once in source order before validation. An earlier fault prevents later evaluation. Constructors and observations do not read a host clock or perform external effects.

Date.parseIso accepts exactly ten ASCII characters in the form YYYY-MM-DD. The year has four digits and the month and day each have two digits. Hyphens occur after the year and month.

The components must form a valid Gregorian date in the same range as Date.fromYmd. Valid text returns Ok containing that date. Invalid grammar or an invalid calendar date returns Err containing a descriptive nonempty string.

Parsing does not trim whitespace or normalize another spelling. Signs, omitted zero padding, alternate separators, non ASCII digits, timestamps, time zones, and extra characters are rejected.

Date.toIso returns exactly the same ten character form using ASCII digits and zero padding. It has no locale or time zone parameter and leaves the receiver unchanged.

Parsing the formatted text recovers the original date. Formatting accepted input returns that same text. Date.fromYmd and Date.parseIso establish the same component and range invariants.

The receiver or argument is evaluated once before the operation. These operations do not change the input or perform external effects. Error strings have no stable machine readable format.

Date.addDays accepts a signed int count of whole calendar days. Positive values move forward, negative values move backward, and zero returns the same date value.

The result follows the same proleptic Gregorian calendar as Date.fromYmd. Month boundaries, leap days, and year boundaries are crossed by counting calendar days. Historical calendar cutovers and daylight saving changes do not alter the result.

The result must remain from 0001-01-01 through 9999-12-31. A count whose mathematical result is outside that range raises TPZ4004 during execution. An intermediate integer overflow also raises TPZ4004.

An invalid result does not wrap, saturate, return a partial date, or change the receiver. Evaluation stops at the fault before later statements run.

The receiver is evaluated before the day count and each is evaluated once. An earlier fault prevents later evaluation. The operation has no external effects.

Adding a count and then its negative recovers the starting date when both results lie in range. Date.toIso and the component accessors observe the resulting date without changing it.