silk.time.plain_date.

Calendar dates without a time or a time zone: the PlainDate type and Weekday.

When to use#

Use PlainDate for a day that means the same thing everywhere, such as a birthday, a due date, or a date in a file. It is not a point in time: the same date starts at different instants in different time zones. For a point in time, use silk.time.instant.

Details#

Dates are in the ISO 8601 calendar, which applies the Gregorian leap year rule to every year. The range is -271821-04-19 to +275760-09-13, the range of ECMAScript Temporal. Values are always valid dates: a PlainDate cannot hold February 30.

Examples#

Parse a date, move it, and print it#

silk
import silk.core.result { Result }
import silk.time.plain_date { PlainDate, Weekday }
import silk.time.text { TimeParseError }

pub fn main() -> i32 {
  match PlainDate.parse("2026-11-19") {
    Result<PlainDate, TimeParseError>.Success { value } => {
      let later = value.addDays(45)
      if later.year() != 2027 || later.month() != 1 || later.day() != 3 {
        return 1
      }
      if value.daysUntil(later) != 45 {
        return 2
      }
      match value.weekday() {
        Weekday.Thursday => {
          return 0
        }
        _ => {
          return 3
        }
      }
    }
    Result<PlainDate, TimeParseError>.Failure { error: _ } => {
      return 4
    }
  }
}

Import as PlainDate with import silk.time.plain_date { PlainDate }.

Public declarations: 2.

Weekday#

silk
pub enum Weekday

A day of the week.

Monday#

silk
Monday

Day 1 of the ISO 8601 week.

Tuesday#

silk
Tuesday

Day 2 of the ISO 8601 week.

Wednesday#

silk
Wednesday

Day 3 of the ISO 8601 week.

Thursday#

silk
Thursday

Day 4 of the ISO 8601 week.

Friday#

silk
Friday

Day 5 of the ISO 8601 week.

Saturday#

silk
Saturday

Day 6 of the ISO 8601 week.

Sunday#

silk
Sunday

Day 7 of the ISO 8601 week.

Implementation Weekday#

silk
impl Weekday

Method number#

silk
pub fn number(self: Self) -> u8

Returns the ISO 8601 number of the day: 1 for Monday to 7 for Sunday.

Associated function fromNumber#

silk
pub fn fromNumber(number: u8) -> Option<Weekday>

Returns the day with the ISO 8601 number number, 1 for Monday to 7 for Sunday, or None for another number.

Method name#

silk
pub fn name(self: Self) -> string<'static>

Returns the English name of the day, such as Monday.

Implementation Debug for Weekday#

silk
impl Debug for Weekday

Writes the English name of the day, such as Monday.

Operation debug#

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

PlainDate#

silk
pub struct PlainDate

A calendar date in the ISO 8601 calendar: a year, a month, and a day, with no time and no time zone.

Details#

A value is always a date that exists, from -271821-04-19 to +275760-09-13. Year 0 is the year before year 1. ==, !=, <, <=, >, and >= compare dates in calendar order. Display writes YYYY-MM-DD, with a sign and six digits for a year outside 0 to 9999.

Implementation Copy for PlainDate#

silk
impl Copy for PlainDate

Implementation PlainDate#

silk
impl PlainDate

Associated function make#

silk
pub fn make(year: i32, month: u8, day: u8) -> PlainDate

Returns the date with the given year, month from 1 to 12, and day of the month from 1.

Gotchas#

A date that does not exist, such as February 30, or a date outside the range traps. PlainDate.checkedMake returns None instead.

Associated function checkedMake#

silk
pub fn checkedMake(year: i32, month: u8, day: u8) -> Option<PlainDate>

Returns the date with the given year, month from 1 to 12, and day of the month from 1, or None when that date does not exist or is outside -271821-04-19 to +275760-09-13.

Associated function min#

silk
pub fn min() -> PlainDate

Returns the first date of the range, -271821-04-19.

Associated function max#

silk
pub fn max() -> PlainDate

Returns the last date of the range, +275760-09-13.

Associated function fromEpochDays#

silk
pub fn fromEpochDays(days: i64) -> Option<PlainDate>

Returns the date that is days days after 1970-01-01, or None when it is outside the range. days can be negative.

Method toEpochDays#

silk
pub fn toEpochDays(self: Self) -> i64

Returns the number of days from 1970-01-01 to this date. It is negative for an earlier date.

Method year#

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

Returns the year. Year 0 is the year before year 1.

Method month#

silk
pub fn month(self: Self) -> u8

Returns the month, from 1 for January to 12 for December.

Method day#

silk
pub fn day(self: Self) -> u8

Returns the day of the month, from 1.

Method toCivil#

silk
pub fn toCivil(self: Self) -> CivilDate

Returns the year, month, and day as plain numbers.

Method weekday#

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

Returns the day of the week.

Method dayOfYear#

silk
pub fn dayOfYear(self: Self) -> u16

Returns the day of the year: 1 for January 1, up to 365, or 366 in a leap year.

Method weekOfYear#

silk
pub fn weekOfYear(self: Self) -> u8

Returns the ISO 8601 week number of the date, from 1 to 53.

Details#

Weeks start on Monday, and week 1 is the week with the first Thursday of the year. So the first days of January can be in week 52 or 53 of the year before, and the last days of December can be in week 1 of the next year. PlainDate.yearOfWeek gives the year that the week belongs to.

Method yearOfWeek#

silk
pub fn yearOfWeek(self: Self) -> i32

Returns the year that the ISO 8601 week of the date belongs to.

Details#

It differs from PlainDate.year for the days of January in the last week of the year before, and the days of December in week 1 of the next year. 2027-01-01 is in week 53 of 2026.

Method daysInMonth#

