Enum RoundingMode

pub enum RoundingMode {
    Down,
    Up,
    Floor,
    Ceiling,
    Nearest,
    Exact,
}

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 RoundingModes.

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

impl Clone for RoundingMode

fn clone(&self) -> RoundingMode

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RoundingMode

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for RoundingMode

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Converts a RoundingMode to a [String].

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::rounding_modes::RoundingMode::*;

assert_eq!(Down.to_string(), "Down");
assert_eq!(Up.to_string(), "Up");
assert_eq!(Floor.to_string(), "Floor");
assert_eq!(Ceiling.to_string(), "Ceiling");
assert_eq!(Nearest.to_string(), "Nearest");
assert_eq!(Exact.to_string(), "Exact");

impl FromStr for RoundingMode

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::{self, *};
use std::str::FromStr;

assert_eq!(RoundingMode::from_str("Down"), Ok(Down));
assert_eq!(RoundingMode::from_str("Up"), Ok(Up));
assert_eq!(RoundingMode::from_str("Floor"), Ok(Floor));
assert_eq!(RoundingMode::from_str("Ceiling"), Ok(Ceiling));
assert_eq!(RoundingMode::from_str("Nearest"), Ok(Nearest));
assert_eq!(RoundingMode::from_str("Exact"), Ok(Exact));
assert_eq!(RoundingMode::from_str("abc"), Err("abc".to_string()));

type Err = String

The associated error which can be returned from parsing.

impl Hash for RoundingMode

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Named for 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.

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!(-Down, Down);
assert_eq!(-Up, Up);
assert_eq!(-Floor, Ceiling);
assert_eq!(-Ceiling, Floor);
assert_eq!(-Nearest, Nearest);
assert_eq!(-Exact, Exact);

type Output = RoundingMode

The resulting type after applying the - operator.

fn neg(self) -> RoundingMode

Performs the unary - operation.

impl NegAssign for RoundingMode

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 = Down;
rm.neg_assign();
assert_eq!(rm, Down);

let mut rm = Floor;
rm.neg_assign();
assert_eq!(rm, Ceiling);

impl Ord for RoundingMode

fn cmp(&self, other: &RoundingMode) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for RoundingMode

fn eq(&self, other: &RoundingMode) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for RoundingMode

fn partial_cmp(&self, other: &RoundingMode) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for RoundingMode

impl Eq for RoundingMode

impl StructuralPartialEq for RoundingMode