logo

Struct rug::Integer

source · []
#[repr(transparent)]
pub struct Integer { /* private fields */ }
Expand description

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 a 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 rug::{Assign, Integer};
// Create an integer initialized as zero.
let mut int = Integer::new();
assert_eq!(int, 0);
assert_eq!(int.to_u32(), Some(0));
int.assign(-14);
assert_eq!(int, -14);
assert_eq!(int.to_u32(), None);
assert_eq!(int.to_i32(), Some(-14));

Arithmetic operations with mixed arbitrary and primitive types are allowed. Note that in the following example, there is only one allocation. The Integer instance is moved into the shift operation so that the result can be stored in the same instance, then that result is similarly consumed by the addition operation.

use rug::Integer;
let mut a = Integer::from(0xc);
a = (a << 80) + 0xffee;
assert_eq!(a.to_string_radix(16), "c0000000000000000ffee");
//                                 ↑   ↑   ↑   ↑   ↑   ↑
//                                80  64  48  32  16   0

Bitwise operations on Integer values behave as if the value uses a two’s-complement representation.

use rug::Integer;

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

let a = Integer::from(0xf00d);
// -1 is all ones in two’s complement
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_eq!(all_ones_xor_a, complement_a);
assert_eq!(complement_a, -0xf00e);
assert_eq!(format!("{:x}", complement_a), "-f00e");

To initialize a large Integer that does not fit in a primitive type, you can parse a string.

use rug::Integer;
let s1 = "123456789012345678901234567890";
let i1 = s1.parse::<Integer>().unwrap();
assert_eq!(i1.significant_bits(), 97);
let s2 = "ffff0000ffff0000ffff0000ffff0000ffff0000";
let i2 = Integer::from_str_radix(s2, 16).unwrap();
assert_eq!(i2.significant_bits(), 160);
assert_eq!(i2.count_ones(), Some(80));

Operations on two borrowed Integer values result in an incomplete-computation value that has to be assigned to a new Integer value.

use rug::Integer;
let a = Integer::from(10);
let b = Integer::from(3);
let a_b_ref = &a + &b;
let a_b = Integer::from(a_b_ref);
assert_eq!(a_b, 13);

As a special case, when an incomplete-computation value is obtained from multiplying two Integer references, it can be added to or subtracted from another Integer (or reference). This can be useful for multiply-accumulate operations.

use rug::Integer;
let mut acc = Integer::from(100);
let m1 = Integer::from(3);
let m2 = Integer::from(7);
// 100 + 3 × 7 = 121
acc += &m1 * &m2;
assert_eq!(acc, 121);
let other = Integer::from(2000);
// Do not consume any values here:
// 2000 - 3 × 7 = 1979
let sub = Integer::from(&other - &m1 * &m2);
assert_eq!(sub, 1979);

The Integer type supports various functions. Most methods have three versions:

  1. The first method consumes the operand.
  2. The second method has a “_mut” suffix and mutates the operand.
  3. The third method has a “_ref” suffix and borrows the operand. The returned item is an incomplete-computation value that can be assigned to an Integer.
use rug::Integer;

// 1. consume the operand
let a = Integer::from(-15);
let abs_a = a.abs();
assert_eq!(abs_a, 15);

// 2. mutate the operand
let mut b = Integer::from(-16);
b.abs_mut();
assert_eq!(b, 16);

// 3. borrow the operand
let c = Integer::from(-17);
let r = c.abs_ref();
let abs_c = Integer::from(r);
assert_eq!(abs_c, 17);
// c was not consumed
assert_eq!(c, -17);

Implementations

Zero.

Examples
use rug::Integer;
assert_eq!(Integer::ZERO, 0);

Constructs a new arbitrary-precision Integer with value 0.

The created Integer will have no allocated memory yet.

Examples
use rug::Integer;
let i = Integer::new();
assert_eq!(i, 0);

Constructs a new arbitrary-precision Integer with at least the specified capacity.

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

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

Reserves capacity for at least additional more bits in the Integer.

If the integer already has enough excess capacity, this function does nothing.

Examples
use rug::Integer;
// 0x2000_0000 needs 30 bits.
let mut i = Integer::from(0x2000_0000);
assert_eq!(i.significant_bits(), 30);
i.reserve(290);
let capacity = i.capacity();
assert!(capacity >= 320);
i.reserve(0);
assert_eq!(i.capacity(), capacity);
i.reserve(291);
assert!(i.capacity() >= 321);

Shrinks the capacity of the Integer as much as possible.

The capacity can still be larger than the number of significant bits.

Examples
use rug::Integer;
// let i be 100 bits wide
let mut i = Integer::from_str_radix("fffff12345678901234567890", 16)
    .unwrap();
assert_eq!(i.significant_bits(), 100);
assert!(i.capacity() >= 100);
i >>= 80;
i.shrink_to_fit();
assert!(i.capacity() >= 20);

Shrinks the capacity of the Integer with a lower bound in bits.

The capacity will remain at least as large as both the current number of siginificant bits and the supplied value.

If the current capacity is less than the lower limit, this method has no effect.

Examples
use rug::Integer;
// let i be 100 bits wide
let mut i = Integer::from_str_radix("fffff12345678901234567890", 16)
    .unwrap();
assert_eq!(i.significant_bits(), 100);
assert!(i.capacity() >= 100);
i >>= 80;
i.shrink_to(50);
assert!(i.capacity() >= 50);
i.shrink_to(0);
assert!(i.capacity() >= 20);

Creates an Integer from an initialized GMP integer.

Safety
  • The function must not be used to create a constant Integer, though it can be used to create a static Integer. This is because constant values are copied on use, leading to undefined behavior when they are dropped.
  • The value must be initialized.
  • The mpz_t type can be considered as a kind of pointer, so there can be multiple copies of it. Since this function takes over ownership, no other copies of the passed value should exist.
Examples
use core::mem::MaybeUninit;
use gmp_mpfr_sys::gmp;
use rug::Integer;
let i = unsafe {
    let mut z = MaybeUninit::uninit();
    gmp::mpz_init_set_ui(z.as_mut_ptr(), 15);
    let z = z.assume_init();
    // z is initialized and unique
    Integer::from_raw(z)
};
assert_eq!(i, 15);
// since i is an Integer now, deallocation is automatic

This can be used to create a static Integer using MPZ_ROINIT_N to initialize the raw value. See the GMP documentation for details.

use gmp_mpfr_sys::gmp::{self, limb_t, mpz_t};
use rug::Integer;
const LIMBS: [limb_t; 2] = [123, 456];
const MPZ: mpz_t =
    unsafe { gmp::MPZ_ROINIT_N(LIMBS.as_ptr() as *mut limb_t, -2) };