silk
pub fn daysInMonth(self: Self) -> u8

Returns the number of days in the month of the date, from 28 to 31.

Method daysInYear#

silk
pub fn daysInYear(self: Self) -> u16

Returns the number of days in the year of the date: 366 in a leap year, 365 otherwise.

Method inLeapYear#

silk
pub fn inLeapYear(self: Self) -> bool

Returns true if the year of the date is a leap year.

Method checkedAddDays#

silk
pub fn checkedAddDays(self: Self, days: i64) -> Option<PlainDate>

Returns the date days days later, or earlier for a negative count, or None when it is outside the range.

Method addDays#

silk
pub fn addDays(self: Self, days: i64) -> PlainDate

Returns the date days days later, or earlier for a negative count.

Gotchas#

A result outside the range traps. PlainDate.checkedAddDays returns None instead.

Method daysUntil#

silk
pub fn daysUntil(self: Self, other: PlainDate) -> i64

Returns the number of days from this date to other. It is negative when other is earlier.

Method checkedAddPeriod#

silk
pub fn checkedAddPeriod(self: Self, period: Period, overflow: Overflow) -> Option<PlainDate>

Returns the date that period leads to from this date, or None when it is outside the range, or when overflow is Reject and the day does not exist in the month reached.

Details#

The years and months are added first. If the month reached has no such day, as for one month after January 31, Overflow.Constrain uses the last day of that month. Then the weeks and days are added, with the whole days of the time part of the period; the rest of the time part is dropped. This is the rule of ECMAScript Temporal.

Gotchas#

The order matters, so adding and then subtracting the same period does not always return the first date: January 31 plus one month is the end of February, and one month before that is January 28 or 29.

Method addPeriod#

silk
pub fn addPeriod(self: Self, period: Period) -> PlainDate

Returns the date that period leads to from this date, with a day that does not exist in the month reached replaced by the last day of that month.

Details#

The rule is the one of PlainDate.checkedAddPeriod with Overflow.Constrain. To go back, add period.negate().

Gotchas#

A result outside the range traps. PlainDate.checkedAddPeriod returns None instead.

Method checkedAddParts#

silk
pub fn checkedAddParts(self: Self, years: i64, months: i64, days: i64, overflow: Overflow) -> Option<PlainDate>

Returns the date years years and months months from this date, and then days days from there, or None when it is outside the range, or when overflow is Reject and the day does not exist in the month reached.

Details#

It is PlainDate.checkedAddPeriod for counts that can have different signs, such as one month later and one day earlier.

Method periodUntil#

silk
pub fn periodUntil(self: Self, other: PlainDate, largest: DateUnit) -> Period

Returns the calendar span from this date to other, counted in largest units first. It is negative when other is earlier, and its time part is empty.

Details#

With DateUnit.Year or DateUnit.Month, the result has the most whole months that can be added to this date without passing other, and then the days that are left. With DateUnit.Week, it has whole weeks and days, and with DateUnit.Day, only days. Adding the result to this date with PlainDate.addPeriod gives other. This is the rule of ECMAScript Temporal.

Gotchas#

The span from other back to this date is not always the negated result. From 2023-01-29 to 2023-03-01 is 1 month and 1 day, and from 2023-03-01 back to 2023-01-29 is 1 month and 3 days.

Associated function parse#

silk
pub fn parse(text: string) -> Result<PlainDate, TimeParseError>

Reads a date from ISO 8601 text such as 2026-11-19.

Details#

The text is YYYY-MM-DD or YYYYMMDD; a year outside 0 to 9999 has a sign and six digits. A time, a numeric UTC offset, and bracketed annotations can follow, as in 2026-11-19T17:36:22+01:00[Europe/Rome]. They are checked and then ignored.

Errors#

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

  • TimeParseReason.OutOfRange if a field names no real value, such as month 13 or February 30, or the date is outside -271821-04-19 to +275760-09-13.

  • TimeParseReason.UtcNotAllowed if the text has the UTC designator Z.

  • TimeParseReason.UnsupportedCalendar if a calendar annotation is not [u-ca=iso8601].

  • TimeParseReason.UnknownCriticalAnnotation if an annotation with an unknown key starts with !.

Associated function parseBytes#

silk
pub fn parseBytes(bytes: &[u8]) -> Result<PlainDate, TimeParseError>

Reads a date from the bytes of ISO 8601 text such as 2026-11-19.

Details#

The text is YYYY-MM-DD or YYYYMMDD; a year outside 0 to 9999 has a sign and six digits. A time, a numeric UTC offset, and bracketed annotations can follow. They are checked and then ignored.

Errors#

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

  • TimeParseReason.OutOfRange if a field names no real value, such as month 13 or February 30, or the date is outside -271821-04-19 to +275760-09-13.

  • TimeParseReason.UtcNotAllowed if the text has the UTC designator Z.

  • TimeParseReason.UnsupportedCalendar if a calendar annotation is not [u-ca=iso8601].

  • TimeParseReason.UnknownCriticalAnnotation if an annotation with an unknown key starts with !.

Implementation Equal for PlainDate#

silk
impl Equal for PlainDate

Operation equals#

silk
equals: PlainDate.same

Implementation Order for PlainDate#

silk
impl Order for PlainDate

Operation compare#

silk
compare: PlainDate.compare

Implementation Display for PlainDate#

silk
impl Display for PlainDate

Writes the date as YYYY-MM-DD, with a sign and six digits for a year outside 0 to 9999, as in 2026-11-19 or -000044-03-15.

Operation display#

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

Implementation Debug for PlainDate#

silk
impl Debug for PlainDate

Writes the same text as Display: the date as YYYY-MM-DD.

Operation debug#

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

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