| 1 | // This file is part of ICU4X. For terms of use, please see the file |
| 2 | // called LICENSE at the top level of the ICU4X source tree |
| 3 | // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). |
| 4 | |
| 5 | //! Zero-copy vector abstractions for arbitrary types, backed by byte slices. |
| 6 | //! |
| 7 | //! `zerovec` enables a far wider range of types — beyond just `&[u8]` and `&str` — to participate in |
| 8 | //! zero-copy deserialization from byte slices. It is `serde` compatible and comes equipped with |
| 9 | //! proc macros |
| 10 | //! |
| 11 | //! Clients upgrading to `zerovec` benefit from zero heap allocations when deserializing |
| 12 | //! read-only data. |
| 13 | //! |
| 14 | //! This crate has four main types: |
| 15 | //! |
| 16 | //! - [`ZeroVec<'a, T>`] (and [`ZeroSlice<T>`](ZeroSlice)) for fixed-width types like `u32` |
| 17 | //! - [`VarZeroVec<'a, T>`] (and [`VarZeroSlice<T>`](ZeroSlice)) for variable-width types like `str` |
| 18 | //! - [`ZeroMap<'a, K, V>`] to map from `K` to `V` |
| 19 | //! - [`ZeroMap2d<'a, K0, K1, V>`] to map from the pair `(K0, K1)` to `V` |
| 20 | //! |
| 21 | //! The first two are intended as close-to-drop-in replacements for `Vec<T>` in Serde structs. The third and fourth are |
| 22 | //! intended as a replacement for `HashMap` or [`LiteMap`](docs.rs/litemap). When used with Serde derives, **be sure to apply |
| 23 | //! `#[serde(borrow)]` to these types**, same as one would for [`Cow<'a, T>`]. |
| 24 | //! |
| 25 | //! [`ZeroVec<'a, T>`], [`VarZeroVec<'a, T>`], [`ZeroMap<'a, K, V>`], and [`ZeroMap2d<'a, K0, K1, V>`] all behave like |
| 26 | //! [`Cow<'a, T>`] in that they abstract over either borrowed or owned data. When performing deserialization |
| 27 | //! from human-readable formats (like `json` and `xml`), typically these types will allocate and fully own their data, whereas if deserializing |
| 28 | //! from binary formats like `bincode` and `postcard`, these types will borrow data directly from the buffer being deserialized from, |
| 29 | //! avoiding allocations and only performing validity checks. As such, this crate can be pretty fast (see [below](#Performance) for more information) |
| 30 | //! on deserialization. |
| 31 | //! |
| 32 | //! See [the design doc](https://github.com/unicode-org/icu4x/blob/main/utils/zerovec/design_doc.md) for details on how this crate |
| 33 | //! works under the hood. |
| 34 | //! |
| 35 | //! # Cargo features |
| 36 | //! |
| 37 | //! This crate has several optional Cargo features: |
| 38 | //! - `serde`: Allows serializing and deserializing `zerovec`'s abstractions via [`serde`](https://docs.rs/serde) |
| 39 | //! - `yoke`: Enables implementations of `Yokeable` from the [`yoke`](https://docs.rs/yoke/) crate, which is also useful |
| 40 | //! in situations involving a lot of zero-copy deserialization. |
| 41 | //! - `derive`: Makes it easier to use custom types in these collections by providing the [`#[make_ule]`](crate::make_ule) and |
| 42 | //! [`#[make_varule]`](crate::make_varule) proc macros, which generate appropriate [`ULE`](crate::ule::ULE) and |
| 43 | //! [`VarULE`](crate::ule::VarULE)-conformant types for a given "normal" type. |
| 44 | //! - `std`: Enabled `std::Error` implementations for error types. This crate is by default `no_std` with a dependency on `alloc`. |
| 45 | //! |
| 46 | //! [`ZeroVec<'a, T>`]: ZeroVec |
| 47 | //! [`VarZeroVec<'a, T>`]: VarZeroVec |
| 48 | //! [`ZeroMap<'a, K, V>`]: ZeroMap |
| 49 | //! [`ZeroMap2d<'a, K0, K1, V>`]: ZeroMap2d |
| 50 | //! [`Cow<'a, T>`]: alloc::borrow::Cow |
| 51 | //! |
| 52 | //! # Examples |
| 53 | //! |
| 54 | //! Serialize and deserialize a struct with ZeroVec and VarZeroVec with Bincode: |
| 55 | //! |
| 56 | //! ``` |
| 57 | //! # #[cfg (feature = "serde" )] { |
| 58 | //! use zerovec::{VarZeroVec, ZeroVec}; |
| 59 | //! |
| 60 | //! // This example requires the "serde" feature |
| 61 | //! #[derive(serde::Serialize, serde::Deserialize)] |
| 62 | //! pub struct DataStruct<'data> { |
| 63 | //! #[serde(borrow)] |
| 64 | //! nums: ZeroVec<'data, u32>, |
| 65 | //! #[serde(borrow)] |
| 66 | //! chars: ZeroVec<'data, char>, |
| 67 | //! #[serde(borrow)] |
| 68 | //! strs: VarZeroVec<'data, str>, |
| 69 | //! } |
| 70 | //! |
| 71 | //! let data = DataStruct { |
| 72 | //! nums: ZeroVec::from_slice_or_alloc(&[211, 281, 421, 461]), |
| 73 | //! chars: ZeroVec::alloc_from_slice(&['ö' , '冇' , 'म' ]), |
| 74 | //! strs: VarZeroVec::from(&["hello" , "world" ]), |
| 75 | //! }; |
| 76 | //! let bincode_bytes = |
| 77 | //! bincode::serialize(&data).expect("Serialization should be successful" ); |
| 78 | //! assert_eq!(bincode_bytes.len(), 67); |
| 79 | //! |
| 80 | //! let deserialized: DataStruct = bincode::deserialize(&bincode_bytes) |
| 81 | //! .expect("Deserialization should be successful" ); |
| 82 | //! assert_eq!(deserialized.nums.first(), Some(211)); |
| 83 | //! assert_eq!(deserialized.chars.get(1), Some('冇' )); |
| 84 | //! assert_eq!(deserialized.strs.get(1), Some("world" )); |
| 85 | //! // The deserialization will not have allocated anything |
| 86 | //! assert!(!deserialized.nums.is_owned()); |
| 87 | //! # } // feature = "serde" |
| 88 | //! ``` |
| 89 | //! |
| 90 | //! Use custom types inside of ZeroVec: |
| 91 | //! |
| 92 | //! ```rust |
| 93 | //! # #[cfg (all(feature = "serde" , feature = "derive" ))] { |
| 94 | //! use zerovec::{ZeroVec, VarZeroVec, ZeroMap}; |
| 95 | //! use std::borrow::Cow; |
| 96 | //! use zerovec::ule::encode_varule_to_box; |
| 97 | //! |
| 98 | //! // custom fixed-size ULE type for ZeroVec |
| 99 | //! #[zerovec::make_ule(DateULE)] |
| 100 | //! #[derive(Copy, Clone, PartialEq, Eq, Ord, PartialOrd, serde::Serialize, serde::Deserialize)] |
| 101 | //! struct Date { |
| 102 | //! y: u64, |
| 103 | //! m: u8, |
| 104 | //! d: u8 |
| 105 | //! } |
| 106 | //! |
| 107 | //! // custom variable sized VarULE type for VarZeroVec |
| 108 | //! #[zerovec::make_varule(PersonULE)] |
| 109 | //! #[zerovec::derive(Serialize, Deserialize)] // add Serde impls to PersonULE |
| 110 | //! #[derive(Clone, PartialEq, Eq, Ord, PartialOrd, serde::Serialize, serde::Deserialize)] |
| 111 | //! struct Person<'a> { |
| 112 | //! birthday: Date, |
| 113 | //! favorite_character: char, |
| 114 | //! #[serde(borrow)] |
| 115 | //! name: Cow<'a, str>, |
| 116 | //! } |
| 117 | //! |
| 118 | //! #[derive(serde::Serialize, serde::Deserialize)] |
| 119 | //! struct Data<'a> { |
| 120 | //! #[serde(borrow)] |
| 121 | //! important_dates: ZeroVec<'a, Date>, |
| 122 | //! // note: VarZeroVec always must reference the ULE type directly |
| 123 | //! #[serde(borrow)] |
| 124 | //! important_people: VarZeroVec<'a, PersonULE>, |
| 125 | //! #[serde(borrow)] |
| 126 | //! birthdays_to_people: ZeroMap<'a, Date, PersonULE> |
| 127 | //! } |
| 128 | //! |
| 129 | //! |
| 130 | //! let person1 = Person { |
| 131 | //! birthday: Date { y: 1990, m: 9, d: 7}, |
| 132 | //! favorite_character: 'π' , |
| 133 | //! name: Cow::from("Kate" ) |
| 134 | //! }; |
| 135 | //! let person2 = Person { |
| 136 | //! birthday: Date { y: 1960, m: 5, d: 25}, |
| 137 | //! favorite_character: '冇' , |
| 138 | //! name: Cow::from("Jesse" ) |
| 139 | //! }; |
| 140 | //! |
| 141 | //! let important_dates = ZeroVec::alloc_from_slice(&[Date { y: 1943, m: 3, d: 20}, Date { y: 1976, m: 8, d: 2}, Date { y: 1998, m: 2, d: 15}]); |
| 142 | //! let important_people = VarZeroVec::from(&[&person1, &person2]); |
| 143 | //! let mut birthdays_to_people: ZeroMap<Date, PersonULE> = ZeroMap::new(); |
| 144 | //! // `.insert_var_v()` is slightly more convenient over `.insert()` for custom ULE types |
| 145 | //! birthdays_to_people.insert_var_v(&person1.birthday, &person1); |
| 146 | //! birthdays_to_people.insert_var_v(&person2.birthday, &person2); |
| 147 | //! |
| 148 | //! let data = Data { important_dates, important_people, birthdays_to_people }; |
| 149 | //! |
| 150 | //! let bincode_bytes = bincode::serialize(&data) |
| 151 | //! .expect("Serialization should be successful" ); |
| 152 | //! assert_eq!(bincode_bytes.len(), 168); |
| 153 | //! |
| 154 | //! let deserialized: Data = bincode::deserialize(&bincode_bytes) |
| 155 | //! .expect("Deserialization should be successful" ); |
| 156 | //! |
| 157 | //! assert_eq!(deserialized.important_dates.get(0).unwrap().y, 1943); |
| 158 | //! assert_eq!(&deserialized.important_people.get(1).unwrap().name, "Jesse" ); |
| 159 | //! assert_eq!(&deserialized.important_people.get(0).unwrap().name, "Kate" ); |
| 160 | //! assert_eq!(&deserialized.birthdays_to_people.get(&person1.birthday).unwrap().name, "Kate" ); |
| 161 | //! |
| 162 | //! } // feature = serde and derive |
| 163 | //! ``` |
| 164 | //! |
| 165 | //! # Performance |
| 166 | //! |
| 167 | //! `zerovec` is designed for fast deserialization from byte buffers with zero memory allocations |
| 168 | //! while minimizing performance regressions for common vector operations. |
| 169 | //! |
| 170 | //! Benchmark results on x86_64: |
| 171 | //! |
| 172 | //! | Operation | `Vec<T>` | `zerovec` | |
| 173 | //! |---|---|---| |
| 174 | //! | Deserialize vec of 100 `u32` | 233.18 ns | 14.120 ns | |
| 175 | //! | Compute sum of vec of 100 `u32` (read every element) | 8.7472 ns | 10.775 ns | |
| 176 | //! | Binary search vec of 1000 `u32` 50 times | 442.80 ns | 472.51 ns | |
| 177 | //! | Deserialize vec of 100 strings | 7.3740 μs\* | 1.4495 μs | |
| 178 | //! | Count chars in vec of 100 strings (read every element) | 747.50 ns | 955.28 ns | |
| 179 | //! | Binary search vec of 500 strings 10 times | 466.09 ns | 790.33 ns | |
| 180 | //! |
| 181 | //! \* *This result is reported for `Vec<String>`. However, Serde also supports deserializing to the partially-zero-copy `Vec<&str>`; this gives 1.8420 μs, much faster than `Vec<String>` but a bit slower than `zerovec`.* |
| 182 | //! |
| 183 | //! | Operation | `HashMap<K,V>` | `LiteMap<K,V>` | `ZeroMap<K,V>` | |
| 184 | //! |---|---|---|---| |
| 185 | //! | Deserialize a small map | 2.72 μs | 1.28 μs | 480 ns | |
| 186 | //! | Deserialize a large map | 50.5 ms | 18.3 ms | 3.74 ms | |
| 187 | //! | Look up from a small deserialized map | 49 ns | 42 ns | 54 ns | |
| 188 | //! | Look up from a large deserialized map | 51 ns | 155 ns | 213 ns | |
| 189 | //! |
| 190 | //! Small = 16 elements, large = 131,072 elements. Maps contain `<String, String>`. |
| 191 | //! |
| 192 | //! The benches used to generate the above table can be found in the `benches` directory in the project repository. |
| 193 | //! `zeromap` benches are named by convention, e.g. `zeromap/deserialize/small`, `zeromap/lookup/large`. The type |
| 194 | //! is appended for baseline comparisons, e.g. `zeromap/lookup/small/hashmap`. |
| 195 | |
| 196 | // https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations |
| 197 | #![cfg_attr (not(any(test, feature = "std" )), no_std)] |
| 198 | #![cfg_attr ( |
| 199 | not(test), |
| 200 | deny( |
| 201 | clippy::indexing_slicing, |
| 202 | clippy::unwrap_used, |
| 203 | clippy::expect_used, |
| 204 | clippy::panic, |
| 205 | clippy::exhaustive_structs, |
| 206 | clippy::exhaustive_enums, |
| 207 | missing_debug_implementations, |
| 208 | ) |
| 209 | )] |
| 210 | // this crate does a lot of nuanced lifetime manipulation, being explicit |
| 211 | // is better here. |
| 212 | #![allow (clippy::needless_lifetimes)] |
| 213 | |
| 214 | extern crate alloc; |
| 215 | |
| 216 | mod error; |
| 217 | mod flexzerovec; |
| 218 | #[cfg (feature = "hashmap" )] |
| 219 | pub mod hashmap; |
| 220 | mod map; |
| 221 | mod map2d; |
| 222 | #[cfg (test)] |
| 223 | pub mod samples; |
| 224 | mod varzerovec; |
| 225 | mod zerovec; |
| 226 | |
| 227 | // This must be after `mod zerovec` for some impls on `ZeroSlice<RawBytesULE>` |
| 228 | // to show up in the right spot in the docs |
| 229 | pub mod ule; |
| 230 | |
| 231 | #[cfg (feature = "yoke" )] |
| 232 | mod yoke_impls; |
| 233 | mod zerofrom_impls; |
| 234 | |
| 235 | pub use crate::error::ZeroVecError; |
| 236 | #[cfg (feature = "hashmap" )] |
| 237 | pub use crate::hashmap::ZeroHashMap; |
| 238 | pub use crate::map::map::ZeroMap; |
| 239 | pub use crate::map2d::map::ZeroMap2d; |
| 240 | pub use crate::varzerovec::{slice::VarZeroSlice, vec::VarZeroVec}; |
| 241 | pub use crate::zerovec::{ZeroSlice, ZeroVec}; |
| 242 | |
| 243 | pub(crate) use flexzerovec::chunk_to_usize; |
| 244 | |
| 245 | #[doc (hidden)] |
| 246 | pub mod __zerovec_internal_reexport { |
| 247 | pub use zerofrom::ZeroFrom; |
| 248 | |
| 249 | pub use alloc::boxed; |
| 250 | |
| 251 | #[cfg (feature = "serde" )] |
| 252 | pub use serde; |
| 253 | } |
| 254 | |
| 255 | pub mod maps { |
| 256 | //! This module contains additional utility types and traits for working with |
| 257 | //! [`ZeroMap`] and [`ZeroMap2d`]. See their docs for more details on the general purpose |
| 258 | //! of these types. |
| 259 | //! |
| 260 | //! [`ZeroMapBorrowed`] and [`ZeroMap2dBorrowed`] are versions of [`ZeroMap`] and [`ZeroMap2d`] |
| 261 | //! that can be used when you wish to guarantee that the map data is always borrowed, leading to |
| 262 | //! relaxed lifetime constraints. |
| 263 | //! |
| 264 | //! The [`ZeroMapKV`] trait is required to be implemented on any type that needs to be used |
| 265 | //! within a map type. [`ZeroVecLike`] and [`MutableZeroVecLike`] are traits used in the |
| 266 | //! internal workings of the map types, and should typically not be used or implemented by |
| 267 | //! users of this crate. |
| 268 | #[doc (no_inline)] |
| 269 | pub use crate::map::ZeroMap; |
| 270 | pub use crate::map::ZeroMapBorrowed; |
| 271 | |
| 272 | #[doc (no_inline)] |
| 273 | pub use crate::map2d::ZeroMap2d; |
| 274 | pub use crate::map2d::ZeroMap2dBorrowed; |
| 275 | |
| 276 | pub use crate::map::{MutableZeroVecLike, ZeroMapKV, ZeroVecLike}; |
| 277 | |
| 278 | pub use crate::map2d::ZeroMap2dCursor; |
| 279 | } |
| 280 | |
| 281 | pub mod vecs { |
| 282 | //! This module contains additional utility types for working with |
| 283 | //! [`ZeroVec`] and [`VarZeroVec`]. See their docs for more details on the general purpose |
| 284 | //! of these types. |
| 285 | //! |
| 286 | //! [`ZeroSlice`] and [`VarZeroSlice`] provide slice-like versions of the vector types |
| 287 | //! for use behind references and in custom ULE types. |
| 288 | //! |
| 289 | //! [`VarZeroVecOwned`] is a special owned/mutable version of [`VarZeroVec`], allowing |
| 290 | //! direct manipulation of the backing buffer. |
| 291 | |
| 292 | #[doc (no_inline)] |
| 293 | pub use crate::zerovec::{ZeroSlice, ZeroVec}; |
| 294 | |
| 295 | #[doc (no_inline)] |
| 296 | pub use crate::varzerovec::{VarZeroSlice, VarZeroVec}; |
| 297 | |
| 298 | pub use crate::varzerovec::{Index16, Index32, VarZeroVecFormat, VarZeroVecOwned}; |
| 299 | |
| 300 | pub use crate::flexzerovec::{FlexZeroSlice, FlexZeroVec, FlexZeroVecOwned}; |
| 301 | } |
| 302 | |
| 303 | // Proc macro reexports |
| 304 | // |
| 305 | // These exist so that our docs can use intra-doc links. |
| 306 | // Due to quirks of how rustdoc does documentation on reexports, these must be in this module and not reexported from |
| 307 | // a submodule |
| 308 | |
| 309 | /// Generate a corresponding [`ULE`] type and the relevant [`AsULE`] implementations for this type |
| 310 | /// |
| 311 | /// This can be attached to structs containing only [`AsULE`] types, or C-like enums that have `#[repr(u8)]` |
| 312 | /// and all explicit discriminants. |
| 313 | /// |
| 314 | /// The type must be [`Copy`], [`PartialEq`], and [`Eq`]. |
| 315 | /// |
| 316 | /// `#[make_ule]` will automatically derive the following traits on the [`ULE`] type: |
| 317 | /// |
| 318 | /// - [`Ord`] and [`PartialOrd`] |
| 319 | /// - [`ZeroMapKV`] |
| 320 | /// |
| 321 | /// To disable one of the automatic derives, use `#[zerovec::skip_derive(...)]` like so: `#[zerovec::skip_derive(ZeroMapKV)]`. |
| 322 | /// `Ord` and `PartialOrd` are implemented as a unit and can only be disabled as a group with `#[zerovec::skip_derive(Ord)]`. |
| 323 | /// |
| 324 | /// The following traits are available to derive, but not automatic: |
| 325 | /// |
| 326 | /// - [`Debug`] |
| 327 | /// |
| 328 | /// To enable one of these additional derives, use `#[zerovec::derive(...)]` like so: `#[zerovec::derive(Debug)]`. |
| 329 | /// |
| 330 | /// In most cases these derives will defer to the impl of the same trait on the current type, so such impls must exist. |
| 331 | /// |
| 332 | /// For enums, this attribute will generate a crate-public `fn new_from_u8(value: u8) -> Option<Self>` |
| 333 | /// method on the main type that allows one to construct the value from a u8. If this method is desired |
| 334 | /// to be more public, it should be wrapped. |
| 335 | /// |
| 336 | /// [`ULE`]: ule::ULE |
| 337 | /// [`AsULE`]: ule::AsULE |
| 338 | /// [`ZeroMapKV`]: maps::ZeroMapKV |
| 339 | /// |
| 340 | /// # Example |
| 341 | /// |
| 342 | /// ```rust |
| 343 | /// use zerovec::ZeroVec; |
| 344 | /// |
| 345 | /// #[zerovec::make_ule(DateULE)] |
| 346 | /// #[derive( |
| 347 | /// Copy, |
| 348 | /// Clone, |
| 349 | /// PartialEq, |
| 350 | /// Eq, |
| 351 | /// Ord, |
| 352 | /// PartialOrd, |
| 353 | /// serde::Serialize, |
| 354 | /// serde::Deserialize, |
| 355 | /// )] |
| 356 | /// struct Date { |
| 357 | /// y: u64, |
| 358 | /// m: u8, |
| 359 | /// d: u8, |
| 360 | /// } |
| 361 | /// |
| 362 | /// #[derive(serde::Serialize, serde::Deserialize)] |
| 363 | /// struct Dates<'a> { |
| 364 | /// #[serde(borrow)] |
| 365 | /// dates: ZeroVec<'a, Date>, |
| 366 | /// } |
| 367 | /// |
| 368 | /// let dates = Dates { |
| 369 | /// dates: ZeroVec::alloc_from_slice(&[ |
| 370 | /// Date { |
| 371 | /// y: 1985, |
| 372 | /// m: 9, |
| 373 | /// d: 3, |
| 374 | /// }, |
| 375 | /// Date { |
| 376 | /// y: 1970, |
| 377 | /// m: 2, |
| 378 | /// d: 20, |
| 379 | /// }, |
| 380 | /// Date { |
| 381 | /// y: 1990, |
| 382 | /// m: 6, |
| 383 | /// d: 13, |
| 384 | /// }, |
| 385 | /// ]), |
| 386 | /// }; |
| 387 | /// |
| 388 | /// let bincode_bytes = |
| 389 | /// bincode::serialize(&dates).expect("Serialization should be successful"); |
| 390 | /// |
| 391 | /// // Will deserialize without allocations |
| 392 | /// let deserialized: Dates = bincode::deserialize(&bincode_bytes) |
| 393 | /// .expect("Deserialization should be successful"); |
| 394 | /// |
| 395 | /// assert_eq!(deserialized.dates.get(1).unwrap().y, 1970); |
| 396 | /// assert_eq!(deserialized.dates.get(2).unwrap().d, 13); |
| 397 | /// ``` |
| 398 | #[cfg (feature = "derive" )] |
| 399 | pub use zerovec_derive::make_ule; |
| 400 | |
| 401 | /// Generate a corresponding [`VarULE`] type and the relevant [`EncodeAsVarULE`]/[`zerofrom::ZeroFrom`] |
| 402 | /// implementations for this type |
| 403 | /// |
| 404 | /// This can be attached to structs containing only [`AsULE`] types with the last fields being |
| 405 | /// [`Cow<'a, str>`](alloc::borrow::Cow), [`ZeroSlice`], or [`VarZeroSlice`]. If there is more than one such field, it will be represented |
| 406 | /// using [`MultiFieldsULE`](crate::ule::MultiFieldsULE) and getters will be generated. Other VarULE fields will be detected if they are |
| 407 | /// tagged with `#[zerovec::varule(NameOfVarULETy)]`. |
| 408 | /// |
| 409 | /// The type must be [`PartialEq`] and [`Eq`]. |
| 410 | /// |
| 411 | /// [`EncodeAsVarULE`] and [`zerofrom::ZeroFrom`] are useful for avoiding the need to deal with |
| 412 | /// the [`VarULE`] type directly. In particular, it is recommended to use [`zerofrom::ZeroFrom`] |
| 413 | /// to convert the [`VarULE`] type back to this type in a cheap, zero-copy way (see the example below |
| 414 | /// for more details). |
| 415 | /// |
| 416 | /// `#[make_varule]` will automatically derive the following traits on the [`VarULE`] type: |
| 417 | /// |
| 418 | /// - [`Ord`] and [`PartialOrd`] |
| 419 | /// - [`ZeroMapKV`] |
| 420 | /// |
| 421 | /// To disable one of the automatic derives, use `#[zerovec::skip_derive(...)]` like so: `#[zerovec::skip_derive(ZeroMapKV)]`. |
| 422 | /// `Ord` and `PartialOrd` are implemented as a unit and can only be disabled as a group with `#[zerovec::skip_derive(Ord)]`. |
| 423 | /// |
| 424 | /// The following traits are available to derive, but not automatic: |
| 425 | /// |
| 426 | /// - [`Debug`] |
| 427 | /// - [`Serialize`](serde::Serialize) |
| 428 | /// - [`Deserialize`](serde::Deserialize) |
| 429 | /// |
| 430 | /// To enable one of these additional derives, use `#[zerovec::derive(...)]` like so: `#[zerovec::derive(Debug)]`. |
| 431 | /// |
| 432 | /// In most cases these derives will defer to the impl of the same trait on the current type, so such impls must exist. |
| 433 | /// |
| 434 | /// This implementation will also by default autogenerate [`Ord`] and [`PartialOrd`] on the [`VarULE`] type based on |
| 435 | /// the implementation on `Self`. You can opt out of this with `#[zerovec::skip_derive(Ord)]` |
| 436 | /// |
| 437 | /// Note that this implementation will autogenerate [`EncodeAsVarULE`] impls for _both_ `Self` and `&Self` |
| 438 | /// for convenience. This allows for a little more flexibility encoding slices. |
| 439 | /// |
| 440 | /// [`EncodeAsVarULE`]: ule::EncodeAsVarULE |
| 441 | /// [`VarULE`]: ule::VarULE |
| 442 | /// [`ULE`]: ule::ULE |
| 443 | /// [`AsULE`]: ule::AsULE |
| 444 | /// [`ZeroMapKV`]: maps::ZeroMapKV |
| 445 | /// |
| 446 | /// # Example |
| 447 | /// |
| 448 | /// ```rust |
| 449 | /// use std::borrow::Cow; |
| 450 | /// use zerofrom::ZeroFrom; |
| 451 | /// use zerovec::ule::encode_varule_to_box; |
| 452 | /// use zerovec::{VarZeroVec, ZeroMap, ZeroVec}; |
| 453 | /// |
| 454 | /// // custom fixed-size ULE type for ZeroVec |
| 455 | /// #[zerovec::make_ule(DateULE)] |
| 456 | /// #[derive(Copy, Clone, PartialEq, Eq, Ord, PartialOrd, serde::Serialize, serde::Deserialize)] |
| 457 | /// struct Date { |
| 458 | /// y: u64, |
| 459 | /// m: u8, |
| 460 | /// d: u8, |
| 461 | /// } |
| 462 | /// |
| 463 | /// // custom variable sized VarULE type for VarZeroVec |
| 464 | /// #[zerovec::make_varule(PersonULE)] |
| 465 | /// #[zerovec::derive(Serialize, Deserialize)] |
| 466 | /// #[derive(Clone, PartialEq, Eq, Ord, PartialOrd, serde::Serialize, serde::Deserialize)] |
| 467 | /// struct Person<'a> { |
| 468 | /// birthday: Date, |
| 469 | /// favorite_character: char, |
| 470 | /// #[serde(borrow)] |
| 471 | /// name: Cow<'a, str>, |
| 472 | /// } |
| 473 | /// |
| 474 | /// #[derive(serde::Serialize, serde::Deserialize)] |
| 475 | /// struct Data<'a> { |
| 476 | /// // note: VarZeroVec always must reference the ULE type directly |
| 477 | /// #[serde(borrow)] |
| 478 | /// important_people: VarZeroVec<'a, PersonULE>, |
| 479 | /// } |
| 480 | /// |
| 481 | /// let person1 = Person { |
| 482 | /// birthday: Date { |
| 483 | /// y: 1990, |
| 484 | /// m: 9, |
| 485 | /// d: 7, |
| 486 | /// }, |
| 487 | /// favorite_character: 'π', |
| 488 | /// name: Cow::from("Kate"), |
| 489 | /// }; |
| 490 | /// let person2 = Person { |
| 491 | /// birthday: Date { |
| 492 | /// y: 1960, |
| 493 | /// m: 5, |
| 494 | /// d: 25, |
| 495 | /// }, |
| 496 | /// favorite_character: '冇', |
| 497 | /// name: Cow::from("Jesse"), |
| 498 | /// }; |
| 499 | /// |
| 500 | /// let important_people = VarZeroVec::from(&[person1, person2]); |
| 501 | /// let data = Data { important_people }; |
| 502 | /// |
| 503 | /// let bincode_bytes = bincode::serialize(&data).expect("Serialization should be successful"); |
| 504 | /// |
| 505 | /// // Will deserialize without allocations |
| 506 | /// let deserialized: Data = |
| 507 | /// bincode::deserialize(&bincode_bytes).expect("Deserialization should be successful"); |
| 508 | /// |
| 509 | /// assert_eq!(&deserialized.important_people.get(1).unwrap().name, "Jesse"); |
| 510 | /// assert_eq!(&deserialized.important_people.get(0).unwrap().name, "Kate"); |
| 511 | /// |
| 512 | /// // Since VarZeroVec produces PersonULE types, it's convenient to use ZeroFrom |
| 513 | /// // to recoup Person values in a zero-copy way |
| 514 | /// let person_converted: Person = |
| 515 | /// ZeroFrom::zero_from(deserialized.important_people.get(1).unwrap()); |
| 516 | /// assert_eq!(person_converted.name, "Jesse"); |
| 517 | /// assert_eq!(person_converted.birthday.y, 1960); |
| 518 | /// ``` |
| 519 | #[cfg (feature = "derive" )] |
| 520 | pub use zerovec_derive::make_varule; |
| 521 | |
| 522 | #[cfg (test)] |
| 523 | mod tests { |
| 524 | use super::*; |
| 525 | use core::mem::size_of; |
| 526 | |
| 527 | /// Checks that the size of the type is one of the given sizes. |
| 528 | /// The size might differ across Rust versions or channels. |
| 529 | macro_rules! check_size_of { |
| 530 | ($sizes:pat, $type:path) => { |
| 531 | assert!( |
| 532 | matches!(size_of::<$type>(), $sizes), |
| 533 | concat!(stringify!($type), " is of size {}" ), |
| 534 | size_of::<$type>() |
| 535 | ); |
| 536 | }; |
| 537 | } |
| 538 | |
| 539 | #[test ] |
| 540 | fn check_sizes() { |
| 541 | check_size_of!(24, ZeroVec<u8>); |
| 542 | check_size_of!(24, ZeroVec<u32>); |
| 543 | check_size_of!(32 | 24, VarZeroVec<[u8]>); |
| 544 | check_size_of!(32 | 24, VarZeroVec<str>); |
| 545 | check_size_of!(48, ZeroMap<u32, u32>); |
| 546 | check_size_of!(56 | 48, ZeroMap<u32, str>); |
| 547 | check_size_of!(56 | 48, ZeroMap<str, u32>); |
| 548 | check_size_of!(64 | 48, ZeroMap<str, str>); |
| 549 | check_size_of!(120 | 96, ZeroMap2d<str, str, str>); |
| 550 | check_size_of!(32 | 24, vecs::FlexZeroVec); |
| 551 | |
| 552 | check_size_of!(24, Option<ZeroVec<u8>>); |
| 553 | check_size_of!(32 | 24, Option<VarZeroVec<str>>); |
| 554 | check_size_of!(64 | 56 | 48, Option<ZeroMap<str, str>>); |
| 555 | check_size_of!(120 | 104 | 96, Option<ZeroMap2d<str, str, str>>); |
| 556 | check_size_of!(32 | 24, Option<vecs::FlexZeroVec>); |
| 557 | } |
| 558 | } |
| 559 | |