Struct rug::integer::SmallInteger
source · [−]pub struct SmallInteger { /* private fields */ }
Expand description
A small integer that does not require any memory allocation.
This can be useful when you have a primitive integer type such as u64
or
i8
, but need a reference to an Integer
.
If there are functions that take a u32
or i32
directly instead of an
Integer
reference, using them can still be faster than using a
SmallInteger
; the functions would still need to check for the size of an
Integer
obtained using SmallInteger
.
The SmallInteger
type can be coerced to an Integer
, as it implements
Deref<Target = Integer>
.
Examples
use rug::{integer::SmallInteger, Integer};
// `a` requires a heap allocation
let mut a = Integer::from(250);
// `b` can reside on the stack
let b = SmallInteger::from(-100);
a.lcm_mut(&b);
assert_eq!(a, 500);
// another computation:
a.lcm_mut(&SmallInteger::from(30));
assert_eq!(a, 1500);
Implementations
Creates a SmallInteger
with value 0.
Examples
use rug::integer::SmallInteger;
let i = SmallInteger::new();
// Borrow i as if it were Integer.
assert_eq!(*i, 0);
Returns a mutable reference to an Integer
for simple operations that
do not need to allocate more space for the number.
Safety
It is undefined behavior to perform operations that reallocate the
internal data of the referenced Integer
or to swap it with another
number.
Some GMP functions swap the allocations of their target operands; calling such functions with the mutable reference returned by this method can lead to undefined behavior.
Examples
use rug::{integer::SmallInteger, Assign};
let mut i = SmallInteger::from(1u64);
let capacity = i.capacity();
// another u64 will not require a reallocation
unsafe {
i.as_nonreallocating_integer().assign(2u64);
}
assert_eq!(*i, 2);
assert_eq!(i.capacity(), capacity);
Methods from Deref<Target = Integer>
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);
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 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
:
- The digit width is not optional and depends on the implementation:
limb_t
is typicallyu64
on 64-bit systems andu32
on 32-bit systems. - 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()]);
pub unsafe fn write_digits_unaligned<T: UnsignedPrimitive>(
&self,
dst: *mut T,
len: usize,
order: Order
)
pub unsafe fn write_digits_unaligned<T: UnsignedPrimitive>(
&self,
dst: *mut T,
len: usize,
order: Order
)
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);
Converts to an i8
if the value fits.
This conversion can also be performed using
i8::try_from(&integer)
i8::try_from(integer)
(&integer).checked_as::<i8>()
integer.borrow().checked_as::<i8>()
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
i16::try_from(&integer)
i16::try_from(integer)
(&integer).checked_as::<i16>()
integer.borrow().checked_as::<i16>()
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
i32::try_from(&integer)
i32::try_from(integer)
(&integer).checked_as::<i32>()
integer.borrow().checked_as::<i32>()
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
i64::try_from(&integer)
i64::try_from(integer)
(&integer).checked_as::<i64>()
integer.borrow().checked_as::<i64>()
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
i128::try_from(&integer)
i128::try_from(integer)
(&integer).checked_as::<i128>()
integer.borrow().checked_as::<i128>()
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
isize::try_from(&integer)
isize::try_from(integer)
(&integer).checked_as::<isize>()
integer.borrow().checked_as::<isize>()
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
u8::try_from(&integer)
u8::try_from(integer)
(&integer).checked_as::<u8>()
integer.borrow().checked_as::<u8>()
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
u16::try_from(&integer)
u16::try_from(integer)
(&integer).checked_as::<u16>()
integer.borrow().checked_as::<u16>()
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
u32::try_from(&integer)
u32::try_from(integer)
(&integer).checked_as::<u32>()
integer.borrow().checked_as::<u32>()
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
u64::try_from(&integer)
u64::try_from(integer)
(&integer).checked_as::<u64>()
integer.borrow().checked_as::<u64>()
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
u128::try_from(&integer)
u128::try_from(integer)
(&integer).checked_as::<u128>()
integer.borrow().checked_as::<u128>()
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
usize::try_from(&integer)
usize::try_from(integer)
(&integer).checked_as::<usize>()
integer.borrow().checked_as::<usize>()
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
(&integer).wrapping_as::<i8>()
integer.borrow().wrapping_as::<i8>()
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
(&integer).wrapping_as::<i16>()
integer.borrow().wrapping_as::<i16>()
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
(&integer).wrapping_as::<i32>()
integer.borrow().wrapping_as::<i32>()
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
(&integer).wrapping_as::<i64>()
integer.borrow().wrapping_as::<i64>()
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
(&integer).wrapping_as::<i128>()
integer.borrow().wrapping_as::<i128>()
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
(&integer).wrapping_as::<isize>()
integer.borrow().wrapping_as::<isize>()
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
(&integer).wrapping_as::<u8>()
integer.borrow().wrapping_as::<u8>()
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
(&integer).wrapping_as::<u16>()
integer.borrow().wrapping_as::<u16>()
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
(&integer).wrapping_as::<u32>()
integer.borrow().wrapping_as::<u32>()
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
(&integer).wrapping_as::<u64>()
integer.borrow().wrapping_as::<u64>()
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
(&integer).wrapping_as::<u128>()
integer.borrow().wrapping_as::<u128>()
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
(&integer).wrapping_as::<usize>()
integer.borrow().wrapping_as::<usize>()
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");
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 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());
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));
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));
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
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);
pub fn clamp_ref<'min, 'max, Min, Max>(
&self,
min: &'min Min,
max: &'max Max
) -> ClampIncomplete<'_, 'min, 'max, Min, Max> where
Self: PartialOrd<Min> + PartialOrd<Max> + for<'a> Assign<&'a Min> + for<'a> Assign<&'a Max>,
pub fn clamp_ref<'min, 'max, Min, Max>(
&self,
min: &'min Min,
max: &'max Max
) -> ClampIncomplete<'_, 'min, 'max, Min, Max> where
Self: PartialOrd<Min> + PartialOrd<Max> + for<'a> Assign<&'a Min> + for<'a> Assign<&'a Max>,
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.
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.
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.
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 following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
Complete<Completed = (Integer, Integer)> for 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.
The following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
Complete<Completed = (Integer, Integer)> for 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.
The following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
Complete<Completed = (Integer, Integer)> for 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.
The following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
Complete<Completed = (Integer, Integer)> for 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 Euclidan division producing both the quotient and remainder, with a positive remainder.
The following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
Complete<Completed = (Integer, Integer)> for 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.
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.
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
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);
pub fn pow_mod_ref<'a>(
&'a self,
exponent: &'a Self,
modulo: &'a Self
) -> Option<PowModIncomplete<'a>>
pub fn pow_mod_ref<'a>(
&'a self,
exponent: &'a Self,
modulo: &'a Self
) -> Option<PowModIncomplete<'a>>
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);
pub fn secure_pow_mod_ref<'a>(
&'a self,
exponent: &'a Self,
modulo: &'a Self
) -> SecurePowModIncomplete<'a>
pub fn secure_pow_mod_ref<'a>(
&'a self,
exponent: &'a Self,
modulo: &'a Self
) -> SecurePowModIncomplete<'a>
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);
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 following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
Complete<Completed = (Integer, Integer)> for 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.
The following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for Integer
From<Src> for Integer
Complete<Completed = Integer> for Src
AddAssign<Src> for Integer
Add<Src> for Integer
,Add<Integer> for Src
SubAssign<Src> for Integer
,SubFrom<Src> for Integer
Sub<Src> for Integer
,Sub<Integer> for 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.
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 following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
Complete<Completed = (Integer, Integer)> for 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.
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.
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.
The following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for Integer
From<Src> for Integer
From<Src> for Option<u32>
Complete<Completed = Integer> for 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 following are implemented with the returned incomplete-computation
value as Src
:
Assign<Src> for (Integer, Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer, &mut Integer)
From<Src> for (Integer, Integer, Integer)
Complete<Completed = (Integer, Integer, Integer)> for Src
In the case that only one of the two cofactors is required, the following are also implemented:
Assign<Src> for (Integer, Integer)
Assign<Src> for (&mut Integer, &mut Integer)
From<Src> for (Integer, Integer)
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.
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.
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 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 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);
pub fn random_below_ref<'a>(
&'a self,
rng: &'a mut dyn MutRandState
) -> RandomBelowIncomplete<'a>
pub fn random_below_ref<'a>(
&'a self,
rng: &'a mut dyn MutRandState
) -> RandomBelowIncomplete<'a>
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
Auto Trait Implementations
impl !RefUnwindSafe for SmallInteger
impl !Sync for SmallInteger
impl Unpin for SmallInteger
impl UnwindSafe for SmallInteger
Blanket Implementations
Mutably borrows from an owned value. Read more
Casts the value.
Casts the value.
Casts the value.
OverflowingCasts the value.
Casts the value.
Casts the value.
Casts the value.
UnwrappedCasts the value.
Casts the value.
WrappingCasts the value.