silk.time.period.
Calendar spans: the Period type, a number of years, months, weeks, and days with an exact
time part, as in "1 month and 2 days".
When to use#
Use Period for a span that a person counts on a calendar: a monthly bill, an age, three
weeks of leave. Its length in seconds depends on where it starts, because months and years
differ in length and a day in a time zone can have 23 or 25 hours. For a span of a fixed
length, such as a timeout, use Duration of silk.time.duration.
Details#
A Period has four calendar fields and one Duration for the time below a day. All parts
that are not zero have the same sign. The calendar fields are not balanced: 14 months stay
14 months, and 1 month is not equal to 30 days. The time part is exact, so 90 minutes and
1 hour 30 minutes are the same value.
The text form is the ISO 8601 duration, such as P1Y2M3DT4H30M. PlainDate.addPeriod and
PlainDate.periodUntil of silk.time.plain_date, and the same functions of
silk.time.plain_date_time, apply a period to a date and measure one. RelativeTo of
silk.time.relative rounds a period, counts it in one unit, and changes its largest unit,
from a starting point.
Examples#
Read a period and look at its parts#
import silk.core.result { Result }
import silk.time.period { Period }
import silk.time.text { TimeParseError }
pub fn main() -> i32 {
match Period.parse("P1Y2M10DT2H30M") {
Result<Period, TimeParseError>.Success { value } => {
if value.years() != 1 || value.months() != 2 || value.weeks() != 0 || value.days() != 10 {
return 1
}
if value.time().wholeSeconds() != 9000 {
return 2
}
if value.negate().sign() != -1 {
return 3
}
return 0
}
Result<Period, TimeParseError>.Failure { error: _ } => {
return 4
}
}
}Import as Period with import silk.time.period { Period }.
Public declarations: 3.
DateUnit#
pub enum DateUnitThe largest calendar unit of a measured Period.
Details#
PlainDate.periodUntil counts in this unit first and in the smaller units after it. With
Month, the span from January 1 of one year to March 1 of the next is 14 months; with
Year, it is 1 year and 2 months; with Day, it is 424 or 425 days.
Year#
YearYears, then months, then days.
Month#
MonthMonths, then days.
Week#
WeekWeeks, then days.
Day#
DayDays only.
Overflow#
pub enum OverflowWhat to do when a date that a period leads to does not exist, such as February 30.
Constrain#
ConstrainUse the last day of that month.
Reject#
RejectGive no result.
Period#
pub struct PeriodA calendar span: years, months, weeks, days, and an exact time part.
Details#
All parts that are not zero have the same sign. == and != compare part by part, so
P1M and P30D are not equal, and neither are P7D and P1W.
Display writes an ISO 8601 duration, such as P1Y2M3DT4H30M, -P3W, or PT0S for the
empty period.
Implementation Copy for Period#
impl Copy for PeriodImplementation Period#
impl PeriodAssociated function zero#
pub fn zero() -> PeriodReturns the empty period.
Associated function make#
pub fn make(years: i64, months: i64, weeks: i64, days: i64, time: Duration) -> PeriodReturns the period with the given parts.
Gotchas#
Parts with different signs, or a part outside the range, trap. Period.checkedMake
returns None instead.
Associated function checkedMake#
pub fn checkedMake(years: i64, months: i64, weeks: i64, days: i64, time: Duration) -> Option<Period>Returns the period with the given parts, or None when two parts have different signs or
a part is outside the range.
Details#
Years, months, and weeks are at most 4,294,967,295 in each direction. The days, as 24 hours each, and the time part are together less than 2^53 seconds. These are the limits of ECMAScript Temporal.
Associated function ofYears#
pub fn ofYears(years: i64) -> PeriodReturns a period of years years. A count outside the range traps.
Associated function ofMonths#
pub fn ofMonths(months: i64) -> PeriodReturns a period of months months. A count outside the range traps.
Associated function ofWeeks#
pub fn ofWeeks(weeks: i64) -> PeriodReturns a period of weeks weeks. A count outside the range traps.
Associated function ofDays#
pub fn ofDays(days: i64) -> PeriodReturns a period of days calendar days. A count outside the range traps.
Associated function ofTime#
pub fn ofTime(time: Duration) -> PeriodReturns a period with only the time part time. A span of 2^53 seconds or more traps.
Method years#
pub fn years(self: Self) -> i64Returns the number of years. It is negative in a negative period.
Method months#
pub fn months(self: Self) -> i64Returns the number of months. It is not limited to 11.
Method weeks#
pub fn weeks(self: Self) -> i64Returns the number of weeks.
Method days#
pub fn days(self: Self) -> i64Returns the number of days. It does not include the days of the weeks.
Method time#
pub fn time(self: Self) -> DurationReturns the time part: the hours, minutes, seconds, and nanoseconds as one exact span. It is not limited to 24 hours.
Method isZero#
pub fn isZero(self: Self) -> boolReturns true if every part is zero.
Method isTimeOnly#
pub fn isTimeOnly(self: Self) -> boolReturns true if the years, months, weeks, and days are all zero.
Method sign#
pub fn sign(self: Self) -> i32Returns -1 for a negative period, 0 for the empty period, and 1 for a positive period.
Method negate#
pub fn negate(self: Self) -> PeriodReturns the period with the sign of every part changed.
Method absolute#
pub fn absolute(self: Self) -> PeriodReturns the period without its sign.
Method checkedAdd#
pub fn checkedAdd(self: Self, other: Period) -> Option<Period>Returns the sum of this period and other, part by part, or None when the parts of the
sum have different signs or a part is outside the range.
Details#
Nothing is balanced: P1M plus P20D is P1M20D. P1M plus -P1D has no result,
because the length of the sum depends on the month.
Method dateOnly#
pub fn dateOnly(self: Self) -> PeriodReturns this period without its time part.
Associated function parse#
pub fn parse(text: string) -> Result<Period, TimeParseError>Reads a period from an ISO 8601 duration such as P1Y2M3DT4H30M.
Details#
The text is an optional sign, P, and then counts with the designators Y, M, W, and
D, then T and counts with H, M, and S, in that order. Each part can be absent,
but at least one is present. The last time count can have a fraction of one to nine digits
after . or ,, as in PT1.5H or PT0.25S. Letter case does not matter. A leading -
makes every part negative.
Errors#
TimeParseReason.UnexpectedEndorUnexpectedCharacterif the text does not have that form.TimeParseReason.OutOfRangeif the parts are outside the range ofPeriod.checkedMake.
Associated function parseBytes#
pub fn parseBytes(bytes: &[u8]) -> Result<Period, TimeParseError>Reads a period from the bytes of an ISO 8601 duration such as P1Y2M3DT4H30M.
Details#
The form is the one of Period.parse.
Errors#
The errors of
Period.parse.
Method write#
pub fn write(self: Self, output: &mut [u8], at: usize) -> usizeWrites the ISO 8601 text of the period into output from index at and returns the index
after the last byte written. The text is at most 100 bytes.
Gotchas#
An output with less room than the text needs traps.
Implementation Equal for Period#
impl Equal for PeriodOperation equals#
equals: Period.sameImplementation Display for Period#
impl Display for PeriodWrites the period as an ISO 8601 duration, such as P1Y2M3DT4H30M, -P3W, or PT0.5S. The
empty period is PT0S.
Operation display#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for Period#
impl Debug for PeriodWrites the same text as Display: an ISO 8601 duration such as P1Y2M3DT4H30M.
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.