silk.time.text.

The shared reader and writer of ISO 8601 and RFC 3339 date and time text, and the error type of every date and time parser.

When to use#

Most programs call parse on a type, such as PlainDate.parse or Instant.parse, and print values with Display. Use Scanner and the write functions to build a parser or a formatter for another type or wire format on the same grammar.

Details#

The grammar is the one of ECMAScript Temporal, which includes RFC 3339 and the bracketed annotations of RFC 9557:

  • A date is YYYY-MM-DD or YYYYMMDD. A year outside 0 to 9999 has a sign and six digits, as in +012026-01-01.

  • A time is HH, HH:MM, HH:MM:SS, or HH:MM:SS.fffffffff with one to nine fraction digits after . or ,. The forms without : are HHMM and HHMMSS. Second 60 reads as 59.

  • T, t, or one space separates a date and a time.

  • An offset is Z, z, +HH, +HH:MM, +HHMM, +HH:MM:SS, or +HHMMSS, with - for offsets behind UTC.

  • Annotations follow in brackets: a time zone such as [Europe/Rome], then key=value pairs such as [u-ca=iso8601]. A ! after [ marks an annotation as critical.

A Scanner remembers the first failure and then does nothing. A parser calls the readers in order and checks Scanner.failure one time at the end.

Examples#

Read a date and time with an offset#

silk
import silk.core.option { Option }
import silk.text.string { String }
import silk.time.text { OffsetKind, Scanner, TimeParseError }

pub fn main() -> i32 {
  let mut scanner = Scanner.make(String.utf8Bytes("2026-11-19T17:36:22.5+01:00"))
  let parsed = scanner.dateTime()
  match scanner.failure() {
    Option<TimeParseError>.Some { value } => {
      return 1
    }
    Option<TimeParseError>.None => {}
  }
  if parsed.date.year != 2026 || parsed.time.nanosecond != 500000000 {
    return 2
  }
  if parsed.offset.seconds != 3600 {
    return 3
  }
  return 0
}

Import as text with import silk.time.text as text.

Public declarations: 12.

TimeParseReason#

silk
pub enum TimeParseReason

The cause of a TimeParseError.

UnexpectedEnd#

silk
UnexpectedEnd

The text ends where a digit or a separator must be.

UnexpectedCharacter#

silk
UnexpectedCharacter

The byte at the error offset is not valid in that position.

OutOfRange#

silk
OutOfRange

A field has the right form and a value that does not exist, such as month 13, February 30, or hour 24, or the result is outside the range of the type.

UtcNotAllowed#

silk
UtcNotAllowed

The text has the UTC designator Z, and the type has no zone. A plain date or time with Z is rejected because the local value it names depends on a zone that the text does not give.

MissingOffset#

silk
MissingOffset

The text has no UTC offset, and the type needs one to name a point in time.

MissingTime#

silk
MissingTime

The text has no time of day, and the type needs one.

MissingDate#

silk
MissingDate

The text has no date, and the type needs one. Only silk.time.pattern reports it.

UnsupportedCalendar#

silk
UnsupportedCalendar

The text has a calendar annotation that the parser does not take: any but [u-ca=iso8601] for the types of the ISO 8601 calendar, and a name that is no calendar for CalendarDate.

UnknownCriticalAnnotation#

silk
UnknownCriticalAnnotation

The text has an annotation that is marked critical with ! and has a key that this parser does not know.

Ambiguous#

silk
Ambiguous

The text can be read as a time and also as a year and month or a month and day, such as 1214. Write a time with the prefix T to make it clear.

MissingZone#

silk
MissingZone

The text has no time zone annotation such as [Europe/Rome], and the type needs one.

Implementation Debug for TimeParseReason#

silk
impl Debug for TimeParseReason

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

TimeParseError#

silk
pub struct TimeParseError

The error of every date and time parser: why the text is not valid and where.

Field reason#

silk
pub reason: TimeParseReason

The cause.

Field offset#

silk
pub offset: usize

The byte offset in the text where the parser found the problem. For a missing part it is the offset where the part must start.

Implementation Copy for TimeParseError#

silk
impl Copy for TimeParseError

Implementation Debug for TimeParseError#

silk
impl Debug for TimeParseError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

ClockTime#

silk
pub struct ClockTime

A time of day as plain numbers, as a Scanner reads it.

Field hour#

silk
pub hour: u8

The hour, from 0 to 23.

Field minute#

silk
pub minute: u8

The minute, from 0 to 59.

Field second#

silk
pub second: u8

The second, from 0 to 59. The scanner reads second 60 as 59.

Field nanosecond#

silk
pub nanosecond: u32

The fraction of the second in nanoseconds, from 0 to 999,999,999.

Implementation Copy for ClockTime#

silk
impl Copy for ClockTime

OffsetKind#

silk
pub enum OffsetKind

How a text states its UTC offset.

Absent#

silk
Absent

The text has no offset.

Utc#

silk
Utc

The text has the UTC designator Z or z.

Numeric#

silk
Numeric

The text has a numeric offset such as +01:00.

ParsedOffset#

silk
pub struct ParsedOffset

The UTC offset that a Scanner read.

Field kind#

silk
pub kind: OffsetKind

How the text states the offset.

Field seconds#

silk
pub seconds: i32

The offset in seconds east of UTC. It is 0 unless kind is Numeric.

Implementation Copy for ParsedOffset#

silk
impl Copy for ParsedOffset

ParsedDateTime#

silk
pub struct ParsedDateTime

The parts of a date and time text that Scanner.dateTime read.

Field date#

silk
pub date: CivilDate

The date.

Field time#

silk
pub time: ClockTime

The time of day. It is midnight when hasTime is false.

Field hasTime#

silk
pub hasTime: bool

true if the text has a time of day.

Field offset#

silk
pub offset: ParsedOffset

The UTC offset. Its kind is Absent when the text has none.

Implementation Copy for ParsedDateTime#

silk
impl Copy for ParsedDateTime

Scanner#

silk
pub struct Scanner<'text>

A reader of date and time text that keeps the first failure.

Details#

Each reader consumes its part and moves forward. After the first failure, each reader does nothing and returns a zero value, so a parser can call them in order and ask Scanner.failure one time at the end.

Implementation Scanner<'text>#

silk
impl<'text> Scanner<'text>

Associated function make#

silk
pub fn make(bytes: &'text [u8]) -> Scanner<'text>

Returns a scanner at the start of bytes.

Method allowCalendars#

silk
pub fn allowCalendars(self: &mut Self) -> ()

Makes Scanner.annotations accept a calendar annotation with any value, such as [u-ca=hebrew]. The caller reads the value with Scanner.calendarAnnotation and decides if it knows that calendar.

Method failure#

silk
pub fn failure(self: &Self) -> Option<TimeParseError>

Returns the first failure, or None if every reader so far succeeded.

Method reject#

silk
pub fn reject(self: &mut Self, reason: TimeParseReason, offset: usize) -> ()

Records a failure at byte offset unless one is already recorded.

Method rejectHere#

silk
pub fn rejectHere(self: &mut Self, reason: TimeParseReason) -> ()

Records a failure at the next byte to read unless one is already recorded.

Method position#

silk
pub fn position(self: &Self) -> usize

Returns the byte offset of the next byte to read.

Method atEnd#

silk
pub fn atEnd(self: &Self) -> bool

Returns true if no bytes are left.

Method peek#

silk
pub fn peek(self: &Self) -> u8

Returns the next byte without consuming it, or 0 at the end of the text.

Method accept#

silk
pub fn accept(self: &mut Self, byte: u8) -> bool

Consumes the next byte if it is byte and returns true. Otherwise it consumes nothing.

Method expect#

silk
pub fn expect(self: &mut Self, byte: u8) -> ()

Consumes the next byte, which must be byte. Another byte or the end of the text is a failure.

Method digits#

silk
pub fn digits(self: &mut Self, count: usize) -> u32

Consumes exactly count decimal digits and returns their value. count is at most 9.

Method letters#

silk
pub fn letters(self: &mut Self) -> &'text [u8]

Consumes the ASCII letters at the next position and returns them. The result is empty when the next byte is not a letter.

Method end#

silk
pub fn end(self: &mut Self) -> ()

Fails with UnexpectedCharacter if bytes are left.

Method date#

silk
pub fn date(self: &mut Self) -> CivilDate

Reads a date: YYYY-MM-DD, YYYYMMDD, or one of them with a signed six-digit year.

Details#

The month and the day must exist in that year of the ISO calendar, or the scanner fails with OutOfRange. The year -000000 is not valid.

Method year#

silk
pub fn year(self: &mut Self) -> i32

Reads a year: four digits, or a sign and six digits. The year -000000 is a failure.

Method time#

silk
pub fn time(self: &mut Self) -> ClockTime

Reads a time of day: HH, HH:MM, HH:MM:SS, HHMM, or HHMMSS, with an optional fraction of one to nine digits after the seconds.

Details#

The hour must be at most 23 and the minute at most 59, or the scanner fails with OutOfRange. The second can be 60, for a leap second, and reads as 59.

Method fraction#

silk
pub fn fraction(self: &mut Self) -> u32

Reads one to nine fraction digits and returns them as nanoseconds, so 5 is 500,000,000. No digit, or a tenth digit, is a failure.

Method offset#

silk
pub fn offset(self: &mut Self) -> ParsedOffset

Reads a UTC offset if the next byte starts one: Z, z, or a sign with HH, HH:MM, HHMM, HH:MM:SS, or HHMMSS.

Details#

When the next byte is not Z, z, +, or -, the scanner consumes nothing and the kind of the result is Absent. The hour must be at most 23, and the minute and the second at most 59, or the scanner fails with OutOfRange.

Method annotations#

silk
pub fn annotations(self: &mut Self) -> ()

Reads the bracketed annotations that end a text, such as [Europe/Rome][u-ca=iso8601].

Details#

The first annotation can be a time zone, which has no =. The scanner keeps it for Scanner.zoneAnnotation. The others are key=value pairs. The calendar key u-ca must have the value iso8601, in any letter case, or the scanner fails with UnsupportedCalendar. After Scanner.allowCalendars, every value is accepted. The scanner keeps the value of the first calendar annotation for Scanner.calendarAnnotation. An annotation with another key is skipped, unless it starts with !, which fails with UnknownCriticalAnnotation.

Method zoneAnnotation#

silk
pub fn zoneAnnotation(self: &Self) -> &'text [u8]

Returns the name inside the time zone annotation that Scanner.annotations read, such as Europe/Rome, or an empty slice if the text has none.

Method calendarAnnotation#

silk
pub fn calendarAnnotation(self: &Self) -> &'text [u8]

Returns the value of the first calendar annotation that Scanner.annotations read, such as hebrew for [u-ca=hebrew], or an empty slice if the text has none.

Method dateTime#

silk
pub fn dateTime(self: &mut Self) -> ParsedDateTime

Reads a whole date and time text: a date, then optionally T, t, or a space and a time, then optionally an offset, then annotations, then the end of the text.

Details#

An offset is read only after a time. The result says which parts the text has; the caller decides which are required and which are not allowed.

Method timeOfDay#

silk
pub fn timeOfDay(self: &mut Self) -> ParsedDateTime

Reads a whole time text: optionally T or t, a time, then optionally an offset, then annotations, then the end of the text.

Details#

Without the prefix T, a text that is also a valid year and month or month and day fails with Ambiguous. These are HHMM when it is a valid MMDD, HHMMSS when it is a valid YYYYMM, and an hour or HHMM with an offset when it is a valid MM-DD or YYYY-MM. The date of the result is 1970-01-01.

writeTwo#

silk
pub fn writeTwo(output: &mut [u8], at: usize, value: u8) -> usize

Writes value as two decimal digits at output[at] and returns at + 2. value must be at most 99.

writeYear#

silk
pub fn writeYear(output: &mut [u8], at: usize, year: i32) -> usize

Writes a year at output[at] and returns the offset after it.

Details#

A year from 0 to 9999 is four digits. Another year is a sign and six digits, as in +012026 or -000044. year must be within 999,999 of zero.

writeDate#

silk
pub fn writeDate(output: &mut [u8], at: usize, date: CivilDate) -> usize

Writes a date as YYYY-MM-DD at output[at] and returns the offset after it. The text is 10 bytes, or 13 for a year outside 0 to 9999.

writeTime#

silk
pub fn writeTime(output: &mut [u8], at: usize, time: ClockTime) -> usize

Writes a time as HH:MM:SS at output[at], with a fraction when time.nanosecond is not zero, and returns the offset after it.

Details#

The fraction has as many digits as the value needs, without zeros at the end: 12:30:00.5 or 12:30:00.000000001. The text is at most 18 bytes.

writeOffset#

silk
pub fn writeOffset(output: &mut [u8], at: usize, seconds: i32) -> usize

Writes a UTC offset of seconds seconds east of UTC as +HH:MM at output[at] and returns the offset after it.

Details#

An offset with a seconds part is +HH:MM:SS. Offsets behind UTC have the sign -, and zero is +00:00. The text is at most 9 bytes. seconds must be within 24 hours of zero.

Category: Time.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page