Struct rug::integer::SmallInteger

#[repr(C)]
pub struct SmallInteger { /* fields omitted */ }

A small integer that does not require any memory allocation.

This can be useful when you have a u64, i64, u32 or i32 but need a reference to an Integer.

If there are functions that take a u32 or i32 directly instead of an Integer reference, using them can still be faster than using a SmallInteger; the functions would still need to check for the size of an Integer obtained using SmallInteger.

The SmallInteger type can be coerced to an Integer, as it implements Deref with an Integer target.

Examples

use rug::Integer;
use rug::integer::SmallInteger;
// `a` requires a heap allocation
let mut a = Integer::from(250);
// `b` can reside on the stack
let b = SmallInteger::from(-100);
a.lcm_mut(&b);
assert_eq!(a, 500);
// another computation:
a.lcm_mut(&SmallInteger::from(30));
assert_eq!(a, 1500);

Methods

impl SmallInteger

fn new() -> SmallInteger

Creates a SmallInteger with value 0.

Examples

use rug::integer::SmallInteger;
let i = SmallInteger::new();
// Borrow i as if it were Integer.
assert_eq!(*i, 0);

Methods from Deref<Target = Integer>

fn capacity(&self) -> usize

Returns the capacity in bits that can be stored without reallocating.

Examples

use rug::Integer;
let i = Integer::with_capacity(137);
assert!(i.capacity() >= 137);

fn to_i32(&self) -> Option<i32>

Converts to an i32 if the value fits.

Examples

use rug::Integer;
let fits = Integer::from(-50);
assert_eq!(fits.to_i32(), Some(-50));
let small = Integer::from(-123456789012345_i64);
assert_eq!(small.to_i32(), None);
let large = Integer::from(123456789012345_u64);
assert_eq!(large.to_i32(), None);

fn to_i64(&self) -> Option<i64>

Converts to an i64 if the value fits.

Examples

use rug::Integer;
let fits = Integer::from(-50);
assert_eq!(fits.to_i64(), Some(-50));
let small = Integer::from_str_radix("-fedcba9876543210", 16).unwrap();
assert_eq!(small.to_i64(), None);
let large = Integer::from_str_radix("fedcba9876543210", 16).unwrap();
assert_eq!(large.to_i64(), None);

fn to_u32(&self) -> Option<u32>

Converts to a u32 if the value fits.

Examples

use rug::Integer;
let fits = Integer::from(1234567890);
assert_eq!(fits.to_u32(), Some(1234567890));
let neg = Integer::from(-1);
assert_eq!(neg.to_u32(), None);
let large = "123456789012345".parse::<Integer>().unwrap();
assert_eq!(large.to_u32(), None);

fn to_u64(&self) -> Option<u64>

Converts to a u64 if the value fits.

Examples

use rug::Integer;
let fits = Integer::from(123456789012345_u64);
assert_eq!(fits.to_u64(), Some(123456789012345));
let neg = Integer::from(-1);
assert_eq!(neg.to_u64(), None);
let large = "1234567890123456789012345".parse::<Integer>().unwrap();
assert_eq!(large.to_u64(), None);

fn to_i32_wrapping(&self) -> i32

Converts to an i32, wrapping if the value does not fit.

Examples

use rug::Integer;
let fits = Integer::from(-0xabcdef_i32);
assert_eq!(fits.to_i32_wrapping(), -0xabcdef);
let small = Integer::from(0x1_ffff_ffff_u64);
assert_eq!(small.to_i32_wrapping(), -1);
let large = Integer::from_str_radix("1234567890abcdef", 16).unwrap();
assert_eq!(large.to_i32_wrapping(), 0x90abcdef_u32 as i32);

fn to_i64_wrapping(&self) -> i64

Converts to an i64, wrapping if the value does not fit.

Examples

use rug::Integer;
let fits = Integer::from(-0xabcdef);
assert_eq!(fits.to_i64_wrapping(), -0xabcdef);
let small = Integer::from_str_radix("1ffffffffffffffff", 16).unwrap();
assert_eq!(small.to_i64_wrapping(), -1);
let large = Integer::from_str_radix("f1234567890abcdef", 16).unwrap();
assert_eq!(large.to_i64_wrapping(), 0x1234567890abcdef_i64);

fn to_u32_wrapping(&self) -> u32

Converts to a u32, wrapping if the value does not fit.

Examples

use rug::Integer;
let fits = Integer::from(0x90abcdef_u32);
assert_eq!(fits.to_u32_wrapping(), 0x90abcdef);
let neg = Integer::from(-1);
assert_eq!(neg.to_u32_wrapping(), 0xffffffff);
let large = Integer::from_str_radix("1234567890abcdef", 16).unwrap();
assert_eq!(large.to_u32_wrapping(), 0x90abcdef);

fn to_u64_wrapping(&self) -> u64

Converts to a u64, wrapping if the value does not fit.

Examples

use rug::Integer;
let fits = Integer::from(0x90abcdef_u64);
assert_eq!(fits.to_u64_wrapping(), 0x90abcdef);
let neg = Integer::from(-1);
assert_eq!(neg.to_u64_wrapping(), 0xffff_ffff_ffff_ffff);
let large = Integer::from_str_radix("f123456789abcdef0", 16).unwrap();
assert_eq!(large.to_u64_wrapping(), 0x123456789abcdef0);

