cuprate_helper/
map.rs

Help
1//! Mapping of data types.
2//!
3//! This module provides functions solely for mapping data types into others, mostly similar ones.
4//!
5//! `#[no_std]` compatible.
6
7//---------------------------------------------------------------------------------------------------- Use
8use core::net::Ipv4Addr;
9
10use monero_serai::transaction::Timelock;
11
12use cuprate_constants::block::MAX_BLOCK_HEIGHT;
13
14use crate::cast::{u64_to_usize, usize_to_u64};
15
16//---------------------------------------------------------------------------------------------------- `(u64, u64) <-> u128`
17/// Split a [`u128`] value into 2 64-bit values.
18///
19/// The tuple returned is `(low, high)` where `low` is the least significant
20/// 64-bits of `number`, and `high` is the most significant.
21///
22/// Note that the output of this function are `u64` representations of _bits_, not numerical values.
23///
24/// See [`combine_low_high_bits_to_u128`] for the inverse function.
25///
26/// ```rust
27/// # use cuprate_helper::map::*;
28/// let value = u128::MAX - 1;
29/// let low = u64::MAX - 1;
30/// let high = u64::MAX;
31///
32/// assert_eq!(split_u128_into_low_high_bits(value), (low, high));
33/// assert_eq!(split_u128_into_low_high_bits(0), (0, 0));
34/// ```
35#[inline]
36pub const fn split_u128_into_low_high_bits(value: u128) -> (u64, u64) {
37    #[expect(clippy::cast_possible_truncation)]
38    (value as u64, (value >> 64) as u64)
39}
40
41/// Combine 2 64-bit values into a single [`u128`] value.
42///
43/// The inputs:
44/// - `low_bits` are the _least_ significant 64-bits of `cumulative_difficulty`
45/// - `high_bits` are the _most_ significant 64-bits of `cumulative_difficulty`
46///
47/// Note that `low_bits` & `high_bits` should be `u64` representation of _bits_, not numerical values.
48///
49/// See [`split_u128_into_low_high_bits`] for the inverse function.
50///
51/// ```rust
52/// # use cuprate_helper::map::*;
53/// let value = u128::MAX - 1;
54/// let low = u64::MAX - 1;
55/// let high = u64::MAX;
56///
57/// assert_eq!(combine_low_high_bits_to_u128(low, high), value);
58/// assert_eq!(combine_low_high_bits_to_u128(0, 0), 0);
59/// ```
60#[inline]
61pub const fn combine_low_high_bits_to_u128(low_bits: u64, high_bits: u64) -> u128 {
62    let res = (high_bits as u128) << 64;
63    res | (low_bits as u128)
64}
65
66//---------------------------------------------------------------------------------------------------- IPv4
67/// Convert an [`Ipv4Addr`] to a [`u32`].
68///
69/// For why this exists, see: <https://architecture.cuprate.org/oddities/le-ipv4.html>.
70#[inline]
71pub const fn ipv4_from_u32(ip: u32) -> Ipv4Addr {
72    let [a, b, c, d] = ip.to_le_bytes();
73    Ipv4Addr::new(a, b, c, d)
74}
75
76/// Convert a [`u32`] to an [`Ipv4Addr`].
77///
78/// For why this exists, see: <https://architecture.cuprate.org/oddities/le-ipv4.html>.
79#[inline]
80pub const fn u32_from_ipv4(ip: Ipv4Addr) -> u32 {
81    u32::from_le_bytes(ip.octets())
82}
83
84//---------------------------------------------------------------------------------------------------- Timelock
85/// Map a [`u64`] to a [`Timelock`].
86///
87/// Height/time is not differentiated via type, but rather:
88/// "height is any value less than [`MAX_BLOCK_HEIGHT`] and timestamp is any value above"
89/// so the `u64/usize` is stored without any tag.
90///
91/// See [`timelock_to_u64`] for the inverse function.
92///
93/// - <https://github.com/Cuprate/cuprate/pull/102#discussion_r1558504285>
94/// - <https://github.com/serai-dex/serai/blob/bc1dec79917d37d326ac3d9bc571a64131b0424a/coins/monero/src/transaction.rs#L139>
95///
96/// ```rust
97/// # use cuprate_helper::map::*;
98/// # use monero_serai::transaction::*;
99/// use cuprate_constants::block::{MAX_BLOCK_HEIGHT, MAX_BLOCK_HEIGHT_USIZE};
100/// assert_eq!(u64_to_timelock(0), Timelock::None);
101/// assert_eq!(u64_to_timelock(MAX_BLOCK_HEIGHT-1), Timelock::Block(MAX_BLOCK_HEIGHT_USIZE-1));
102/// assert_eq!(u64_to_timelock(MAX_BLOCK_HEIGHT), Timelock::Time(MAX_BLOCK_HEIGHT));
103/// ```
104pub const fn u64_to_timelock(u: u64) -> Timelock {
105    if u == 0 {
106        Timelock::None
107    } else if u < MAX_BLOCK_HEIGHT {
108        Timelock::Block(u64_to_usize(u))
109    } else {
110        Timelock::Time(u)
111    }
112}
113
114/// Map [`Timelock`] to a [`u64`].
115///
116/// See [`u64_to_timelock`] for the inverse function and more documentation.
117///
118/// ```rust
119/// # use cuprate_helper::map::*;
120/// # use monero_serai::transaction::*;
121/// use cuprate_constants::block::{MAX_BLOCK_HEIGHT, MAX_BLOCK_HEIGHT_USIZE};
122/// assert_eq!(timelock_to_u64(Timelock::None), 0);
123/// assert_eq!(timelock_to_u64(Timelock::Block(MAX_BLOCK_HEIGHT_USIZE-1)), MAX_BLOCK_HEIGHT-1);
124/// assert_eq!(timelock_to_u64(Timelock::Time(MAX_BLOCK_HEIGHT)), MAX_BLOCK_HEIGHT);
125/// ```
126pub const fn timelock_to_u64(timelock: Timelock) -> u64 {
127    match timelock {
128        Timelock::None => 0,
129        Timelock::Block(u) => usize_to_u64(u),
130        Timelock::Time(u) => u,
131    }
132}
133
134//---------------------------------------------------------------------------------------------------- Tests
135#[cfg(test)]
136mod test {}
cuprate_helper/map.rs

cuprate_helper/
map.rs
