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#

silk
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#

silk
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#

silk
pub kind: [T; 0]

Empty. It names the time type.

Implementation TimeText<T>#

silk
impl<T> TimeText<T>

Associated function make#

silk
pub fn make() -> TimeText<T>

Returns the codec for the time type T.

Implementation Codec<Instant, String> for TimeText<Instant>#

silk
impl Codec<Instant, String> for TimeText<Instant>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> Instant ! Issue | OutOfMemoryError ? &mut Allocator

Parses a date and time with an offset, such as 2026-11-19T18:36:22Z.

Operation encode#

silk
effect fn encode(self: &Self, value: &Instant) -> String ! OutOfMemoryError ? &mut Allocator

Writes the instant in UTC, such as 2026-11-19T17:36:22Z.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is an RFC 3339 date and time with an offset.

Implementation Codec<PlainDate, String> for TimeText<PlainDate>#

silk
impl Codec<PlainDate, String> for TimeText<PlainDate>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> PlainDate ! Issue | OutOfMemoryError ? &mut Allocator

Parses a date, such as 2026-11-19.

Operation encode#

silk
effect fn encode(self: &Self, value: &PlainDate) -> String ! OutOfMemoryError ? &mut Allocator

Writes the date as YYYY-MM-DD.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is an ISO 8601 date.

Implementation Codec<PlainTime, String> for TimeText<PlainTime>#

silk
impl Codec<PlainTime, String> for TimeText<PlainTime>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> PlainTime ! Issue | OutOfMemoryError ? &mut Allocator

Parses a time of day, such as 18:36:22.5.

Operation encode#

silk
effect fn encode(self: &Self, value: &PlainTime) -> String ! OutOfMemoryError ? &mut Allocator

Writes the time as HH:MM:SS with the fraction it has.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is an ISO 8601 time of day.

Implementation Codec<PlainDateTime, String> for TimeText<PlainDateTime>#

silk
impl Codec<PlainDateTime, String> for TimeText<PlainDateTime>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> PlainDateTime ! Issue | OutOfMemoryError ? &mut Allocator

Parses a date and time without an offset, such as 2026-11-19T18:36:22.

Operation encode#

silk
effect fn encode(self: &Self, value: &PlainDateTime) -> String ! OutOfMemoryError ? &mut Allocator

Writes the date, T, and the time.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is an ISO 8601 date and time.

Implementation Codec<PlainYearMonth, String> for TimeText<PlainYearMonth>#

silk
impl Codec<PlainYearMonth, String> for TimeText<PlainYearMonth>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> PlainYearMonth ! Issue | OutOfMemoryError ? &mut Allocator

Parses a year and month, such as 2026-11.

Operation encode#

silk
effect fn encode(self: &Self, value: &PlainYearMonth) -> String ! OutOfMemoryError ? &mut Allocator

Writes the month as YYYY-MM.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is an ISO 8601 year and month.

Implementation Codec<PlainMonthDay, String> for TimeText<PlainMonthDay>#

silk
impl Codec<PlainMonthDay, String> for TimeText<PlainMonthDay>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> PlainMonthDay ! Issue | OutOfMemoryError ? &mut Allocator

Parses a month and day, such as 11-19 or --11-19.

Operation encode#

silk
effect fn encode(self: &Self, value: &PlainMonthDay) -> String ! OutOfMemoryError ? &mut Allocator

Writes the day as MM-DD.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is an ISO 8601 month and day.

Implementation Codec<Period, String> for TimeText<Period>#

silk
impl Codec<Period, String> for TimeText<Period>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> Period ! Issue | OutOfMemoryError ? &mut Allocator

Parses a duration, such as P1Y2M3DT4H.

Operation encode#

silk
effect fn encode(self: &Self, value: &Period) -> String ! OutOfMemoryError ? &mut Allocator

Writes the period as an ISO 8601 duration.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is an ISO 8601 duration.

Implementation Codec<UtcOffset, String> for TimeText<UtcOffset>#

silk
impl Codec<UtcOffset, String> for TimeText<UtcOffset>

Operation decode#

silk
effect fn decode(self: &Self, input: String) -> UtcOffset ! Issue | OutOfMemoryError ? &mut Allocator

Parses an offset, such as +01:00 or Z.

Operation encode#

silk
effect fn encode(self: &Self, value: &UtcOffset) -> String ! OutOfMemoryError ? &mut Allocator

Writes the offset, such as +01:00.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the text is a UTC offset.

UnixSeconds#

silk
pub struct UnixSeconds

The 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#

silk
impl Codec<Instant, i64> for UnixSeconds

Operation decode#

silk
effect fn decode(self: &Self, input: i64) -> Instant ! Issue | OutOfMemoryError ? &mut Allocator

Returns the instant input seconds from the Unix epoch.

Operation encode#

silk
effect fn encode(self: &Self, value: &Instant) -> i64 ! OutOfMemoryError ? &mut Allocator

Returns the whole seconds from the Unix epoch to value.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports that the number is a Unix time in seconds.

UnixMilliseconds#

silk
pub struct UnixMilliseconds

The 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#

silk
impl Codec<Instant, i64> for UnixMilliseconds

Operation decode#

silk
effect fn decode(self: &Self, input: i64) -> Instant ! Issue | OutOfMemoryError ? &mut Allocator

Returns the instant input milliseconds from the Unix epoch.

Operation encode#

silk
effect fn encode(self: &Self, value: &Instant) -> i64 ! OutOfMemoryError ? &mut Allocator

Returns the whole milliseconds from the Unix epoch to value.

Operation hints#

silk
effect fn hints(self: &Self, constraints: &mut List<Constraint>, notes: &mut List<string<'static>>, onWire: bool)
    -> () ! OutOfMemoryError ? &mut Allocator

Reports 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.

View the source of this page