Skip to content
Protos

std:datetime/ISO8601

std:datetime/ISO8601

Section titled “std:datetime/ISO8601”

Canonical occurrence: protos/lib/datetime/ISO8601.protos · Protos revision: e99b712ecf658a527b1fe82c8beba2c1286d8dc9.

A deliberately bounded canonical text profile for LIB013 date-time values, inspired by the ISO 8601 extended representations. This is not full ISO 8601 acceptance: only the forms below are accepted, and other valid ISO 8601 representations (basic format, ordinal and week dates, reduced or truncated precision, comma fractions, expanded years, durations) signal an Error. The value modules remain the semantic authority; every parse constructs its result through std:datetime/Date, std:datetime/Time, std:datetime/LocalDateTime, std:datetime/Offset, and std:datetime/OffsetDateTime, and this profile defines no value semantics.

Grammar, with every numeric field made of exactly the stated count of ASCII decimal digits:

  • YEAR is YYYY for years 0 through 9999, or -YYYY holding the absolute value for years -1 through -9999. -0000, a + sign, and any other digit count are rejected.
  • DATE is YEAR-MM-DD.
  • TIME is HH:MM:SS optionally followed by . and one through nine digits, the decimal fraction of one second. Precision is exactly nanoseconds; ten or more fraction digits signal an Error and are never rounded. There are no leap seconds, so second 60 is rejected, and hour 24 is rejected.
  • LOCAL is DATE T TIME with an uppercase T.
  • OFFSET is Z, +HH:MM, -HH:MM, +HH:MM:SS, or -HH:MM:SS. Fixed offsets keep one-second resolution and must lie within std:datetime/Offset’s -18:00:00 through +18:00:00. The negative zero spellings -00:00 and -00:00:00 are rejected.
  • An offset date-time is LOCAL immediately followed by OFFSET.

No whitespace, trailing text, or other characters are accepted. Formatting writes exactly these forms: the fraction is omitted for zero nanoseconds and otherwise is the nine-digit fraction with trailing zeros removed; a zero offset is written Z, and a nonzero offset ±HH:MM, or ±HH:MM:SS when it is not a whole number of minutes. Parsing a formatted value answers an equal value.

An offset here is only the fixed std:datetime/Offset; the profile has no time-zone, time-zone database, locale, or clock authority and reads no host state.

Observable top-level slots

Section titled “Observable top-level slots”

This page lists the complete mechanically observable top-level slot inventory required by D067. Authored documentation, when present, is canonical D062 prose; mechanical presence alone does not create a stability or compatibility promise.

formatDate

Section titled “formatDate”

Answers the canonical YEAR-MM-DD text of date, a value recognized by std:datetime/Date. Any other argument signals an Error.

Mechanical facts

Section titled “Mechanical facts”

formatInstant

Section titled “formatInstant”

Answers the canonical UTC text of instant, a value recognized by std:datetime/Instant: the offset date-time std:datetime/OffsetDateTime.fromInstant(instant, Offset(0)) as written by formatOffsetDateTime, which always ends in Z. Instants are unbounded, but an instant whose UTC date lies outside std:datetime/Date’s supported years has no text in this profile and signals an Error; there is no other fallback representation. Any other argument signals an Error.

Mechanical facts

Section titled “Mechanical facts”

formatLocalDateTime

Section titled “formatLocalDateTime”

Answers the canonical DATE T TIME text of dateTime, a value recognized by std:datetime/LocalDateTime. Any other argument signals an Error.

Mechanical facts

Section titled “Mechanical facts”

formatOffsetDateTime

Section titled “formatOffsetDateTime”

Answers the canonical text of value, a value recognized by std:datetime/OffsetDateTime: its stored local date-time as written by formatLocalDateTime, followed by Z for a zero offset, ±HH:MM for a whole number of minutes, or ±HH:MM:SS otherwise. The local date-time and offset are written exactly as stored; nothing is normalized to UTC or rounded. Any other argument signals an Error.

Mechanical facts

Section titled “Mechanical facts”

formatTime

Section titled “formatTime”

Answers the canonical HH:MM:SS[.fraction] text of time, a value recognized by std:datetime/Time. The fraction is omitted when the nanosecond is zero and is otherwise the nine-digit nanosecond with trailing zeros removed. Any other argument signals an Error.

Mechanical facts

Section titled “Mechanical facts”

parseDate

Section titled “parseDate”

Parses text as exactly YEAR-MM-DD and answers a fresh std:datetime/Date. A non-String argument, any other form, or a date that std:datetime/Date rejects signals an Error.

Mechanical facts

Section titled “Mechanical facts”

parseInstant

Section titled “parseInstant”

Parses text with parseOffsetDateTime and answers the std:datetime/Instant it identifies through std:datetime/OffsetDateTime.toInstant. Any offset form of this profile is accepted. Invalid text signals an Error.

Mechanical facts

Section titled “Mechanical facts”

parseLocalDateTime

Section titled “parseLocalDateTime”

Parses text as exactly DATE T TIME with an uppercase T and answers a fresh std:datetime/LocalDateTime built from parseDate and parseTime. A non-String argument, a missing or different separator, an offset or other suffix, or an invalid date or time signals an Error.

Mechanical facts

Section titled “Mechanical facts”

parseOffsetDateTime

Section titled “parseOffsetDateTime”

Parses text as a local date-time immediately followed by Z, ±HH:MM, or ±HH:MM:SS, and answers a fresh std:datetime/OffsetDateTime holding the local date-time and offset exactly as written; nothing is normalized to UTC. A non-String argument, a missing or malformed offset, -00:00 or -00:00:00, an offset outside std:datetime/Offset’s range, trailing text, or an invalid local date-time signals an Error.

Mechanical facts

Section titled “Mechanical facts”

parseTime

Section titled “parseTime”

Parses text as exactly HH:MM:SS with an optional . and one through nine fraction digits, and answers a fresh std:datetime/Time. Shorter fractions are right-padded with zeros to nanoseconds. A non-String argument, any other form, ten or more fraction digits, or a time that std:datetime/Time rejects (including hour 24 and second 60) signals an Error.

Mechanical facts

Section titled “Mechanical facts”

Exact module source · Standard-library API · Standard library overview