// Must *not* be const, otherwise it would lead to undefined
// behavior on use, as it would create a copy that is dropped.
static I: Integer = unsafe { Integer::from_raw(MPZ) };
let check = -((Integer::from(LIMBS[1]) << gmp::NUMB_BITS) + LIMBS[0]);
assert_eq!(I, check);

Converts an Integer into a GMP integer.

The returned object should be freed to avoid memory leaks.

Examples
use gmp_mpfr_sys::gmp;
use rug::Integer;
let i = Integer::from(15);
let mut z = i.into_raw();
unsafe {
    let u = gmp::mpz_get_ui(&z);
    assert_eq!(u, 15);
    // free object to prevent memory leak
    gmp::mpz_clear(&mut z);
}

Returns a pointer to the inner GMP integer.

The returned pointer will be valid for as long as self is valid.

Examples
use gmp_mpfr_sys::gmp;
use rug::Integer;
let i = Integer::from(15);
let z_ptr = i.as_raw();
unsafe {
    let u = gmp::mpz_get_ui(z_ptr);
    assert_eq!(u, 15);
}
// i is still valid
assert_eq!(i, 15);

Returns an unsafe mutable pointer to the inner GMP integer.

The returned pointer will be valid for as long as self is valid.

Examples
use gmp_mpfr_sys::gmp;
use rug::Integer;
let mut i = Integer::from(15);
let z_ptr = i.as_raw_mut();
unsafe {
    gmp::mpz_add_ui(z_ptr, z_ptr, 20);
}
assert_eq!(i, 35);

Creates an Integer from a slice of digits of type T, where T can be any unsigned integer primitive type.

The resulting value cannot be negative.

Examples
use rug::{integer::Order, Integer};
let digits = [0x5678u16, 0x1234u16];
let i = Integer::from_digits(&digits, Order::Lsf);
assert_eq!(i, 0x1234_5678);

Assigns from a slice of digits of type T, where T can be any unsigned integer primitive type.

The resulting value cannot be negative.

Examples
use rug::{integer::Order, Integer};
let digits = [0x5678u16, 0x1234u16];
let mut i = Integer::new();
i.assign_digits(&digits, Order::Lsf);
assert_eq!(i, 0x1234_5678);

Assigns from digits of type T in a memory area, where T can be any unsigned integer primitive type.

The memory area is addressed using a pointer and a length. The len parameter is the number of digits, not the number of bytes.

There are no data alignment restrictions on src, any address is allowed.

The resulting value cannot be negative.

Safety

To avoid undefined behavior, src must be valid for reading len digits, that is len × size_of::<T>() bytes.

Examples
use rug::{integer::Order, Integer};
// hex bytes: [ fe dc ba 98 87 87 87 87 76 54 32 10 ]
let digits = [
    0xfedc_ba98u32.to_be(),
    0x8787_8787u32.to_be(),
    0x7654_3210u32.to_be(),
];
let ptr = digits.as_ptr();
let mut i = Integer::new();
unsafe {
    let unaligned = (ptr as *const u8).offset(2) as *const u32;
    i.assign_digits_unaligned(unaligned, 2, Order::MsfBe);
}
assert_eq!(i, 0xba98_8787_8787_7654u64);

Returns the number of digits of type T required to represent the absolute value.

T can be any unsigned integer primitive type.

Examples
use rug::Integer;

let i: Integer = Integer::from(1) << 256;
assert_eq!(i.significant_digits::<bool>(), 257);
assert_eq!(i.significant_digits::<u8>(), 33);
assert_eq!(i.significant_digits::<u16>(), 17);
assert_eq!(i.significant_digits::<u32>(), 9);
assert_eq!(i.significant_digits::<u64>(), 5);

Converts the absolute value to a Vec of digits of type T, where T can be any unsigned integer primitive type.

The Integer type also has the as_limbs method, which can be used to borrow the digits without copying them. This does come with some more constraints compared to to_digits:

  1. The digit width is not optional and depends on the implementation: limb_t is typically u64 on 64-bit systems and u32 on 32-bit systems.
  2. The order is not optional and is least significant digit first, with each digit in the target’s endianness, equivalent to Order::Lsf.
Examples
use rug::{integer::Order, Integer};
let i = Integer::from(0x1234_5678_9abc_def0u64);
let digits = i.to_digits::<u32>(Order::MsfBe);
assert_eq!(digits, [0x1234_5678u32.to_be(), 0x9abc_def0u32.to_be()]);

let zero = Integer::new();
let digits_zero = zero.to_digits::<u32>(Order::MsfBe);
assert!(digits_zero.is_empty());

Writes the absolute value into a slice of digits of type T, where T can be any unsigned integer primitive type.

The slice must be large enough to hold the digits; the minimum size can be obtained using the significant_digits method.

Panics

Panics if the slice does not have sufficient capacity.

Examples
use rug::{integer::Order, Integer};
let i = Integer::from(0x1234_5678_9abc_def0u64);
let mut digits = [0xffff_ffffu32; 4];
i.write_digits(&mut digits, Order::MsfBe);
let word0 = 0x9abc_def0u32;
let word1 = 0x1234_5678u32;
assert_eq!(digits, [0, 0, word1.to_be(), word0.to_be()]);

Writes the absolute value into a memory area of digits of type T, where T can be any unsigned integer primitive type.

The memory area is addressed using a pointer and a length. The len parameter is the number of digits, not the number of bytes.

The length must be large enough to hold the digits; the minimum length can be obtained using the significant_digits method.

There are no data alignment restrictions on dst, any address is allowed.

The memory locations can be uninitialized before this method is called; this method sets all len elements, padding with zeros if the length is larger than required.

Safety

To avoid undefined behavior, dst must be valid for writing len digits, that is len × size_of::<T>() bytes.

Panics

Panics if the length is less than the number of digits.

Examples
use rug::{integer::Order, Integer};
let i = Integer::from(0xfedc_ba98_7654_3210u64);
let mut digits = [0xffff_ffffu32; 4];
let ptr = digits.as_mut_ptr();
unsafe {
    let unaligned = (ptr as *mut u8).offset(2) as *mut u32;
    i.write_digits_unaligned(unaligned, 3, Order::MsfBe);
}
assert_eq!(
    digits,
    [
        0xffff_0000u32.to_be(),
        0x0000_fedcu32.to_be(),
        0xba98_7654u32.to_be(),
        0x3210_ffffu32.to_be(),
    ]
);

The following example shows how to write into uninitialized memory. In practice, the following code could be replaced by a call to the safe method to_digits.

use rug::{integer::Order, Integer};
let i = Integer::from(0x1234_5678_9abc_def0u64);
let len = i.significant_digits::<u32>();
assert_eq!(len, 2);

// The following code is equivalent to:
//     let digits = i.to_digits::<u32>(Order::MsfBe);
let mut digits = Vec::<u32>::with_capacity(len);
let ptr = digits.as_mut_ptr();
unsafe {
    i.write_digits_unaligned(ptr, len, Order::MsfBe);
    digits.set_len(len);
}

