silk.time.codec.
Codecs that read and write the silk.time types in any data format of silk.schema: as ISO
8601 text with TimeText, or as a Unix time with UnixSeconds and UnixMilliseconds.
When to use#
Use these codecs for a date or time in a field of a type that implements Schema. Wrap the
value in a type of your own, and call Schemas.readVia, Schemas.writeVia and
Schemas.shapeVia with the codec from its read, write and shape. Put a codec in a chain
of silk.schema.codec to trim the text first or to check the value afterwards.
To read a TOML date or time that is not text, use the TOML codecs of silk.toml.codec.
Details#
TimeText<T> is implemented for Instant, PlainDate, PlainTime, PlainDateTime,
PlainYearMonth, PlainMonthDay, Period and UtcOffset. Decoding calls the parse of the
type, so it accepts the same text, and fails with IssueReason.InvalidValue for other text.
Encoding writes the text that Display writes, which parse reads back to the same value.
Gotchas#
A Unix time has no fraction below its unit: UnixSeconds drops the part of an Instant below
one second when it encodes, and UnixMilliseconds the part below one millisecond.
Examples#
Decode a date and write it back#
import silk.core.effect { Effect }
import silk.core.result { Result }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.schema.codec { Codec }
import silk.schema.issue { Issue }
import silk.text.string { String }
import silk.time.codec { TimeText }
import silk.time.plain_date { PlainDate }
effect fn nextDay(text: string) -> String ! Issue | OutOfMemoryError ? &mut Allocator {
let codec = TimeText<PlainDate>.make()
let date = run Codec.decode(&codec, run String.copy(text))
return run Codec.encode(&codec, &date.addDays(1))
}
pub effect fn main() -> i32 ! OutOfMemoryError {
let mut allocator = Allocator.systemAllocatorProvider()
let written = run Effect.result(nextDay("2026-12-31")) |> Effect.provideMut<Allocator>(&mut allocator)
return match move written {
Result<String, Issue | OutOfMemoryError>.Success {value} => if value.view() == "2027-01-01" { 0 } else { 1 }
Result<String, Issue | OutOfMemoryError>.Failure {..} => 2
}
}Import as TimeText with import silk.time.codec { TimeText }.
Public declarations: 3.
TimeText#
pub struct TimeText<T>The codec between a silk.time value T and its ISO 8601 text.
Details#
It is implemented for Instant, PlainDate, PlainTime, PlainDateTime, PlainYearMonth,
PlainMonthDay, Period and UtcOffset. Decoding accepts the text that the parse of T
accepts, and fails with IssueReason.InvalidValue for other text. Encoding writes the text
that Display writes for T.
Field kind#
pub kind: [T; 0]Empty. It names the time type.
Implementation TimeText<T>#
impl<T> TimeText<T>Associated function make#
pub fn make() -> TimeText<T>Returns the codec for the time type T.
Implementation Codec<Instant, String> for TimeText<Instant>#
impl Codec<Instant, String> for TimeText<Instant>Operation decode#
effect fn decode(self: &Self, input: String) -> Instant ! Issue | OutOfMemoryError ? &mut AllocatorParses a date and time with an offset, such as 2026-11-19T18:36:22Z.
Operation encode#
effect fn encode(self: &Self, value: &Instant) -> String ! OutOfMemoryError ? &mut AllocatorWrites the instant in UTC, such as 2026-11-19T17:36:22Z.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is an RFC 3339 date and time with an offset.
Implementation Codec<PlainDate, String> for TimeText<PlainDate>#
impl Codec<PlainDate, String> for TimeText<PlainDate>Operation decode#
effect fn decode(self: &Self, input: String) -> PlainDate ! Issue | OutOfMemoryError ? &mut AllocatorParses a date, such as 2026-11-19.
Operation encode#
effect fn encode(self: &Self, value: &PlainDate) -> String ! OutOfMemoryError ? &mut AllocatorWrites the date as YYYY-MM-DD.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is an ISO 8601 date.
Implementation Codec<PlainTime, String> for TimeText<PlainTime>#
impl Codec<PlainTime, String> for TimeText<PlainTime>Operation decode#
effect fn decode(self: &Self, input: String) -> PlainTime ! Issue | OutOfMemoryError ? &mut AllocatorParses a time of day, such as 18:36:22.5.
Operation encode#
effect fn encode(self: &Self, value: &PlainTime) -> String ! OutOfMemoryError ? &mut AllocatorWrites the time as HH:MM:SS with the fraction it has.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is an ISO 8601 time of day.
Implementation Codec<PlainDateTime, String> for TimeText<PlainDateTime>#
impl Codec<PlainDateTime, String> for TimeText<PlainDateTime>Operation decode#
effect fn decode(self: &Self, input: String) -> PlainDateTime ! Issue | OutOfMemoryError ? &mut AllocatorParses a date and time without an offset, such as 2026-11-19T18:36:22.
Operation encode#
effect fn encode(self: &Self, value: &PlainDateTime) -> String ! OutOfMemoryError ? &mut AllocatorWrites the date, T, and the time.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is an ISO 8601 date and time.
Implementation Codec<PlainYearMonth, String> for TimeText<PlainYearMonth>#
impl Codec<PlainYearMonth, String> for TimeText<PlainYearMonth>Operation decode#
effect fn decode(self: &Self, input: String) -> PlainYearMonth ! Issue | OutOfMemoryError ? &mut AllocatorParses a year and month, such as 2026-11.
Operation encode#
effect fn encode(self: &Self, value: &PlainYearMonth) -> String ! OutOfMemoryError ? &mut AllocatorWrites the month as YYYY-MM.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is an ISO 8601 year and month.
Implementation Codec<PlainMonthDay, String> for TimeText<PlainMonthDay>#
impl Codec<PlainMonthDay, String> for TimeText<PlainMonthDay>Operation decode#
effect fn decode(self: &Self, input: String) -> PlainMonthDay ! Issue | OutOfMemoryError ? &mut AllocatorParses a month and day, such as 11-19 or --11-19.
Operation encode#
effect fn encode(self: &Self, value: &PlainMonthDay) -> String ! OutOfMemoryError ? &mut AllocatorWrites the day as MM-DD.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is an ISO 8601 month and day.
Implementation Codec<Period, String> for TimeText<Period>#
impl Codec<Period, String> for TimeText<Period>Operation decode#
effect fn decode(self: &Self, input: String) -> Period ! Issue | OutOfMemoryError ? &mut AllocatorParses a duration, such as P1Y2M3DT4H.
Operation encode#
effect fn encode(self: &Self, value: &Period) -> String ! OutOfMemoryError ? &mut AllocatorWrites the period as an ISO 8601 duration.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is an ISO 8601 duration.
Implementation Codec<UtcOffset, String> for TimeText<UtcOffset>#
impl Codec<UtcOffset, String> for TimeText<UtcOffset>Operation decode#
effect fn decode(self: &Self, input: String) -> UtcOffset ! Issue | OutOfMemoryError ? &mut AllocatorParses an offset, such as +01:00 or Z.
Operation encode#
effect fn encode(self: &Self, value: &UtcOffset) -> String ! OutOfMemoryError ? &mut AllocatorWrites the offset, such as +01:00.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the text is a UTC offset.
UnixSeconds#
pub struct UnixSecondsThe codec between an Instant and a count of whole seconds from the Unix epoch.
Details#
Decoding fails with IssueReason.InvalidValue for a count outside the range of Instant.
Encoding rounds down to the second, so an instant before 1970 with a fraction gives the second
before it.
Implementation Codec<Instant, i64> for UnixSeconds#
impl Codec<Instant, i64> for UnixSecondsOperation decode#
effect fn decode(self: &Self, input: i64) -> Instant ! Issue | OutOfMemoryError ? &mut AllocatorReturns the instant input seconds from the Unix epoch.
Operation encode#
effect fn encode(self: &Self, value: &Instant) -> i64 ! OutOfMemoryError ? &mut AllocatorReturns the whole seconds from the Unix epoch to value.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the number is a Unix time in seconds.
UnixMilliseconds#
pub struct UnixMillisecondsThe codec between an Instant and a count of whole milliseconds from the Unix epoch, the time
value of JavaScript.
Details#
Decoding fails with IssueReason.InvalidValue for a count outside the range of Instant.
Encoding rounds down to the millisecond.
Implementation Codec<Instant, i64> for UnixMilliseconds#
impl Codec<Instant, i64> for UnixMillisecondsOperation decode#
effect fn decode(self: &Self, input: i64) -> Instant ! Issue | OutOfMemoryError ? &mut AllocatorReturns the instant input milliseconds from the Unix epoch.
Operation encode#
effect fn encode(self: &Self, value: &Instant) -> i64 ! OutOfMemoryError ? &mut AllocatorReturns the whole milliseconds from the Unix epoch to value.
Operation hints#
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
-> () ! OutOfMemoryError ? &mut AllocatorReports that the number is a Unix time in milliseconds.
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.