//! Module containing integer aritimetic methods closely following the Rust
//! standard library API for `uN` types.
use super::U256;
use crate::intrinsics;
use core::{
mem::{self, MaybeUninit},
num::ParseIntError,
};
impl U256 {
/// The smallest value that can be represented by this integer type.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::MIN, U256::new(0));
/// ```
pub const MIN: Self = Self([0; 2]);
/// The largest value that can be represented by this integer type.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(
/// U256::MAX.to_string(),
/// "115792089237316195423570985008687907853269984665640564039457584007913129639935",
/// );
/// ```
pub const MAX: Self = Self([!0; 2]);
/// The size of this integer type in bits.
///
/// # Examples
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::BITS, 256);
/// ```
pub const BITS: u32 = 256;
/// Converts a string slice in a given base to an integer.
///
/// The string is expected to be an optional `+` sign followed by digits.
/// Leading and trailing whitespace represent an error. Digits are a subset
/// of these characters, depending on `radix`:
///
/// * `0-9`
/// * `a-z`
/// * `A-Z`
///
/// # Panics
///
/// This function panics if `radix` is not in the range from 2 to 36.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::from_str_radix("A", 16), Ok(U256::new(10)));
/// ```
#[inline]
pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
crate::parse::from_str_radix(src, radix, None)
}
/// Returns the number of ones in the binary representation of `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0b01001100);
/// assert_eq!(n.count_ones(), 3);
/// ```
#[inline]
pub const fn count_ones(self) -> u32 {
let Self([a, b]) = self;
a.count_ones() + b.count_ones()
}
/// Returns the number of zeros in the binary representation of `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::MIN.count_zeros(), 256);
/// assert_eq!(U256::MAX.count_zeros(), 0);
/// ```
#[inline]
pub const fn count_zeros(self) -> u32 {
let Self([a, b]) = self;
a.count_zeros() + b.count_zeros()
}
/// Returns the number of leading zeros in the binary representation of
/// `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::MAX >> 2u32;
/// assert_eq!(n.leading_zeros(), 2);
/// ```
#[inline]
pub fn leading_zeros(self) -> u32 {
intrinsics::signed::uctlz(&self)
}
/// Returns the number of trailing zeros in the binary representation of
/// `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0b0101000);
/// assert_eq!(n.trailing_zeros(), 3);
/// ```
#[inline]
pub fn trailing_zeros(self) -> u32 {
intrinsics::signed::ucttz(&self)
}
/// Returns the number of leading ones in the binary representation of
/// `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = !(U256::MAX >> 2u32);
/// assert_eq!(n.leading_ones(), 2);
/// ```
#[inline]
pub fn leading_ones(self) -> u32 {
(!self).leading_zeros()
}
/// Returns the number of trailing ones in the binary representation of
/// `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0b1010111);
/// assert_eq!(n.trailing_ones(), 3);
/// ```
#[inline]
pub fn trailing_ones(self) -> u32 {
(!self).trailing_zeros()
}
/// Shifts the bits to the left by a specified amount, `n`, wrapping the
/// truncated bits to the end of the resulting integer.
///
/// Please note this isn't the same operation as the `<<` shifting
/// operator!
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::from_words(
/// 0x13f40000000000000000000000000000,
/// 0x00000000000000000000000000004f76,
/// );
/// let m = U256::new(0x4f7613f4);
/// assert_eq!(n.rotate_left(16), m);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn rotate_left(self, n: u32) -> Self {
let mut r = MaybeUninit::uninit();
intrinsics::signed::urol3(&mut r, &self, n);
unsafe { r.assume_init() }
}
/// Shifts the bits to the right by a specified amount, `n`, wrapping the
/// truncated bits to the beginning of the resulting integer.
///
/// Please note this isn't the same operation as the `>>` shifting operator!
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0x4f7613f4);
/// let m = U256::from_words(
/// 0x13f40000000000000000000000000000,
/// 0x00000000000000000000000000004f76,
/// );
///
/// assert_eq!(n.rotate_right(16), m);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn rotate_right(self, n: u32) -> Self {
let mut r = MaybeUninit::uninit();
intrinsics::signed::uror3(&mut r, &self, n);
unsafe { r.assume_init() }
}
/// Reverses the byte order of the integer.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// );
/// assert_eq!(
/// n.swap_bytes(),
/// U256::from_words(
/// 0x1f1e1d1c_1b1a1918_17161514_13121110,
/// 0x0f0e0d0c_0b0a0908_07060504_03020100,
/// ),
/// );
/// ```
#[inline]
pub const fn swap_bytes(self) -> Self {
let Self([a, b]) = self;
Self([b.swap_bytes(), a.swap_bytes()])
}
/// Reverses the bit pattern of the integer.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// );
/// assert_eq!(
/// n.reverse_bits(),
/// U256::from_words(
/// 0xf878b838_d8589818_e868a828_c8488808,
/// 0xf070b030_d0509010_e060a020_c0408000,
/// ),
/// );
/// ```
#[inline]
pub const fn reverse_bits(self) -> Self {
let Self([a, b]) = self;
Self([b.reverse_bits(), a.reverse_bits()])
}
/// Converts an integer from big endian to the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are swapped.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0x1A);
/// if cfg!(target_endian = "big") {
/// assert_eq!(U256::from_be(n), n);
/// } else {
/// assert_eq!(U256::from_be(n), n.swap_bytes());
/// }
/// ```
#[inline]
#[allow(clippy::wrong_self_convention)]
pub const fn from_be(x: Self) -> Self {
#[cfg(target_endian = "big")]
{
x
}
#[cfg(not(target_endian = "big"))]
{
x.swap_bytes()
}
}
/// Converts an integer from little endian to the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are swapped.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0x1A);
/// if cfg!(target_endian = "little") {
/// assert_eq!(U256::from_le(n), n)
/// } else {
/// assert_eq!(U256::from_le(n), n.swap_bytes())
/// }
/// ```
#[inline]
#[allow(clippy::wrong_self_convention)]
pub const fn from_le(x: Self) -> Self {
#[cfg(target_endian = "little")]
{
x
}
#[cfg(not(target_endian = "little"))]
{
x.swap_bytes()
}
}
/// Converts `self` to big endian from the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are swapped.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0x1A);
/// if cfg!(target_endian = "big") {
/// assert_eq!(n.to_be(), n)
/// } else {
/// assert_eq!(n.to_be(), n.swap_bytes())
/// }
/// ```
#[inline]
pub const fn to_be(self) -> Self {
#[cfg(target_endian = "big")]
{
self
}
#[cfg(not(target_endian = "big"))]
{
self.swap_bytes()
}
}
/// Converts `self` to little endian from the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are swapped.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// let n = U256::new(0x1A);
/// if cfg!(target_endian = "little") {
/// assert_eq!(n.to_le(), n)
/// } else {
/// assert_eq!(n.to_le(), n.swap_bytes())
/// }
/// ```
#[inline]
pub const fn to_le(self) -> Self {
#[cfg(target_endian = "little")]
{
self
}
#[cfg(not(target_endian = "little"))]
{
self.swap_bytes()
}
}
/// Checked integer addition. Computes `self + rhs`, returning `None` if
/// overflow occurred.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!((U256::MAX - 2).checked_add(U256::new(1)), Some(U256::MAX - 1));
/// assert_eq!((U256::MAX - 2).checked_add(U256::new(3)), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_add(self, rhs: Self) -> Option<Self> {
let (a, b) = self.overflowing_add(rhs);
if b {
None
} else {
Some(a)
}
}
/// Checked integer subtraction. Computes `self - rhs`, returning `None` if
/// overflow occurred.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(1).checked_sub(U256::new(1)), Some(U256::ZERO));
/// assert_eq!(U256::new(0).checked_sub(U256::new(1)), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_sub(self, rhs: Self) -> Option<Self> {
let (a, b) = self.overflowing_sub(rhs);
if b {
None
} else {
Some(a)
}
}
/// Checked integer multiplication. Computes `self * rhs`, returning `None`
/// if overflow occurred.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).checked_mul(U256::new(1)), Some(U256::new(5)));
/// assert_eq!(U256::MAX.checked_mul(U256::new(2)), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_mul(self, rhs: Self) -> Option<Self> {
let (a, b) = self.overflowing_mul(rhs);
if b {
None
} else {
Some(a)
}
}
/// Checked integer division. Computes `self / rhs`, returning `None` if
/// `rhs == 0`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(128).checked_div(U256::new(2)), Some(U256::new(64)));
/// assert_eq!(U256::new(1).checked_div(U256::new(0)), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_div(self, rhs: Self) -> Option<Self> {
if rhs == U256::ZERO {
None
} else {
Some(self / rhs)
}
}
/// Checked Euclidean division. Computes `self.div_euclid(rhs)`, returning
/// `None` if `rhs == 0`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(128).checked_div_euclid(U256::new(2)), Some(U256::new(64)));
/// assert_eq!(U256::new(1).checked_div_euclid(U256::new(0)), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
if rhs == U256::ZERO {
None
} else {
Some(self.div_euclid(rhs))
}
}
/// Checked integer remainder. Computes `self % rhs`, returning `None` if
/// `rhs == 0`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).checked_rem(U256::new(2)), Some(U256::new(1)));
/// assert_eq!(U256::new(5).checked_rem(U256::new(0)), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_rem(self, rhs: Self) -> Option<Self> {
if rhs == U256::ZERO {
None
} else {
Some(self % rhs)
}
}
/// Checked Euclidean modulo. Computes `self.rem_euclid(rhs)`, returning
/// `None` if `rhs == 0`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).checked_rem_euclid(U256::new(2)), Some(U256::new(1)));
/// assert_eq!(U256::new(5).checked_rem_euclid(U256::new(0)), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
if rhs == U256::ZERO {
None
} else {
Some(self.rem_euclid(rhs))
}
}
/// Checked negation. Computes `-self`, returning `None` unless `self == 0`.
///
/// Note that negating any positive integer will overflow.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::ZERO.checked_neg(), Some(U256::ZERO));
/// assert_eq!(U256::new(1).checked_neg(), None);
/// ```
#[inline]
pub fn checked_neg(self) -> Option<Self> {
let (a, b) = self.overflowing_neg();
if b {
None
} else {
Some(a)
}
}
/// Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is
/// larger than or equal to the number of bits in `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(0x1).checked_shl(4), Some(U256::new(0x10)));
/// assert_eq!(U256::new(0x10).checked_shl(257), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_shl(self, rhs: u32) -> Option<Self> {
let (a, b) = self.overflowing_shl(rhs);
if b {
None
} else {
Some(a)
}
}
/// Checked shift right. Computes `self >> rhs`, returning `None` if `rhs`
/// is larger than or equal to the number of bits in `self`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(0x10).checked_shr(4), Some(U256::new(0x1)));
/// assert_eq!(U256::new(0x10).checked_shr(257), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_shr(self, rhs: u32) -> Option<Self> {
let (a, b) = self.overflowing_shr(rhs);
if b {
None
} else {
Some(a)
}
}
/// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
/// overflow occurred.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(2).checked_pow(5), Some(U256::new(32)));
/// assert_eq!(U256::MAX.checked_pow(2), None);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn checked_pow(self, mut exp: u32) -> Option<Self> {
let mut base = self;
let mut acc = U256::ONE;
while exp > 1 {
if (exp & 1) == 1 {
acc = acc.checked_mul(base)?;
}
exp /= 2;
base = base.checked_mul(base)?;
}
// Deal with the final bit of the exponent separately, since
// squaring the base afterwards is not necessary and may cause a
// needless overflow.
if exp == 1 {
acc = acc.checked_mul(base)?;
}
Some(acc)
}
/// Saturating integer addition. Computes `self + rhs`, saturating at the
/// numeric bounds instead of overflowing.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).saturating_add(U256::new(1)), U256::new(101));
/// assert_eq!(U256::MAX.saturating_add(U256::new(127)), U256::MAX);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn saturating_add(self, rhs: Self) -> Self {
self.checked_add(rhs).unwrap_or(U256::MAX)
}
/// Saturating integer subtraction. Computes `self - rhs`, saturating at the
/// numeric bounds instead of overflowing.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).saturating_sub(U256::new(27)), U256::new(73));
/// assert_eq!(U256::new(13).saturating_sub(U256::new(127)), U256::new(0));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn saturating_sub(self, rhs: Self) -> Self {
self.checked_sub(rhs).unwrap_or(U256::MIN)
}
/// Saturating integer multiplication. Computes `self * rhs`, saturating at
/// the numeric bounds instead of overflowing.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(2).saturating_mul(U256::new(10)), U256::new(20));
/// assert_eq!((U256::MAX).saturating_mul(U256::new(10)), U256::MAX);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn saturating_mul(self, rhs: Self) -> Self {
match self.checked_mul(rhs) {
Some(x) => x,
None => Self::MAX,
}
}
/// Saturating integer division. Computes `self / rhs`, saturating at the
/// numeric bounds instead of overflowing.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).saturating_div(U256::new(2)), U256::new(2));
/// ```
///
/// ```should_panic
/// # use ethnum::U256;
/// let _ = U256::new(1).saturating_div(U256::ZERO);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn saturating_div(self, rhs: Self) -> Self {
// on unsigned types, there is no overflow in integer division
self.wrapping_div(rhs)
}
/// Saturating integer exponentiation. Computes `self.pow(exp)`, saturating
/// at the numeric bounds instead of overflowing.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(4).saturating_pow(3), U256::new(64));
/// assert_eq!(U256::MAX.saturating_pow(2), U256::MAX);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn saturating_pow(self, exp: u32) -> Self {
match self.checked_pow(exp) {
Some(x) => x,
None => Self::MAX,
}
}
/// Wrapping (modular) addition. Computes `self + rhs`, wrapping around at
/// the boundary of the type.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(200).wrapping_add(U256::new(55)), U256::new(255));
/// assert_eq!(U256::new(200).wrapping_add(U256::MAX), U256::new(199));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_add(self, rhs: Self) -> Self {
let mut result = MaybeUninit::uninit();
intrinsics::signed::uadd3(&mut result, &self, &rhs);
unsafe { result.assume_init() }
}
/// Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around
/// at the boundary of the type.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).wrapping_sub(U256::new(100)), U256::new(0));
/// assert_eq!(U256::new(100).wrapping_sub(U256::MAX), U256::new(101));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_sub(self, rhs: Self) -> Self {
let mut result = MaybeUninit::uninit();
intrinsics::signed::usub3(&mut result, &self, &rhs);
unsafe { result.assume_init() }
}
/// Wrapping (modular) multiplication. Computes `self * rhs`, wrapping
/// around at the boundary of the type.
///
/// # Examples
///
/// Basic usage:
///
/// Please note that this example is shared between integer types.
/// Which explains why `u8` is used here.
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(10).wrapping_mul(U256::new(12)), U256::new(120));
/// assert_eq!(U256::MAX.wrapping_mul(U256::new(2)), U256::MAX - 1);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_mul(self, rhs: Self) -> Self {
let mut result = MaybeUninit::uninit();
intrinsics::signed::umul3(&mut result, &self, &rhs);
unsafe { result.assume_init() }
}
/// Wrapping (modular) division. Computes `self / rhs`. Wrapped division on
/// unsigned types is just normal division. There's no way wrapping could
/// ever happen. This function exists, so that all operations are accounted
/// for in the wrapping operations.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).wrapping_div(U256::new(10)), U256::new(10));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_div(self, rhs: Self) -> Self {
self / rhs
}
/// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`. Wrapped
/// division on unsigned types is just normal division. There's no way
/// wrapping could ever happen. This function exists, so that all operations
/// are accounted for in the wrapping operations. Since, for the positive
/// integers, all common definitions of division are equal, this is exactly
/// equal to `self.wrapping_div(rhs)`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).wrapping_div_euclid(U256::new(10)), U256::new(10));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_div_euclid(self, rhs: Self) -> Self {
self / rhs
}
/// Wrapping (modular) remainder. Computes `self % rhs`. Wrapped remainder
/// calculation on unsigned types is just the regular remainder calculation.
/// There's no way wrapping could ever happen. This function exists, so that
/// all operations are accounted for in the wrapping operations.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).wrapping_rem(U256::new(10)), U256::new(0));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_rem(self, rhs: Self) -> Self {
self % rhs
}
/// Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`. Wrapped
/// modulo calculation on unsigned types is just the regular remainder
/// calculation. There's no way wrapping could ever happen. This function
/// exists, so that all operations are accounted for in the wrapping
/// operations. Since, for the positive integers, all common definitions of
/// division are equal, this is exactly equal to `self.wrapping_rem(rhs)`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).wrapping_rem_euclid(U256::new(10)), U256::new(0));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_rem_euclid(self, rhs: Self) -> Self {
self % rhs
}
/// Wrapping (modular) negation. Computes `-self`, wrapping around at the
/// boundary of the type.
///
/// Since unsigned types do not have negative equivalents all applications
/// of this function will wrap (except for `-0`). For values smaller than
/// the corresponding signed type's maximum the result is the same as
/// casting the corresponding signed value. Any larger values are equivalent
/// to `MAX + 1 - (val - MAX - 1)` where `MAX` is the corresponding signed
/// type's maximum.
///
/// # Examples
///
/// Basic usage:
///
/// Please note that this example is shared between integer types.
/// Which explains why `i8` is used here.
///
/// ```
/// # use ethnum::{U256, AsU256};
/// assert_eq!(U256::new(100).wrapping_neg(), (-100i128).as_u256());
/// assert_eq!(
/// U256::from_words(i128::MIN as _, 0).wrapping_neg(),
/// U256::from_words(i128::MIN as _, 0),
/// );
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_neg(self) -> Self {
self.overflowing_neg().0
}
/// Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask`
/// removes any high-order bits of `rhs` that would cause the shift to
/// exceed the bitwidth of the type.
///
/// Note that this is *not* the same as a rotate-left; the RHS of a wrapping
/// shift-left is restricted to the range of the type, rather than the bits
/// shifted out of the LHS being returned to the other end. The primitive
/// integer types all implement a `rotate_left` function, which maybe what
/// you want instead.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(1).wrapping_shl(7), U256::new(128));
/// assert_eq!(U256::new(1).wrapping_shl(128), U256::from_words(1, 0));
/// assert_eq!(U256::new(1).wrapping_shl(256), U256::new(1));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_shl(self, rhs: u32) -> Self {
let mut result = MaybeUninit::uninit();
intrinsics::signed::ushl3(&mut result, &self, rhs & 0xff);
unsafe { result.assume_init() }
}
/// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask`
/// removes any high-order bits of `rhs` that would cause the shift to
/// exceed the bitwidth of the type.
///
/// Note that this is *not* the same as a rotate-right; the RHS of a
/// wrapping shift-right is restricted to the range of the type, rather than
/// the bits shifted out of the LHS being returned to the other end. The
/// primitive integer types all implement a `rotate_right` function, which
/// may be what you want instead.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(128).wrapping_shr(7), U256::new(1));
/// assert_eq!(U256::from_words(128, 0).wrapping_shr(128), U256::new(128));
/// assert_eq!(U256::new(128).wrapping_shr(256), U256::new(128));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_shr(self, rhs: u32) -> Self {
let mut result = MaybeUninit::uninit();
intrinsics::signed::ushr3(&mut result, &self, rhs & 0xff);
unsafe { result.assume_init() }
}
/// Wrapping (modular) exponentiation. Computes `self.pow(exp)`, wrapping
/// around at the boundary of the type.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(3).wrapping_pow(5), U256::new(243));
/// assert_eq!(
/// U256::new(1337).wrapping_pow(42),
/// U256::from_words(
/// 45367329835866155830012179193722278514,
/// 159264946433345088039815329994094210673,
/// ),
/// );
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn wrapping_pow(self, mut exp: u32) -> Self {
let mut base = self;
let mut acc = U256::ONE;
while exp > 1 {
if (exp & 1) == 1 {
acc = acc.wrapping_mul(base);
}
exp /= 2;
base = base.wrapping_mul(base);
}
// Deal with the final bit of the exponent separately, since
// squaring the base afterwards is not necessary and may cause a
// needless overflow.
if exp == 1 {
acc = acc.wrapping_mul(base);
}
acc
}
/// Calculates `self` + `rhs`
///
/// Returns a tuple of the addition along with a boolean indicating whether
/// an arithmetic overflow would occur. If an overflow would have occurred
/// then the wrapped value is returned.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).overflowing_add(U256::new(2)), (U256::new(7), false));
/// assert_eq!(U256::MAX.overflowing_add(U256::new(1)), (U256::new(0), true));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_add(self, rhs: Self) -> (Self, bool) {
let mut result = MaybeUninit::uninit();
let overflow = intrinsics::signed::uaddc(&mut result, &self, &rhs);
(unsafe { result.assume_init() }, overflow)
}
/// Calculates `self` - `rhs`
///
/// Returns a tuple of the subtraction along with a boolean indicating
/// whether an arithmetic overflow would occur. If an overflow would have
/// occurred then the wrapped value is returned.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).overflowing_sub(U256::new(2)), (U256::new(3), false));
/// assert_eq!(U256::new(0).overflowing_sub(U256::new(1)), (U256::MAX, true));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
let mut result = MaybeUninit::uninit();
let overflow = intrinsics::signed::usubc(&mut result, &self, &rhs);
(unsafe { result.assume_init() }, overflow)
}
/// Computes the absolute difference between `self` and `other`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(100).abs_diff(U256::new(80)), 20);
/// assert_eq!(U256::new(100).abs_diff(U256::new(110)), 10);
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn abs_diff(self, other: Self) -> Self {
if self < other {
other - self
} else {
self - other
}
}
/// Calculates the multiplication of `self` and `rhs`.
///
/// Returns a tuple of the multiplication along with a boolean indicating
/// whether an arithmetic overflow would occur. If an overflow would have
/// occurred then the wrapped value is returned.
///
/// # Examples
///
/// Basic usage:
///
/// Please note that this example is shared between integer types.
/// Which explains why `u32` is used here.
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).overflowing_mul(U256::new(2)), (U256::new(10), false));
/// assert_eq!(
/// U256::MAX.overflowing_mul(U256::new(2)),
/// (U256::MAX - 1, true),
/// );
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
let mut result = MaybeUninit::uninit();
let overflow = intrinsics::signed::umulc(&mut result, &self, &rhs);
(unsafe { result.assume_init() }, overflow)
}
/// Calculates the divisor when `self` is divided by `rhs`.
///
/// Returns a tuple of the divisor along with a boolean indicating whether
/// an arithmetic overflow would occur. Note that for unsigned integers
/// overflow never occurs, so the second value is always `false`.
///
/// # Panics
///
/// This function will panic if `rhs` is 0.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).overflowing_div(U256::new(2)), (U256::new(2), false));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_div(self, rhs: Self) -> (Self, bool) {
(self / rhs, false)
}
/// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
///
/// Returns a tuple of the divisor along with a boolean indicating whether
/// an arithmetic overflow would occur. Note that for unsigned integers
/// overflow never occurs, so the second value is always `false`. Since,
/// for the positive integers, all common definitions of division are equal,
/// this is exactly equal to `self.overflowing_div(rhs)`.
///
/// # Panics
///
/// This function will panic if `rhs` is 0.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).overflowing_div_euclid(U256::new(2)), (U256::new(2), false));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
(self / rhs, false)
}
/// Calculates the remainder when `self` is divided by `rhs`.
///
/// Returns a tuple of the remainder after dividing along with a boolean
/// indicating whether an arithmetic overflow would occur. Note that for
/// unsigned integers overflow never occurs, so the second value is always
/// `false`.
///
/// # Panics
///
/// This function will panic if `rhs` is 0.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).overflowing_rem(U256::new(2)), (U256::new(1), false));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
(self % rhs, false)
}
/// Calculates the remainder `self.rem_euclid(rhs)` as if by Euclidean
/// division.
///
/// Returns a tuple of the modulo after dividing along with a boolean
/// indicating whether an arithmetic overflow would occur. Note that for
/// unsigned integers overflow never occurs, so the second value is always
/// `false`. Since, for the positive integers, all common definitions of
/// division are equal, this operation is exactly equal to
/// `self.overflowing_rem(rhs)`.
///
/// # Panics
///
/// This function will panic if `rhs` is 0.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(5).overflowing_rem_euclid(U256::new(2)), (U256::new(1), false));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
(self % rhs, false)
}
/// Negates self in an overflowing fashion.
///
/// Returns `!self + 1` using wrapping operations to return the value that
/// represents the negation of this unsigned value. Note that for positive
/// unsigned values overflow always occurs, but negating 0 does not
/// overflow.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::{U256, AsU256};
/// assert_eq!(U256::new(0).overflowing_neg(), (U256::new(0), false));
/// assert_eq!(U256::new(2).overflowing_neg(), ((-2i32).as_u256(), true));
/// ```
#[inline]
pub fn overflowing_neg(self) -> (Self, bool) {
((!self).wrapping_add(U256::ONE), self != U256::ZERO)
}
/// Shifts self left by `rhs` bits.
///
/// Returns a tuple of the shifted version of self along with a boolean
/// indicating whether the shift value was larger than or equal to the
/// number of bits. If the shift value is too large, then value is masked
/// (N-1) where N is the number of bits, and this value is then used to
/// perform the shift.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(0x1).overflowing_shl(4), (U256::new(0x10), false));
/// assert_eq!(U256::new(0x1).overflowing_shl(260), (U256::new(0x10), true));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
(self.wrapping_shl(rhs), rhs > 255)
}
/// Shifts self right by `rhs` bits.
///
/// Returns a tuple of the shifted version of self along with a boolean
/// indicating whether the shift value was larger than or equal to the
/// number of bits. If the shift value is too large, then value is masked
/// (N-1) where N is the number of bits, and this value is then used to
/// perform the shift.
///
/// # Examples
///
/// Basic usage
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(0x10).overflowing_shr(4), (U256::new(0x1), false));
/// assert_eq!(U256::new(0x10).overflowing_shr(260), (U256::new(0x1), true));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
(self.wrapping_shr(rhs), rhs > 255)
}
/// Raises self to the power of `exp`, using exponentiation by squaring.
///
/// Returns a tuple of the exponentiation along with a bool indicating
/// whether an overflow happened.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(3).overflowing_pow(5), (U256::new(243), false));
/// assert_eq!(
/// U256::new(1337).overflowing_pow(42),
/// (
/// U256::from_words(
/// 45367329835866155830012179193722278514,
/// 159264946433345088039815329994094210673,
/// ),
/// true,
/// )
/// );
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
let mut base = self;
let mut acc = U256::ONE;
let mut overflown = false;
// Scratch space for storing results of overflowing_mul.
let mut r;
while exp > 1 {
if (exp & 1) == 1 {
r = acc.overflowing_mul(base);
acc = r.0;
overflown |= r.1;
}
exp /= 2;
r = base.overflowing_mul(base);
base = r.0;
overflown |= r.1;
}
// Deal with the final bit of the exponent separately, since
// squaring the base afterwards is not necessary and may cause a
// needless overflow.
if exp == 1 {
r = acc.overflowing_mul(base);
acc = r.0;
overflown |= r.1;
}
(acc, overflown)
}
/// Raises self to the power of `exp`, using exponentiation by squaring.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(2).pow(5), U256::new(32));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn pow(self, mut exp: u32) -> Self {
let mut base = self;
let mut acc = U256::ONE;
while exp > 1 {
if (exp & 1) == 1 {
acc *= base;
}
exp /= 2;
base = base * base;
}
// Deal with the final bit of the exponent separately, since
// squaring the base afterwards is not necessary and may cause a
// needless overflow.
if exp == 1 {
acc *= base;
}
acc
}
/// Performs Euclidean division.
///
/// Since, for the positive integers, all common definitions of division are
/// equal, this is exactly equal to `self / rhs`.
///
/// # Panics
///
/// This function will panic if `rhs` is 0.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(7).div_euclid(U256::new(4)), U256::new(1));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn div_euclid(self, rhs: Self) -> Self {
self / rhs
}
/// Calculates the least remainder of `self (mod rhs)`.
///
/// Since, for the positive integers, all common definitions of division are
/// equal, this is exactly equal to `self % rhs`.
///
/// # Panics
///
/// This function will panic if `rhs` is 0.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(7).rem_euclid(U256::new(4)), U256::new(3));
/// ```
#[must_use = "this returns the result of the operation, \
without modifying the original"]
#[inline]
pub fn rem_euclid(self, rhs: Self) -> Self {
self % rhs
}
/// Returns `true` if and only if `self == 2^k` for some `k`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert!(U256::new(16).is_power_of_two());
/// assert!(!U256::new(10).is_power_of_two());
/// ```
#[inline]
pub fn is_power_of_two(self) -> bool {
self.count_ones() == 1
}
/// Returns one less than next power of two. (For 8u8 next power of two is
/// 8u8 and for 6u8 it is 8u8).
///
/// 8u8.one_less_than_next_power_of_two() == 7
/// 6u8.one_less_than_next_power_of_two() == 7
///
/// This method cannot overflow, as in the `next_power_of_two` overflow
/// cases it instead ends up returning the maximum value of the type, and
/// can return 0 for 0.
#[inline]
fn one_less_than_next_power_of_two(self) -> Self {
if self <= 1 {
return U256::ZERO;
}
let p = self - 1;
let z = p.leading_zeros();
U256::MAX >> z
}
/// Returns the smallest power of two greater than or equal to `self`.
///
/// When return value overflows (i.e., `self > (1 << (N-1))` for type `uN`),
/// it panics in debug mode and return value is wrapped to 0 in release mode
/// (the only situation in which method can return 0).
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(2).next_power_of_two(), U256::new(2));
/// assert_eq!(U256::new(3).next_power_of_two(), U256::new(4));
/// ```
#[inline]
pub fn next_power_of_two(self) -> Self {
self.one_less_than_next_power_of_two() + 1
}
/// Returns the smallest power of two greater than or equal to `n`. If the
/// next power of two is greater than the type's maximum value, `None` is
/// returned, otherwise the power of two is wrapped in `Some`.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// # use ethnum::U256;
/// assert_eq!(U256::new(2).checked_next_power_of_two(), Some(U256::new(2)));
/// assert_eq!(U256::new(3).checked_next_power_of_two(), Some(U256::new(4)));
/// assert_eq!(U256::MAX.checked_next_power_of_two(), None);
/// ```
#[inline]
pub fn checked_next_power_of_two(self) -> Option<Self> {
self.one_less_than_next_power_of_two()
.checked_add(U256::ONE)
}
/// Return the memory representation of this integer as a byte array in big
/// endian (network) byte order.
///
/// # Examples
///
/// ```
/// # use ethnum::U256;
/// let bytes = U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// );
/// assert_eq!(
/// bytes.to_be_bytes(),
/// [
/// 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
/// 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
/// ],
/// );
/// ```
#[inline]
pub fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
self.to_be().to_ne_bytes()
}
/// Return the memory representation of this integer as a byte array in
/// little endian byte order.
///
/// # Examples
///
/// ```
/// # use ethnum::U256;
/// let bytes = U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// );
/// assert_eq!(
/// bytes.to_le_bytes(),
/// [
/// 0x1f, 0x1e, 0x1d, 0x1c, 0x1b, 0x1a, 0x19, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11, 0x10,
/// 0x0f, 0x0e, 0x0d, 0x0c, 0x0b, 0x0a, 0x09, 0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01, 0x00,
/// ],
/// );
/// ```
#[inline]
pub fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
self.to_le().to_ne_bytes()
}
/// Return the memory representation of this integer as a byte array in
/// native byte order.
///
/// As the target platform's native endianness is used, portable code should
/// use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, instead.
///
/// [`to_be_bytes`]: #method.to_be_bytes
/// [`to_le_bytes`]: #method.to_le_bytes
///
/// # Examples
///
/// ```
/// # use ethnum::U256;
/// let bytes = U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// );
/// assert_eq!(
/// bytes.to_ne_bytes(),
/// if cfg!(target_endian = "big") {
/// [
/// 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
/// 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
/// ]
/// } else {
/// [
/// 0x1f, 0x1e, 0x1d, 0x1c, 0x1b, 0x1a, 0x19, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11, 0x10,
/// 0x0f, 0x0e, 0x0d, 0x0c, 0x0b, 0x0a, 0x09, 0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01, 0x00,
/// ]
/// }
/// );
/// ```
#[inline]
pub fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
unsafe { mem::transmute(self) }
}
/// Create an integer value from its representation as a byte array in big
/// endian.
///
/// # Examples
///
/// ```
/// # use ethnum::U256;
/// let value = U256::from_be_bytes([
/// 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
/// 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
/// ]);
/// assert_eq!(
/// value,
/// U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// ),
/// );
/// ```
///
/// When starting from a slice rather than an array, fallible conversion
/// APIs can be used:
///
/// ```
/// # use ethnum::U256;
/// use std::convert::TryInto;
///
/// fn read_be_u256(input: &mut &[u8]) -> U256 {
/// let (int_bytes, rest) = input.split_at(std::mem::size_of::<U256>());
/// *input = rest;
/// U256::from_be_bytes(int_bytes.try_into().unwrap())
/// }
/// ```
#[inline]
pub fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
Self::from_be(Self::from_ne_bytes(bytes))
}
/// Create an integer value from its representation as a byte array in
/// little endian.
///
/// # Examples
///
/// ```
/// # use ethnum::U256;
/// let value = U256::from_le_bytes([
/// 0x1f, 0x1e, 0x1d, 0x1c, 0x1b, 0x1a, 0x19, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11, 0x10,
/// 0x0f, 0x0e, 0x0d, 0x0c, 0x0b, 0x0a, 0x09, 0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01, 0x00,
/// ]);
/// assert_eq!(
/// value,
/// U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// ),
/// );
/// ```
///
/// When starting from a slice rather than an array, fallible conversion
/// APIs can be used:
///
/// ```
/// # use ethnum::U256;
/// use std::convert::TryInto;
///
/// fn read_be_u256(input: &mut &[u8]) -> U256 {
/// let (int_bytes, rest) = input.split_at(std::mem::size_of::<U256>());
/// *input = rest;
/// U256::from_le_bytes(int_bytes.try_into().unwrap())
/// }
/// ```
#[inline]
pub fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
Self::from_le(Self::from_ne_bytes(bytes))
}
/// Create an integer value from its memory representation as a byte array
/// in native endianness.
///
/// As the target platform's native endianness is used, portable code likely
/// wants to use [`from_be_bytes`] or [`from_le_bytes`], as appropriate
/// instead.
///
/// [`from_be_bytes`]: #method.from_be_bytes
/// [`from_le_bytes`]: #method.from_le_bytes
///
/// # Examples
///
/// ```
/// # use ethnum::U256;
/// let value = U256::from_ne_bytes(if cfg!(target_endian = "big") {
/// [
/// 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
/// 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
/// ]
/// } else {
/// [
/// 0x1f, 0x1e, 0x1d, 0x1c, 0x1b, 0x1a, 0x19, 0x18, 0x17, 0x16, 0x15, 0x14, 0x13, 0x12, 0x11, 0x10,
/// 0x0f, 0x0e, 0x0d, 0x0c, 0x0b, 0x0a, 0x09, 0x08, 0x07, 0x06, 0x05, 0x04, 0x03, 0x02, 0x01, 0x00,
/// ]
/// });
/// assert_eq!(
/// value,
/// U256::from_words(
/// 0x00010203_04050607_08090a0b_0c0d0e0f,
/// 0x10111213_14151617_18191a1b_1c1d1e1f,
/// ),
/// );
/// ```
///
/// When starting from a slice rather than an array, fallible conversion
/// APIs can be used:
///
/// ```
/// # use ethnum::U256;
/// use std::convert::TryInto;
///
/// fn read_be_u256(input: &mut &[u8]) -> U256 {
/// let (int_bytes, rest) = input.split_at(std::mem::size_of::<U256>());
/// *input = rest;
/// U256::from_ne_bytes(int_bytes.try_into().unwrap())
/// }
/// ```
#[inline]
pub fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
unsafe { mem::transmute(bytes) }
}
}