fn to_f32(&self) -> f32

Converts to an f32, rounding towards zero.

Examples

use rug::Integer;
use std::f32;
let min = Integer::from_f32(f32::MIN).unwrap();
let min_minus_one = min - 1u32;
// min_minus_one is truncated to f32::MIN
assert_eq!(min_minus_one.to_f32(), f32::MIN);
let times_two = min_minus_one * 2u32;
// times_two is too small
assert_eq!(times_two.to_f32(), f32::NEG_INFINITY);

fn to_f64(&self) -> f64

Converts to an f64, rounding towards zero.

Examples

use rug::Integer;
use std::f64;

// An `f64` has 53 bits of precision.
let exact = 0x1f_ffff_ffff_ffff_u64;
let i = Integer::from(exact);
assert_eq!(i.to_f64(), exact as f64);

// large has 56 ones
let large = 0xff_ffff_ffff_ffff_u64;
// trunc has 53 ones followed by 3 zeros
let trunc = 0xff_ffff_ffff_fff8_u64;
let j = Integer::from(large);
assert_eq!(j.to_f64() as u64, trunc);

let max = Integer::from_f64(f64::MAX).unwrap();
let max_plus_one = max + 1u32;
// max_plus_one is truncated to f64::MAX
assert_eq!(max_plus_one.to_f64(), f64::MAX);
let times_two = max_plus_one * 2u32;
// times_two is too large
assert_eq!(times_two.to_f64(), f64::INFINITY);

fn to_f32_exp(&self) -> (f32, u32)

Converts to an f32 and an exponent, rounding towards zero.

The returned f32 is in the range 0.5 ≤ x < 1. If the value is zero, (0.0, 0) is returned.

Examples

use rug::Integer;
let zero = Integer::new();
let (d0, exp0) = zero.to_f32_exp();
assert_eq!((d0, exp0), (0.0, 0));
let fifteen = Integer::from(15);
let (d15, exp15) = fifteen.to_f32_exp();
assert_eq!((d15, exp15), (15.0 / 16.0, 4));

fn to_f64_exp(&self) -> (f64, u32)

Converts to an f64 and an exponent, rounding towards zero.

The returned f64 is in the range 0.5 ≤ x < 1. If the value is zero, (0.0, 0) is returned.

Examples

use rug::Integer;
let zero = Integer::new();
let (d0, exp0) = zero.to_f64_exp();
assert_eq!((d0, exp0), (0.0, 0));
let fifteen = Integer::from(15);
let (d15, exp15) = fifteen.to_f64_exp();
assert_eq!((d15, exp15), (15.0 / 16.0, 4));

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

Returns a string representation of the number for the specified radix.

Examples

use rug::{Assign, Integer};
let mut i = Integer::new();
assert_eq!(i.to_string_radix(10), "0");
i.assign(-10);
assert_eq!(i.to_string_radix(16), "-a");
i.assign(0x1234cdef);
assert_eq!(i.to_string_radix(4), "102031030313233");
i.assign_str_radix("1234567890aAbBcCdDeEfF", 16).unwrap();
assert_eq!(i.to_string_radix(16), "1234567890aabbccddeeff");

Panics

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

fn as_neg(&self) -> BorrowInteger

Borrows a negated copy of the Integer.

The returned object implements Deref with an Integer target. This method performs a shallow copy and negates it, and negation does not change the allocated data.

Examples

use rug::Integer;
let i = Integer::from(42);
let neg_i = i.as_neg();
assert_eq!(*neg_i, -42);
// methods taking &self can be used on the returned object
let reneg_i = neg_i.as_neg();
assert_eq!(*reneg_i, 42);
assert_eq!(*reneg_i, i);

fn as_abs(&self) -> BorrowInteger

Borrows an absolute copy of the Integer.

The returned object implements Deref with an Integer target. This method performs a shallow copy and possibly negates it, and negation does not change the allocated data.

Examples

use rug::Integer;
let i = Integer::from(-42);
let abs_i = i.as_abs();
assert_eq!(*abs_i, 42);
// methods taking &self can be used on the returned object
let reabs_i = abs_i.as_abs();
assert_eq!(*reabs_i, 42);
assert_eq!(*reabs_i, *abs_i);

fn is_even(&self) -> bool

Returns true if the number is even.

Examples

use rug::Integer;
assert!(!(Integer::from(13).is_even()));
assert!(Integer::from(-14).is_even());

fn is_odd(&self) -> bool

Returns true if the number is odd.

Examples

use rug::Integer;
assert!(Integer::from(13).is_odd());
assert!(!Integer::from(-14).is_odd());

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

Returns true if the number is divisible by divisor. Unlike other division functions, divisor can be zero.

Examples

use rug::Integer;
let i = Integer::from(230);
assert!(i.is_divisible(&Integer::from(10)));
assert!(!i.is_divisible(&Integer::from(100)));
assert!(!i.is_divisible(&Integer::new()));

fn is_divisible_u(&self, divisor: u32) -> bool

