silk.time.plain_date.
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#
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#
pub enum WeekdayA day of the week.
Monday#
MondayDay 1 of the ISO 8601 week.
Tuesday#
TuesdayDay 2 of the ISO 8601 week.
Wednesday#
WednesdayDay 3 of the ISO 8601 week.
Thursday#
ThursdayDay 4 of the ISO 8601 week.
Friday#
FridayDay 5 of the ISO 8601 week.
Saturday#
SaturdayDay 6 of the ISO 8601 week.
Sunday#
SundayDay 7 of the ISO 8601 week.
Implementation Weekday#
impl WeekdayMethod number#
pub fn number(self: Self) -> u8Returns the ISO 8601 number of the day: 1 for Monday to 7 for Sunday.
Associated function fromNumber#
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#
pub fn name(self: Self) -> string<'static>Returns the English name of the day, such as Monday.
Implementation Debug for Weekday#
impl Debug for WeekdayWrites the English name of the day, such as Monday.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterPlainDate#
pub struct PlainDateA 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#
impl Copy for PlainDateImplementation PlainDate#
impl PlainDateAssociated function make#
pub fn make(year: i32, month: u8, day: u8) -> PlainDateReturns 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#
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#
pub fn min() -> PlainDateReturns the first date of the range, -271821-04-19.
Associated function max#
pub fn max() -> PlainDateReturns the last date of the range, +275760-09-13.
Associated function fromEpochDays#
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#
pub fn toEpochDays(self: Self) -> i64Returns the number of days from 1970-01-01 to this date. It is negative for an earlier
date.
Method year#
pub fn year(self: Self) -> i32Returns the year. Year 0 is the year before year 1.
Method month#
pub fn month(self: Self) -> u8Returns the month, from 1 for January to 12 for December.
Method day#
pub fn day(self: Self) -> u8Returns the day of the month, from 1.
Method toCivil#
pub fn toCivil(self: Self) -> CivilDateReturns the year, month, and day as plain numbers.
Method weekday#
pub fn weekday(self: Self) -> WeekdayReturns the day of the week.
Method dayOfYear#
pub fn dayOfYear(self: Self) -> u16Returns the day of the year: 1 for January 1, up to 365, or 366 in a leap year.
Method weekOfYear#
pub fn weekOfYear(self: Self) -> u8Returns 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#
pub fn yearOfWeek(self: Self) -> i32Returns 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#
pub fn daysInMonth(self: Self) -> u8Returns the number of days in the month of the date, from 28 to 31.
Method daysInYear#
pub fn daysInYear(self: Self) -> u16Returns the number of days in the year of the date: 366 in a leap year, 365 otherwise.
Method inLeapYear#
pub fn inLeapYear(self: Self) -> boolReturns true if the year of the date is a leap year.
Method checkedAddDays#
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#
pub fn addDays(self: Self, days: i64) -> PlainDateReturns 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#
pub fn daysUntil(self: Self, other: PlainDate) -> i64Returns the number of days from this date to other. It is negative when other is earlier.
Method checkedAddPeriod#
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#
pub fn addPeriod(self: Self, period: Period) -> PlainDateReturns 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#
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#
pub fn periodUntil(self: Self, other: PlainDate, largest: DateUnit) -> PeriodReturns 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#
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.UnexpectedEndorUnexpectedCharacterif the text does not have that form.TimeParseReason.OutOfRangeif a field names no real value, such as month 13 or February 30, or the date is outside-271821-04-19to+275760-09-13.TimeParseReason.UtcNotAllowedif the text has the UTC designatorZ.TimeParseReason.UnsupportedCalendarif a calendar annotation is not[u-ca=iso8601].TimeParseReason.UnknownCriticalAnnotationif an annotation with an unknown key starts with!.
Associated function parseBytes#
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.UnexpectedEndorUnexpectedCharacterif the text does not have that form.TimeParseReason.OutOfRangeif a field names no real value, such as month 13 or February 30, or the date is outside-271821-04-19to+275760-09-13.TimeParseReason.UtcNotAllowedif the text has the UTC designatorZ.TimeParseReason.UnsupportedCalendarif a calendar annotation is not[u-ca=iso8601].TimeParseReason.UnknownCriticalAnnotationif an annotation with an unknown key starts with!.
Implementation Equal for PlainDate#
impl Equal for PlainDateOperation equals#
equals: PlainDate.sameImplementation Order for PlainDate#
impl Order for PlainDateOperation compare#
compare: PlainDate.compareImplementation Display for PlainDate#
impl Display for PlainDateWrites 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#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for PlainDate#
impl Debug for PlainDateWrites the same text as Display: the date as YYYY-MM-DD.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterCategory: 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.