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#
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#
pub enum RoundingModeWhich 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#
CeilUp.
Floor#
FloorDown.
Expand#
ExpandAway from zero.
Trunc#
TruncToward zero.
HalfCeil#
HalfCeilTo the nearest step, and up from the middle.
HalfFloor#
HalfFloorTo the nearest step, and down from the middle.
HalfExpand#
HalfExpandTo the nearest step, and away from zero from the middle. This is the rounding of school arithmetic.
HalfTrunc#
HalfTruncTo the nearest step, and toward zero from the middle.
HalfEven#
HalfEvenTo the nearest step, and from the middle to the step that is an even multiple.
Implementation RoundingMode#
impl RoundingModeMethod roundsUp#
pub fn roundsUp(self: Self, negative: bool, half: Ordering, lowerIsOdd: bool) -> boolReturns 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#
pub fn asIfPositive(self: Self) -> RoundingModeReturns 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#
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#
pub enum TimeUnitA unit of time of a fixed length.
Day#
Day24 hours.
Hour#
Hour60 minutes.
Minute#
Minute60 seconds.
Second#
SecondOne second.
Millisecond#
MillisecondA thousandth of a second.
Microsecond#
MicrosecondA millionth of a second.
Nanosecond#
NanosecondA billionth of a second.
Implementation TimeUnit#
impl TimeUnitMethod nanoseconds#
pub fn nanoseconds(self: Self) -> i64Returns the length of the unit in nanoseconds.
TimeIncrement#
pub struct TimeIncrementA step that times are rounded to: a count of one TimeUnit that divides one day evenly.
Implementation Copy for TimeIncrement#
impl Copy for TimeIncrementImplementation TimeIncrement#
impl TimeIncrementAssociated function of#
pub fn of(count: u32, unit: TimeUnit) -> TimeIncrementReturns 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#
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#
pub fn one(unit: TimeUnit) -> TimeIncrementReturns the step of one unit.
Method nanoseconds#
pub fn nanoseconds(self: Self) -> i64Returns the length of the step in nanoseconds.
Method roundDayPart#
pub fn roundDayPart(self: Self, value: i64, mode: RoundingMode, negative: bool, days: i64) -> i64Returns 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.