assert_eq!(digits, [0x1234_5678u32.to_be(), 0x9abc_def0u32.to_be()]);

Extracts a slice of limbs used to store the value.

The slice contains the absolute value of self, with the least significant limb first.

The Integer type also implements AsRef<[limb_t]>, which is equivalent to this method.

Examples
use rug::Integer;
assert!(Integer::new().as_limbs().is_empty());
assert_eq!(Integer::from(13).as_limbs(), &[13]);
assert_eq!(Integer::from(-23).as_limbs(), &[23]);

int.as_limbs() is like a borrowing non-copy version of int.to_digits::<[limb_t]>(Order::Lsf).

use gmp_mpfr_sys::gmp::limb_t;
use rug::{integer::Order, Integer};
let int = Integer::from(0x1234_5678_9abc_def0u64);
// no copying for int_slice, which is borrowing int
let int_slice = int.as_limbs();
// digits is a copy and does not borrow int
let digits = int.to_digits::<limb_t>(Order::Lsf);
// no copying for digits_slice, which is borrowing digits
let digits_slice = &digits[..];
assert_eq!(int_slice, digits_slice);

Creates an Integer from an f32 if it is finite, rounding towards zero.

This conversion can also be performed using value.checked_as::<Integer>().

Examples
use core::f32;
use rug::Integer;
let i = Integer::from_f32(-5.6).unwrap();
assert_eq!(i, -5);
let neg_inf = Integer::from_f32(f32::NEG_INFINITY);
assert!(neg_inf.is_none());

Creates an Integer from an f64 if it is finite, rounding towards zero.

This conversion can also be performed using value.checked_as::<Integer>().

Examples
use core::f64;
use rug::Integer;
let i = Integer::from_f64(1e20).unwrap();
assert_eq!(i, "100000000000000000000".parse::<Integer>().unwrap());
let inf = Integer::from_f64(f64::INFINITY);
assert!(inf.is_none());

Parses an Integer using the given radix.

Panics

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

Examples
use rug::Integer;
let i = Integer::from_str_radix("-ff", 16).unwrap();
assert_eq!(i, -0xff);

Parses a decimal string slice (&str) or byte slice (&[u8]) into an Integer.

The following are implemented with the unwrapped returned incomplete-computation value as Src:

The string can start with an optional minus or plus sign. ASCII whitespace is ignored everywhere in the string. Underscores anywhere except before the first digit are ignored as well.

Examples
use rug::{Complete, Integer};

assert_eq!(Integer::parse("1223").unwrap().complete(), 1223);
assert_eq!(Integer::parse("123 456 789").unwrap().complete(), 123_456_789);

let invalid = Integer::parse("789a");
assert!(invalid.is_err());

Parses a string slice (&str) or byte slice (&[u8]) into an Integer.

The following are implemented with the unwrapped returned incomplete-computation value as Src:

The string can start with an optional minus or plus sign. ASCII whitespace is ignored everywhere in the string. Underscores anywhere except before the first digit are ignored as well.

Panics

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

Examples
use rug::{Complete, Integer};

let valid1 = Integer::parse_radix("1223", 4);
assert_eq!(valid1.unwrap().complete(), 3 + 4 * (2 + 4 * (2 + 4 * 1)));
let valid2 = Integer::parse_radix("1234 abcd", 16);
assert_eq!(valid2.unwrap().complete(), 0x1234_abcd);

let invalid = Integer::parse_radix("123", 3);
assert!(invalid.is_err());

Converts to an i8 if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(-100);
assert_eq!(fits.to_i8(), Some(-100));
let small = Integer::from(-200);
assert_eq!(small.to_i8(), None);
let large = Integer::from(200);
assert_eq!(large.to_i8(), None);

Converts to an i16 if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(-30_000);
assert_eq!(fits.to_i16(), Some(-30_000));
let small = Integer::from(-40_000);
assert_eq!(small.to_i16(), None);
let large = Integer::from(40_000);
assert_eq!(large.to_i16(), None);

Converts to an i32 if the value fits.

This conversion can also be performed using

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_i64);
assert_eq!(large.to_i32(), None);

Converts to an i64 if the value fits.

This conversion can also be performed using

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

Converts to an i128 if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(-50);
assert_eq!(fits.to_i128(), Some(-50));
let small: Integer = Integer::from(-1) << 130;
assert_eq!(small.to_i128(), None);
let large: Integer = Integer::from(1) << 130;
assert_eq!(large.to_i128(), None);

Converts to an isize if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(0x1000);
assert_eq!(fits.to_isize(), Some(0x1000));
let large: Integer = Integer::from(0x1000) << 128;
assert_eq!(large.to_isize(), None);

Converts to an u8 if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(200);
assert_eq!(fits.to_u8(), Some(200));
let neg = Integer::from(-1);
assert_eq!(neg.to_u8(), None);
let large = Integer::from(300);
assert_eq!(large.to_u8(), None);

Converts to an u16 if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(60_000);
assert_eq!(fits.to_u16(), Some(60_000));
let neg = Integer::from(-1);
assert_eq!(neg.to_u16(), None);
let large = Integer::from(70_000);
assert_eq!(large.to_u16(), None);

Converts to an u32 if the value fits.

This conversion can also be performed using

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 = Integer::from(123456789012345_u64);
assert_eq!(large.to_u32(), None);

Converts to an u64 if the value fits.

This conversion can also be performed using

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

Converts to an u128 if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(12345678901234567890_u128);
assert_eq!(fits.to_u128(), Some(12345678901234567890));
let neg = Integer::from(-1);
assert_eq!(neg.to_u128(), None);
let large = "1234567890123456789012345678901234567890"
    .parse::<Integer>()
    .unwrap();
assert_eq!(large.to_u128(), None);

Converts to an usize if the value fits.

This conversion can also be performed using

Examples
use rug::Integer;
let fits = Integer::from(0x1000);
assert_eq!(fits.to_usize(), Some(0x1000));
let neg = Integer::from(-1);
assert_eq!(neg.to_usize(), None);
let large: Integer = Integer::from(0x1000) << 128;
assert_eq!(large.to_usize(), None);

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

This conversion can also be performed using

Examples
use rug::Integer;
let large = Integer::from(0x1234);
assert_eq!(large.to_i8_wrapping(), 0x34);

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

This conversion can also be performed using

Examples
use rug::Integer;
let large = Integer::from(0x1234_5678);
assert_eq!(large.to_i16_wrapping(), 0x5678);

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

This conversion can also be performed using

Examples
use rug::Integer;
let large = Integer::from(0x1234_5678_9abc_def0_u64);
assert_eq!(large.to_i32_wrapping(), 0x9abc_def0_u32 as i32);

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

