pub struct SqlUint<const BITS: usize, const LIMBS: usize>(/* private fields */);
Expand description
A SQL-compatible wrapper for 256-bit unsigned integers.
SqlU256
wraps alloy::primitives::U256
and implements all necessary traits
for seamless SQLx database integration. It provides full arithmetic operations,
type conversions, and consistent hexadecimal storage format across databases.
§Features
- Arithmetic Operations: Supports +, -, *, /, %, bitwise operations, and more
- Type Conversions: Convert from/to various integer types with overflow checking
- Database Storage: Consistent hexadecimal format (0x…) across all databases
- Input Flexibility:
FromStr
accepts both decimal and hexadecimal strings - SQLx Integration: Implements
Type
,Encode
, andDecode
for MySQL, PostgreSQL, SQLite
§Examples
use ethereum_mysql::SqlU256;
use alloy::primitives::U256;
use std::str::FromStr;
// Create from various types
let from_u64 = SqlU256::from(42u64);
let from_decimal = SqlU256::from_str("123456789").unwrap();
let from_hex = SqlU256::from_str("0x75bcd15").unwrap();
let zero = SqlU256::ZERO;
// Arithmetic operations
let a = SqlU256::from(100u64);
let b = SqlU256::from(50u64);
let sum = a + b; // 150
let product = a * b; // 5000
let power = a.pow(2); // 10000
// Safe operations
let checked = a.checked_add(b); // Some(150)
let saturated = a.saturating_sub(SqlU256::from(200u64)); // 0
// Type conversions
let back_to_u256: U256 = from_u64.into(); // SqlU256 -> U256 (always safe)
let back_to_u64: u64 = from_u64.try_into().unwrap(); // SqlU256 -> u64 (may overflow)
Implementations§
Source§impl SqlUint<256, 4>
impl SqlUint<256, 4>
Sourcepub fn pow(self, exp: usize) -> Self
pub fn pow(self, exp: usize) -> Self
Returns the power of this value raised to the given exponent
Sourcepub fn checked_add(self, rhs: Self) -> Option<Self>
pub fn checked_add(self, rhs: Self) -> Option<Self>
Checked addition. Returns None
if overflow occurred.
Sourcepub fn checked_sub(self, rhs: Self) -> Option<Self>
pub fn checked_sub(self, rhs: Self) -> Option<Self>
Checked subtraction. Returns None
if overflow occurred.
Sourcepub fn checked_mul(self, rhs: Self) -> Option<Self>
pub fn checked_mul(self, rhs: Self) -> Option<Self>
Checked multiplication. Returns None
if overflow occurred.
Sourcepub fn checked_div(self, rhs: Self) -> Option<Self>
pub fn checked_div(self, rhs: Self) -> Option<Self>
Checked division. Returns None
if rhs == 0
.
Sourcepub fn saturating_add(self, rhs: Self) -> Self
pub fn saturating_add(self, rhs: Self) -> Self
Saturating addition. Clamps the result to U256::MAX
if overflow occurred.
Sourcepub fn saturating_sub(self, rhs: Self) -> Self
pub fn saturating_sub(self, rhs: Self) -> Self
Saturating subtraction. Clamps the result to 0
if underflow occurred.
Sourcepub fn saturating_mul(self, rhs: Self) -> Self
pub fn saturating_mul(self, rhs: Self) -> Self
Saturating multiplication. Clamps the result to U256::MAX
if overflow occurred.
Source§impl<const BITS: usize, const LIMBS: usize> SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> SqlUint<BITS, LIMBS>
Sourcepub const ZERO: Self
pub const ZERO: Self
Creates a new SqlUint
from a Uint
value.
§Examples
Equivalent to SqlU256::from(0u64)
but available as a compile-time constant.
Sourcepub fn inner(&self) -> &Uint<BITS, LIMBS>
pub fn inner(&self) -> &Uint<BITS, LIMBS>
Returns a reference to the inner U256
value.
This is useful when you need to interact with APIs that expect U256
directly.
§Examples
use ethereum_mysql::SqlU256;
let sql_u256 = SqlU256::from(42u64);
let inner_ref: &alloy::primitives::U256 = sql_u256.inner();
Sourcepub fn into_inner(self) -> Uint<BITS, LIMBS>
pub fn into_inner(self) -> Uint<BITS, LIMBS>
Consumes self and returns the inner Uint value.
Source§impl SqlUint<256, 4>
impl SqlUint<256, 4>
Sourcepub fn from_be_slice(bytes: &[u8]) -> Self
pub fn from_be_slice(bytes: &[u8]) -> Self
Creates a SqlU256 from a big-endian byte slice (pads/truncates as alloy U256).
Sourcepub fn as_u8(&self) -> Result<u8, &'static str>
pub fn as_u8(&self) -> Result<u8, &'static str>
Try to convert this value to u8. Returns Err if out of range.
Sourcepub fn as_u16(&self) -> Result<u16, &'static str>
pub fn as_u16(&self) -> Result<u16, &'static str>
Try to convert this value to u16. Returns Err if out of range.
Sourcepub fn as_u32(&self) -> Result<u32, &'static str>
pub fn as_u32(&self) -> Result<u32, &'static str>
Try to convert this value to u32. Returns Err if out of range.
Methods from Deref<Target = Uint<BITS, LIMBS>>§
Sourcepub fn to_base_le(&self, base: u64) -> impl Iterator<Item = u64>
pub fn to_base_le(&self, base: u64) -> impl Iterator<Item = u64>
Returns an iterator over the base base
digits of the number in
little-endian order.
Pro tip: instead of setting base = 10
, set it to the highest
power of 10
that still fits u64
. This way much fewer iterations
are required to extract all the digits.
§Panics
Panics if the base is less than 2.
Sourcepub fn to_base_be(&self, base: u64) -> impl Iterator<Item = u64>
pub fn to_base_be(&self, base: u64) -> impl Iterator<Item = u64>
Returns an iterator over the base base
digits of the number in
big-endian order.
Pro tip: instead of setting base = 10
, set it to the highest
power of 10
that still fits u64
. This way much fewer iterations
are required to extract all the digits.
§Panics
Panics if the base is less than 2.
Sourcepub fn bit(&self, index: usize) -> bool
pub fn bit(&self, index: usize) -> bool
Returns whether a specific bit is set.
Returns false
if index
exceeds the bit width of the number.
Sourcepub fn byte(&self, index: usize) -> u8
pub fn byte(&self, index: usize) -> u8
Returns a specific byte. The byte at index 0
is the least significant
byte (little endian).
§Panics
Panics if index
is greater than or equal to the byte width of the
number.
§Examples
let x = uint!(0x1234567890_U64);
let bytes = [
x.byte(0), // 0x90
x.byte(1), // 0x78
x.byte(2), // 0x56
x.byte(3), // 0x34
x.byte(4), // 0x12
x.byte(5), // 0x00
x.byte(6), // 0x00
x.byte(7), // 0x00
];
assert_eq!(bytes, x.to_le_bytes());
Panics if out of range.
let x = uint!(0x1234567890_U64);
let _ = x.byte(8);
Sourcepub fn checked_byte(&self, index: usize) -> Option<u8>
pub fn checked_byte(&self, index: usize) -> Option<u8>
Returns a specific byte, or None
if index
is out of range. The byte
at index 0
is the least significant byte (little endian).
§Examples
let x = uint!(0x1234567890_U64);
assert_eq!(x.checked_byte(0), Some(0x90));
assert_eq!(x.checked_byte(7), Some(0x00));
// Out of range
assert_eq!(x.checked_byte(8), None);
Sourcepub fn leading_zeros(&self) -> usize
pub fn leading_zeros(&self) -> usize
Returns the number of leading zeros in the binary representation of
self
.
Sourcepub fn leading_ones(&self) -> usize
pub fn leading_ones(&self) -> usize
Returns the number of leading ones in the binary representation of
self
.
Sourcepub fn trailing_zeros(&self) -> usize
pub fn trailing_zeros(&self) -> usize
Returns the number of trailing zeros in the binary representation of
self
.
Sourcepub fn trailing_ones(&self) -> usize
pub fn trailing_ones(&self) -> usize
Returns the number of trailing ones in the binary representation of
self
.
Sourcepub fn count_ones(&self) -> usize
pub fn count_ones(&self) -> usize
Returns the number of ones in the binary representation of self
.
Sourcepub fn count_zeros(&self) -> usize
pub fn count_zeros(&self) -> usize
Returns the number of zeros in the binary representation of self
.
Sourcepub fn bit_len(&self) -> usize
pub fn bit_len(&self) -> usize
Returns the dynamic length of this number in bits, ignoring leading zeros.
For the maximum length of the type, use Uint::BITS
.
Sourcepub fn byte_len(&self) -> usize
pub fn byte_len(&self) -> usize
Returns the dynamic length of this number in bytes, ignoring leading zeros.
For the maximum length of the type, use Uint::BYTES
.
Sourcepub fn most_significant_bits(&self) -> (u64, usize)
pub fn most_significant_bits(&self) -> (u64, usize)
Returns the most significant 64 bits of the number and the exponent.
Given return value $(\mathtt{bits}, \mathtt{exponent})$, the self
can
be approximated as
$$ \mathtt{self} ≈ \mathtt{bits} ⋅ 2^\mathtt{exponent} $$
If self
is $<≥> 2^{63}$, then exponent
will be zero and bits
will
have leading zeros.
pub const BYTES: usize
Sourcepub fn as_le_slice(&self) -> &[u8] ⓘ
pub fn as_le_slice(&self) -> &[u8] ⓘ
Access the underlying store as a little-endian slice of bytes.
Only available on little-endian targets.
If BITS
does not evenly divide 8, it is padded with zero bits in the
most significant position.
Sourcepub fn as_le_bytes(&self) -> Cow<'_, [u8]>
pub fn as_le_bytes(&self) -> Cow<'_, [u8]>
Access the underlying store as a little-endian bytes.
Uses an optimized implementation on little-endian targets.
Sourcepub fn as_le_bytes_trimmed(&self) -> Cow<'_, [u8]>
pub fn as_le_bytes_trimmed(&self) -> Cow<'_, [u8]>
Access the underlying store as a little-endian bytes with trailing zeros removed.
Uses an optimized implementation on little-endian targets.
Sourcepub fn to_le_bytes<const BYTES: usize>(&self) -> [u8; BYTES]
pub fn to_le_bytes<const BYTES: usize>(&self) -> [u8; BYTES]
Converts the Uint
to a little-endian byte array of size exactly
Self::BYTES
.
§Panics
Panics if the generic parameter BYTES
is not exactly Self::BYTES
.
Ideally this would be a compile time error, but this is blocked by
Rust issue #60551.
Sourcepub fn to_le_bytes_vec(&self) -> Vec<u8> ⓘ
pub fn to_le_bytes_vec(&self) -> Vec<u8> ⓘ
Converts the Uint
to a little-endian byte vector of size exactly
Self::BYTES
.
This method is useful when Self::to_le_bytes
can not be used because
byte size is not known compile time.
Sourcepub fn to_le_bytes_trimmed_vec(&self) -> Vec<u8> ⓘ
pub fn to_le_bytes_trimmed_vec(&self) -> Vec<u8> ⓘ
Converts the Uint
to a little-endian byte vector with trailing zeros
bytes removed.
Sourcepub fn to_be_bytes<const BYTES: usize>(&self) -> [u8; BYTES]
pub fn to_be_bytes<const BYTES: usize>(&self) -> [u8; BYTES]
Converts the Uint
to a big-endian byte array of size exactly
Self::BYTES
.
§Panics
Panics if the generic parameter BYTES
is not exactly Self::BYTES
.
Ideally this would be a compile time error, but this is blocked by
Rust issue #60551.
Sourcepub fn to_be_bytes_vec(&self) -> Vec<u8> ⓘ
pub fn to_be_bytes_vec(&self) -> Vec<u8> ⓘ
Converts the Uint
to a big-endian byte vector of size exactly
Self::BYTES
.
This method is useful when Self::to_be_bytes
can not be used because
byte size is not known compile time.
Sourcepub fn to_be_bytes_trimmed_vec(&self) -> Vec<u8> ⓘ
pub fn to_be_bytes_trimmed_vec(&self) -> Vec<u8> ⓘ
Converts the Uint
to a big-endian byte vector with leading zeros
bytes removed.
Sourcepub fn copy_le_bytes_to(&self, buf: &mut [u8]) -> usize
pub fn copy_le_bytes_to(&self, buf: &mut [u8]) -> usize
Writes the little-endian representation of the Uint
to the given
buffer. The buffer must be large enough to hold Self::BYTES
bytes.
§Panics
Panics if the buffer is not large enough to hold Self::BYTES
bytes.
§Returns
The number of bytes written to the buffer (always equal to
Self::BYTES
, but often useful to make explicit for encoders).
Sourcepub fn checked_copy_le_bytes_to(&self, buf: &mut [u8]) -> Option<usize>
pub fn checked_copy_le_bytes_to(&self, buf: &mut [u8]) -> Option<usize>
Writes the little-endian representation of the Uint
to the given
buffer. The buffer must be large enough to hold Self::BYTES
bytes.
§Returns
None
, if the buffer is not large enough to hold Self::BYTES
bytes, and does not modify the buffer.
Some
with the number of bytes written to the buffer (always
equal to Self::BYTES
, but often useful to make explicit for
encoders).
Sourcepub fn copy_be_bytes_to(&self, buf: &mut [u8]) -> usize
pub fn copy_be_bytes_to(&self, buf: &mut [u8]) -> usize
Writes the big-endian representation of the Uint
to the given
buffer. The buffer must be large enough to hold Self::BYTES
bytes.
§Panics
Panics if the buffer is not large enough to hold Self::BYTES
bytes.
§Returns
The number of bytes written to the buffer (always equal to
Self::BYTES
, but often useful to make explicit for encoders).
Sourcepub fn checked_copy_be_bytes_to(&self, buf: &mut [u8]) -> Option<usize>
pub fn checked_copy_be_bytes_to(&self, buf: &mut [u8]) -> Option<usize>
Writes the big-endian representation of the Uint
to the given
buffer. The buffer must be large enough to hold Self::BYTES
bytes.
§Returns
None
, if the buffer is not large enough to hold Self::BYTES
bytes, and does not modify the buffer.
Some
with the number of bytes written to the buffer (always
equal to Self::BYTES
, but often useful to make explicit for
encoders).
Sourcepub fn const_is_zero(&self) -> bool
pub fn const_is_zero(&self) -> bool
Returns true
if the value is zero.
Note that this currently might perform worse than
is_zero
.
Sourcepub fn const_eq(&self, other: &Uint<BITS, LIMBS>) -> bool
pub fn const_eq(&self, other: &Uint<BITS, LIMBS>) -> bool
Returns true
if self
equals other
.
Note that this currently might perform worse than the derived
PartialEq
(==
operator).
Sourcepub fn wrapping_to<T>(&self) -> T
pub fn wrapping_to<T>(&self) -> T
§Examples
assert_eq!(300_U12.wrapping_to::<i8>(), 44_i8);
assert_eq!(255_U32.wrapping_to::<i8>(), -1_i8);
assert_eq!(0x1337cafec0d3_U256.wrapping_to::<U32>(), 0xcafec0d3_U32);
Sourcepub fn saturating_to<T>(&self) -> T
pub fn saturating_to<T>(&self) -> T
§Examples
assert_eq!(300_U12.saturating_to::<i16>(), 300_i16);
assert_eq!(255_U32.saturating_to::<i8>(), 127);
assert_eq!(0x1337cafec0d3_U256.saturating_to::<U32>(), U32::MAX);
pub const LIMBS: usize
pub const MASK: u64
pub const BITS: usize = BITS
pub const ZERO: Uint<BITS, LIMBS>
pub const ONE: Uint<BITS, LIMBS>
pub const MIN: Uint<BITS, LIMBS> = Self::ZERO
pub const MAX: Uint<BITS, LIMBS>
Trait Implementations§
Source§impl AddAssign<&SqlUint<256, 4>> for SqlU256
impl AddAssign<&SqlUint<256, 4>> for SqlU256
Source§fn add_assign(&mut self, rhs: &Self)
fn add_assign(&mut self, rhs: &Self)
+=
operation. Read moreSource§impl<const BITS: usize, const LIMBS: usize> AsRef<Uint<BITS, LIMBS>> for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> AsRef<Uint<BITS, LIMBS>> for SqlUint<BITS, LIMBS>
Source§impl<'a, const BITS: usize, const LIMBS: usize, DB: Database> Decode<'a, DB> for SqlUint<BITS, LIMBS>
Available on crate feature sqlx
only.
impl<'a, const BITS: usize, const LIMBS: usize, DB: Database> Decode<'a, DB> for SqlUint<BITS, LIMBS>
sqlx
only.Source§impl<'de, const BITS: usize, const LIMBS: usize> Deserialize<'de> for SqlUint<BITS, LIMBS>
impl<'de, const BITS: usize, const LIMBS: usize> Deserialize<'de> for SqlUint<BITS, LIMBS>
Source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
Source§impl DivAssign<&SqlUint<256, 4>> for SqlU256
impl DivAssign<&SqlUint<256, 4>> for SqlU256
Source§fn div_assign(&mut self, rhs: &Self)
fn div_assign(&mut self, rhs: &Self)
/=
operation. Read moreSource§impl<'a, const BITS: usize, const LIMBS: usize, DB: Database> Encode<'a, DB> for SqlUint<BITS, LIMBS>
Available on crate feature sqlx
only.
impl<'a, const BITS: usize, const LIMBS: usize, DB: Database> Encode<'a, DB> for SqlUint<BITS, LIMBS>
sqlx
only.Source§fn encode_by_ref(
&self,
buf: &mut <DB as Database>::ArgumentBuffer<'a>,
) -> Result<IsNull, BoxDynError>
fn encode_by_ref( &self, buf: &mut <DB as Database>::ArgumentBuffer<'a>, ) -> Result<IsNull, BoxDynError>
Source§fn encode(
self,
buf: &mut <DB as Database>::ArgumentBuffer<'q>,
) -> Result<IsNull, Box<dyn Error + Sync + Send>>where
Self: Sized,
fn encode(
self,
buf: &mut <DB as Database>::ArgumentBuffer<'q>,
) -> Result<IsNull, Box<dyn Error + Sync + Send>>where
Self: Sized,
self
into buf
in the expected format for the database.fn produces(&self) -> Option<<DB as Database>::TypeInfo>
fn size_hint(&self) -> usize
Source§impl MulAssign<&SqlUint<256, 4>> for SqlU256
impl MulAssign<&SqlUint<256, 4>> for SqlU256
Source§fn mul_assign(&mut self, rhs: &Self)
fn mul_assign(&mut self, rhs: &Self)
*=
operation. Read moreSource§impl<const BITS: usize, const LIMBS: usize> Ord for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> Ord for SqlUint<BITS, LIMBS>
1.21.0 · Source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
Source§impl PartialOrd<SqlUint<256, 4>> for u128
impl PartialOrd<SqlUint<256, 4>> for u128
Source§impl PartialOrd<SqlUint<256, 4>> for u16
impl PartialOrd<SqlUint<256, 4>> for u16
Source§impl PartialOrd<SqlUint<256, 4>> for u32
impl PartialOrd<SqlUint<256, 4>> for u32
Source§impl PartialOrd<SqlUint<256, 4>> for u64
impl PartialOrd<SqlUint<256, 4>> for u64
Source§impl PartialOrd<SqlUint<256, 4>> for u8
impl PartialOrd<SqlUint<256, 4>> for u8
Source§impl<const BITS: usize, const LIMBS: usize> PartialOrd for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> PartialOrd for SqlUint<BITS, LIMBS>
Source§impl RemAssign<&SqlUint<256, 4>> for SqlU256
impl RemAssign<&SqlUint<256, 4>> for SqlU256
Source§fn rem_assign(&mut self, rhs: &Self)
fn rem_assign(&mut self, rhs: &Self)
%=
operation. Read moreSource§impl SubAssign<&SqlUint<256, 4>> for SqlU256
impl SubAssign<&SqlUint<256, 4>> for SqlU256
Source§fn sub_assign(&mut self, rhs: &Self)
fn sub_assign(&mut self, rhs: &Self)
-=
operation. Read moreSource§impl<const BITS: usize, const LIMBS: usize, DB: Database> Type<DB> for SqlUint<BITS, LIMBS>
Available on crate feature sqlx
only.
impl<const BITS: usize, const LIMBS: usize, DB: Database> Type<DB> for SqlUint<BITS, LIMBS>
sqlx
only.impl<const BITS: usize, const LIMBS: usize> Copy for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> Eq for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> StructuralPartialEq for SqlUint<BITS, LIMBS>
Auto Trait Implementations§
impl<const BITS: usize, const LIMBS: usize> Freeze for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> RefUnwindSafe for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> Send for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> Sync for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> Unpin for SqlUint<BITS, LIMBS>
impl<const BITS: usize, const LIMBS: usize> UnwindSafe for SqlUint<BITS, LIMBS>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more