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-DDorYYYYMMDD. 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, orHH:MM:SS.fffffffffwith one to nine fraction digits after.or,. The forms without:areHHMMandHHMMSS. Second60reads as59.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], thenkey=valuepairs 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#
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#
pub enum TimeParseReasonThe cause of a TimeParseError.
UnexpectedEnd#
UnexpectedEndThe text ends where a digit or a separator must be.
UnexpectedCharacter#
UnexpectedCharacterThe byte at the error offset is not valid in that position.
OutOfRange#
OutOfRangeA 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#
UtcNotAllowedThe 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#
MissingOffsetThe text has no UTC offset, and the type needs one to name a point in time.
MissingTime#
MissingTimeThe text has no time of day, and the type needs one.
MissingDate#
MissingDateThe text has no date, and the type needs one. Only silk.time.pattern reports it.
UnsupportedCalendar#
UnsupportedCalendarThe 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#
UnknownCriticalAnnotationThe text has an annotation that is marked critical with ! and has a key that this parser
does not know.
Ambiguous#
AmbiguousThe 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#
MissingZoneThe text has no time zone annotation such as [Europe/Rome], and the type needs one.
Implementation Debug for TimeParseReason#
impl Debug for TimeParseReasonOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterTimeParseError#
pub struct TimeParseErrorThe error of every date and time parser: why the text is not valid and where.
Field reason#
pub reason: TimeParseReasonThe cause.
Field offset#
pub offset: usizeThe 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#
impl Copy for TimeParseErrorImplementation Debug for TimeParseError#
impl Debug for TimeParseErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterClockTime#
pub struct ClockTimeA time of day as plain numbers, as a Scanner reads it.
Field hour#
pub hour: u8The hour, from 0 to 23.
Field minute#
pub minute: u8The minute, from 0 to 59.
Field second#
pub second: u8The second, from 0 to 59. The scanner reads second 60 as 59.
Field nanosecond#
pub nanosecond: u32The fraction of the second in nanoseconds, from 0 to 999,999,999.
Implementation Copy for ClockTime#
impl Copy for ClockTimeOffsetKind#
pub enum OffsetKindHow a text states its UTC offset.
Absent#
AbsentThe text has no offset.
Utc#
UtcThe text has the UTC designator Z or z.
Numeric#
NumericThe text has a numeric offset such as +01:00.
ParsedOffset#
pub struct ParsedOffsetThe UTC offset that a Scanner read.
Field kind#
pub kind: OffsetKindHow the text states the offset.
Field seconds#
pub seconds: i32The offset in seconds east of UTC. It is 0 unless kind is Numeric.
Implementation Copy for ParsedOffset#
impl Copy for ParsedOffsetParsedDateTime#
pub struct ParsedDateTimeThe parts of a date and time text that Scanner.dateTime read.
Field date#
pub date: CivilDateThe date.
Field time#
pub time: ClockTimeThe time of day. It is midnight when hasTime is false.
Field hasTime#
pub hasTime: booltrue if the text has a time of day.
Field offset#
pub offset: ParsedOffsetThe UTC offset. Its kind is Absent when the text has none.
Implementation Copy for ParsedDateTime#
impl Copy for ParsedDateTimeScanner#
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>#
impl<'text> Scanner<'text>Associated function make#
pub fn make(bytes: &'text [u8]) -> Scanner<'text>Returns a scanner at the start of bytes.
Method allowCalendars#
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#
pub fn failure(self: &Self) -> Option<TimeParseError>Returns the first failure, or None if every reader so far succeeded.
Method reject#
pub fn reject(self: &mut Self, reason: TimeParseReason, offset: usize) -> ()Records a failure at byte offset unless one is already recorded.
Method rejectHere#
pub fn rejectHere(self: &mut Self, reason: TimeParseReason) -> ()Records a failure at the next byte to read unless one is already recorded.
Method position#
pub fn position(self: &Self) -> usizeReturns the byte offset of the next byte to read.
Method atEnd#
pub fn atEnd(self: &Self) -> boolReturns true if no bytes are left.
Method peek#
pub fn peek(self: &Self) -> u8Returns the next byte without consuming it, or 0 at the end of the text.
Method accept#
pub fn accept(self: &mut Self, byte: u8) -> boolConsumes the next byte if it is byte and returns true. Otherwise it consumes nothing.
Method expect#
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#
pub fn digits(self: &mut Self, count: usize) -> u32Consumes exactly count decimal digits and returns their value. count is at most 9.
Method letters#
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#
pub fn end(self: &mut Self) -> ()Fails with UnexpectedCharacter if bytes are left.
Method date#
pub fn date(self: &mut Self) -> CivilDateReads 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#
pub fn year(self: &mut Self) -> i32Reads a year: four digits, or a sign and six digits. The year -000000 is a failure.
Method time#
pub fn time(self: &mut Self) -> ClockTimeReads 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#
pub fn fraction(self: &mut Self) -> u32Reads 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#
pub fn offset(self: &mut Self) -> ParsedOffsetReads 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#
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#
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#
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#
pub fn dateTime(self: &mut Self) -> ParsedDateTimeReads 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#
pub fn timeOfDay(self: &mut Self) -> ParsedDateTimeReads 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#
pub fn writeTwo(output: &mut [u8], at: usize, value: u8) -> usizeWrites value as two decimal digits at output[at] and returns at + 2. value must be at
most 99.
writeYear#
pub fn writeYear(output: &mut [u8], at: usize, year: i32) -> usizeWrites 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#
pub fn writeDate(output: &mut [u8], at: usize, date: CivilDate) -> usizeWrites 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#
pub fn writeTime(output: &mut [u8], at: usize, time: ClockTime) -> usizeWrites 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#
pub fn writeOffset(output: &mut [u8], at: usize, seconds: i32) -> usizeWrites 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.