silk.time.rounding.

How silk.time rounds: the RoundingMode, the TimeUnit, and the TimeIncrement that the round functions of the time types take.

When to use#

Use these types to round a time to a step, such as the nearest 15 minutes or the second below. Duration.round, PlainTime.round, PlainDateTime.round, Instant.round, and ZonedDateTime.round each take a TimeIncrement and a RoundingMode.

Details#

A TimeIncrement is a count of one unit, such as 15 minutes or 250 milliseconds. It must divide one day of 24 hours evenly, so the steps start again at each midnight: 90 minutes and 6 hours are steps, and 7 hours is not.

The nine modes are the ones of ECMAScript Temporal and of Intl.NumberFormat. Four of them always round in one direction, and five round to the nearest step and differ only for a value exactly between two steps.

Examples#

Round a time of day to a quarter of an hour#

silk
import silk.time.plain_time { PlainTime }
import silk.time.rounding { RoundingMode, TimeIncrement, TimeUnit }

pub fn main() -> i32 {
  let quarter = TimeIncrement.of(15, TimeUnit.Minute)
  let time = PlainTime.make(17, 38, 0, 0)
  let nearest = time.round(quarter, RoundingMode.HalfExpand)
  let below = time.round(quarter, RoundingMode.Floor)
  if nearest.hour() != 17 || nearest.minute() != 45 {
    return 1
  }
  if below.hour() != 17 || below.minute() != 30 {
    return 2
  }
  return 0
}

Import as RoundingMode with import silk.time.rounding { RoundingMode }.

Public declarations: 3.

RoundingMode#

silk
pub enum RoundingMode

Which of the two nearest steps a rounded value takes.

Details#

"Up" is toward positive infinity, or later in time. "Away from zero" and "toward zero" are different from up and down only for a negative Duration; for a time, a date, or an instant they are up and down.

Ceil#

silk
Ceil

Up.

Floor#

silk
Floor

Down.

Expand#

silk
Expand

Away from zero.

Trunc#

silk
Trunc

Toward zero.

HalfCeil#

silk
HalfCeil

To the nearest step, and up from the middle.

HalfFloor#

silk
HalfFloor

To the nearest step, and down from the middle.

HalfExpand#

silk
HalfExpand

To the nearest step, and away from zero from the middle. This is the rounding of school arithmetic.

HalfTrunc#

silk
HalfTrunc

To the nearest step, and toward zero from the middle.

HalfEven#

silk
HalfEven

To the nearest step, and from the middle to the step that is an even multiple.

Implementation RoundingMode#

silk
impl RoundingMode

Method roundsUp#

silk
pub fn roundsUp(self: Self, negative: bool, half: Ordering, lowerIsOdd: bool) -> bool

Returns true if a value between two steps rounds to the upper one.

Details#

negative says that the value is below zero. half compares the distance from the lower step with half a step: Less when the value is nearer to the lower step, Equal in the middle. lowerIsOdd says that the lower step is an odd multiple of the step size.

Method asIfPositive#

silk
pub fn asIfPositive(self: Self) -> RoundingMode

Returns the mode that rounds every value as this mode rounds a positive value.

Details#

Expand becomes Ceil, Trunc becomes Floor, HalfExpand becomes HalfCeil, and HalfTrunc becomes HalfFloor. A point on a timeline, such as an Instant before 1970, rounds this way: "away from zero" means later in time on both sides of the epoch.

Method roundToMultiple#

silk
pub fn roundToMultiple(self: Self, value: i64, step: i64) -> Option<i64>

Returns value rounded to a multiple of step, or None when step is not positive or the result does not fit an i64.

TimeUnit#

silk
pub enum TimeUnit

A unit of time of a fixed length.

Day#

silk
Day

24 hours.

Hour#

silk
Hour

60 minutes.

Minute#

silk
Minute

60 seconds.

Second#

silk
Second

One second.

Millisecond#

silk
Millisecond

A thousandth of a second.

Microsecond#

silk
Microsecond

A millionth of a second.

Nanosecond#

silk
Nanosecond

A billionth of a second.

Implementation TimeUnit#

silk
impl TimeUnit

Method nanoseconds#

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

Returns the length of the unit in nanoseconds.

TimeIncrement#

silk
pub struct TimeIncrement

A step that times are rounded to: a count of one TimeUnit that divides one day evenly.

Implementation Copy for TimeIncrement#

silk
impl Copy for TimeIncrement

Implementation TimeIncrement#

silk
impl TimeIncrement

Associated function of#

silk
pub fn of(count: u32, unit: TimeUnit) -> TimeIncrement

Returns the step of count units, such as 15 minutes.

Gotchas#

A step that is empty or does not divide 24 hours evenly, such as 7 hours, traps. TimeIncrement.checkedOf returns None instead.

Associated function checkedOf#

silk
pub fn checkedOf(count: u32, unit: TimeUnit) -> Option<TimeIncrement>

Returns the step of count units, or None when count is 0 or the step does not divide 24 hours evenly.

Associated function one#

silk
pub fn one(unit: TimeUnit) -> TimeIncrement

Returns the step of one unit.

Method nanoseconds#

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

Returns the length of the step in nanoseconds.

Method roundDayPart#

silk
pub fn roundDayPart(self: Self, value: i64, mode: RoundingMode, negative: bool, days: i64) -> i64

Returns value, a count of nanoseconds from 0 to one day, rounded to this step. The result is from 0 to one day.

Details#

negative and days are for a value that is the part of a larger count above a whole number of days: negative says that the whole count is below zero, and days is the number of whole days below this part. RoundingMode.HalfEven counts the steps from the start of the whole count. For a time of day, pass false and 0.

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