This conversion can also be performed using

Examples
use rug::Integer;
let large = Integer::from_str_radix("f123456789abcdef0", 16).unwrap();
assert_eq!(large.to_i64_wrapping(), 0x1234_5678_9abc_def0);

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

This conversion can also be performed using

Examples
use rug::Integer;
let s = "f123456789abcdef0123456789abcdef0";
let large = Integer::from_str_radix(s, 16).unwrap();
assert_eq!(
    large.to_i128_wrapping(),
    0x1234_5678_9abc_def0_1234_5678_9abc_def0
);

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

This conversion can also be performed using

Examples
use rug::Integer;
let large: Integer = (Integer::from(0x1000) << 128) | 0x1234;
assert_eq!(large.to_isize_wrapping(), 0x1234);

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

This conversion can also be performed using

Examples
use rug::Integer;
let neg = Integer::from(-1);
assert_eq!(neg.to_u8_wrapping(), 0xff);
let large = Integer::from(0x1234);
assert_eq!(large.to_u8_wrapping(), 0x34);

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

This conversion can also be performed using

Examples
use rug::Integer;
let neg = Integer::from(-1);
assert_eq!(neg.to_u16_wrapping(), 0xffff);
let large = Integer::from(0x1234_5678);
assert_eq!(large.to_u16_wrapping(), 0x5678);

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

This conversion can also be performed using

Examples
use rug::Integer;
let neg = Integer::from(-1);
assert_eq!(neg.to_u32_wrapping(), 0xffff_ffff);
let large = Integer::from(0x1234_5678_9abc_def0_u64);
assert_eq!(large.to_u32_wrapping(), 0x9abc_def0);

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

This conversion can also be performed using

Examples
use rug::Integer;
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(), 0x1234_5678_9abc_def0);

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

This conversion can also be performed using

Examples
use rug::Integer;
let neg = Integer::from(-1);
assert_eq!(
    neg.to_u128_wrapping(),
    0xffff_ffff_ffff_ffff_ffff_ffff_ffff_ffff
);
let s = "f123456789abcdef0123456789abcdef0";
let large = Integer::from_str_radix(s, 16).unwrap();
assert_eq!(
    large.to_u128_wrapping(),
    0x1234_5678_9abc_def0_1234_5678_9abc_def0
);

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

This conversion can also be performed using

Examples
use rug::Integer;
let large: Integer = (Integer::from(0x1000) << 128) | 0x1234;
assert_eq!(large.to_usize_wrapping(), 0x1234);

Converts to an f32, rounding towards zero.

This conversion can also be performed using

Examples
use core::f32;
use rug::Integer;
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);

Converts to an f64, rounding towards zero.

This conversion can also be performed using

Examples
use core::f64;
use rug::Integer;

// 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);

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

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

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

Panics

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

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(Integer::parse_radix("123456789aAbBcCdDeEfF", 16).unwrap());
assert_eq!(i.to_string_radix(16), "123456789aabbccddeeff");

Assigns from an f32 if it is finite, rounding towards zero.

Examples
use core::f32;
use rug::Integer;
let mut i = Integer::new();
let ret = i.assign_f64(-12.7);
assert!(ret.is_ok());
assert_eq!(i, -12);
let ret = i.assign_f32(f32::NAN);
assert!(ret.is_err());
assert_eq!(i, -12);

Assigns from an f64 if it is finite, rounding towards zero.

Examples
use rug::Integer;
let mut i = Integer::new();
let ret = i.assign_f64(12.7);
assert!(ret.is_ok());
assert_eq!(i, 12);
let ret = i.assign_f64(1.0 / 0.0);
assert!(ret.is_err());
assert_eq!(i, 12);

Borrows a negated copy of the Integer.

The returned object implements Deref<Target = Integer>.

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

Borrows an absolute copy of the Integer.

The returned object implements Deref<Target = Integer>.

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

Borrows a copy of the Integer as a Rational number.

The returned object implements Deref<Target = Rational>.

Examples
use rug::Integer;
let i = Integer::from(42);
let r = i.as_rational();
assert_eq!(*r, (42, 1));
// methods taking &self can be used on the returned object
let recip_r = r.as_recip();
assert_eq!(*recip_r, (1, 42));

Returns true if the number is even.

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

Returns true if the number is odd.

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

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()));

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

Returns true if the number is divisible by 2b.

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

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

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

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

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

Returns true if the number is a perfect power.

Examples
use rug::Integer;
// 0 is 0 to the power of anything
assert!(Integer::from(0).is_perfect_power());
// 25 is 5 to the power of 2
assert!(Integer::from(25).is_perfect_power());
// -243 is -3 to the power of 5
assert!(Integer::from(243).is_perfect_power());

assert!(!Integer::from(24).is_perfect_power());
assert!(!Integer::from(-100).is_perfect_power());

Returns true if the number is a perfect square.

Examples
use rug::Integer;
assert!(Integer::from(0).is_perfect_square());
assert!(Integer::from(1).is_perfect_square());
assert!(Integer::from(4).is_perfect_square());
assert!(Integer::from(9).is_perfect_square());

assert!(!Integer::from(15).is_perfect_square());
assert!(!Integer::from(-9).is_perfect_square());

Returns true if the number is a power of two.

Examples
use rug::Integer;
assert!(Integer::from(1).is_power_of_two());
assert!(Integer::from(4).is_power_of_two());
assert!(Integer::from(1 << 30).is_power_of_two());

assert!(!Integer::from(7).is_power_of_two());
assert!(!Integer::from(0).is_power_of_two());
assert!(!Integer::from(-1).is_power_of_two());

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

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

Compares the absolute values.

Examples
use core::cmp::Ordering;
use rug::Integer;
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);

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);  //   “1”
assert_eq!(Integer::from(4).significant_bits(), 3);  // “100”
assert_eq!(Integer::from(7).significant_bits(), 3);  // “111”
assert_eq!(Integer::from(-1).significant_bits(), 1); //   “1”
assert_eq!(Integer::from(-4).significant_bits(), 3); // “100”
assert_eq!(Integer::from(-7).significant_bits(), 3); // “111”

Returns the number of bits required to represent the value using a two’s-complement representation.

For non-negative numbers, this method returns one more than the significant_bits method, since an extra zero is needed before the most significant bit.

Examples
use rug::Integer;

assert_eq!(Integer::from(-5).signed_bits(), 4); // “1011”
assert_eq!(Integer::from(-4).signed_bits(), 3); //  “100”
assert_eq!(Integer::from(-3).signed_bits(), 3); //  “101”
assert_eq!(Integer::from(-2).signed_bits(), 2); //   “10”
assert_eq!(Integer::from(-1).signed_bits(), 1); //    “1”
assert_eq!(Integer::from(0).signed_bits(), 1);  //    “0”
assert_eq!(Integer::from(1).signed_bits(), 2);  //   “01”
assert_eq!(Integer::from(2).signed_bits(), 3);  //  “010”
assert_eq!(Integer::from(3).signed_bits(), 3);  //  “011”
assert_eq!(Integer::from(4).signed_bits(), 4);  // “0100”

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

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

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

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

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

