kaspa_utils/lib.rs
1//!
2//! # Kaspa Utilities
3//!
4//! General purpose utilities and various type extensions used across the Rusty Kaspa codebase.
5//!
6#![allow(clippy::arithmetic_side_effects)]
7#![no_std]
8
9extern crate alloc;
10extern crate core;
11
12#[cfg(feature = "std")]
13extern crate std;
14
15pub mod any;
16pub mod arc;
17pub mod binary_heap;
18pub mod channel;
19
20#[cfg(feature = "expiring-cache")]
21pub mod expiring_cache;
22
23#[cfg(feature = "hashmap")]
24pub mod hashmap;
25pub mod hex;
26pub mod iter;
27
28#[cfg(feature = "mem_size")]
29pub mod mem_size;
30pub mod networking;
31pub mod refs;
32
33pub mod as_slice;
34
35/// # Examples
36/// ## Implement serde::Serialize/serde::Deserialize for the Vec field of the struct
37/// ```
38/// #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
39/// struct MyStructVec {
40/// #[serde(with = "kaspa_utils::serde_bytes")]
41/// v: Vec<u8>,
42/// }
43/// let v = vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
44/// let len = v.len();
45/// let test_struct = MyStructVec { v: v.clone() };
46///
47/// // Serialize using bincode
48/// let encoded = bincode::serialize(&test_struct).unwrap();
49/// assert_eq!(encoded, len.to_le_bytes().into_iter().chain(v.into_iter()).collect::<Vec<_>>());
50/// // Deserialize using bincode
51/// let decoded: MyStructVec = bincode::deserialize(&encoded).unwrap();
52/// assert_eq!(test_struct, decoded);
53///
54/// let expected_str = r#"{"v":"000102030405060708090a0b0c0d0e0f10111213"}"#;
55/// // Serialize using serde_json
56/// let json = serde_json::to_string(&test_struct).unwrap();
57/// assert_eq!(expected_str, json);
58/// // Deserialize using serde_json
59/// let from_json: MyStructVec = serde_json::from_str(&json).unwrap();
60/// assert_eq!(test_struct, from_json);
61/// ```
62/// ## Implement serde::Serialize/serde::Deserialize for the SmallVec field of the struct
63/// ```
64/// use smallvec::{smallvec, SmallVec};
65/// #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
66/// struct MyStructSmallVec {
67/// #[serde(with = "kaspa_utils::serde_bytes")]
68/// v: SmallVec<[u8; 19]>,
69/// }
70/// let v = smallvec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
71/// let len = v.len();
72/// let test_struct = MyStructSmallVec { v: v.clone() };
73///
74/// // Serialize using bincode
75/// let encoded = bincode::serialize(&test_struct).unwrap();
76/// assert_eq!(encoded, len.to_le_bytes().into_iter().chain(v.into_iter()).collect::<Vec<_>>());
77/// // Deserialize using bincode
78/// let decoded: MyStructSmallVec = bincode::deserialize(&encoded).unwrap();
79/// assert_eq!(test_struct, decoded);
80///
81/// let expected_str = r#"{"v":"000102030405060708090a0b0c0d0e0f10111213"}"#;
82/// // Serialize using serde_json
83/// let json = serde_json::to_string(&test_struct).unwrap();
84/// assert_eq!(expected_str, json);
85/// // Deserialize using serde_json
86/// let from_json: MyStructSmallVec = serde_json::from_str(&json).unwrap();
87/// assert_eq!(test_struct, from_json);
88/// ```
89pub mod serde_bytes;
90
91/// # Examples
92/// ## Implement serde::Serialize/serde::Deserialize for the Vec field of the struct
93/// ```
94/// #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
95/// struct MyStructVec {
96/// #[serde(with = "kaspa_utils::serde_bytes_optional")]
97/// v: Option<Vec<u8>>,
98/// }
99/// let v = vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
100/// let len = v.len();
101/// let test_struct = MyStructVec { v: Some(v.clone()) };
102///
103///
104/// // Serialize using bincode
105/// let encoded = bincode::serialize(&test_struct).unwrap();
106/// assert_eq!(encoded, std::iter::once(1).chain(len.to_le_bytes().into_iter()).chain(v.into_iter()).collect::<Vec<_>>());
107/// // Deserialize using bincode
108/// let decoded: MyStructVec = bincode::deserialize(&encoded).unwrap();
109/// assert_eq!(test_struct, decoded);
110///
111/// let expected_str = r#"{"v":"000102030405060708090a0b0c0d0e0f10111213"}"#;
112/// // Serialize using serde_json
113/// let json = serde_json::to_string(&test_struct).unwrap();
114/// assert_eq!(expected_str, json);
115/// // Deserialize using serde_json
116/// let from_json: MyStructVec = serde_json::from_str(&json).unwrap();
117/// assert_eq!(test_struct, from_json);
118pub mod serde_bytes_optional;
119
120/// # Examples
121///
122/// ```
123/// #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
124/// struct TestStruct {
125/// #[serde(with = "kaspa_utils::serde_bytes_fixed")]
126/// v: [u8; 20],
127/// }
128/// let test_struct = TestStruct { v: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] };
129///
130/// // Serialize using bincode
131/// let encoded = bincode::serialize(&test_struct).unwrap();
132/// assert_eq!(encoded, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]);
133/// // Deserialize using bincode
134/// let decoded: TestStruct = bincode::deserialize(&encoded).unwrap();
135/// assert_eq!(test_struct, decoded);
136///
137/// let expected_str = r#"{"v":"000102030405060708090a0b0c0d0e0f10111213"}"#;
138/// // Serialize using serde_json
139/// let json = serde_json::to_string(&test_struct).unwrap();
140/// assert_eq!(expected_str, json);
141/// // Deserialize using serde_json
142/// let from_json: TestStruct = serde_json::from_str(&json).unwrap();
143/// assert_eq!(test_struct, from_json);
144/// ```
145pub mod serde_bytes_fixed;
146/// # Examples
147/// ## Implement serde::Serialize/serde::Deserialize using declarative macro
148/// ```
149/// use std as alloc;
150/// #[derive(Debug, Copy, Clone, PartialEq, Eq)]
151/// struct MyStruct([u8; 20]);
152///
153/// impl AsRef<[u8; 20]> for MyStruct {
154/// fn as_ref(&self) -> &[u8; 20] {
155/// &self.0
156/// }
157/// }
158/// impl kaspa_utils::hex::FromHex for MyStruct {
159/// type Error = faster_hex::Error;
160/// fn from_hex(hex_str: &str) -> Result<Self, Self::Error> {
161/// let mut bytes = [0u8; 20];
162/// faster_hex::hex_decode(hex_str.as_bytes(), &mut bytes)?;
163/// Ok(MyStruct(bytes))
164/// }
165/// }
166/// impl From<[u8; 20]> for MyStruct {
167/// fn from(value: [u8; 20]) -> Self {
168/// MyStruct(value)
169/// }
170/// }
171/// kaspa_utils::serde_impl_ser_fixed_bytes_ref!(MyStruct, 20);
172/// kaspa_utils::serde_impl_deser_fixed_bytes_ref!(MyStruct, 20);
173///
174/// let test_struct = MyStruct([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]);
175/// let expected_str = r#""000102030405060708090a0b0c0d0e0f10111213""#;
176/// // Serialize using serde_json
177/// let json = serde_json::to_string(&test_struct).unwrap();
178/// assert_eq!(expected_str, json);
179/// // Deserialize using serde_json
180/// let from_json: MyStruct = serde_json::from_str(&json).unwrap();
181/// assert_eq!(test_struct, from_json);
182/// // Serialize using bincode
183/// let encoded = bincode::serialize(&test_struct).unwrap();
184/// assert_eq!(encoded, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]);
185/// // Deserialize using bincode
186/// let decoded: MyStruct = bincode::deserialize(&encoded).unwrap();
187/// assert_eq!(test_struct, decoded);
188/// ```
189///
190/// ## Implement serde::Serialize/serde::Deserialize for the field of the struct
191/// ```
192/// #[derive(Debug, Copy, Clone, PartialEq, Eq)]
193/// struct MyStruct([u8; 20]);
194///
195/// impl AsRef<[u8; 20]> for MyStruct {
196/// fn as_ref(&self) -> &[u8; 20] {
197/// &self.0
198/// }
199/// }
200/// impl kaspa_utils::hex::FromHex for MyStruct {
201/// type Error = faster_hex::Error;
202/// fn from_hex(hex_str: &str) -> Result<Self, Self::Error> {
203/// let mut bytes = [0u8; 20];
204/// faster_hex::hex_decode(hex_str.as_bytes(), &mut bytes)?;
205/// Ok(MyStruct(bytes))
206/// }
207/// }
208/// impl From<[u8; 20]> for MyStruct {
209/// fn from(value: [u8; 20]) -> Self {
210/// MyStruct(value)
211/// }
212/// }
213///
214/// #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
215/// struct TestStruct {
216/// #[serde(with = "kaspa_utils::serde_bytes_fixed_ref")]
217/// v: MyStruct,
218/// }
219///
220/// let test_struct = TestStruct { v: MyStruct([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]) };
221///
222/// // Serialize using bincode
223/// let encoded = bincode::serialize(&test_struct).unwrap();
224/// assert_eq!(encoded, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]);
225/// // Deserialize using bincode
226/// let decoded: TestStruct = bincode::deserialize(&encoded).unwrap();
227/// assert_eq!(test_struct, decoded);
228///
229/// let expected_str = r#"{"v":"000102030405060708090a0b0c0d0e0f10111213"}"#;
230/// // Serialize using serde_json
231/// let json = serde_json::to_string(&test_struct).unwrap();
232/// assert_eq!(expected_str, json);
233/// // Deserialize using serde_json
234/// let from_json: TestStruct = serde_json::from_str(&json).unwrap();
235/// assert_eq!(test_struct, from_json);
236/// ```
237pub mod serde_bytes_fixed_ref;
238pub mod serde_bytes_fixed_ref_optional;
239#[cfg(feature = "sim")]
240pub mod sim;
241
242#[cfg(feature = "sync")] // todo can be used in nostd if event-listener version is updated
243pub mod sync;
244
245#[cfg(feature = "triggers")]
246pub mod triggers;
247pub mod vec;
248
249#[cfg(all(not(target_arch = "wasm32"), feature = "fd_budget"))]
250pub mod fd_budget;