silk.time.pattern.

Writes and reads dates and times with strftime patterns, such as %Y-%m-%d %H:%M:%S %z.

When to use#

Use TimePattern for a date format that is not ISO 8601: a log line, a file name, a date in a form that a person typed, or the format of another program. For ISO 8601 text, the parse and Display of the time types are shorter and faster.

Details#

A pattern is literal text and directives. A directive is %, optional flags, an optional width, and one letter.

DirectiveMeaningExample
%YYear, four digits or more2026
%CCentury, the year divided by 10020
%yYear in the century, 00 to 9926
%mMonth, 01 to 1211
%B, %b, %hEnglish month name, full or three lettersNovember, Nov
%dDay of the month, 01 to 3109
%eDay of the month, padded with a space 9
%jDay of the year, 001 to 366323
%A, %aEnglish weekday name, full or three lettersThursday, Thu
%uWeekday, 1 for Monday to 7 for Sunday4
%wWeekday, 0 for Sunday to 6 for Saturday4
%G, %gYear of the ISO 8601 week, whole or two digits2026, 26
%VISO 8601 week, 01 to 5347
%UWeek of the year with Sunday first, 00 to 5346
%WWeek of the year with Monday first, 00 to 5346
%HHour, 00 to 2318
%kHour, 0 to 23, padded with a space18
%IHour of the 12-hour clock, 01 to 1206
%lHour of the 12-hour clock, padded with a space 6
%p, %PAM or PM, and am or pmPM, pm
%MMinute, 00 to 5936
%SSecond, 00 to 5922
%fFraction of a second, without zeros at the end5
%NFraction of a second, nine digits500000000
%zUTC offset; %:z has a colon, %::z has seconds+0100, +01:00
%ZAbbreviation of the time zone. It cannot be read.CET
%sSeconds from the Unix epoch1795109782
%F%Y-%m-%d2026-11-19
%T, %X%H:%M:%S18:36:22
%R%H:%M18:36
%D, %x%m/%d/%y11/19/26
%r%I:%M:%S %p06:36:22 PM
%c%a %b %e %H:%M:%S %YThu Nov 19 18:36:22 2026
%n, %t, %%A line feed, a tab, and %

The flags are - for no padding, _ for padding with spaces, 0 for padding with zeros, and ^ for upper case. A width, such as the 3 of %3f, sets the least number of characters, and for %f and %N the exact number of digits. %.f writes a point and the fraction, and nothing for a whole second.

A pattern that is a constant is checked when the program is compiled: an unknown directive, or a directive that the value cannot supply, such as %H for a PlainDate, is a compile error. The functions with Dynamic in the name take a pattern that is known only at run time and report the same problems as a PatternError.

A year before 0 has a minus sign before its digits, as in -0044, and a width counts the sign.

Reading is lenient about digits and space: a number can have fewer digits than its width, white space in the pattern matches any amount of white space, a directive that is padded with spaces (%e, %k, %l, or the flag _) can have spaces before it, and names match in any case, in the full or the short form. A year can have a sign, and then up to six digits. %z reads Z, +01, +0100, +01:00, and the forms with seconds. The text must end where the pattern ends.

A date is read from a year with a month and a day, a day of the year, or a week and a weekday. A two-digit year without a century is from 1969 to 2068. A time of day needs an hour; the minute and the second are 0 if the pattern has none.

Gotchas#

The names are English only. Names in other languages belong to a locale library.

Examples#

Read a date and write it in another form#

silk
import silk.core.effect { Effect }
import silk.core.result { Result }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.text.string { String }
import silk.time.pattern { TimePattern }
import silk.time.plain_date { PlainDate }
import silk.time.text { TimeParseError }

effect fn long(text: string) -> String ! OutOfMemoryError ? &mut Allocator {
  return match TimePattern.parse<PlainDate>("%d/%m/%Y", text) {
    Result<PlainDate, TimeParseError>.Success { value } => run TimePattern.format("%A, %B %-d, %Y", &value)
    Result<PlainDate, TimeParseError>.Failure {..} => run String.copy("not a date")
  }
}

pub effect fn main() -> i32 ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let written = run long("19/11/2026") |> Effect.provideMut<Allocator>(&mut allocator)
  return if written.view() == "Thursday, November 19, 2026" { 0 } else { 1 }
}

Import as TimePattern with import silk.time.pattern { TimePattern }.

Public declarations: 9.

PatternReason#

silk
pub enum PatternReason

The cause of a PatternError.

UnknownDirective#

silk
UnknownDirective

The letter after % is not a directive.

UnfinishedDirective#