Returns true if the number is divisible by divisor. Unlike other division functions, divisor can be zero.

Examples

use rug::Integer;
let i = Integer::from(230);
assert!(i.is_divisible_u(23));
assert!(!i.is_divisible_u(100));
assert!(!i.is_divisible_u(0));

fn is_divisible_2pow(&self, b: u32) -> bool

Returns true if the number is divisible by 2^b.

Examples

use rug::Integer;
let i = Integer::from(15 << 17);
assert!(i.is_divisible_2pow(16));
assert!(i.is_divisible_2pow(17));
assert!(!i.is_divisible_2pow(18));

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

Returns true if the number is congruent to c mod divisor, that is, if there exists a q such that self = c + q × divisor. Unlike other division functions, divisor can be zero.

Examples

use rug::Integer;
let n = Integer::from(105);
let divisor = Integer::from(10);
assert!(n.is_congruent(&Integer::from(5), &divisor));
assert!(n.is_congruent(&Integer::from(25), &divisor));
assert!(!n.is_congruent(&Integer::from(7), &divisor));
// n is congruent to itself if divisor is 0
assert!(n.is_congruent(&n, &Integer::from(0)));

fn is_congruent_u(&self, c: u32, divisor: u32) -> bool

Returns true if the number is congruent to c mod divisor, that is, if there exists a q such that self = c + q × divisor. Unlike other division functions, divisor can be zero.

Examples

use rug::Integer;
let n = Integer::from(105);
assert!(n.is_congruent_u(3335, 10));
assert!(!n.is_congruent_u(107, 10));
// n is congruent to itself if divisor is 0
assert!(n.is_congruent_u(105, 0));

fn is_congruent_2pow(&self, c: &Integer, b: u32) -> bool

Returns true if the number is congruent to c mod 2^b, that is, if there exists a q such that self = c + q × 2^b.

Examples

use rug::Integer;
let n = Integer::from(13 << 17 | 21);
assert!(n.is_congruent_2pow(&Integer::from(7 << 17 | 21), 17));
assert!(!n.is_congruent_2pow(&Integer::from(13 << 17 | 22), 17));

fn is_perfect_power(&self) -> bool

Returns true if the number is a perfect power.

Examples

use rug::{Assign, Integer};
// 0 is 0 to the power of anything
let mut i = Integer::from(0);
assert!(i.is_perfect_power());
// 243 is 3 to the power of 5
i.assign(243);
assert!(i.is_perfect_power());
// 10 is not a perfect power
i.assign(10);
assert!(!i.is_perfect_power());

fn is_perfect_square(&self) -> bool

Returns true if the number is a perfect square.

Examples

use rug::{Assign, Integer};
let mut i = Integer::from(1);
assert!(i.is_perfect_square());
i.assign(9);
assert!(i.is_perfect_square());
i.assign(15);
assert!(!i.is_perfect_square());

fn cmp0(&self) -> Ordering

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

Examples

use rug::Integer;
use std::cmp::Ordering;
assert_eq!(Integer::from(-5).cmp0(), Ordering::Less);
assert_eq!(Integer::from(0).cmp0(), Ordering::Equal);
assert_eq!(Integer::from(5).cmp0(), Ordering::Greater);

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

Compares the absolute values.

Examples

use rug::Integer;
use std::cmp::Ordering;
let a = Integer::from(-10);
let b = Integer::from(4);
assert_eq!(a.cmp(&b), Ordering::Less);
assert_eq!(a.cmp_abs(&b), Ordering::Greater);

fn significant_bits(&self) -> u32

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

Examples

use rug::Integer;

assert_eq!(Integer::from(0).significant_bits(), 0);
assert_eq!(Integer::from(1).significant_bits(), 1);
assert_eq!(Integer::from(-1).significant_bits(), 1);
assert_eq!(Integer::from(4).significant_bits(), 3);
assert_eq!(Integer::from(-4).significant_bits(), 3);
assert_eq!(Integer::from(7).significant_bits(), 3);
assert_eq!(Integer::from(-7).significant_bits(), 3);

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

Returns the number of one bits if the value ≥ 0.

Examples

use rug::Integer;
assert_eq!(Integer::from(0).count_ones(), Some(0));
assert_eq!(Integer::from(15).count_ones(), Some(4));
assert_eq!(Integer::from(-1).count_ones(), None);

fn count_zeros(&self) -> Option<u32>

Returns the number of zero bits if the value < 0.

Examples

use rug::Integer;
assert_eq!(Integer::from(0).count_zeros(), None);
assert_eq!(Integer::from(1).count_zeros(), None);
assert_eq!(Integer::from(-1).count_zeros(), Some(0));
assert_eq!(Integer::from(-2).count_zeros(), Some(1));
assert_eq!(Integer::from(-7).count_zeros(), Some(2));
assert_eq!(Integer::from(-8).count_zeros(), Some(3));

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

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

use rug::Integer;
// -2 is ...11111110
assert_eq!(Integer::from(-2).find_zero(0), Some(0));
assert_eq!(Integer::from(-2).find_zero(1), None);
// 15 is ...00001111
assert_eq!(Integer::from(15).find_zero(0), Some(4));
assert_eq!(Integer::from(15).find_zero(20), Some(20));

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

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

