Struct rugint::Integer

pub struct Integer { /* fields omitted */ }

An arbitrary-precision integer.

Standard arithmetic operations, bitwise operations and comparisons are supported. In standard arithmetic operations such as addition, you can mix Integer and primitive integer types; the result will be an Integer.

Internally the integer is not stored using two's-complement representation, however, for bitwise operations and shifts, the functionality is the same as if the representation was using two's complement.

Examples

use rugint::Integer;

let mut i = Integer::from(1) << 1000;
// i is now 1000000... (1000 zeros)
assert!(i.significant_bits() == 1001);
assert!(i.find_one(0) == Some(1000));
i -= 1;
// i is now 111111... (1000 ones)
assert!(i.count_ones() == Some(1000));

let a = Integer::from(0xf00d);
let all_ones_xor_a = Integer::from(-1) ^ &a;
// a is unchanged as we borrowed it
let complement_a = !a;
// now a has been moved, so this would cause an error:
// assert!(a > 0);
assert!(all_ones_xor_a == complement_a);
assert!(complement_a == -0xf00e);
assert!(format!("{:x}", complement_a) == "-f00e");

Methods

impl Integer

fn new() -> Integer

Constructs a new arbitrary-precision integer with value 0.

fn to_u32(&self) -> u32

Converts to a u32. If the value is too large for the target type, only the least-significant bits are returned.

fn to_i32(&self) -> i32

Converts to an i32. If the value is too large for the target type, only the least-significant bits are returned.

fn to_f64(&self) -> f64

Converts to an f64 rounding towards zero.

fn to_f32(&self) -> f32

Converts to an f32 rounding towards zero.

fn div_rem(&mut self, divisor: &mut Integer)