silk
UnfinishedDirective

The pattern ends after %, a flag, or a width.

InvalidModifier#

silk
InvalidModifier

A : is before a directive other than %z, or a . is before a directive other than %f and %N.

WidthTooLarge#

silk
WidthTooLarge

A width is above 64.

NotAvailable#

silk
NotAvailable

The directive needs a part that the value does not have, such as %H for a PlainDate.

NotReadable#

silk
NotReadable

The directive is %Z, which can be written and cannot be read.

MissingDate#

silk
MissingDate

The pattern does not give a date, and the type needs one.

MissingTime#

silk
MissingTime

The pattern does not give a time of day, and the type needs one.

MissingOffset#

silk
MissingOffset

The pattern does not give a UTC offset, and the type needs one.

Implementation Debug for PatternReason#

silk
impl Debug for PatternReason

Operation debug#

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

PatternError#

silk
pub struct PatternError

The error of a pattern that is known only at run time: why the pattern cannot be used and where.

Field reason#

silk
pub reason: PatternReason

The cause.

Field offset#

silk
pub offset: usize

The byte offset of the directive in the pattern. For a missing part it is the length of the pattern.

Implementation Copy for PatternError#

silk
impl Copy for PatternError

Implementation Debug for PatternError#

silk
impl Debug for PatternError

Operation debug#

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

PatternParts#

silk
pub struct PatternParts

The parts of a value that directives can write.

Field date#

silk
pub date: bool

The value has a date.

Field time#

silk
pub time: bool

The value has a time of day.

Field offset#

silk
pub offset: bool

The value has a UTC offset.

Field zone#

silk
pub zone: bool

The value has a time zone abbreviation.

Implementation Copy for PatternParts#

silk
impl Copy for PatternParts

PatternKind#

silk
pub enum PatternKind

What a type needs from a pattern to be read from text.

Date#

silk
Date

A date.

Time#

silk
Time

A time of day.

DateTime#

silk
DateTime

A date. The time of day is midnight if the pattern has none.

Instant#

silk
Instant

A date, a time of day and a UTC offset, or the seconds from the Unix epoch.

TimeFields#

silk
pub struct TimeFields

The fields of a date and time that directives write.

When to use#

Return it from PatternSource.fields to make a type of your own writable with a pattern. Fields that the type does not have can hold any value, because the directives that read them are refused for the type.

Field year#

silk
pub year: i32

The year.

Field month#

silk
pub month: u8

The month, 1 to 12.

Field day#

silk
pub day: u8

The day of the month, 1 to 31.

Field hour#

silk
pub hour: u8

The hour, 0 to 23.

Field minute#

silk
pub minute: u8

The minute, 0 to 59.

Field second#

silk
pub second: u8

The second, 0 to 59.

Field nanosecond#

silk
pub nanosecond: u32

The nanoseconds in the second.

Field offsetSeconds#

silk
pub offsetSeconds: i32

The UTC offset in seconds.

Field abbreviation#

silk
pub abbreviation: [u8; 12]

The time zone abbreviation, in the first abbreviationLength bytes.

Field abbreviationLength#

silk
pub abbreviationLength: usize

The length of the abbreviation.

Implementation Copy for TimeFields#

silk
impl Copy for TimeFields

Implementation TimeFields#

silk
impl TimeFields

Associated function ofDate#

silk
pub fn ofDate(date: PlainDate) -> TimeFields

Returns the fields of date at midnight UTC.

Method withTime#

silk
pub fn withTime(self: Self, time: PlainTime) -> TimeFields

Returns the fields with the time of day time.

Method withZone#

silk
pub fn withZone(self: Self, offset: UtcOffset, name: string) -> TimeFields

Returns the fields with the UTC offset offset and the time zone abbreviation name, of which the first 12 bytes are kept.

PatternSource#

silk
pub interface PatternSource

A value that a pattern can write.

Details#

It is implemented for PlainDate, PlainTime, PlainDateTime, Instant, which is written in UTC, and ZonedDateTime.

Operation parts#

silk
static fn parts() -> PatternParts

Returns the parts that the type has. A directive that needs another part is refused.

Operation fields#

silk
fn fields(self: &Self) -> TimeFields

Returns the fields of the value.

Implementation PatternSource for PlainDate#

silk
impl PatternSource for PlainDate

Operation parts#

silk
static fn parts() -> PatternParts

A date only.

Operation fields#

silk
fn fields(self: &Self) -> TimeFields

Returns the date at midnight.

Implementation PatternSource for PlainTime#

silk
impl PatternSource for PlainTime

Operation parts#