use rug::Integer;
// 1 is ...00000001
assert_eq!(Integer::from(1).find_one(0), Some(0));
assert_eq!(Integer::from(1).find_one(1), None);
// -16 is ...11110000
assert_eq!(Integer::from(-16).find_one(0), Some(4));
assert_eq!(Integer::from(-16).find_one(20), Some(20));

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

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

Examples

use rug::Integer;
let i = Integer::from(0b100101);
assert!(i.get_bit(0));
assert!(!i.get_bit(1));
assert!(i.get_bit(5));
let neg = Integer::from(-1);
assert!(neg.get_bit(1000));

fn hamming_dist(&self, other: &Integer) -> Option<u32>

Retuns the Hamming distance if the two numbers have the same sign.

The Hamming distance is the number of different bits.

Examples

use rug::Integer;
let i = Integer::from(-1);
assert_eq!(Integer::from(0).hamming_dist(&i), None);
assert_eq!(Integer::from(-1).hamming_dist(&i), Some(0));
// -1 is ...11111111 and -13 is ...11110011
assert_eq!(Integer::from(-13).hamming_dist(&i), Some(2));

fn abs(self) -> Integer

Computes the absolute value.

Examples

use rug::Integer;
let i = Integer::from(-100);
let abs = i.abs();
assert_eq!(abs, 100);

fn abs_ref(&self) -> AbsRef

Computes the absolute value.

Examples

use rug::Integer;
let i = Integer::from(-100);
let r = i.abs_ref();
let abs = Integer::from(r);
assert_eq!(abs, 100);
assert_eq!(i, -100);

fn clamp<'a, Min, Max>(self, min: &'a Min, max: &'a Max) -> Integer where
    Integer: PartialOrd<Min> + PartialOrd<Max> + Assign<&'a Min> + Assign<&'a Max>, 

Clamps the value within the specified bounds.

Examples

use rug::Integer;
let min = -10;
let max = 10;
let too_small = Integer::from(-100);
let clamped1 = too_small.clamp(&min, &max);
assert_eq!(clamped1, -10);
let in_range = Integer::from(3);
let clamped2 = in_range.clamp(&min, &max);
assert_eq!(clamped2, 3);

Panics

Panics if the maximum value is less than the minimum value.

fn clamp_ref<'a, Min, Max>(
    &'a self,
    min: &'a Min,
    max: &'a Max
) -> ClampRef<'a, Min, Max> where
    Integer: PartialOrd<Min> + PartialOrd<Max> + Assign<&'a Min> + Assign<&'a Max>, 

Clamps the value within the specified bounds.

Examples

use rug::Integer;
let min = -10;
let max = 10;
let too_small = Integer::from(-100);
let r1 = too_small.clamp_ref(&min, &max);
let clamped1 = Integer::from(r1);
assert_eq!(clamped1, -10);
let in_range = Integer::from(3);
let r2 = in_range.clamp_ref(&min, &max);
let clamped2 = Integer::from(r2);
assert_eq!(clamped2, 3);

Panics

Panics if the maximum value is less than the minimum value.

fn keep_bits(self, n: u32) -> Integer

Keeps the n least significant bits only.

Examples

use rug::Integer;
let i = Integer::from(-1);
let keep_8 = i.keep_bits(8);
assert_eq!(keep_8, 0xff);

fn keep_bits_ref(&self, n: u32) -> KeepBitsRef

Keeps the n least significant bits only.

Examples

use rug::Integer;
let i = Integer::from(-1);
let r = i.keep_bits_ref(8);
let eight_bits = Integer::from(r);
assert_eq!(eight_bits, 0xff);

fn next_power_of_two(self) -> Integer

Finds the next power of two, or 1 if the number ≤ 0.

Examples

use rug::Integer;
let i = Integer::from(-3).next_power_of_two();
assert_eq!(i, 1);
let i = Integer::from(4).next_power_of_two();
assert_eq!(i, 4);
let i = Integer::from(7).next_power_of_two();
assert_eq!(i, 8);

fn next_power_of_two_ref(&self) -> NextPowerTwoRef

Finds the next power of two, or 1 if the number ≤ 0.

Examples

use rug::Integer;
let i = Integer::from(53);
let r = i.next_power_of_two_ref();
let next = Integer::from(r);
assert_eq!(next, 64);

fn div_rem(self, divisor: Integer) -> (Integer, Integer)

Performs a division producing both the quotient and remainder.

The remainder has the same sign as the dividend.

Examples

