silk.time.relative.

Periods measured from a starting point: RelativeTo rounds a Period, gives its total in one unit, and changes its largest unit.

When to use#

Use RelativeTo for a question about a Period whose answer depends on where the period starts: how many months 100 days are, what P1M45D is in months and days, or what a period is when rounded to whole weeks. Months and years have different lengths, and in a time zone a day has 23 or 25 hours on the day of a change, so a period alone cannot answer.

To round an exact span, use Duration.round. To get the period between two dates, use the periodUntil function of the date types.

Details#

A RelativeTo is a starting point: a PlainDate, where every day is 24 hours, or a ZonedDateTime, where days have the length that they have in the zone. Each function moves from the starting point by the whole period, as addPeriod does, and measures the way to the point reached.

The functions follow Temporal.Duration.prototype.round and total of ECMAScript Temporal with a relativeTo option.

Examples#

Count, balance, and round a period from a date#

silk
import silk.core.option { Option }
import silk.time.period { DateUnit, Period }
import silk.time.plain_date { PlainDate }
import silk.time.relative { PeriodRounding, RelativeTo }
import silk.time.rounding { RoundingMode }

pub fn main() -> i32 {
  let start = RelativeTo.date(PlainDate.make(2027, 1, 1))
  // January has 31 days and February has 28, so 45 days are one and a half months.
  if let Option<f64>.Some { value: months } = start.total(Period.ofDays(45), DateUnit.Month) {
    if months != 1.5 {
      return 1
    }
  }
  if let Option<Period>.Some { value: balanced } = start.balance(Period.ofDays(45), DateUnit.Month) {
    if balanced.months() != 1 || balanced.days() != 14 {
      return 2
    }
  }
  let toMonths = PeriodRounding.toUnit(DateUnit.Month, RoundingMode.HalfExpand)
  if let Option<Period>.Some { value: rounded } = start.round(Period.ofDays(45), toMonths) {
    if rounded.months() != 2 || rounded.days() != 0 {
      return 3
    }
  }
  return 0
}

Import as RelativeTo with import silk.time.relative { RelativeTo }.

Public declarations: 2.

PeriodRounding#

silk
pub struct PeriodRounding

How RelativeTo.round rounds a period: the smallest unit or step that stays, the mode, and the largest unit of the result.

Details#

PeriodRounding.toUnit rounds to whole years, months, weeks, or days, and PeriodRounding.toStep rounds the time part to a step such as 15 minutes.

Without PeriodRounding.upTo or PeriodRounding.asTime, the largest unit of the result is the largest unit of the period that is not zero, or the unit that the period is rounded to when that is larger.

Implementation Copy for PeriodRounding#

silk
impl Copy for PeriodRounding

Implementation PeriodRounding#

silk
impl PeriodRounding

Associated function toUnit#

silk
pub fn toUnit(unit: DateUnit, mode: RoundingMode) -> PeriodRounding

Returns the rounding to whole units of unit.

Associated function toStep#

silk
pub fn toStep(step: TimeIncrement, mode: RoundingMode) -> PeriodRounding

Returns the rounding of the time part to a multiple of step.

Details#

A step of one day is the rounding to whole days, as with toUnit(DateUnit.Day, mode). TimeIncrement.one(TimeUnit.Nanosecond) rounds nothing, and is the way to change only the largest unit.

Method every#

silk
pub fn every(self: Self, count: u32) -> PeriodRounding

Returns this rounding to a multiple of count units, such as every 3 months. It has an effect only on a rounding from PeriodRounding.toUnit.

Gotchas#

A count of 0 traps. With a count above 1, the result must have one unit: a rounding whose largest unit is not the rounded unit has no result, because the larger units would take parts of the multiple.

Method upTo#

silk
pub fn upTo(self: Self, largest: DateUnit) -> PeriodRounding

Returns this rounding with largest as the largest unit of the result.

Details#

With DateUnit.Month, a result has months, days, and a time part, and no years or weeks. A largest unit that is smaller than the unit of the rounding has no result.

Method asTime#

silk
pub fn asTime(self: Self) -> PeriodRounding

Returns this rounding with a result that has only a time part: the exact span of the period from the starting point. It has no result with a rounding from PeriodRounding.toUnit.

RelativeTo#

silk
pub struct RelativeTo<'z>

A starting point that periods are measured from.

Details#

RelativeTo.date starts at midnight of a date and counts every day as 24 hours. RelativeTo.zoned starts at a ZonedDateTime and counts days on the calendar of its zone.

Every function has no result when a date that it needs is outside the range of the date types.

Implementation Copy for RelativeTo<'z>#

silk
impl<'z> Copy for RelativeTo<'z>

Implementation RelativeTo<'z>#

silk
impl<'z> RelativeTo<'z>

Associated function date#

silk
pub fn date(date: PlainDate) -> RelativeTo<'static>

Returns the starting point at midnight of date, with days of 24 hours.

Associated function zoned#

silk
pub fn zoned(value: ZonedDateTime<'z>) -> RelativeTo<'z>

Returns the starting point at value, in its zone.

Method span#

silk
pub fn span(self: Self, period: Period) -> Option<Duration>

Returns the exact span from the starting point to the point that period reaches.

Details#

From a date, one day is 24 hours. From a ZonedDateTime, the span of P1D is 23 or 25 hours over a daylight saving change.

Method total#

silk
pub fn total(self: Self, period: Period, unit: DateUnit) -> Option<f64>

Returns period as a count of unit, with a fraction for the part of a unit.

Details#

The whole units are counted on the calendar from the starting point, and the fraction is the part of the next unit that the rest covers: from January 1, 45 days are 1 month and 14 of the 28 days of February, so 1.5 months. The result is negative for a negative period.

Method balance#

silk
pub fn balance(self: Self, period: Period, largest: DateUnit) -> Option<Period>

Returns the period from the starting point to the point that period reaches, with largest as its largest unit.

Details#

From January 1, P45D with DateUnit.Month is P1M14D, and P1M14D with DateUnit.Day is P45D. A time part of 24 hours or more moves into the days.

Method round#

silk
pub fn round(self: Self, period: Period, rounding: PeriodRounding) -> Option<Period>

Returns period rounded as rounding says.

Details#

The period is first put in the units from the largest unit of the rounding down, as RelativeTo.balance does. The rounded unit then takes one of the two values around the period: for whole months, the result is the number of months before the point reached or the next one, by the part of that month that the rest covers. A unit that reaches the next larger unit moves into it: P11M20D rounded to months is P1Y.

RoundingMode.HalfExpand rounds to the nearest value, and away from zero from the middle.

Gotchas#

There is no result when the largest unit of the rounding is smaller than its smallest unit, or when PeriodRounding.every has a count above 1 and the largest unit is not the rounded unit.

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