```
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§

source§### impl Clone for RoundingMode

### impl Clone for RoundingMode

source§#### fn clone(&self) -> RoundingMode

#### fn clone(&self) -> RoundingMode

1.0.0 · source§#### fn clone_from(&mut self, source: &Self)

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

`source`

. Read moresource§### impl Debug for RoundingMode

### impl Debug for RoundingMode

source§### impl Display for RoundingMode

### impl Display for RoundingMode

source§#### fn 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");
```

source§### impl FromStr for RoundingMode

### impl FromStr for RoundingMode

source§#### fn 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()));
```

source§### impl Hash for RoundingMode

### impl Hash for RoundingMode

source§### impl Named for RoundingMode

### impl Named for RoundingMode

source§### impl 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

`-`

operator.source§#### fn neg(self) -> RoundingMode

#### fn neg(self) -> RoundingMode

`-`

operation. Read moresource§### impl NegAssign for RoundingMode

### impl NegAssign for RoundingMode

source§#### fn 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);
```

source§### impl Ord for RoundingMode

### impl Ord for RoundingMode

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

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

1.21.0 · source§#### fn max(self, other: Self) -> Selfwhere
Self: Sized,

#### fn max(self, other: Self) -> Selfwhere Self: Sized,

source§### impl PartialEq for RoundingMode

### impl PartialEq for RoundingMode

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

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

`self`

and `other`

values to be equal, and is used
by `==`

.source§### impl PartialOrd for RoundingMode

### impl PartialOrd for RoundingMode

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

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

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read more