silk
static fn parts() -> PatternParts

A time of day only.

Operation fields#

silk
fn fields(self: &Self) -> TimeFields

Returns the time of day.

Implementation PatternSource for PlainDateTime#

silk
impl PatternSource for PlainDateTime

Operation parts#

silk
static fn parts() -> PatternParts

A date and a time of day.

Operation fields#

silk
fn fields(self: &Self) -> TimeFields

Returns the date and the time of day.

Implementation PatternSource for Instant#

silk
impl PatternSource for Instant

Operation parts#

silk
static fn parts() -> PatternParts

Every part: the date and time in UTC, the offset zero and the abbreviation UTC.

Operation fields#

silk
fn fields(self: &Self) -> TimeFields

Returns the date and time in UTC.

Implementation PatternSource for ZonedDateTime<'z>#

silk
impl<'z> PatternSource for ZonedDateTime<'z>

Operation parts#

silk
static fn parts() -> PatternParts

Every part.

Operation fields#

silk
fn fields(self: &Self) -> TimeFields

Returns the local date and time, the offset and the abbreviation of the zone.

PatternTarget#

silk
pub interface PatternTarget

A type that a pattern can read.

Details#

It is implemented for PlainDate, PlainTime, PlainDateTime and Instant. To read a ZonedDateTime, read a PlainDateTime and give it a zone with ZonedDateTime.fromLocal.

Operation kind#

silk
static fn kind() -> PatternKind

Returns what the type needs from a pattern.

Operation resolve#

silk
fn resolve(parsed: &ParsedFields) -> Result<Self, TimeParseError>

Returns the value that the fields name.

Errors#

  • TimeParseError if a part is missing or names no real value.

Implementation PatternTarget for PlainDate#

silk
impl PatternTarget for PlainDate

Operation kind#

silk
static fn kind() -> PatternKind

A date.

Operation resolve#

silk
fn resolve(parsed: &ParsedFields) -> Result<PlainDate, TimeParseError>

Returns the date.

Implementation PatternTarget for PlainTime#

silk
impl PatternTarget for PlainTime

Operation kind#

silk
static fn kind() -> PatternKind

A time of day.

Operation resolve#

silk
fn resolve(parsed: &ParsedFields) -> Result<PlainTime, TimeParseError>

Returns the time of day.

Implementation PatternTarget for PlainDateTime#

silk
impl PatternTarget for PlainDateTime

Operation kind#

silk
static fn kind() -> PatternKind

A date, with a time of day if the pattern has one.

Operation resolve#

silk
fn resolve(parsed: &ParsedFields) -> Result<PlainDateTime, TimeParseError>

Returns the date and time.

Implementation PatternTarget for Instant#

silk
impl PatternTarget for Instant

Operation kind#

silk
static fn kind() -> PatternKind

A date, a time of day and an offset, or the seconds from the Unix epoch.

Operation resolve#

silk
fn resolve(parsed: &ParsedFields) -> Result<Instant, TimeParseError>

Returns the instant.

ParsedFields#

silk
pub struct ParsedFields

What a pattern read from a text, before it becomes a value.

When to use#

Get it from TimePattern.parseFields to read a text that has more than one value, such as a local date and time with its offset, or to accept a text that can leave parts out.

Implementation Copy for ParsedFields#

silk
impl Copy for ParsedFields

Implementation ParsedFields#

silk
impl ParsedFields

Method weekday#

silk
pub fn weekday(self: &Self) -> Option<Weekday>

Returns the weekday that the text names, or None if the pattern has no weekday.

Method offset#

silk
pub fn offset(self: &Self) -> Option<UtcOffset>

Returns the UTC offset that the text names, or None if the pattern has no %z.

Method date#

silk
pub fn date(self: &Self) -> Result<PlainDate, TimeParseError>

Returns the date that the text names.

Details#

The date is the year with the month and the day, or with the day of the year, or with a week of %U or %W and a weekday, or the ISO 8601 week year with %V and a weekday. A text with only %s gives the date in UTC.

Errors#

  • TimeParseReason.MissingDate if the pattern does not give a date.

  • TimeParseReason.OutOfRange if the date does not exist, or a weekday in the text is not the weekday of the date.

Method time#

silk
pub fn time(self: &Self) -> Result<PlainTime, TimeParseError>

Returns the time of day that the text names.

Details#

The hour is %H, or %I with %p; %I without %p is before noon. The minute, the second and the fraction are 0 if the pattern has none. A text with only %s gives the time in UTC.

Errors#

  • TimeParseReason.MissingTime if the pattern does not give an hour.

  • TimeParseReason.OutOfRange if the time does not exist, such as hour 24 or second 60.

