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#

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

silk
pub enum DateUnit

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

silk
Year

Years, then months, then days.

Month#

silk
Month

Months, then days.

Week#

silk
Week

Weeks, then days.

Day#

silk
Day

Days only.

Overflow#

silk
pub enum Overflow

What to do when a date that a period leads to does not exist, such as February 30.

Constrain#

silk
Constrain

Use the last day of that month.

Reject#

silk
Reject

Give no result.

Period#

silk
pub struct Period

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

silk
impl Copy for Period

Implementation Period#

silk
impl Period

Associated function zero#

silk
pub fn zero() -> Period

Returns the empty period.

Associated function make#

silk
pub fn make(years: i64, months: i64, weeks: i64, days: i64, time: Duration) -> Period

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

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

silk
pub fn ofYears(years: i64) -> Period

Returns a period of years years. A count outside the range traps.

Associated function ofMonths#

silk
pub fn ofMonths(months: i64) -> Period

Returns a period of months months. A count outside the range traps.

Associated function ofWeeks#

silk
pub fn ofWeeks(weeks: i64) -> Period

Returns a period of weeks weeks. A count outside the range traps.

Associated function ofDays#

silk
pub fn ofDays(days: i64) -> Period

Returns a period of days calendar days. A count outside the range traps.

Associated function ofTime#

silk
pub fn ofTime(time: Duration) -> Period

Returns a period with only the time part time. A span of 2^53 seconds or more traps.

Method years#

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

Returns the number of years. It is negative in a negative period.

Method months#

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

Returns the number of months. It is not limited to 11.

Method weeks#

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

Returns the number of weeks.

Method days#

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

Returns the number of days. It does not include the days of the weeks.

Method time#

silk
pub fn time(self: Self) -> Duration

Returns the time part: the hours, minutes, seconds, and nanoseconds as one exact span. It is not limited to 24 hours.

Method isZero#

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

Returns true if every part is zero.

Method isTimeOnly#

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

Returns true if the years, months, weeks, and days are all zero.

Method sign#

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

Returns -1 for a negative period, 0 for the empty period, and 1 for a positive period.

Method negate#

silk
pub fn negate(self: Self) -> Period

Returns the period with the sign of every part changed.

Method absolute#

silk
pub fn absolute(self: Self) -> Period

Returns the period without its sign.

Method checkedAdd#

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

silk
pub fn dateOnly(self: Self) -> Period

Returns this period without its time part.

Associated function parse#

silk
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.UnexpectedEnd or UnexpectedCharacter if the text does not have that form.

  • TimeParseReason.OutOfRange if the parts are outside the range of Period.checkedMake.

Associated function parseBytes#

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

Method write#

silk
pub fn write(self: Self, output: &mut [u8], at: usize) -> usize

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

silk
impl Equal for Period

Operation equals#

silk
equals: Period.same

Implementation Display for Period#

silk
impl Display for Period

Writes the period as an ISO 8601 duration, such as P1Y2M3DT4H30M, -P3W, or PT0.5S. The empty period is PT0S.

Operation display#

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

Implementation Debug for Period#

silk
impl Debug for Period

Writes the same text as Display: an ISO 8601 duration such as P1Y2M3DT4H30M.

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