Computes the quotient and remainder of self divided by divisor. The remainder is stored indivisor`.

fn abs(&mut self) -> &mut Integer

Computes the absolute value of self.

fn div_exact(&mut self, other: &Integer) -> &mut Integer

Divides self by other. This is much faster than normal division, but produces correct results only when the division is exact.

Panics

Panics if other is zero.

fn is_divisible(&self, other: &Integer) -> bool

Returns true if self is divisible by other.

fn is_congruent(&self, c: &Integer, d: &Integer) -> bool

Returns true if self is congruent to c modulo d, that is, if there exists a q such that self == c + q * d. Unlike other division functions, d can be zero.

fn root(&mut self, n: u32) -> &mut Integer

Computes the nth root of self and truncates the result.

fn root_rem(&mut self, buf: &mut Integer, n: u32)

Computes the nth root of self and returns the truncated root and the remainder. The remainder is self minus the truncated root raised to the power of n. The remainder is stored in buf.

fn sqrt(&mut self) -> &mut Integer

Computes the square root of self and truncates the result.

fn sqrt_rem(&mut self, buf: &mut Integer)

Computes the square root of self and returns the truncated root and the remainder. The remainder is self minus the truncated root squared. The remainder is stored in buf.

fn is_perfect_power(&self) -> bool

Returns true if self is a perfect power.

fn is_perfect_square(&self) -> bool

Returns true if self is a perfect square.

fn gcd(&mut self, other: &Integer) -> &mut Integer

Finds the greatest common divisor. The result is always positive except when both inputs are zero.

fn lcm(&mut self, other: &Integer) -> &mut Integer

Finds the least common multiple. The result is always positive except when one or both inputs are zero.

fn invert(&mut self, m: &Integer) -> Option<&mut Integer>

Finds the inverse of self modulo m if an inverse exists.

Panics

Panics if m is zero.

fn set_factorial(&mut self, n: u32) -> &mut Integer

Computes the factorial of n. The value of self is ignored.

fn set_factorial_2(&mut self, n: u32) -> &mut Integer

Computes the double factorial of n. The value of self is ignored.

fn set_factorial_m(&mut self, n: u32, m: u32) -> &mut Integer

Computes the m-multi factorial of n. The value of self is ignored.

fn set_primorial(&mut self, n: u32) -> &mut Integer

Computes the primorial of n. The value of self is ignored.

fn binomial(&mut self, k: u32) -> &mut Integer

Computes the binomial coefficient self over k.

fn set_binomial(&mut self, n: u32, k: u32) -> &mut Integer

Computes the binomial coefficient n over k. The value of self is ignored.

fn cmp_abs(&self, other: &Integer) -> Ordering

Compares the absolute values of self and other.

fn sign(&self) -> Ordering

Returns the same result as self.cmp(0), but is faster.

fn significant_bits(&self) -> usize

Returns the number of bits required to represent the absolute value of self.

Examples

use rugint::Integer;

let i = Integer::from(0);
assert!(i.significant_bits() == 0);
let i = Integer::from(4);
assert!(i.significant_bits() == 3);
let i = Integer::from(7);
assert!(i.significant_bits() == 3);

fn count_ones(&self) -> Option<BitCount>

Returns the number of ones in self if the value >= 0.

fn ham_dist(&self, other: &Integer) -> Option<BitCount>

Retuns the Hamming distance between self and other if they have the same sign, otherwise None.

fn find_zero(&self, start: BitCount) -> Option<BitCount>

Returns the location of the first zero, starting at start. If the bit at location start is zero, returns start.

fn find_one(&self, start: BitCount) -> Option<BitCount>

Returns the location of the first one, starting at start. If the bit at location start is one, returns start.

fn set_bit(&mut self, index: BitCount, val: bool) -> &mut Integer

Sets the bit at location index to 1 if val is true or 0 if val is false.

fn get_bit(&self, index: BitCount) -> bool

Returns true if the bit at location index is 1 or false if the bit is 0.

fn invert_bit(&mut self, index: BitCount) -> &mut Integer

Toggles the bit at location index.

fn random_bits<R: Rng>(&mut self, bits: BitCount, rng: &mut R) -> &mut Integer

Generates a random number consisting of the required number of bits.

Examples

extern crate rand;
extern crate rugint;
use rugint::Integer;
fn main() {
    let mut rng = rand::thread_rng();
    let mut i = Integer::new();
    i.random_bits(0, &mut rng);
    assert!(i == 0);
    i.random_bits(80, &mut rng);
    assert!(i.significant_bits() <= 80);
}

fn random_below<R: Rng>(&mut self, rng: &mut R) -> &mut Integer

Generates a non-negative random number below the given value.

Examples

extern crate rand;
extern crate rugint;
use rugint::Integer;
fn main() {
    let mut rng = rand::thread_rng();
    let bound = Integer::from(15);
    let mut random = bound.clone();
    random.random_below(&mut rng);
    println!("0 <= {} < {}", random, bound);
    assert!(random < bound);
}

Panics

Panics if self is less than or equal to zero.

fn to_string_radix(&self, radix: i32) -> String

Returns a string representation of self for the specified radix.

Panics

Panics if radix is less than 2 or greater than 36.

fn from_str_radix(src: &str, radix: i32) -> Result<Integer, ()>

Parses an Integer.

See the corresponding assignment.

Panics

Panics if radix is less than 2 or greater than 36.

fn assign_str(&mut self, src: &str) -> Result<(), ()>

Parses an Integer from a string.

Examples

use rugint::Integer;
let mut i = Integer::new();
i.assign_str("123").unwrap();
assert!(i == 123);
let ret = i.assign_str("bad");
assert!(ret.is_err());

fn assign_str_radix(&mut self, src: &str, radix: i32) -> Result<(), ()>

Parses an Integer from a string with the specified radix.

Examples

use rugint::Integer;
let mut i = Integer::new();
i.assign_str_radix("ff", 16).unwrap();
assert!(i == 255);

Panics

Panics if radix is less than 2 or greater than 36.

Trait Implementations

impl Drop for Integer

fn drop(&mut self)

A method called when the value goes out of scope.

impl Default for Integer

fn default() -> Integer

Returns the "default value" for a type.

impl Clone for Integer

fn clone(&self) -> Integer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl FromStr for Integer

type Err = ()

The associated error which can be returned from parsing.

fn from_str(src: &str) -> Result<Integer, ()>

Parses an Integer.

See the corresponding assignment.

impl<'a> From<&'a Integer> for Integer

fn from(t: &Integer) -> Integer

Constructs an Integer from another Integer.

impl From<u32> for Integer

fn from(t: u32) -> Integer

Constructs an Integer from a u32.

impl From<i32> for Integer

fn from(t: i32) -> Integer

Constructs an Integer from an i32.

impl<'a> Assign<&'a Integer> for Integer

fn assign(&mut self, other: &'a Integer)

Assigns from another Integer.

impl<'a> Assign<Integer> for Integer

fn assign(&mut self, other: Integer)

Assigns from another Integer.

impl Assign<u32> for Integer

fn assign(&mut self, val: u32)

Assigns from a u32.

impl Assign<i32> for Integer

fn assign(&mut self, val: i32)

Assigns from an i32.

impl Assign<f64> for Integer

fn assign(&mut self, val: f64)

Assigns from an f64, rounding towards zero.

impl Assign<f32> for Integer

fn assign(&mut self, val: f32)

Assigns from an f32, rounding towards zero.

impl<'a> Add<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the + operator

fn add(self, op: &'a Integer) -> Integer

The method for the + operator

impl Add<Integer> for Integer

type Output = Integer

The resulting type after applying the + operator

fn add(self, op: Integer) -> Integer

The method for the + operator

impl<'a> AddAssign<&'a Integer> for Integer

fn add_assign(&mut self, op: &'a Integer)

The method for the += operator

impl AddAssign<Integer> for Integer

fn add_assign(&mut self, op: Integer)

The method for the += operator

impl<'a> Sub<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the - operator

fn sub(self, op: &'a Integer) -> Integer

The method for the - operator

impl Sub<Integer> for Integer

type Output = Integer

The resulting type after applying the - operator

fn sub(self, op: Integer) -> Integer

The method for the - operator

impl<'a> SubAssign<&'a Integer> for Integer

fn sub_assign(&mut self, op: &'a Integer)

The method for the -= operator

impl SubAssign<Integer> for Integer

fn sub_assign(&mut self, op: Integer)

The method for the -= operator

impl<'a> Mul<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the * operator

fn mul(self, op: &'a Integer) -> Integer

The method for the * operator

impl Mul<Integer> for Integer

type Output = Integer

The resulting type after applying the * operator

fn mul(self, op: Integer) -> Integer

The method for the * operator

impl<'a> MulAssign<&'a Integer> for Integer

fn mul_assign(&mut self, op: &'a Integer)

The method for the *= operator

impl MulAssign<Integer> for Integer

fn mul_assign(&mut self, op: Integer)

The method for the *= operator

impl<'a> Div<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the / operator

fn div(self, op: &'a Integer) -> Integer

The method for the / operator

impl Div<Integer> for Integer

type Output = Integer

The resulting type after applying the / operator

fn div(self, op: Integer) -> Integer

The method for the / operator

impl<'a> DivAssign<&'a Integer> for Integer

fn div_assign(&mut self, op: &'a Integer)

The method for the /= operator

impl DivAssign<Integer> for Integer

fn div_assign(&mut self, op: Integer)

The method for the /= operator

impl<'a> Rem<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the % operator

fn rem(self, op: &'a Integer) -> Integer

The method for the % operator

impl Rem<Integer> for Integer

type Output = Integer

The resulting type after applying the % operator

fn rem(self, op: Integer) -> Integer

The method for the % operator

impl<'a> RemAssign<&'a Integer> for Integer

fn rem_assign(&mut self, op: &'a Integer)

The method for the %= operator

impl RemAssign<Integer> for Integer

fn rem_assign(&mut self, op: Integer)

The method for the %= operator

impl SubFromAssign for Integer

fn sub_from_assign(&mut self, lhs: Integer)

Peforms the subtraction.

impl<'a> SubFromAssign<&'a Integer> for Integer

fn sub_from_assign(&mut self, lhs: &Integer)

Peforms the subtraction.

impl DivFromAssign for Integer

fn div_from_assign(&mut self, lhs: Integer)

Peforms the division.

impl<'a> DivFromAssign<&'a Integer> for Integer

fn div_from_assign(&mut self, lhs: &Integer)

Peforms the division.

impl Add<u32> for Integer

type Output = Integer

The resulting type after applying the + operator

fn add(self, op: u32) -> Integer

The method for the + operator

impl AddAssign<u32> for Integer

fn add_assign(&mut self, op: u32)

The method for the += operator

impl Sub<u32> for Integer

type Output = Integer

The resulting type after applying the - operator

fn sub(self, op: u32) -> Integer

The method for the - operator

impl SubAssign<u32> for Integer

fn sub_assign(&mut self, op: u32)

The method for the -= operator

impl SubFromAssign<u32> for Integer

fn sub_from_assign(&mut self, lhs: u32)

Peforms the subtraction.

impl Mul<u32> for Integer

type Output = Integer

The resulting type after applying the * operator

fn mul(self, op: u32) -> Integer

The method for the * operator

impl MulAssign<u32> for Integer

fn mul_assign(&mut self, op: u32)

The method for the *= operator

impl Mul<i32> for Integer

type Output = Integer

The resulting type after applying the * operator

fn mul(self, op: i32) -> Integer

The method for the * operator

impl MulAssign<i32> for Integer

fn mul_assign(&mut self, op: i32)

The method for the *= operator

impl Div<u32> for Integer

type Output = Integer

The resulting type after applying the / operator

fn div(self, op: u32) -> Integer

The method for the / operator

impl DivAssign<u32> for Integer

fn div_assign(&mut self, op: u32)

The method for the /= operator

impl Rem<u32> for Integer

type Output = Integer

The resulting type after applying the % operator

fn rem(self, op: u32) -> Integer

The method for the % operator

impl RemAssign<u32> for Integer

fn rem_assign(&mut self, op: u32)

The method for the %= operator

impl Shl<u32> for Integer

type Output = Integer

The resulting type after applying the << operator

fn shl(self, op: u32) -> Integer

The method for the << operator

impl ShlAssign<u32> for Integer

fn shl_assign(&mut self, op: u32)

The method for the <<= operator

impl Shr<u32> for Integer

type Output = Integer

The resulting type after applying the >> operator

fn shr(self, op: u32) -> Integer

The method for the >> operator

impl ShrAssign<u32> for Integer

fn shr_assign(&mut self, op: u32)

The method for the >>= operator

impl Pow<u32> for Integer

type Output = Integer

The resulting type after the power operation.

fn pow(self, op: u32) -> Integer

Performs the power operation.

impl PowAssign<u32> for Integer

fn pow_assign(&mut self, op: u32)

Peforms the power operation.

impl Neg for Integer

type Output = Integer

The resulting type after applying the - operator

fn neg(self) -> Integer

The method for the unary - operator

impl NegAssign for Integer

fn neg_assign(&mut self)

Peforms the negation.

impl Eq for Integer

impl Ord for Integer

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

This method returns an Ordering between self and other.

impl PartialEq for Integer

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd for Integer

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialOrd<f64> for Integer

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialEq<f64> for Integer

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<f32> for Integer

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialEq<f32> for Integer

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<u32> for Integer

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialEq<u32> for Integer

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<i32> for Integer

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl PartialEq<i32> for Integer

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<'a> BitAnd<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the & operator

fn bitand(self, op: &'a Integer) -> Integer

The method for the & operator

impl BitAnd for Integer

type Output = Integer

The resulting type after applying the & operator

fn bitand(self, op: Integer) -> Integer

The method for the & operator

impl<'a> BitAndAssign<&'a Integer> for Integer

fn bitand_assign(&mut self, op: &'a Integer)

The method for the &= operator

impl BitAndAssign<Integer> for Integer

fn bitand_assign(&mut self, op: Integer)

The method for the &= operator

impl<'a> BitOr<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the | operator

fn bitor(self, op: &'a Integer) -> Integer

The method for the | operator

impl BitOr for Integer

type Output = Integer

The resulting type after applying the | operator

fn bitor(self, op: Integer) -> Integer

The method for the | operator

impl<'a> BitOrAssign<&'a Integer> for Integer

fn bitor_assign(&mut self, op: &'a Integer)

The method for the |= operator

impl BitOrAssign<Integer> for Integer

fn bitor_assign(&mut self, op: Integer)

The method for the |= operator

impl<'a> BitXor<&'a Integer> for Integer

type Output = Integer

The resulting type after applying the ^ operator

fn bitxor(self, op: &'a Integer) -> Integer

The method for the ^ operator

impl BitXor for Integer

type Output = Integer

The resulting type after applying the ^ operator

fn bitxor(self, op: Integer) -> Integer

The method for the ^ operator

impl<'a> BitXorAssign<&'a Integer> for Integer

fn bitxor_assign(&mut self, op: &'a Integer)

The method for the ^= operator

impl BitXorAssign<Integer> for Integer

fn bitxor_assign(&mut self, op: Integer)

The method for the ^= operator

impl Not for Integer

type Output = Integer

The resulting type after applying the ! operator

fn not(self) -> Integer

The method for the unary ! operator

impl NotAssign for Integer

fn not_assign(&mut self)

Peforms the complement.

impl Display for Integer

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Debug for Integer

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Binary for Integer

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Octal for Integer

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl LowerHex for Integer

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl UpperHex for Integer

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.