Crate roundable

Round numbers and durations to a given factor

This provides an implementation of rounding for various values, including the the native number types and core::time::Duration (also known as std::time::Duration).

The Roundable trait adds the following functions to roundable values:

• Roundable::try_round_to(factor, tie_strategy) (returns None on overflow)
• Roundable::round_to(factor, tie_strategy) (panics on overflow)

Example

use roundable::{Roundable, Tie};

assert!(310 == 314.round_to(10, Tie::Up));
assert!(300.0 == 314.1.round_to(100.0, Tie::Up));

// To avoid panicking on overflow:
assert!(Some(260) == 255.try_round_to(10, Tie::Up));
assert!(None == 255u8.try_round_to(10, Tie::Up));

Tie strategies

“Ties” are numbers exactly halfway between two round numbers, e.g. 0.5 when rounding to the nearest whole number. Traditionally, ties are resolved by picking the higher number, but there are other strategies. Roundable supports the following rules:

• Tie::Up: Round ties up (what most people consider correct).
• Tie::Down: Round ties down.
• Tie::TowardZero: Round ties toward zero.
• Tie::AwayFromZero: Round ties away from zero.
• Tie::TowardEven: Round ties toward the “even” number (see docs).
• Tie::TowardOdd: Round ties toward the “odd” number (see docs).

Rounding Duration

Duration can be rounded to a Duration factor, just like a number type. For convenience, there are a number of constants that can be used to make rounding Duration easier.

use roundable::{SECOND, MINUTE, Roundable, Tie};
use std::time::Duration;

assert!(Duration::ZERO == Duration::from_millis(314).round_to(SECOND, Tie::Up));
assert!(MINUTE == Duration::from_millis(59_500).round_to(SECOND, Tie::Up));

#![no_std] by default

You can use this crate with or without std and alloc. You do not need to enable or disable features either way.

Minimum supported Rust version

Currently the minimum supported Rust version (MSRV) is 1.56.1. Future increases in the MSRV will require a major version bump.

Enums

• Tie
  How to handle a value that is exactly half, e.g. 5.round_to(10, ...).

Constants

• HOUR
  An hour. Useful for rounding Duration.
• MICROSECOND
  A microsecond. Useful for rounding Duration.
• MILLISECOND
  A millisecond. Useful for rounding Duration.
• MINUTE
  A minute. Useful for rounding Duration.
• SECOND
  A second. Useful for rounding Duration.

Traits

• Roundable
  Methods to round to an arbitrary factor.

Functions

• nanos_to_duration
  Create a new Duration from a u128 of nanoseconds.