Examples
use rug::{Assign, Integer};
let mut i = Integer::from(-1);
assert_eq!(*i.set_bit(0, false), -2);
i.assign(0xff);
assert_eq!(*i.set_bit(11, true), 0x8ff);

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

Toggles the bit at location index.

Examples
use rug::Integer;
let mut i = Integer::from(0b100101);
i.toggle_bit(5);
assert_eq!(i, 0b101);

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

Adds a list of Integer values.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};

let values = [
    Integer::from(5),
    Integer::from(1024),
    Integer::from(-100_000),
    Integer::from(-4),
];

let sum = Integer::sum(values.iter()).complete();
let expected = 5 + 1024 - 100_000 - 4;
assert_eq!(sum, expected);

Finds the dot product of a list of Integer value pairs.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};

let a = [Integer::from(270), Integer::from(-11)];
let b = [Integer::from(100), Integer::from(5)];

let dot = Integer::dot(a.iter().zip(b.iter())).complete();
let expected = 270 * 100 - 11 * 5;
assert_eq!(dot, expected);

Multiplies a list of Integer values.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};

let values = [
    Integer::from(5),
    Integer::from(1024),
    Integer::from(-100_000),
    Integer::from(-4),
];

let product = Integer::product(values.iter()).complete();
let expected = 5 * 1024 * -100_000 * -4;
assert_eq!(product, expected);

Computes the absolute value.

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

Computes the absolute value.

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

Computes the absolute value.

The following are implemented with the returned incomplete-computation value as Src:

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

Computes the signum.

  • 0 if the value is zero
  • 1 if the value is positive
  • −1 if the value is negative
Examples
use rug::Integer;
assert_eq!(Integer::from(-100).signum(), -1);
assert_eq!(Integer::from(0).signum(), 0);
assert_eq!(Integer::from(100).signum(), 1);

Computes the signum.

  • 0 if the value is zero
  • 1 if the value is positive
  • −1 if the value is negative
Examples
use rug::Integer;
let mut i = Integer::from(-100);
i.signum_mut();
assert_eq!(i, -1);

Computes the signum.

  • 0 if the value is zero
  • 1 if the value is positive
  • −1 if the value is negative

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Integer;
let i = Integer::from(-100);
let r = i.signum_ref();
let signum = Integer::from(r);
assert_eq!(signum, -1);
assert_eq!(i, -100);

Clamps the value within the specified bounds.

Panics

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

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

Clamps the value within the specified bounds.

Panics

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

Examples
use rug::Integer;
let min = -10;
let max = 10;
let mut too_small = Integer::from(-100);
too_small.clamp_mut(&min, &max);
assert_eq!(too_small, -10);
let mut in_range = Integer::from(3);
in_range.clamp_mut(&min, &max);
assert_eq!(in_range, 3);

Clamps the value within the specified bounds.

The following are implemented with the returned incomplete-computation value as Src:

Panics

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

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

Keeps the n least significant bits only, producing a result that is greater or equal to 0.

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

Keeps the n least significant bits only, producing a result that is greater or equal to 0.

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

Keeps the n least significant bits only, producing a result that is greater or equal to 0.

The following are implemented with the returned incomplete-computation value as Src:

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

Keeps the n least significant bits only, producing a negative result if the nth least significant bit is one.

Examples
use rug::Integer;
let i = Integer::from(-1);
let i_keep_8 = i.keep_signed_bits(8);
assert_eq!(i_keep_8, -1);
let j = Integer::from(15 << 8 | 15);
let j_keep_8 = j.keep_signed_bits(8);
assert_eq!(j_keep_8, 15);

Keeps the n least significant bits only, producing a negative result if the nth least significant bit is one.

Examples
use rug::Integer;
let mut i = Integer::from(-1);
i.keep_signed_bits_mut(8);
assert_eq!(i, -1);
let mut j = Integer::from(15 << 8 | 15);
j.keep_signed_bits_mut(8);
assert_eq!(j, 15);

Keeps the n least significant bits only, producing a negative result if the nth least significant bit is one.

The following are implemented with the returned incomplete-computation value as Src:

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

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

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

Examples
use rug::Integer;
let mut i = Integer::from(53);
i.next_power_of_two_mut();
assert_eq!(i, 64);

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

The following are implemented with the returned incomplete-computation value as Src:

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

Performs a division producing both the quotient and remainder.

The remainder has the same sign as the dividend.

Panics

Panics if divisor is zero.

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

Performs a division producing both the quotient and remainder.

The remainder has the same sign as the dividend.

The quotient is stored in self and the remainder is stored in divisor.

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
let mut dividend_quotient = Integer::from(-23);
let mut divisor_rem = Integer::from(10);
dividend_quotient.div_rem_mut(&mut divisor_rem);
assert_eq!(dividend_quotient, -2);
assert_eq!(divisor_rem, -3);

Performs a division producing both the quotient and remainder.

The following are implemented with the returned incomplete-computation value as Src:

The remainder has the same sign as the dividend.

Examples
use rug::{Complete, Integer};
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_ref(&divisor).complete();
assert_eq!(quotient, 2);
assert_eq!(rem, -3);

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.

Panics

Panics if divisor is zero.

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

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.

The quotient is stored in self and the remainder is stored in divisor.

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
let mut dividend_quotient = Integer::from(-23);
let mut divisor_rem = Integer::from(10);
dividend_quotient.div_rem_ceil_mut(&mut divisor_rem);
assert_eq!(dividend_quotient, -2);
assert_eq!(divisor_rem, -3);

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.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_ceil_ref(&divisor).complete();
assert_eq!(quotient, 3);
assert_eq!(rem, 7);

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

The remainder has the same sign as the divisor.

Panics

Panics if divisor is zero.

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

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

The remainder has the same sign as the divisor.

The quotient is stored in self and the remainder is stored in divisor.

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
let mut dividend_quotient = Integer::from(-23);
let mut divisor_rem = Integer::from(10);
dividend_quotient.div_rem_floor_mut(&mut divisor_rem);
assert_eq!(dividend_quotient, -3);
assert_eq!(divisor_rem, 7);

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

The remainder has the same sign as the divisor.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_floor_ref(&divisor).complete();
assert_eq!(quotient, 2);
assert_eq!(rem, -3);

Performs a division producing both the quotient and remainder, with the quotient rounded to the nearest integer.

