]> git.proxmox.com Git - rustc.git/blob - vendor/zerovec/src/lib.rs
New upstream version 1.75.0+dfsg1
[rustc.git] / vendor / zerovec / src / lib.rs
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/docs/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!(32, Option<ZeroVec<u8>>);
553 check_size_of!(32, Option<VarZeroVec<str>>);
554 check_size_of!(64 | 56, Option<ZeroMap<str, str>>);
555 check_size_of!(120 | 104, Option<ZeroMap2d<str, str, str>>);
556 check_size_of!(32, Option<vecs::FlexZeroVec>);
557 }
558 }