| 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 |  | 
|---|