When the quotient before rounding lies exactly between two integers, it is rounded away from zero.

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
// 23 / -10 → -2 rem 3
let (q, rem) = Integer::from(23).div_rem_round((-10).into());
assert!(q == -2 && rem == 3);
// 25 / 10 → 3 rem -5
let (q, rem) = Integer::from(25).div_rem_round(10.into());
assert!(q == 3 && rem == -5);
// -27 / 10 → -3 rem 3
let (q, rem) = Integer::from(-27).div_rem_round(10.into());
assert!(q == -3 && rem == 3);

Performs a division producing both the quotient and remainder, with the quotient rounded to the nearest integer.

When the quotient before rounding lies exactly between two integers, it is rounded away from zero.

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
// -25 / -10 → 3 rem 5
let mut dividend_quotient = Integer::from(-25);
let mut divisor_rem = Integer::from(-10);
dividend_quotient.div_rem_round_mut(&mut divisor_rem);
assert_eq!(dividend_quotient, 3);
assert_eq!(divisor_rem, 5);

Performs a division producing both the quotient and remainder, with the quotient rounded to the nearest integer.

When the quotient before rounding lies exactly between two integers, it is rounded away from zero.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
// -28 / -10 → 3 rem 2
let dividend = Integer::from(-28);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_round_ref(&divisor).complete();
assert_eq!(quotient, 3);
assert_eq!(rem, 2);

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

Panics

Panics if divisor is zero.

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

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

The quotient is stored in self and the remainder is stored in divisor.

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
let mut dividend_quotient = Integer::from(-23);
let mut divisor_rem = Integer::from(10);
dividend_quotient.div_rem_euc_mut(&mut divisor_rem);
assert_eq!(dividend_quotient, -3);
assert_eq!(divisor_rem, 7);

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

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
let dividend = Integer::from(-23);
let divisor = Integer::from(-10);
let (quotient, rem) = dividend.div_rem_euc_ref(&divisor).complete();
assert_eq!(quotient, 3);
assert_eq!(rem, 7);

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

The result is always zero or positive.

Panics

Panics if modulo is zero.

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

Performs an exact division.

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

Panics

Panics if divisor is zero.

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

Performs an exact division.

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

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
let mut i = Integer::from(12345 * 54321);
i.div_exact_mut(&Integer::from(12345));
assert_eq!(i, 54321);

Performs an exact division dividend / self.

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

Panics

Panics if self is zero.

Examples
use rug::Integer;
let mut i = Integer::from(12345);
i.div_exact_from(&Integer::from(12345 * 54321));
assert_eq!(i, 54321);

Performs an exact division.

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

The following are implemented with the returned incomplete-computation value as Src:

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

Performs an exact division.

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

Panics

Panics if divisor is zero.

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

Performs an exact division.

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

Panics

Panics if divisor is zero.

Examples
use rug::Integer;
let mut i = Integer::from(12345 * 54321);
i.div_exact_u_mut(12345);
assert_eq!(i, 54321);

Performs an exact division.

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

The following are implemented with the returned incomplete-computation value as Src:

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

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

The inverse exists if the modulo is not zero, and self and the modulo are co-prime, that is their GCD is 1.

Examples
use rug::Integer;
let n = Integer::from(2);
// Modulo 4, 2 has no inverse: there is no i such that 2 × i = 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);

Finds the inverse modulo modulo if an inverse exists.

The inverse exists if the modulo is not zero, and self and the modulo are co-prime, that is their GCD is 1.

Examples
use rug::Integer;
let mut n = Integer::from(2);
// Modulo 4, 2 has no inverse: there is no i such that 2 × i = 1.
match n.invert_mut(&Integer::from(4)) {
    Ok(()) => unreachable!(),
    Err(()) => assert_eq!(n, 2),
}
// Modulo 5, the inverse of 2 is 3, as 2 × 3 = 1.
match n.invert_mut(&Integer::from(5)) {
    Ok(()) => assert_eq!(n, 3),
    Err(()) => unreachable!(),
}

Finds the inverse modulo modulo if an inverse exists.

The inverse exists if the modulo is not zero, and self and the modulo are co-prime, that is their GCD is 1.

The following are implemented with the unwrapped returned incomplete-computation value as Src:

Examples
use rug::Integer;
let two = Integer::from(2);
let four = Integer::from(4);
let five = Integer::from(5);

// Modulo 4, 2 has no inverse, there is no i such that 2 × i = 1.
// For this conversion, if no inverse exists, the Integer
// created is left unchanged as 0.
assert!(two.invert_ref(&four).is_none());

// Modulo 5, the inverse of 2 is 3, as 2 × 3 = 1.
let r = two.invert_ref(&five).unwrap();
let inverse = Integer::from(r);
assert_eq!(inverse, 3);

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 the exponent is negative, then the number must have an inverse for an answer to exist.

When the exponent is positive and the modulo is not zero, an answer always exists.

Examples
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);

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

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

Examples
use rug::{Assign, Integer};
// Modulo 1000, 2 has no inverse: there is no i such that 2 × i = 1.
let mut n = Integer::from(2);
let e = Integer::from(-5);
let m = Integer::from(1000);
match n.pow_mod_mut(&e, &m) {
    Ok(()) => unreachable!(),
    Err(()) => assert_eq!(n, 2),
}
// 7 × 143 modulo 1000 = 1, so 7 has an inverse 143.
// 7 ^ -5 modulo 1000 = 143 ^ 5 modulo 1000 = 943.
n.assign(7);
match n.pow_mod_mut(&e, &m) {
    Ok(()) => assert_eq!(n, 943),
    Err(()) => unreachable!(),
}

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

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

The following are implemented with the unwrapped returned incomplete-computation value as Src:

Examples
use rug::Integer;
let two = Integer::from(2);
let thousand = Integer::from(1000);
let minus_five = Integer::from(-5);
let seven = Integer::from(7);

// Modulo 1000, 2 has no inverse: there is no i such that 2 × i = 1.
assert!(two.pow_mod_ref(&minus_five, &thousand).is_none());

// 7 × 143 modulo 1000 = 1, so 7 has an inverse 143.
// 7 ^ -5 modulo 1000 = 143 ^ 5 modulo 1000 = 943.
let r = seven.pow_mod_ref(&minus_five, &thousand).unwrap();
let power = Integer::from(r);
assert_eq!(power, 943);

Raises a number to the power of exponent modulo modulo, with resilience to side-channel attacks.

The exponent must be greater than zero, and the modulo must be odd.

This method is intended for cryptographic purposes where resilience to side-channel attacks is desired. The function is designed to take the same time and use the same cache access patterns for same-sized arguments, assuming that the arguments are placed at the same position and the machine state is identical when starting.

Panics

Panics if exponent ≤ 0 or if modulo is even.

