Trait malachite_base::num::arithmetic::traits::RoundToMultipleOfPowerOf2
source · [−]pub trait RoundToMultipleOfPowerOf2<RHS> {
type Output;
fn round_to_multiple_of_power_of_2(
self,
pow: RHS,
rm: RoundingMode
) -> Self::Output;
}
Expand description
Rounds a number to a multiple of $2^k$, according to a specified rounding mode.
Required Associated Types
Required Methods
fn round_to_multiple_of_power_of_2(
self,
pow: RHS,
rm: RoundingMode
) -> Self::Output
Implementations on Foreign Types
sourceimpl RoundToMultipleOfPowerOf2<u64> for u8
impl RoundToMultipleOfPowerOf2<u64> for u8
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u8
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u8
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = u8
sourceimpl RoundToMultipleOfPowerOf2<u64> for u16
impl RoundToMultipleOfPowerOf2<u64> for u16
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u16
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u16
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = u16
sourceimpl RoundToMultipleOfPowerOf2<u64> for u32
impl RoundToMultipleOfPowerOf2<u64> for u32
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u32
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u32
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = u32
sourceimpl RoundToMultipleOfPowerOf2<u64> for u64
impl RoundToMultipleOfPowerOf2<u64> for u64
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u64
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u64
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = u64
sourceimpl RoundToMultipleOfPowerOf2<u64> for u128
impl RoundToMultipleOfPowerOf2<u64> for u128
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u128
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> u128
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = u128
sourceimpl RoundToMultipleOfPowerOf2<u64> for usize
impl RoundToMultipleOfPowerOf2<u64> for usize
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> usize
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> usize
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = usize
sourceimpl RoundToMultipleOfPowerOf2<u64> for i8
impl RoundToMultipleOfPowerOf2<u64> for i8
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i8
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i8
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = i8
sourceimpl RoundToMultipleOfPowerOf2<u64> for i16
impl RoundToMultipleOfPowerOf2<u64> for i16
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i16
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i16
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = i16
sourceimpl RoundToMultipleOfPowerOf2<u64> for i32
impl RoundToMultipleOfPowerOf2<u64> for i32
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i32
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i32
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = i32
sourceimpl RoundToMultipleOfPowerOf2<u64> for i64
impl RoundToMultipleOfPowerOf2<u64> for i64
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i64
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i64
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = i64
sourceimpl RoundToMultipleOfPowerOf2<u64> for i128
impl RoundToMultipleOfPowerOf2<u64> for i128
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i128
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> i128
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.
type Output = i128
sourceimpl RoundToMultipleOfPowerOf2<u64> for isize
impl RoundToMultipleOfPowerOf2<u64> for isize
sourcefn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> isize
fn round_to_multiple_of_power_of_2(self, pow: u64, rm: RoundingMode) -> isize
Rounds a number to a multiple of $2^k$ according to a specified rounding mode.
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, RoundingMode::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
isExact
, butself
is not a multiple of the power of 2. - If
rm
isFloor
, butself
is negative with a too-large absolute value to round to the next lowest multiple. - If
rm
isCeiling
, butself
is too large to round to the next highest multiple. - If
rm
isUp
, butself
has too large an absolute value to round to the next multiple with a greater absolute value. - If
rm
isNearest
, but the nearest multiple is outside the representable range.
Examples
See here.