use rug::Integer;
let dividend = Integer::from(23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem(divisor);
assert_eq!(quotient, -2);
assert_eq!(rem, 3);

Panics

Panics if divisor is zero.

fn div_rem_ref<'a>(&'a self, divisor: &'a Integer) -> DivRemRef<'a>

Performs a division producing both the quotient and remainder.

The remainder has the same sign as the dividend.

Examples

use rug::Integer;
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let r = dividend.div_rem_ref(&divisor);
let (quotient, rem) = <(Integer, Integer)>::from(r);
assert_eq!(quotient, 2);
assert_eq!(rem, -3);

fn div_rem_ceil(self, divisor: Integer) -> (Integer, Integer)

Performs a division producing both the quotient and remainder, with the quotient rounded up.

The sign of the remainder is the opposite of the divisor’s sign.

Examples

use rug::Integer;
let dividend = Integer::from(23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_ceil(divisor);
assert_eq!(quotient, -2);
assert_eq!(rem, 3);

Panics

Panics if divisor is zero.

fn div_rem_ceil_ref<'a>(&'a self, divisor: &'a Integer) -> DivRemCeilRef<'a>

Performs a division producing both the quotient and remainder, with the quotient rounded up.

The sign of the remainder is the opposite of the divisor’s sign.

Examples

use rug::Integer;
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let r = dividend.div_rem_ceil_ref(&divisor);
let (quotient, rem) = <(Integer, Integer)>::from(r);
assert_eq!(quotient, 3);
assert_eq!(rem, 7);

fn div_rem_floor(self, divisor: Integer) -> (Integer, Integer)

Performs a division producing both the quotient and remainder, with the quotient rounded down.

The remainder has the same sign as the divisor.

Examples

use rug::Integer;
let dividend = Integer::from(23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_floor(divisor);
assert_eq!(quotient, -3);
assert_eq!(rem, -7);

Panics

Panics if divisor is zero.

fn div_rem_floor_ref<'a>(&'a self, divisor: &'a Integer) -> DivRemFloorRef<'a>

Performs a division producing both the quotient and remainder, with the quotient rounded down.

The remainder has the same sign as the divisor.

Examples

use rug::Integer;
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let r = dividend.div_rem_floor_ref(&divisor);
let (quotient, rem) = <(Integer, Integer)>::from(r);
assert_eq!(quotient, 2);
assert_eq!(rem, -3);

fn div_rem_euc(self, divisor: Integer) -> (Integer, Integer)

Performs Euclidean division producing both the quotient and remainder, with a positive remainder.

Examples

use rug::Integer;
let dividend = Integer::from(23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_euc(divisor);
assert_eq!(quotient, -2);
assert_eq!(rem, 3);

Panics

Panics if divisor is zero.

fn div_rem_euc_ref<'a>(&'a self, divisor: &'a Integer) -> DivRemEucRef<'a>

Performs Euclidan division producing both the quotient and remainder, with a positive remainder.

Examples

use rug::Integer;
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let r = dividend.div_rem_euc_ref(&divisor);
let (quotient, rem) = <(Integer, Integer)>::from(r);
assert_eq!(quotient, 3);
assert_eq!(rem, 7);

fn mod_u(&self, modulo: u32) -> u32

Returns the modulo, or the remainder of Euclidean division by a u32.

The result is always zero or positive.

Examples

use rug::Integer;
let pos = Integer::from(23);
assert_eq!(pos.mod_u(1), 0);
assert_eq!(pos.mod_u(10), 3);
assert_eq!(pos.mod_u(100), 23);
let neg = Integer::from(-23);
assert_eq!(neg.mod_u(1), 0);
assert_eq!(neg.mod_u(10), 7);
assert_eq!(neg.mod_u(100), 77);

Panics

Panics if modulo is zero.

fn div_exact(self, divisor: &Integer) -> Integer

Performs an exact division.

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

Examples

use rug::Integer;
let i = Integer::from(12345 * 54321);
let quotient = i.div_exact(&Integer::from(12345));
assert_eq!(quotient, 54321);

Panics

Panics if divisor is zero.

fn div_exact_ref<'a>(&'a self, divisor: &'a Integer) -> DivExactRef<'a>

Performs an exact division.

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

Examples

use rug::Integer;
let i = Integer::from(12345 * 54321);
let divisor = Integer::from(12345);
let r = i.div_exact_ref(&divisor);
let quotient = Integer::from(r);
assert_eq!(quotient, 54321);

fn div_exact_u(self, divisor: u32) -> Integer

Performs an exact division.

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

Examples

use rug::Integer;
let i = Integer::from(12345 * 54321);
let q = i.div_exact_u(12345);
assert_eq!(q, 54321);

Panics

Panics if divisor is zero.

fn div_exact_u_ref(&self, divisor: u32) -> DivExactURef

Performs an exact division.

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

Examples

use rug::Integer;
let i = Integer::from(12345 * 54321);
let r = i.div_exact_u_ref(12345);
assert_eq!(Integer::from(r), 54321);

fn invert(self, modulo: &Integer) -> Result<Integer, Integer>

Finds the inverse modulo modulo and returns Ok(inverse) if it exists, or Err(unchanged) if the inverse does not exist.

Examples

use rug::Integer;
let n = Integer::from(2);
// Modulo 4, 2 has no inverse: there is no x such that 2 * x = 1.
let inv_mod_4 = match n.invert(&Integer::from(4)) {
    Ok(_) => unreachable!(),
    Err(unchanged) => unchanged,
};
// no inverse exists, so value is unchanged
assert_eq!(inv_mod_4, 2);
let n = inv_mod_4;
// Modulo 5, the inverse of 2 is 3, as 2 * 3 = 1.
let inv_mod_5 = match n.invert(&Integer::from(5)) {
    Ok(inverse) => inverse,
    Err(_) => unreachable!(),
};
assert_eq!(inv_mod_5, 3);

Panics

Panics if modulo is zero.

fn invert_ref<'a>(&'a self, modulo: &'a Integer) -> InvertRef<'a>

Finds the inverse modulo modulo if an inverse exists.

Examples

use rug::{Assign, Integer};
let n = Integer::from(2);
// Modulo 4, 2 has no inverse, there is no x such that 2 * x = 1.
// For this conversion, if no inverse exists, the Integer
// created is left unchanged as 0.
let mut ans = Result::from(n.invert_ref(&Integer::from(4)));
match ans {
    Ok(_) => unreachable!(),
    Err(ref unchanged) => assert_eq!(*unchanged, 0),
}
// Modulo 5, the inverse of 2 is 3, as 2 * 3 = 1.
ans.assign(n.invert_ref(&Integer::from(5)));
match ans {
    Ok(ref inverse) => assert_eq!(*inverse, 3),
    Err(_) => unreachable!(),
};

fn pow_mod(
    self,
    exponent: &Integer,
    modulo: &Integer
) -> Result<Integer, Integer>

Raises a number to the power of exponent modulo modulo and returns Ok(power) if an answer exists, or Err(unchanged) if it does not.

If exponent is negative, then the number must have an inverse modulo modulo for an answer to exist.

Examples

When the exponent is positive, an answer always exists.

use rug::Integer;
// 7 ^ 5 = 16807
let n = Integer::from(7);
let e = Integer::from(5);
let m = Integer::from(1000);
let power = match n.pow_mod(&e, &m) {
    Ok(power) => power,
    Err(_) => unreachable!(),
};
assert_eq!(power, 807);

When the exponent is negative, an answer exists if an inverse exists.

use rug::Integer;
// 7 * 143 modulo 1000 = 1, so 7 has an inverse 143.
// 7 ^ -5 modulo 1000 = 143 ^ 5 modulo 1000 = 943.
let n = Integer::from(7);
let e = Integer::from(-5);
let m = Integer::from(1000);
let power = match n.pow_mod(&e, &m) {
    Ok(power) => power,
    Err(_) => unreachable!(),
};
assert_eq!(power, 943);

fn pow_mod_ref<'a>(
    &'a self,
    exponent: &'a Integer,
    modulo: &'a Integer
) -> PowModRef<'a>

Raises a number to the power of exponent modulo modulo if an answer exists.

If exponent is negative, then the number must have an inverse modulo modulo for an answer to exist.

Examples

use rug::{Assign, Integer};
// Modulo 1000, 2 has no inverse: there is no x such that 2 * x =  1.
let two = Integer::from(2);
let e = Integer::from(-5);
let m = Integer::from(1000);
let mut ans = Result::from(two.pow_mod_ref(&e, &m));
match ans {
    Ok(_) => unreachable!(),
    Err(ref unchanged) => assert_eq!(*unchanged, 0),
}
// 7 * 143 modulo 1000 = 1, so 7 has an inverse 143.
// 7 ^ -5 modulo 1000 = 143 ^ 5 modulo 1000 = 943.
let seven = Integer::from(7);
ans.assign(seven.pow_mod_ref(&e, &m));
match ans {
    Ok(ref power) => assert_eq!(*power, 943),
    Err(_) => unreachable!(),
}

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

Computes the nth root and truncates the result.

Examples

use rug::Integer;
let i = Integer::from(1004);
let root = i.root(3);
assert_eq!(root, 10);

fn root_ref(&self, n: u32) -> RootRef

Computes the nth root and truncates the result.

Examples

use rug::Integer;
let i = Integer::from(1004);
assert_eq!(Integer::from(i.root_ref(3)), 10);

fn root_rem(self, remainder: Integer, n: u32) -> (Integer, Integer)

Computes the nth root and returns the truncated root and the remainder.

The remainder is the original number minus the truncated root raised to the power of n.

The initial value of remainder is ignored.

Examples

use rug::Integer;
let i = Integer::from(1004);
let (root, rem) = i.root_rem(Integer::new(), 3);
assert_eq!(root, 10);
assert_eq!(rem, 4);

fn root_rem_ref(&self, n: u32) -> RootRemRef

Computes the nth root and returns the truncated root and the remainder.

The remainder is the original number minus the truncated root raised to the power of n.

Examples

use rug::{Assign, Integer};
let i = Integer::from(1004);
let r = i.root_rem_ref(3);
let mut root = Integer::new();
let mut rem = Integer::new();
(&mut root, &mut rem).assign(r);
assert_eq!(root, 10);
assert_eq!(rem, 4);
let (other_root, other_rem) = <(Integer, Integer)>::from(r);
assert_eq!(other_root, 10);
assert_eq!(other_rem, 4);

fn sqrt(self) -> Integer

Computes the square root and truncates the result.

Examples

use rug::Integer;
let i = Integer::from(104);
let sqrt = i.sqrt();
assert_eq!(sqrt, 10);

fn sqrt_ref(&self) -> SqrtRef

Computes the square root and truncates the result.

Examples

use rug::Integer;
let i = Integer::from(104);
assert_eq!(Integer::from(i.sqrt_ref()), 10);

fn sqrt_rem(self, remainder: Integer) -> (Integer, Integer)

Computes the square root and the remainder.

The remainder is the original number minus the truncated root squared.

The initial value of remainder is ignored.

Examples

use rug::Integer;
let i = Integer::from(104);
let (sqrt, rem) = i.sqrt_rem(Integer::new());
assert_eq!(sqrt, 10);
assert_eq!(rem, 4);

fn sqrt_rem_ref(&self) -> SqrtRemRef

Computes the square root and the remainder.

The remainder is the original number minus the truncated root squared.

Examples

use rug::{Assign, Integer};
let i = Integer::from(104);
let r = i.sqrt_rem_ref();
let mut sqrt = Integer::new();
let mut rem = Integer::new();
(&mut sqrt, &mut rem).assign(r);
assert_eq!(sqrt, 10);
assert_eq!(rem, 4);
let (other_sqrt, other_rem) = <(Integer, Integer)>::from(r);
assert_eq!(other_sqrt, 10);
assert_eq!(other_rem, 4);

fn is_probably_prime(&self, reps: u32) -> IsPrime

Determines wheter a number is prime using some trial divisions, then reps Miller-Rabin probabilistic primality tests.

Examples

use rug::Integer;
use rug::integer::IsPrime;
let no = Integer::from(163 * 4003);
assert_eq!(no.is_probably_prime(15), IsPrime::No);
let yes = Integer::from(21_751);
assert_eq!(yes.is_probably_prime(15), IsPrime::Yes);
// 817_504_243 is actually a prime.
let probably = Integer::from(817_504_243);
assert_eq!(probably.is_probably_prime(15), IsPrime::Probably);

fn next_prime(self) -> Integer

Identifies primes using a probabilistic algorithm; the chance of a composite passing will be extremely small.

Examples

use rug::Integer;
let i = Integer::from(800_000_000);
let prime = i.next_prime();
assert_eq!(prime, 800_000_011);

fn next_prime_ref(&self) -> NextPrimeRef

Identifies primes using a probabilistic algorithm; the chance of a composite passing will be extremely small.

Examples

use rug::Integer;
let i = Integer::from(800_000_000);
let r = i.next_prime_ref();
let prime = Integer::from(r);
assert_eq!(prime, 800_000_011);

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

Finds the greatest common divisor.

The result is always positive except when both inputs are zero.

Examples

use rug::{Assign, Integer};
let a = Integer::new();
let mut b = Integer::new();
// gcd of 0, 0 is 0
let gcd1 = a.gcd(&b);
assert_eq!(gcd1, 0);
b.assign(10);
// gcd of 0, 10 is 10
let gcd2 = gcd1.gcd(&b);
assert_eq!(gcd2, 10);
b.assign(25);
// gcd of 10, 25 is 5
let gcd3 = gcd2.gcd(&b);
assert_eq!(gcd3, 5);

fn gcd_ref<'a>(&'a self, other: &'a Integer) -> GcdRef<'a>

Finds the greatest common divisor.

The result is always positive except when both inputs are zero.

Examples

use rug::Integer;
let a = Integer::from(100);
let b = Integer::from(125);
let r = a.gcd_ref(&b);
// gcd of 100, 125 is 25
assert_eq!(Integer::from(r), 25);

fn gcd_coeffs(self, other: Integer, rop: Integer) -> (Integer, Integer, Integer)

Finds the greatest common divisor (GCD) of the two inputs (self and other), and two multiplication coefficients to obtain the GCD from the two inputs.

The GCD is always positive except when both inputs are zero. If the inputs are a and b, the GCD is g, and the multiplication coefficients are s and t, then

a × s + b × t = g

The values s and t are chosen such that normally, |s| < |b| / (2g) and |t| < |a| / (2g), and these relations define s and t uniquely. There are a few exceptional cases:

• If |a| = |b|, then s = 0, t = sgn(b).
• Otherwise, if b = 0 or |b| = 2g, then s = sgn(a), and if a = 0 or |a| = 2g, then t = sgn(b).

Examples

use rug::Integer;
let a = Integer::from(4);
let b = Integer::from(6);
let (g, s, t) = a.gcd_coeffs(b, Integer::new());
assert_eq!(g, 2);
assert_eq!(s, -1);
assert_eq!(t, 1);

fn gcd_coeffs_ref<'a>(&'a self, other: &'a Integer) -> GcdCoeffsRef<'a>

Finds the greatest common divisor (GCD) of the two inputs (self and other), and two multiplication coefficients to obtain the GCD from the two inputs.

The GCD is always positive except when both inputs are zero. If the inputs are a and b, the GCD is g, and the multiplication coefficients are s and t, then

a × s + b × t = g

The values s and t are chosen such that normally, |s| < |b| / (2g) and |t| < |a| / (2g), and these relations define s and t uniquely. There are a few exceptional cases:

• If |a| = |b|, then s = 0, t = sgn(b).
• Otherwise, if b = 0 or |b| = 2g, then s = sgn(a), and if a = 0 or |a| = 2g, then t = sgn(b).

Examples

use rug::{Assign, Integer};
let a = Integer::from(4);
let b = Integer::from(6);
let r = a.gcd_coeffs_ref(&b);
let mut g = Integer::new();
let mut s = Integer::new();
let mut t = Integer::new();
(&mut g, &mut s, &mut t).assign(r);
assert_eq!(a, 4);
assert_eq!(b, 6);
assert_eq!(g, 2);
assert_eq!(s, -1);
assert_eq!(t, 1);

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

Finds the least common multiple.

The result is always positive except when one or both inputs are zero.

Examples

use rug::{Assign, Integer};
let a = Integer::from(10);
let mut b = Integer::from(25);
// lcm of 10, 25 is 50
let lcm1 = a.lcm(&b);
assert_eq!(lcm1, 50);
b.assign(0);
// lcm of 50, 0 is 0
let lcm2 = lcm1.lcm(&b);
assert_eq!(lcm2, 0);

fn lcm_ref<'a>(&'a self, other: &'a Integer) -> LcmRef<'a>

Finds the least common multiple.

The result is always positive except when one or both inputs are zero.

Examples

use rug::Integer;
let a = Integer::from(100);
let b = Integer::from(125);
let r = a.lcm_ref(&b);
// lcm of 100, 125 is 500
assert_eq!(Integer::from(r), 500);

fn jacobi(&self, n: &Integer) -> i32

Calculates the Jacobi symbol (self/n).

Examples

use rug::{Assign, Integer};
let m = Integer::from(10);
let mut n = Integer::from(13);
assert_eq!(m.jacobi(&n), 1);
n.assign(15);
assert_eq!(m.jacobi(&n), 0);
n.assign(17);
assert_eq!(m.jacobi(&n), -1);

fn legendre(&self, p: &Integer) -> i32

Calculates the Legendre symbol (self/p).

Examples

use rug::{Assign, Integer};
let a = Integer::from(5);
let mut p = Integer::from(7);
assert_eq!(a.legendre(&p), -1);
p.assign(11);
assert_eq!(a.legendre(&p), 1);

fn kronecker(&self, n: &Integer) -> i32

Calculates the Jacobi symbol (self/n) with the Kronecker extension.

Examples

use rug::{Assign, Integer};
let k = Integer::from(3);
let mut n = Integer::from(16);
assert_eq!(k.kronecker(&n), 1);
n.assign(17);
assert_eq!(k.kronecker(&n), -1);
n.assign(18);
assert_eq!(k.kronecker(&n), 0);

fn remove_factor(self, factor: &Integer) -> (Integer, u32)

Removes all occurrences of factor, and returns the number of occurrences removed.

Examples

use rug::Integer;
let mut i = Integer::new();
i.assign_u_pow_u(13, 50);
i *= 1000;
let (remove, count) = i.remove_factor(&Integer::from(13));
assert_eq!(remove, 1000);
assert_eq!(count, 50);

fn remove_factor_ref<'a>(&'a self, factor: &'a Integer) -> RemoveFactorRef<'a>

Removes all occurrences of factor, and counts the number of occurrences removed.

Examples

use rug::{Assign, Integer};
let mut i = Integer::new();
i.assign_u_pow_u(13, 50);
i *= 1000;
let factor = Integer::from(13);
let r = i.remove_factor_ref(&factor);
let (mut j, mut count) = (Integer::new(), 0);
(&mut j, &mut count).assign(r);
assert_eq!(count, 50);
assert_eq!(j, 1000);

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

Computes the binomial coefficient over k.

Examples

use rug::Integer;
// 7 choose 2 is 21
let i = Integer::from(7);
let bin = i.binomial(2);
assert_eq!(bin, 21);

fn binomial_ref(&self, k: u32) -> BinomialRef

Computes the binomial coefficient over k.

Examples

use rug::Integer;
// 7 choose 2 is 21
let i = Integer::from(7);
assert_eq!(Integer::from(i.binomial_ref(2)), 21);

fn random_below(self, rng: &mut RandState) -> Integer

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

Examples

use rug::Integer;
use rug::rand::RandState;
let mut rand = RandState::new();
let i = Integer::from(15);
let below = i.random_below(&mut rand);
println!("0 ≤ {} < 15", below);
assert!(below < 15);

Panics

Panics if the boundary value is less than or equal to zero.

Trait Implementations

impl Default for SmallInteger

fn default() -> SmallInteger

Returns the "default value" for a type.

impl Deref for SmallInteger

type Target = Integer

The resulting type after dereferencing.

fn deref(&self) -> &Integer

Dereferences the value.

impl<T> From<T> for SmallInteger where
    SmallInteger: Assign<T>, 

fn from(val: T) -> SmallInteger

Performs the conversion.

impl Assign<i32> for SmallInteger

fn assign(&mut self, val: i32)

Peforms the assignement.

impl Assign<i64> for SmallInteger

fn assign(&mut self, val: i64)

Peforms the assignement.

impl Assign<u32> for SmallInteger

fn assign(&mut self, val: u32)

Peforms the assignement.

impl Assign<u64> for SmallInteger

fn assign(&mut self, val: u64)

Peforms the assignement.