Examples
use rug::Integer;
// 7 ^ 4 mod 13 = 9
let n = Integer::from(7);
let e = Integer::from(4);
let m = Integer::from(13);
let power = n.secure_pow_mod(&e, &m);
assert_eq!(power, 9);

Raises a number to the power of exponent modulo modulo, with resilience to side-channel attacks.

The exponent must be greater than zero, and the modulo must be odd.

This method is intended for cryptographic purposes where resilience to side-channel attacks is desired. The function is designed to take the same time and use the same cache access patterns for same-sized arguments, assuming that the arguments are placed at the same position and the machine state is identical when starting.

Panics

Panics if exponent ≤ 0 or if modulo is even.

Examples
use rug::Integer;
// 7 ^ 4 mod 13 = 9
let mut n = Integer::from(7);
let e = Integer::from(4);
let m = Integer::from(13);
n.secure_pow_mod_mut(&e, &m);
assert_eq!(n, 9);

Raises a number to the power of exponent modulo modulo, with resilience to side-channel attacks.

The exponent must be greater than zero, and the modulo must be odd.

This method is intended for cryptographic purposes where resilience to side-channel attacks is desired. The function is designed to take the same time and use the same cache access patterns for same-sized arguments, assuming that the arguments are placed at the same position and the machine state is identical when starting.

The following are implemented with the returned incomplete-computation value as Src:

Panics

Panics if exponent ≤ 0 or if modulo is even.

Examples
use rug::Integer;
// 7 ^ 4 mod 13 = 9
let n = Integer::from(7);
let e = Integer::from(4);
let m = Integer::from(13);
let power = Integer::from(n.secure_pow_mod_ref(&e, &m));
assert_eq!(power, 9);

Raises base to the power of exponent.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
assert_eq!(Integer::u_pow_u(13, 12).complete(), 13_u64.pow(12));

Raises base to the power of exponent.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Assign, Integer};
let mut ans = Integer::new();
ans.assign(Integer::i_pow_u(-13, 13));
assert_eq!(ans, (-13_i64).pow(13));
ans.assign(Integer::i_pow_u(13, 13));
assert_eq!(ans, (13_i64).pow(13));

Computes the nth root and truncates the result.

Panics

Panics if n is zero or if n is even and the value is negative.

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

Computes the nth root and truncates the result.

Panics

Panics if n is zero or if n is even and the value is negative.

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

Computes the nth root and truncates the result.

The following are implemented with the returned incomplete-computation value as Src:

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

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.

Panics

Panics if n is zero or if n is even and the value is negative.

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

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.

Panics

Panics if n is zero or if n is even and the value is negative.

Examples
use rug::Integer;
let mut i = Integer::from(1004);
let mut rem = Integer::new();
i.root_rem_mut(&mut rem, 3);
assert_eq!(i, 10);
assert_eq!(rem, 4);

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 following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Assign, Complete, Integer};
let i = Integer::from(1004);
let mut root = Integer::new();
let mut rem = Integer::new();
// 1004 = 10^3 + 5
(&mut root, &mut rem).assign(i.root_rem_ref(3));
assert_eq!(root, 10);
assert_eq!(rem, 4);
// 1004 = 3^6 + 275
let (other_root, other_rem) = i.root_rem_ref(6).complete();
assert_eq!(other_root, 3);
assert_eq!(other_rem, 275);

Computes the square.

This method cannot be replaced by a multiplication using the * operator: i * i and i * &i are both errors.

Examples
use rug::Integer;
let i = Integer::from(13);
let square = i.square();
assert_eq!(square, 169);

Computes the square.

This method cannot be replaced by a compound multiplication and assignment using the *= operataor: i *= i; and i *= &i; are both errors.

Examples
use rug::Integer;
let mut i = Integer::from(13);
i.square_mut();
assert_eq!(i, 169);

Computes the square.

The following are implemented with the returned incomplete-computation value as Src:

i.square_ref() produces the exact same result as &i * &i.

Examples
use rug::Integer;
let i = Integer::from(13);
assert_eq!(Integer::from(i.square_ref()), 169);

Computes the square root and truncates the result.

Panics

Panics if the value is negative.

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

Computes the square root and truncates the result.

Panics

Panics if the value is negative.

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

Computes the square root and truncates the result.

The following are implemented with the returned incomplete-computation value as Src:

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

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.

Panics

Panics if the value is negative.

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

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.

Panics

Panics if the value is negative.

Examples
use rug::Integer;
let mut i = Integer::from(104);
let mut rem = Integer::new();
i.sqrt_rem_mut(&mut rem);
assert_eq!(i, 10);
assert_eq!(rem, 4);

Computes the square root and the remainder.

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

The following are implemented with the returned incomplete-computation value as Src:

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

Determines wheter a number is prime.

This function uses some trial divisions, a Baille-PSW probable prime test, then reps − 24 Miller-Rabin probabilistic primality tests.

Examples
use rug::{integer::IsPrime, Integer};
let no = Integer::from(163 * 4003);
assert_eq!(no.is_probably_prime(30), IsPrime::No);
let yes = Integer::from(817_504_243);
assert_eq!(yes.is_probably_prime(30), IsPrime::Yes);
// 16_412_292_043_871_650_369 is actually a prime.
let probably = Integer::from(16_412_292_043_871_650_369_u64);
assert_eq!(probably.is_probably_prime(30), IsPrime::Probably);

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

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

Examples
use rug::Integer;
let mut i = Integer::from(800_000_000);
i.next_prime_mut();
assert_eq!(i, 800_000_011);

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

The following are implemented with the returned incomplete-computation value as Src:

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

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

Finds the greatest common divisor.

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

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

Finds the greatest common divisor.

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

The following are implemented with the returned incomplete-computation value as Src:

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

Finds the greatest common divisor.

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

Examples
use rug::Integer;
let i = Integer::new();
// gcd of 0, 0 is 0
let gcd1 = i.gcd_u(0);
assert_eq!(gcd1, 0);
// gcd of 0, 10 is 10
let gcd2 = gcd1.gcd_u(10);
assert_eq!(gcd2, 10);
// gcd of 10, 25 is 5
let gcd3 = gcd2.gcd_u(25);
assert_eq!(gcd3, 5);

Finds the greatest common divisor.

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

Examples
use rug::Integer;
let mut i = Integer::new();
// gcd of 0, 0 is 0
i.gcd_u_mut(0);
assert_eq!(i, 0);
// gcd of 0, 10 is 10
i.gcd_u_mut(10);
assert_eq!(i, 10);
// gcd of 10, 25 is 5
i.gcd_u_mut(25);
assert_eq!(i, 5);

Finds the greatest common divisor.

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

The following are implemented with the returned incomplete-computation value as Src:

The last item above is useful to obtain the result as a u32 if it fits. If other > 0 , the result always fits. If the result does not fit, it is equal to the absolute value of self.

