Trait malachite_base::num::arithmetic::traits::RoundToMultiple

pub trait RoundToMultiple<RHS = Self> {
    type Output;

    // Required method
    fn round_to_multiple(
        self,
        other: RHS,
        rm: RoundingMode
    ) -> (Self::Output, Ordering);
}

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

Required Associated Types

type Output

Required Methods

fn round_to_multiple( self, other: RHS, rm: RoundingMode ) -> (Self::Output, Ordering)

Implementations on Foreign Types

impl RoundToMultiple for i8

fn round_to_multiple(self, other: i8, rm: RoundingMode) -> (i8, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding mode that is guaranteed to return without a panic is Down.

Let $q = \frac{x}{|y|}$:

$f(x, y, \mathrm{Down}) = \operatorname{sgn}(q) |y| \lfloor |q| \rfloor.$

$f(x, y, \mathrm{Up}) = \operatorname{sgn}(q) |y| \lceil |q| \rceil.$

$f(x, y, \mathrm{Floor}) = |y| \lfloor q \rfloor.$

$f(x, y, \mathrm{Ceiling}) = |y| \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = i8

impl RoundToMultiple for i16

fn round_to_multiple(self, other: i16, rm: RoundingMode) -> (i16, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding mode that is guaranteed to return without a panic is Down.

Let $q = \frac{x}{|y|}$:

$f(x, y, \mathrm{Down}) = \operatorname{sgn}(q) |y| \lfloor |q| \rfloor.$

$f(x, y, \mathrm{Up}) = \operatorname{sgn}(q) |y| \lceil |q| \rceil.$

$f(x, y, \mathrm{Floor}) = |y| \lfloor q \rfloor.$

$f(x, y, \mathrm{Ceiling}) = |y| \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = i16

impl RoundToMultiple for i32

fn round_to_multiple(self, other: i32, rm: RoundingMode) -> (i32, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding mode that is guaranteed to return without a panic is Down.

Let $q = \frac{x}{|y|}$:

$f(x, y, \mathrm{Down}) = \operatorname{sgn}(q) |y| \lfloor |q| \rfloor.$

$f(x, y, \mathrm{Up}) = \operatorname{sgn}(q) |y| \lceil |q| \rceil.$

$f(x, y, \mathrm{Floor}) = |y| \lfloor q \rfloor.$

$f(x, y, \mathrm{Ceiling}) = |y| \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = i32

impl RoundToMultiple for i64

fn round_to_multiple(self, other: i64, rm: RoundingMode) -> (i64, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding mode that is guaranteed to return without a panic is Down.

Let $q = \frac{x}{|y|}$:

$f(x, y, \mathrm{Down}) = \operatorname{sgn}(q) |y| \lfloor |q| \rfloor.$

$f(x, y, \mathrm{Up}) = \operatorname{sgn}(q) |y| \lceil |q| \rceil.$

$f(x, y, \mathrm{Floor}) = |y| \lfloor q \rfloor.$

$f(x, y, \mathrm{Ceiling}) = |y| \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = i64

impl RoundToMultiple for i128

fn round_to_multiple(self, other: i128, rm: RoundingMode) -> (i128, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding mode that is guaranteed to return without a panic is Down.

Let $q = \frac{x}{|y|}$:

$f(x, y, \mathrm{Down}) = \operatorname{sgn}(q) |y| \lfloor |q| \rfloor.$

$f(x, y, \mathrm{Up}) = \operatorname{sgn}(q) |y| \lceil |q| \rceil.$

$f(x, y, \mathrm{Floor}) = |y| \lfloor q \rfloor.$

$f(x, y, \mathrm{Ceiling}) = |y| \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = i128

impl RoundToMultiple for isize

fn round_to_multiple(self, other: isize, rm: RoundingMode) -> (isize, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding mode that is guaranteed to return without a panic is Down.

Let $q = \frac{x}{|y|}$:

$f(x, y, \mathrm{Down}) = \operatorname{sgn}(q) |y| \lfloor |q| \rfloor.$

$f(x, y, \mathrm{Up}) = \operatorname{sgn}(q) |y| \lceil |q| \rceil.$

$f(x, y, \mathrm{Floor}) = |y| \lfloor q \rfloor.$

$f(x, y, \mathrm{Ceiling}) = |y| \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = isize

impl RoundToMultiple for u8

fn round_to_multiple(self, other: u8, rm: RoundingMode) -> (u8, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding modes that are guaranteed to return without a panic are Down and Floor.

Let $q = \frac{x}{y}$:

$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = y \lfloor q \rfloor.$

$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = y \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = x$, but panics if $q \notin \N$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = u8

impl RoundToMultiple for u16

fn round_to_multiple(self, other: u16, rm: RoundingMode) -> (u16, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding modes that are guaranteed to return without a panic are Down and Floor.

Let $q = \frac{x}{y}$:

$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = y \lfloor q \rfloor.$

$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = y \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = x$, but panics if $q \notin \N$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = u16

impl RoundToMultiple for u32

fn round_to_multiple(self, other: u32, rm: RoundingMode) -> (u32, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding modes that are guaranteed to return without a panic are Down and Floor.

Let $q = \frac{x}{y}$:

$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = y \lfloor q \rfloor.$

$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = y \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = x$, but panics if $q \notin \N$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = u32

impl RoundToMultiple for u64

fn round_to_multiple(self, other: u64, rm: RoundingMode) -> (u64, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding modes that are guaranteed to return without a panic are Down and Floor.

Let $q = \frac{x}{y}$:

$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = y \lfloor q \rfloor.$

$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = y \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = x$, but panics if $q \notin \N$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = u64

impl RoundToMultiple for u128

fn round_to_multiple(self, other: u128, rm: RoundingMode) -> (u128, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding modes that are guaranteed to return without a panic are Down and Floor.

Let $q = \frac{x}{y}$:

$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = y \lfloor q \rfloor.$

$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = y \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = x$, but panics if $q \notin \N$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = u128

impl RoundToMultiple for usize

fn round_to_multiple(self, other: usize, rm: RoundingMode) -> (usize, Ordering)

Rounds a number to a multiple of another number, according to a specified rounding mode. An Ordering is also returned, indicating whether the returned value is less than, equal to, or greater than the original value.

The only rounding modes that are guaranteed to return without a panic are Down and Floor.

Let $q = \frac{x}{y}$:

$f(x, y, \mathrm{Down}) = f(x, y, \mathrm{Floor}) = y \lfloor q \rfloor.$

$f(x, y, \mathrm{Up}) = f(x, y, \mathrm{Ceiling}) = y \lceil q \rceil.$

$$ f(x, y, \mathrm{Nearest}) = \begin{cases} y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ y \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ y \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is odd.} \end{cases} $$

$f(x, y, \mathrm{Exact}) = x$, but panics if $q \notin \N$.

The following two expressions are equivalent:

• x.round_to_multiple(other, RoundingMode::Exact)
• { assert!(x.divisible_by(other)); x }

but the latter should be used as it is clearer and more efficient.

Worst-case complexity

Constant time and additional memory.

Panics

• If rm is Exact, but self is not a multiple of other.
• If the multiple is outside the representable range.
• If self is nonzero, other is zero, and rm is trying to round away from zero.

Examples

See here.

type Output = usize

Implementors