Struct libera::all::Integer32

source ·

pub struct Integer32(pub i32);

Available on crate feature numera only.

Expand description

numera A 32-bit integer number, from the set $\Z$, also known as Z32.

The range of valid numeric values is $\lbrack$i32::MIN $\dots$ i32::MAX$\rbrack$. It is equivalent to the i32 primitive.

Tuple Fields§

pub const fn digits(&self) -> usize

Returns the number of digits in base 10.

source §

impl Integer32

Methods for non-negative integers

source

pub fn is_prime(&self) -> Option<bool>

Returns Some(true) if this integer is prime, Some(false) if it’s not prime, or None if it can not be determined.

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 Integer32

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

Integer exponentiation.

Raises self to the power of exp

Panics

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

source

pub const fn checked_pow(self, exp: u32) -> Option<Integer32>

Checked integer exponentiation.

Returns None on overflow.

source

pub const fn saturating_pow(self, exp: u32) -> Integer32

Saturating integer exponentiation.

Raises self to the power of exp, saturating at the numeric bounds instead of overflowing.

source

pub const fn wrapping_pow(self, exp: u32) -> Integer32

Wrapping (modular) integer exponentiation.

Raises self to the power of exp, wrapping around at the boundary of the type.

source

pub const fn overflowing_pow(self, exp: u32) -> (Integer32, bool)

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 Integer32

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.

$$ \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::Integer32;

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

source

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

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::Integer32;

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

source

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

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::Integer32;

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

source

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

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::Integer32;

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

source

pub fn checked_sqrt_floor(self) -> Option<(Integer32, 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::Integer32;

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

source

pub fn checked_sqrt_ceil(self) -> Option<(Integer32, 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::Integer32;

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

source

pub fn checked_sqrt_round(self) -> Option<(Integer32, 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::Integer32;

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

source §

impl Integer32

Subtraction

source

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

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: Integer32) -> Option<Integer32>

Checked subtraction.

source

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

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

source

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

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

source

pub const fn overflowing_sub(self, rhs: Integer32) -> (Integer32, 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 Integer32

Constructors

source

pub const fn new(value: i32) -> Integer32

Returns a new Integer32.

source §

impl Integer32

Methods for resizing

source

pub fn as_larger(&self) -> Integer64

Returns the current number as the next larger bit-size.

This method is not implemented for the largest available bit-size.

source

pub fn as_larger_or_same(&self) -> Integer64

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) -> Result<Integer64, NumeraError>

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) -> Integer

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