Method dateTime#

silk
pub fn dateTime(self: &Self) -> Result<PlainDateTime, TimeParseError>

Returns the date and time that the text names. The time is midnight if the pattern has no time of day.

Errors#

  • TimeParseReason.MissingDate if the pattern does not give a date.

  • TimeParseReason.OutOfRange if the date or the time does not exist.

Method instant#

silk
pub fn instant(self: &Self) -> Result<Instant, TimeParseError>

Returns the instant that the text names: the seconds of %s, or the date and time at the offset of %z.

Errors#

  • TimeParseReason.MissingDate, MissingTime or MissingOffset if the pattern does not give that part and has no %s.

  • TimeParseReason.OutOfRange if the date or the time does not exist, or the instant is outside the range of Instant.

TimePattern#

silk
pub struct TimePattern

Functions that write and read dates and times with strftime patterns.

Implementation TimePattern#

silk
impl TimePattern

Associated function write#

silk
pub effect fn write<T: PatternSource>(static pattern: string<'static>, value: &T) -> ()
    ! WriterError
    ? &mut Writer

Writes value with the constant pattern pattern to the Writer.

Details#

The pattern is checked when the program is compiled. A directive that is not known, or that needs a part value does not have, is a compile error.

Errors#

  • WriterError if the Writer fails.

Associated function format#

silk
pub effect fn format<T: PatternSource>(static pattern: string<'static>, value: &T) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns value written with the constant pattern pattern.

Details#

The pattern is checked when the program is compiled, as TimePattern.write checks it.

Errors#

  • OutOfMemoryError if the Allocator cannot supply the text.

Associated function parse#

silk
pub fn parse<T: PatternTarget>(static pattern: string<'static>, text: string) -> Result<T, TimeParseError>

Reads a T from text with the constant pattern pattern.

Details#

The pattern is checked when the program is compiled. A directive that is not known, %Z, or a pattern that does not give what T needs, such as a PlainDate without a year, is a compile error.

Errors#

  • TimeParseReason.UnexpectedEnd or UnexpectedCharacter if text does not have the form of the pattern.

  • TimeParseReason.OutOfRange if a field names no real value, such as month 13 or February 30, or a weekday that is not the weekday of the date.

Associated function parseFields#

silk
pub fn parseFields(static pattern: string<'static>, text: string) -> Result<ParsedFields, TimeParseError>

Reads the fields of text with the constant pattern pattern, without making a value.

When to use#

Use it for a text that has more than one value, or parts that a single type does not hold, and take the values with ParsedFields.date, ParsedFields.time and the others.

Errors#

  • TimeParseReason.UnexpectedEnd or UnexpectedCharacter if text does not have the form of the pattern.

  • TimeParseReason.OutOfRange if a field is outside its range, such as month 13.

Associated function validate#

silk
pub fn validate<T: PatternSource>(pattern: string) -> Result<(), PatternError>

Checks a pattern that is known only at run time, for writing a T.

Errors#

  • PatternError if a directive is malformed or unknown, or needs a part that T does not have.

Associated function formatDynamic#

silk
pub effect fn formatDynamic<T: PatternSource>(pattern: string, value: &T) -> Result<String, PatternError>
    ! OutOfMemoryError
    ? &mut Allocator

Returns value written with a pattern that is known only at run time.

Errors#

  • PatternError as the Result failure if a directive is malformed or unknown, or needs a part that value does not have.

  • OutOfMemoryError if the Allocator cannot supply the text.

Associated function parseFieldsDynamic#

silk
pub fn parseFieldsDynamic(pattern: string, text: string) -> Result<Result<ParsedFields, TimeParseError>, PatternError>

Reads the fields of text with a pattern that is known only at run time.

Details#

The outer Result fails for a pattern that cannot be used, and the inner one for a text that does not have the form of the pattern.

Errors#

  • PatternError if a directive is malformed or unknown, or is %Z.

  • TimeParseError in the inner Result, as TimePattern.parseFields returns it.

Associated function parseDynamic#

silk
pub fn parseDynamic<T: PatternTarget>(pattern: string, text: string) -> Result<Result<T, TimeParseError>, PatternError>

Reads a T from text with a pattern that is known only at run time.

Details#

The outer Result fails for a pattern that cannot be used, and the inner one for a text that does not have the form of the pattern.

Errors#

  • PatternError if a directive is malformed or unknown, or is %Z, or the pattern does not give what T needs.

  • TimeParseError in the inner Result, as TimePattern.parse returns it.

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