Trait malachite_base::num::arithmetic::traits::RoundToMultipleOfPowerOf2

pub trait RoundToMultipleOfPowerOf2<RHS> {
    type Output;

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

Rounds a number to a multiple of $2^k$, 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_of_power_of_2( self, pow: RHS, rm: RoundingMode, ) -> (Self::Output, Ordering)

Implementations on Foreign Types

impl RoundToMultipleOfPowerOf2<u64> for i8

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (i8, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = i8

impl RoundToMultipleOfPowerOf2<u64> for i16

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (i16, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = i16

impl RoundToMultipleOfPowerOf2<u64> for i32

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (i32, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = i32

impl RoundToMultipleOfPowerOf2<u64> for i64

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (i64, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = i64

impl RoundToMultipleOfPowerOf2<u64> for i128

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (i128, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = i128

impl RoundToMultipleOfPowerOf2<u64> for isize

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (isize, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = isize

impl RoundToMultipleOfPowerOf2<u64> for u8

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (u8, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = u8

impl RoundToMultipleOfPowerOf2<u64> for u16

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (u16, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = u16

impl RoundToMultipleOfPowerOf2<u64> for u32

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (u32, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = u32

impl RoundToMultipleOfPowerOf2<u64> for u64

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (u64, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = u64

impl RoundToMultipleOfPowerOf2<u64> for u128

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (u128, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = u128

impl RoundToMultipleOfPowerOf2<u64> for usize

fn round_to_multiple_of_power_of_2( self, pow: u64, rm: RoundingMode, ) -> (usize, Ordering)

Rounds a number to a multiple of $2^k$ 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}{2^k}$:

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

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

$f(x, k, \mathrm{Floor}) = 2^k \lfloor q \rfloor.$

$f(x, k, \mathrm{Ceiling}) = 2^k \lceil q \rceil.$

$$ f(x, k, \mathrm{Nearest}) = \begin{cases} 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor < \frac{1}{2} \\ 2^k \lceil q \rceil & \text{if} \quad q - \lfloor q \rfloor > \frac{1}{2} \\ 2^k \lfloor q \rfloor & \text{if} \quad q - \lfloor q \rfloor = \frac{1}{2} \ \text{and} \ \lfloor q \rfloor \ \text{is even} \\ 2^k \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, k, \mathrm{Exact}) = 2^k q$, but panics if $q \notin \Z$.

The following two expressions are equivalent:

• x.round_to_multiple_of_power_of_2(pow, Exact)
• { assert!(x.divisible_by_power_of_2(pow)); 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 the power of 2.
• If rm is Floor, but self is negative with a too-large absolute value to round to the next lowest multiple.
• If rm is Ceiling, but self is too large to round to the next highest multiple.
• If rm is Up, but self has too large an absolute value to round to the next multiple with a greater absolute value.
• If rm is Nearest, but the nearest multiple is outside the representable range.

Examples

See here.

type Output = usize

Implementors