Examples
use rug::Integer;
let i = Integer::from(100);
let r = i.gcd_u_ref(125);
// gcd of 100, 125 is 25
assert_eq!(Integer::from(r), 25);
let r = i.gcd_u_ref(125);
assert_eq!(Option::<u32>::from(r), Some(25));

Finds the greatest common divisor (GCD) of the two inputs (self and other), and two cofactors 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, then the GCD is g and the cofactors are s and t such that

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

The initial value of rop is ignored.

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

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

The GCD is stored in self, and the two cofactors are stored in other and rop.

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

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

The initial value of rop is ignored.

Examples
use rug::Integer;
let mut a_g = Integer::from(4);
let mut b_s = Integer::from(6);
let mut t = Integer::new();
a_g.gcd_cofactors_mut(&mut b_s, &mut t);
assert_eq!(a_g, 2);
assert_eq!(b_s, -1);
assert_eq!(t, 1);

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

The following are implemented with the returned incomplete-computation value as Src:

In the case that only one of the two cofactors is required, the following are also implemented:

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

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_cofactors_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);

In the case that only one of the two cofactors is required, this can be achieved as follows:

use rug::{Assign, Integer};
let a = Integer::from(4);
let b = Integer::from(6);

// no t required
let (mut g1, mut s1) = (Integer::new(), Integer::new());
(&mut g1, &mut s1).assign(a.gcd_cofactors_ref(&b));
assert_eq!(g1, 2);
assert_eq!(s1, -1);

// no s required
let (mut g2, mut t2) = (Integer::new(), Integer::new());
(&mut g2, &mut t2).assign(b.gcd_cofactors_ref(&a));
assert_eq!(g2, 2);
assert_eq!(t2, 1);

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

Finds the least common multiple.

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

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

Finds the least common multiple.

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

The following are implemented with the returned incomplete-computation value as Src:

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

Finds the least common multiple.

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

Examples
use rug::Integer;
let i = Integer::from(10);
// lcm of 10, 25 is 50
let lcm1 = i.lcm_u(25);
assert_eq!(lcm1, 50);
// lcm of 50, 0 is 0
let lcm2 = lcm1.lcm_u(0);
assert_eq!(lcm2, 0);

Finds the least common multiple.

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

Examples
use rug::Integer;
let mut i = Integer::from(10);
// lcm of 10, 25 is 50
i.lcm_u_mut(25);
assert_eq!(i, 50);
// lcm of 50, 0 is 0
i.lcm_u_mut(0);
assert_eq!(i, 0);

Finds the least common multiple.

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

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::Integer;
let i = Integer::from(100);
let r = i.lcm_u_ref(125);
// lcm of 100, 125 is 500
assert_eq!(Integer::from(r), 500);

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

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

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

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

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

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

Examples
use rug::Integer;
let mut i = Integer::from(Integer::u_pow_u(13, 50));
i *= 1000;
let count = i.remove_factor_mut(&Integer::from(13));
assert_eq!(i, 1000);
assert_eq!(count, 50);

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

Examples
use rug::{Assign, Integer};
let mut i = Integer::from(Integer::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);

Computes the factorial of n.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
// 10 × 9 × 8 × 7 × 6 × 5 × 4 × 3 × 2 × 1
assert_eq!(Integer::factorial(10).complete(), 3628800);

Computes the double factorial of n.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
// 10 × 8 × 6 × 4 × 2
assert_eq!(Integer::factorial_2(10).complete(), 3840);

Computes the m-multi factorial of n.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
// 10 × 7 × 4 × 1
assert_eq!(Integer::factorial_m(10, 3).complete(), 280);

Computes the primorial of n.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{Complete, Integer};
// 7 × 5 × 3 × 2
assert_eq!(Integer::primorial(10).complete(), 210);

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

Computes the binomial coefficient over k.

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

Computes the binomial coefficient over k.

The following are implemented with the returned incomplete-computation value as Src:

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

Computes the binomial coefficient n over k.

The following are implemented with the returned incomplete-computation value as Src:

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

Computes the Fibonacci number.

The following are implemented with the returned incomplete-computation value as Src:

This function is meant for an isolated number. If a sequence of Fibonacci numbers is required, the first two values of the sequence should be computed with the fibonacci_2 method, then iterations should be used.

Examples
use rug::{Complete, Integer};
assert_eq!(Integer::fibonacci(12).complete(), 144);

Computes a Fibonacci number, and the previous Fibonacci number.

The following are implemented with the returned incomplete-computation value as Src:

This function is meant to calculate isolated numbers. If a sequence of Fibonacci numbers is required, the first two values of the sequence should be computed with this function, then iterations should be used.

Examples
use rug::{Assign, Integer};
let f = Integer::fibonacci_2(12);
let mut pair = <(Integer, Integer)>::from(f);
assert_eq!(pair.0, 144);
assert_eq!(pair.1, 89);
// Fibonacci number F[-1] is 1
pair.assign(Integer::fibonacci_2(0));
assert_eq!(pair.0, 0);
assert_eq!(pair.1, 1);

Computes the Lucas number.

The following are implemented with the returned incomplete-computation value as Src:

This function is meant for an isolated number. If a sequence of Lucas numbers is required, the first two values of the sequence should be computed with the lucas_2 method, then iterations should be used.

Examples
use rug::{Complete, Integer};
assert_eq!(Integer::lucas(12).complete(), 322);

Computes a Lucas number, and the previous Lucas number.

The following are implemented with the returned incomplete-computation value as Src:

This function is meant to calculate isolated numbers. If a sequence of Lucas numbers is required, the first two values of the sequence should be computed with this function, then iterations should be used.

Examples
use rug::{Assign, Integer};
let l = Integer::lucas_2(12);
let mut pair = <(Integer, Integer)>::from(l);
assert_eq!(pair.0, 322);
assert_eq!(pair.1, 199);
pair.assign(Integer::lucas_2(0));
assert_eq!(pair.0, 2);
assert_eq!(pair.1, -1);

Generates a random number with a specified maximum number of bits.

The following are implemented with the returned incomplete-computation value as Src:

Examples
use rug::{rand::RandState, Assign, Integer};
let mut rand = RandState::new();
let mut i = Integer::from(Integer::random_bits(0, &mut rand));
assert_eq!(i, 0);
i.assign(Integer::random_bits(80, &mut rand));
assert!(i.significant_bits() <= 80);

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

Panics

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

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

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

Panics

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

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

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

The following are implemented with the returned incomplete-computation value as Src:

Panics

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

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

Trait Implementations

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

The rounding method.

The direction from rounding.

Performs the addition. Read more

The rounding method.

The direction from rounding.

Performs the addition. Read more

The rounding method.

The direction from rounding.

Performs the addition. Read more

The rounding method.

The direction from rounding.

Performs the addition. Read more

Peforms the addition. Read more