assert_eq![Z8::new(7).div_trunc(Z8::new(3)), Z8::new(2)];
assert_eq![Z8::new(7).div_trunc(Z8::new(-3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_trunc(Z8::new(3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_trunc(Z8::new(-3)), Z8::new(2)];

// tie-breaking
assert_eq![Z8::new(8).div_trunc(Z8::new(5)), Z8::new(1)]; // 8/5 = 1.6 => 1
assert_eq![Z8::new(6).div_trunc(Z8::new(4)), Z8::new(1)]; // 6/4 = 1.5 => 1
assert_eq![Z8::new(7).div_trunc(Z8::new(5)), Z8::new(1)]; // 7/5 = 1.4 => 1

Source

pub const fn checked_div_trunc(self, rhs: Integer128) -> Option<Integer128>

Returns the checked truncated division.

Rounds the quotient towards zero, or away from infinity.

§Examples

// invalid operands
assert_eq![Z8::new(7).checked_div_trunc(Z8::new(0)), None]; // division by 0
assert_eq![Z8::MIN.checked_div_trunc(Z8::new(-1)), None]; // overflow

Source

pub const fn div_euclid(self, rhs: Integer128) -> Integer128

Returns the euclidean division.

Ensures that the remainder is always non-negative and smaller than the divisor.

§Panics

If rhs is 0 or if division results in overflow.

§Examples

assert_eq![Z8::new(7).div_euclid(Z8::new(3)), Z8::new(2)];
assert_eq![Z8::new(7).div_euclid(Z8::new(-3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_euclid(Z8::new(3)), Z8::new(-3)];
assert_eq![Z8::new(-7).div_euclid(Z8::new(-3)), Z8::new(3)];

// tie-breaking
assert_eq![Z8::new(8).div_trunc(Z8::new(5)), Z8::new(1)]; // 8/5 = 1.6 => 1
assert_eq![Z8::new(6).div_trunc(Z8::new(4)), Z8::new(1)]; // 6/4 = 1.5 => 1
assert_eq![Z8::new(7).div_trunc(Z8::new(5)), Z8::new(1)]; // 7/5 = 1.4 => 1

Source

pub const fn checked_div_euclid(self, rhs: Integer128) -> Option<Integer128>

Returns the checked euclidean division.

Ensures that the remainder is always non-negative and smaller than the divisor.

§Examples

// invalid operands
assert_eq![Z8::new(7).checked_div_euclid(Z8::new(0)), None]; // division by 0
assert_eq![Z8::MIN.checked_div_euclid(Z8::new(-1)), None]; // overflow

Source

pub const fn div_floor(self, rhs: Integer128) -> Integer128

Returns the floored division

Rounds the quotient towards negative infinity.

§Panics

If rhs is 0 or if the division results in overflow.

§Notation

$ \left\lfloor \frac{x}{y} \right\rfloor $

§Examples

assert_eq![Z8::new(7).div_floor(Z8::new(3)), Z8::new(2)];
assert_eq![Z8::new(7).div_floor(Z8::new(-3)), Z8::new(-3)];
assert_eq![Z8::new(-7).div_floor(Z8::new(3)), Z8::new(-3)];
assert_eq![Z8::new(-7).div_floor(Z8::new(-3)), Z8::new(2)];

// tie-breaking
assert_eq![Z8::new(8).div_trunc(Z8::new(5)), Z8::new(1)]; // 8/5 = 1.6 => 1
assert_eq![Z8::new(6).div_trunc(Z8::new(4)), Z8::new(1)]; // 6/4 = 1.5 => 1
assert_eq![Z8::new(7).div_trunc(Z8::new(5)), Z8::new(1)]; // 7/5 = 1.4 => 1

Source

pub const fn checked_div_floor(self, rhs: Integer128) -> Option<Integer128>

Returns the checked floored division.

Rounds the quotient towards negative infinity.

§Notation

$ \left\lfloor \frac{x}{y} \right\rfloor $

§Examples

// invalid operands
assert_eq![Z8::new(7).checked_div_floor(Z8::new(0)), None]; // division by 0
assert_eq![Z8::MIN.checked_div_floor(Z8::new(-1)), None]; // overflow

Source

pub const fn div_ceil(self, rhs: Integer128) -> Integer128

Returns the ceiled division.

Rounds the quotient towards positive infinity.

§Notation

$ \left\lceil \frac{x}{y} \right\rceil $

§Examples

assert_eq![Z8::new(7).div_ceil(Z8::new(3)), Z8::new(3)];
assert_eq![Z8::new(7).div_ceil(Z8::new(-3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_ceil(Z8::new(3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_ceil(Z8::new(-3)), Z8::new(3)];

// tie-breaking
assert_eq![Z8::new(8).div_ceil(Z8::new(5)), Z8::new(2)]; // 8/5 = 1.6 => 2
assert_eq![Z8::new(6).div_ceil(Z8::new(4)), Z8::new(2)]; // 6/4 = 1.5 => 2
assert_eq![Z8::new(7).div_ceil(Z8::new(5)), Z8::new(2)]; // 7/5 = 1.4 => 2

Source

pub const fn checked_div_ceil(self, rhs: Integer128) -> Option<Integer128>

Returns the checked ceiled division.

Rounds the quotient towards positive infinity.

§Notation

$ \left\lceil \frac{x}{y} \right\rceil $

§Examples

// invalid operands
assert_eq![Z8::new(7).checked_div_ceil(Z8::new(0)), None]; // division by 0
assert_eq![Z8::MIN.checked_div_ceil(Z8::new(-1)), None]; // overflow

Source

pub const fn div_half_away(self, rhs: Integer128) -> Integer128

Returns the rounded division half away from 0.

Rounds the quotient to the nearest integer, tie-breaking away from 0 (w).

§Panics

If rhs is 0 or if the division results in overflow.

§Examples

assert_eq![Z8::new(7).div_half_away(Z8::new(3)), Z8::new(2)];
assert_eq![Z8::new(7).div_half_away(Z8::new(-3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_half_away(Z8::new(3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_half_away(Z8::new(-3)), Z8::new(2)];

// half tie-breaking
assert_eq![Z8::new(6).div_half_away(Z8::new(4)), Z8::new(2)]; // 6/4 = 1.5 => 2
assert_eq![Z8::new(7).div_half_away(Z8::new(5)), Z8::new(1)]; // 7/5 = 1.25 => 1

Source

pub const fn checked_div_half_away(self, rhs: Integer128) -> Option<Integer128>

Returns the checked rounded division half away from 0.

Rounds the quotient to the nearest integer, tie-breaking away from 0 (w).

§Examples

// invalid operands
assert_eq![Z8::new(7).checked_div_half_away(Z8::new(0)), None]; // division by 0
assert_eq![Z8::MIN.checked_div_half_away(Z8::new(-1)), None]; // overflow

Source

pub const fn div_half_even(self, rhs: Integer128) -> Integer128

Returns the rounded division half to even.

Rounds the quotient to the nearest integer, tie-breaking to the nearest even number.

This is also known as bankers’ rounding and is often the default rounding method, since it helps eliminate positive/negative bias and bias towards/away from zero (w).

§Panics

If rhs is 0 or if the division results in overflow.

§Examples

assert_eq![Z8::new(7).div_half_even(Z8::new(3)), Z8::new(2)];
assert_eq![Z8::new(7).div_half_even(Z8::new(-3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_half_even(Z8::new(3)), Z8::new(-2)];
assert_eq![Z8::new(-7).div_half_even(Z8::new(-3)), Z8::new(2)];

// half tie-breaking
assert_eq![Z8::new(6).div_half_even(Z8::new(4)), Z8::new(2)]; // 6/4 = 1.5 => 2
assert_eq![Z8::new(7).div_half_even(Z8::new(5)), Z8::new(2)]; // 7/5 = 1.25 => 2

Source

pub const fn checked_div_half_even(self, rhs: Integer128) -> Option<Integer128>

Returns the checked rounded division half to even.

Rounds the quotient to the nearest integer, tie-breaking to the nearest even number.

This is also known as bankers’ rounding and is often the default rounding method, since it helps eliminate positive/negative bias and bias towards/away from zero (w).

§Examples

// invalid operands
assert_eq![Z8::new(7).checked_div_half_away(Z8::new(0)), None]; // division by 0
assert_eq![Z8::MIN.checked_div_half_away(Z8::new(-1)), None]; // overflow

Source §

impl Integer128

§Division and remainder

Source

pub const fn div_rem(self, rhs: Integer128) -> (Integer128, Integer128)

Alias of div_rem_trunc.

Source

pub const fn div_rem_trunc(self, rhs: Integer128) -> (Integer128, Integer128)

Returns the truncated (quotient, remainder).

§Panics

If rhs is 0 or if division results in overflow.

assert_eq![Z8::new(7).div_rem_trunc(Z8::new(3)), (Z8::new(2), Z8::new(1))];
assert_eq![Z8::new(7).div_rem_trunc(Z8::new(-3)), (Z8::new(-2), Z8::new(1))];
assert_eq![Z8::new(-7).div_rem_trunc(Z8::new(3)), (Z8::new(-2), Z8::new(-1))];
assert_eq![Z8::new(-7).div_rem_trunc(Z8::new(-3)), (Z8::new(2), Z8::new(-1))];

Source

pub const fn div_rem_euclid(self, rhs: Integer128) -> (Integer128, Integer128)

Returns the euclidean (quotient, remainder).

§Panics

If rhs is 0 or if division results in overflow.

§Examples

assert_eq![Z8::new(7).div_rem_euclid(Z8::new(3)), (Z8::new(2), Z8::new(1))];
assert_eq![Z8::new(7).div_rem_euclid(Z8::new(-3)), (Z8::new(-2), Z8::new(1))];
assert_eq![Z8::new(-7).div_rem_euclid(Z8::new(3)), (Z8::new(-3), Z8::new(2))];
assert_eq![Z8::new(-7).div_rem_euclid(Z8::new(-3)), (Z8::new(3), Z8::new(2))];

Source

pub const fn div_rem_ceil(self, rhs: Integer128) -> (Integer128, Integer128)

Returns the ceiled (quotient, remainder).

§Panics

If rhs is 0 or if division results in overflow.

§Examples

assert_eq![Z8::new(7).div_rem_ceil(Z8::new(3)), (Z8::new(3), Z8::new(-2))];
assert_eq![Z8::new(7).div_rem_ceil(Z8::new(-3)), (Z8::new(-2), Z8::new(1))];
assert_eq![Z8::new(-7).div_rem_ceil(Z8::new(3)), (Z8::new(-2), Z8::new(-1))];
assert_eq![Z8::new(-7).div_rem_ceil(Z8::new(-3)), (Z8::new(3), Z8::new(2))];

Source

pub const fn div_rem_floor(self, rhs: Integer128) -> (Integer128, Integer128)

Returns the floored (quotient, remainder).

§Panics

If rhs is 0 or if division results in overflow.

§Examples

assert_eq![Z8::new(7).div_rem_floor(Z8::new(3)), (Z8::new(2), Z8::new(1))];
assert_eq![Z8::new(7).div_rem_floor(Z8::new(-3)), (Z8::new(-3), Z8::new(-2))];
assert_eq![Z8::new(-7).div_rem_floor(Z8::new(3)), (Z8::new(-3), Z8::new(2))];
assert_eq![Z8::new(-7).div_rem_floor(Z8::new(-3)), (Z8::new(2), Z8::new(-1))];

Source §

impl Integer128

§Multiplication

Source

pub const fn mul(self, rhs: Integer128) -> Integer128

Integer multiplication.

§Panics

Panics in debug, on overflow. While in release, it performs two’s complement wrapping.

Source

pub const fn checked_mul(self, rhs: Integer128) -> Option<Integer128>

Checked integer multiplication.

Returns None on overflow.

Source

pub const fn saturating_mul(self, rhs: Integer128) -> Integer128

Saturating multiplication. Computes self + rhs, saturating at the numeric bounds instead of overflowing.

Source

pub const fn wrapping_mul(self, rhs: Integer128) -> Integer128

Wrapping (modular) multiplication. Computes self + rhs, wrapping around at the boundary of the type.

Source

pub const fn overflowing_mul(self, rhs: Integer128) -> (Integer128, bool)

Overflowing multiplication.

Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

Source §

impl Integer128

§Negation

Source

pub const fn neg(self) -> Integer128

Basic negation. Computes -self.

§Panics

Panics in debug, if self == MIN. While in release, it returns MIN, same as wrapping_neg

Source

pub const fn checked_neg(self) -> Option<Integer128>

Checked negation. Computes -self, returning None if self == MIN instead of overflowing.

Source

pub const fn saturating_neg(self) -> Integer128

Saturating negation. Computes -self, returning MAX if self == MIN instead of overflowing.

Source

pub const fn wrapping_neg(self) -> Integer128

Wrapping negation. Computes -self, returning MIN if self == MIN instead of overflowing.

Source

pub const fn overflowing_neg(self) -> (Integer128, bool)

Overflowing negation. Negates self, overflowing if this is equal to the minimum value.

Returns a tuple of the negated version along with a boolean indicating whether an arithmetic overflow happened. If self == MIN then (MIN, true) is returned.

Source §

impl Integer128

§Exponentiation

Source

pub const fn pow(self, exp: u32) -> Integer128

Integer exponentiation.

Raises self to the power of exp

Overflowing integer exponentiation.

Raises self to the power of exp,

Returns a tuple of the exponentiation along with a boolean indicating whether an overflow happened.

Source §

impl Integer128

§Remainder

Source

pub const fn rem_trunc(self, rhs: Integer128) -> Integer128

Returns the truncated remainder operation.

This is the default remainder operation in Rust, C and Java.

It is based on truncated division, rounding the quotient towards zero, meaning the remainder has the same sign as the dividend.

§Notation

$ x \mod n $

§Examples

use numera::all::Z8;

assert_eq![Z8::new(-5).rem_trunc(Z8::new(2)), Z8::new(-1)];

Source

pub const fn rem_euclid(self, rhs: Integer128) -> Integer128

Returns the euclidean remainder operation.

This is often used in modular arithmetic, since it always returns a non-negative remainder.

It is based on euclidean division, whih ensures that the same value of x will always result in the same remainder when divided by the same value of y.

§Panics

If rhs is 0 or the division results in overflow.

§Examples

use numera::all::Z8;

assert_eq![Z8::new(-5).rem_euclid(Z8::new(2)), Z8::new(1)];

Source

pub const fn checked_rem_euclid(self, rhs: Integer128) -> Option<Integer128>

Returns the checked Euclidean remainder operation.

Computes rem_euclid, returning None if rhs == 0 or the division results in overflow.

§Examples

use numera::all::Z8;

assert_eq![Z8::new(-5).checked_rem_euclid(Z8::new(2)), Some(Z8::new(1))];
assert_eq![Z8::new(-5).checked_rem_euclid(Z8::new(0)), None];

Source

pub const fn rem_floor(self, rhs: Integer128) -> Integer128

Returns the floored remainder operation.

Rounds the quotient towards negative infinity, differing from the truncated division in regard to negative numbers.

This is often used when the quotient represents the number of “groups” of a certain size that can be formed from a given number of items.

§Examples

use numera::all::Z8;

// TODO

Source §

impl Integer128

§Square root

Source

pub fn is_square(self) -> bool

Returns true if self is a perfect square, meaning the square root of self is an integer.

Returns false otherwise, which includes all negative values.

§Algorithm

$$ \text{is\textunderscore square}(n) = \begin{cases} \text{true} & \text{if } \left(\lfloor \sqrt{n} \rfloor\right)^2 = n \cr \text{false} & \text{if } \left(\lfloor \sqrt{n} \rfloor\right)^2 \neq n \end{cases} $$

§Examples

use numera::all::Integer128;

assert_eq![Integer128(12).is_square(), false];
assert_eq![Integer128(13).is_square(), false];
assert_eq![Integer128(16).is_square(), true];
assert_eq![Integer128(20).is_square(), false];
assert_eq![Integer128(21).is_square(), false];

Source

pub fn sqrt_floor(self) -> Option<Integer128>

Returns the floored integer square root.

Returns None if self is negative.

§Algorithm

$$ \left\lfloor \sqrt{x} \right\rfloor = n_{k} $$

Where $n_{k}$ is the result of a sequence of estimates that starts with an initial $n_{0} = x/2$ which is updated using Heron’s method:

$$ n_{i+1} = n_{i} - ( n_{i}^{2} - x) / 2n_{i}, \quad \small\text{for} \quad i = 0, 1, \ldots, k, $$

Where $n_{i}$ is the current estimate, $n_{i+1}$ is the next estimate, $x$ is self, and $k$ is the number of iterations needed to converge to a solution, on the order of the number of bits of self, about $O(\log_2 b)$, which for e.g. 128 bits would be $ ±7 $ iterations.

Hence, the function continues updating the estimate until reaching $n_{k}$, which provides the largest integer less than or equal to the square root of x.

§Examples

use numera::all::Integer128;

assert_eq![Integer128(12).sqrt_floor(), Some(Integer128(3))];
assert_eq![Integer128(13).sqrt_floor(), Some(Integer128(3))];
assert_eq![Integer128(16).sqrt_floor(), Some(Integer128(4))];
assert_eq![Integer128(20).sqrt_floor(), Some(Integer128(4))];
assert_eq![Integer128(21).sqrt_floor(), Some(Integer128(4))];

Source

pub fn sqrt_ceil(self) -> Option<Integer128>

Returns the ceiled integer square root.

Returns None if self is negative.

§Algorithm

$$ \begin{align} \notag \left\lceil \sqrt{x} \thinspace\right\rceil = \begin{cases} n & \text{if } n^2 = x \cr n+1 & \text{if } n^2 < x \end{cases} \cr \notag \small\text{where } n = \lfloor \sqrt{x} \rfloor & \end{align} $$

§Examples

use numera::all::Integer128;

assert_eq![Integer128(12).sqrt_ceil(), Some(Integer128(4))];
assert_eq![Integer128(13).sqrt_ceil(), Some(Integer128(4))];
assert_eq![Integer128(16).sqrt_ceil(), Some(Integer128(4))];
assert_eq![Integer128(20).sqrt_ceil(), Some(Integer128(5))];
assert_eq![Integer128(21).sqrt_ceil(), Some(Integer128(5))];

Source

pub fn sqrt_round(self) -> Option<Integer128>

Returns the rounded integer square root.

Returns None if self is negative.

§Algorithm

$$ \begin{align} \notag \left\lfloor\sqrt{x} \thinspace\right\rceil = \begin{cases} n & \text{if } x - n^2 < (n+1)^2 - x \cr n+1 & \text{if } x - n^2 \geq (n+1)^2 - x \end{cases} \cr \notag \small\text{where } n = \lfloor \sqrt{x} \rfloor & \end{align} $$

§Examples

use numera::all::Integer128;

assert_eq![Integer128(12).sqrt_round(), Some(Integer128(3))];
assert_eq![Integer128(13).sqrt_round(), Some(Integer128(4))];
assert_eq![Integer128(16).sqrt_round(), Some(Integer128(4))];
assert_eq![Integer128(20).sqrt_round(), Some(Integer128(4))];
assert_eq![Integer128(21).sqrt_round(), Some(Integer128(5))];

Source

pub fn checked_sqrt_floor(self) -> Option<(Integer128, bool)>

Returns the checked floored integer square root, as a tuple containing sqrt_floor and is_square.

Returns None if self is negative.

§Examples

use numera::all::Integer128;

assert_eq![Integer128(12).checked_sqrt_floor(), Some((Integer128(3), false))];
assert_eq![Integer128(13).checked_sqrt_floor(), Some((Integer128(3), false))];
assert_eq![Integer128(16).checked_sqrt_floor(), Some((Integer128(4), true))];
assert_eq![Integer128(20).checked_sqrt_floor(), Some((Integer128(4), false))];
assert_eq![Integer128(21).checked_sqrt_floor(), Some((Integer128(4), false))];

Source

pub fn checked_sqrt_ceil(self) -> Option<(Integer128, bool)>

Returns the checked ceiled integer square root, as a tuple containing sqrt_ceil and is_square.

Returns None if self is negative.

§Examples

use numera::all::Integer128;

assert_eq![Integer128(12).checked_sqrt_ceil(), Some((Integer128(4), false))];
assert_eq![Integer128(13).checked_sqrt_ceil(), Some((Integer128(4), false))];
assert_eq![Integer128(16).checked_sqrt_ceil(), Some((Integer128(4), true))];
assert_eq![Integer128(20).checked_sqrt_ceil(), Some((Integer128(5), false))];
assert_eq![Integer128(21).checked_sqrt_ceil(), Some((Integer128(5), false))];

Source

pub fn checked_sqrt_round(self) -> Option<(Integer128, bool)>

Returns the checked rounded integer square root, as a tuple containing sqrt_round and is_square.

Returns None if self is negative.

§Examples

use numera::all::Integer128;

assert_eq![Integer128(12).checked_sqrt_round(), Some((Integer128(3), false))];
assert_eq![Integer128(13).checked_sqrt_round(), Some((Integer128(4), false))];
assert_eq![Integer128(16).checked_sqrt_round(), Some((Integer128(4), true))];
assert_eq![Integer128(20).checked_sqrt_round(), Some((Integer128(4), false))];
assert_eq![Integer128(21).checked_sqrt_round(), Some((Integer128(5), false))];

Source §

impl Integer128

§Subtraction

Source

pub const fn sub(self, rhs: Integer128) -> Integer128

Integer subtraction.

§Panics

Panics in debug, on overflow. While in release, it performs two’s complement wrapping.

Source

pub const fn checked_sub(self, rhs: Integer128) -> Option<Integer128>

Checked subtraction.

Source

pub const fn saturating_sub(self, rhs: Integer128) -> Integer128

Saturating subtraction. Computes self + rhs, saturating at the numeric bounds instead of overflowing.

Source

pub const fn wrapping_sub(self, rhs: Integer128) -> Integer128

Wrapping (modular) subtraction. Computes self + rhs, wrapping around at the boundary of the type.

Source

pub const fn overflowing_sub(self, rhs: Integer128) -> (Integer128, bool)

Overflowing subtraction.

Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

Source §

impl Integer128

§Constructors

Source

pub const fn new(value: i128) -> Self

Returns a new Integer128.

Source §

impl Integer128

§Methods for resizing

Source

pub fn as_larger_or_same(&self) -> Integer128

Returns the current number as the next larger bit-size, or the same if there’s no larger one available.

Source

pub fn try_as_larger(&self) -> NumeraResult<Integer128>

Tries to return the current number as the next larger bit-size.

§Errors

If there’s no larger bit-size available.

Source

pub fn as_smaller_or_same(&self) -> Integers

Available on crate feature try_from only.

Returns the current number as the next smaller bit-size, or the same if the value can’t fit in the smaller bit-size, or if there’s no smaller bit-size available.

Source