pub enum RoundingMode {
Down,
Up,
Floor,
Ceiling,
Nearest,
Exact,
}
Expand description
An enum that specifies how a value should be rounded.
A RoundingMode
can often be specified when a function conceptually returns a value of one
type, but must be rounded to another type. The most common case is a conceptually real-valued
function whose result must be rounded to an integer, like
div_round
.
Examples
Here are some examples of how floating-point values would be rounded to integer values using
the different RoundingMode
s.
x | Floor | Ceiling | Down | Up | Nearest | Exact |
---|---|---|---|---|---|---|
3.0 | 3 | 3 | 3 | 3 | 3 | 3 |
3.2 | 3 | 4 | 3 | 4 | 3 | panic!() |
3.8 | 3 | 4 | 3 | 4 | 4 | panic!() |
3.5 | 3 | 4 | 3 | 4 | 4 | panic!() |
4.5 | 4 | 5 | 4 | 5 | 4 | panic!() |
-3.2 | -4 | -3 | -3 | -4 | -3 | panic!() |
-3.8 | -4 | -3 | -3 | -4 | -4 | panic!() |
-3.5 | -4 | -3 | -3 | -4 | -4 | panic!() |
-4.5 | -5 | -4 | -4 | -5 | -4 | panic!() |
Sometimes a RoundingMode
is used in an unusual context, such as rounding an integer to a
floating-point number, in which case further explanation of its behavior is provided at the
usage site.
A RoundingMode
takes up 1 byte of space.
Variants
Down
Applies the function $x \mapsto \operatorname{sgn}(x) \lfloor |x| \rfloor$. In other words, the value is rounded towards $0$.
Up
Applies the function $x \mapsto \operatorname{sgn}(x) \lceil |x| \rceil$. In other words, the value is rounded away from $0$.
Floor
Applies the floor function: $x \mapsto \lfloor x \rfloor$. In other words, the value is rounded towards $-\infty$.
Ceiling
Applies the ceiling function: $x \mapsto \lceil x \rceil$. In other words, the value is rounded towards $\infty$.
Nearest
Applies the function $$ x \mapsto \begin{cases} \lfloor x \rfloor & x - \lfloor x \rfloor < \frac{1}{2} \\ \lceil x \rceil & x - \lfloor x \rfloor > \frac{1}{2} \\ \lfloor x \rfloor & x - \lfloor x \rfloor = \frac{1}{2} \ \text{and} \ \lfloor x \rfloor \ \text{is even} \\ \lceil x \rceil & x - \lfloor x \rfloor = \frac{1}{2} \ \text{and} \ \lfloor x \rfloor \ \text{is odd.} \end{cases} $$ In other words, it rounds to the nearest integer, and when there’s a tie, it rounds to the nearest even integer. This is also called bankers’ rounding and is often used as a default.
Exact
Panics if the value is not already rounded.
Trait Implementations
sourceimpl Clone for RoundingMode
impl Clone for RoundingMode
sourcefn clone(&self) -> RoundingMode
fn clone(&self) -> RoundingMode
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl Debug for RoundingMode
impl Debug for RoundingMode
sourceimpl Display for RoundingMode
impl Display for RoundingMode
sourcefn fmt(&self, f: &mut Formatter<'_>) -> Result
fn fmt(&self, f: &mut Formatter<'_>) -> Result
Converts a RoundingMode
to a String
.
Worst-case complexity
Constant time and additional memory.
Examples
use malachite_base::rounding_modes::RoundingMode;
assert_eq!(RoundingMode::Down.to_string(), "Down");
assert_eq!(RoundingMode::Up.to_string(), "Up");
assert_eq!(RoundingMode::Floor.to_string(), "Floor");
assert_eq!(RoundingMode::Ceiling.to_string(), "Ceiling");
assert_eq!(RoundingMode::Nearest.to_string(), "Nearest");
assert_eq!(RoundingMode::Exact.to_string(), "Exact");
sourceimpl FromStr for RoundingMode
impl FromStr for RoundingMode
sourcefn from_str(src: &str) -> Result<RoundingMode, String>
fn from_str(src: &str) -> Result<RoundingMode, String>
Converts a string to a RoundingMode
.
If the string does not represent a valid RoundingMode
, an Err
is returned with the
unparseable string.
Worst-case complexity
$T(n) = O(n)$
$M(n) = O(n)$
where $T$ is time, $M$ is additional memory, and $n$ = src.len()
.
The worst case occurs when the input string is invalid and must be copied into an Err
.
Examples
use malachite_base::rounding_modes::RoundingMode;
use std::str::FromStr;
assert_eq!(RoundingMode::from_str("Down"), Ok(RoundingMode::Down));
assert_eq!(RoundingMode::from_str("Up"), Ok(RoundingMode::Up));
assert_eq!(RoundingMode::from_str("Floor"), Ok(RoundingMode::Floor));
assert_eq!(RoundingMode::from_str("Ceiling"), Ok(RoundingMode::Ceiling));
assert_eq!(RoundingMode::from_str("Nearest"), Ok(RoundingMode::Nearest));
assert_eq!(RoundingMode::from_str("Exact"), Ok(RoundingMode::Exact));
assert_eq!(RoundingMode::from_str("abc"), Err("abc".to_string()));
sourceimpl Hash for RoundingMode
impl Hash for RoundingMode
sourceimpl Named for RoundingMode
impl Named for RoundingMode
sourceconst NAME: &'static str = "RoundingMode"
const NAME: &'static str = "RoundingMode"
The name of this type, as given by the stringify
macro.
See the documentation for impl_named
for more details.
sourceimpl Neg for RoundingMode
impl Neg for RoundingMode
Returns the negative of a RoundingMode
.
The negative is defined so that if a RoundingMode
$m$ is used to round the result of an odd
function $f$, then $f(x, -m) = -f(-x, m)$. Floor
and Ceiling
are swapped, and the other
modes are unchanged.
Worst-case complexity
Constant time and additional memory.
Examples
use malachite_base::rounding_modes::RoundingMode;
assert_eq!(-RoundingMode::Down, RoundingMode::Down);
assert_eq!(-RoundingMode::Up, RoundingMode::Up);
assert_eq!(-RoundingMode::Floor, RoundingMode::Ceiling);
assert_eq!(-RoundingMode::Ceiling, RoundingMode::Floor);
assert_eq!(-RoundingMode::Nearest, RoundingMode::Nearest);
assert_eq!(-RoundingMode::Exact, RoundingMode::Exact);
type Output = RoundingMode
type Output = RoundingMode
The resulting type after applying the -
operator.
sourcefn neg(self) -> RoundingMode
fn neg(self) -> RoundingMode
Performs the unary -
operation. Read more
sourceimpl NegAssign for RoundingMode
impl NegAssign for RoundingMode
sourcefn neg_assign(&mut self)
fn neg_assign(&mut self)
Replaces a RoundingMode
with its negative.
The negative is defined so that if a RoundingMode
$m$ is used to round the result of an
odd function $f$, then $f(x, -m) = -f(-x, m)$. Floor
and Ceiling
are swapped, and the
other modes are unchanged.
Worst-case complexity
Constant time and additional memory.
Examples
use malachite_base::num::arithmetic::traits::NegAssign;
use malachite_base::rounding_modes::RoundingMode;
let mut rm = RoundingMode::Down;
rm.neg_assign();
assert_eq!(rm, RoundingMode::Down);
let mut rm = RoundingMode::Floor;
rm.neg_assign();
assert_eq!(rm, RoundingMode::Ceiling);
sourceimpl Ord for RoundingMode
impl Ord for RoundingMode
sourceimpl PartialEq<RoundingMode> for RoundingMode
impl PartialEq<RoundingMode> for RoundingMode
sourceimpl PartialOrd<RoundingMode> for RoundingMode
impl PartialOrd<RoundingMode> for RoundingMode
sourcefn partial_cmp(&self, other: &RoundingMode) -> Option<Ordering>
fn partial_cmp(&self, other: &RoundingMode) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
1.0.0 · sourcefn lt(&self, other: &Rhs) -> bool
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
impl Copy for RoundingMode
impl Eq for RoundingMode
impl StructuralEq for RoundingMode
impl StructuralPartialEq for RoundingMode
Auto Trait Implementations
impl RefUnwindSafe for RoundingMode
impl Send for RoundingMode
impl Sync for RoundingMode
impl Unpin for RoundingMode
impl UnwindSafe for RoundingMode
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more