// This file is part of ICU4X. For terms of use, please see the file
// called LICENSE at the top level of the ICU4X source tree
// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
//! Documentation on implementing custom VarULE types.
//!
//! This module contains documentation for defining custom VarULE types,
//! especially those using complex custom dynamically sized types.
//!
//! In *most cases* you should be able to create custom VarULE types using
//! [`#[make_varule]`](crate::make_ule).
//!
//! # Example
//!
//! For example, if your regular stack type is:
//!
//! ```rust
//! use zerofrom::ZeroFrom;
//! use zerovec::ule::*;
//! use zerovec::ZeroVec;
//!
//! #[derive(serde::Serialize, serde::Deserialize)]
//! struct Foo<'a> {
//! field1: char,
//! field2: u32,
//! #[serde(borrow)]
//! field3: ZeroVec<'a, u32>,
//! }
//! ```
//!
//! then the ULE type will be implemented as follows. Ideally, you should have
//! `EncodeAsVarULE` and `ZeroFrom` implementations on `Foo` pertaining to `FooULE`,
//! as well as a `Serialize` impl on `FooULE` and a `Deserialize` impl on `Box<FooULE>`
//! to enable human-readable serialization and deserialization.
//!
//! ```rust
//! use zerovec::{ZeroVec, VarZeroVec, ZeroSlice};
//! use zerovec::ule::*;
//! use zerofrom::ZeroFrom;
//! use core::mem;
//!
//! # #[derive(serde::Serialize, serde::Deserialize)]
//! # struct Foo<'a> {
//! # field1: char,
//! # field2: u32,
//! # #[serde(borrow)]
//! # field3: ZeroVec<'a, u32>
//! # }
//!
//! // Must be repr(packed) for safety of VarULE!
//! // Must also only contain ULE types
//! #[repr(packed)]
//! struct FooULE {
//! field1: <char as AsULE>::ULE,
//! field2: <u32 as AsULE>::ULE,
//! field3: ZeroSlice<u32>,
//! }
//!
//! // Safety (based on the safety checklist on the VarULE trait):
//! // 1. FooULE does not include any uninitialized or padding bytes. (achieved by `#[repr(packed)]` on
//! // a struct with only ULE fields)
//! // 2. FooULE is aligned to 1 byte. (achieved by `#[repr(packed)]` on
//! // a struct with only ULE fields)
//! // 3. The impl of `validate_byte_slice()` returns an error if any byte is not valid.
//! // 4. The impl of `validate_byte_slice()` returns an error if the slice cannot be used in its entirety
//! // 5. The impl of `from_byte_slice_unchecked()` returns a reference to the same data.
//! // 6. The other VarULE methods use the default impl.
//! // 7. FooULE byte equality is semantic equality
//! unsafe impl VarULE for FooULE {
//! fn validate_byte_slice(bytes: &[u8]) -> Result<(), ZeroVecError> {
//! // validate each field
//! <char as AsULE>::ULE::validate_byte_slice(&bytes[0..3]).map_err(|_| ZeroVecError::parse::<Self>())?;
//! <u32 as AsULE>::ULE::validate_byte_slice(&bytes[3..7]).map_err(|_| ZeroVecError::parse::<Self>())?;
//! let _ = ZeroVec::<u32>::parse_byte_slice(&bytes[7..]).map_err(|_| ZeroVecError::parse::<Self>())?;
//! Ok(())
//! }
//! unsafe fn from_byte_slice_unchecked(bytes: &[u8]) -> &Self {
//! let ptr = bytes.as_ptr();
//! let len = bytes.len();
//! // subtract the length of the char and u32 to get the length of the array
//! let len_new = (len - 7) / 4;
//! // it's hard constructing custom DSTs, we fake a pointer/length construction
//! // eventually we can use the Pointer::Metadata APIs when they stabilize
//! let fake_slice = core::ptr::slice_from_raw_parts(ptr as *const <u32 as AsULE>::ULE, len_new);
//! &*(fake_slice as *const Self)
//! }
//! }
//!
//! unsafe impl EncodeAsVarULE<FooULE> for Foo<'_> {
//! fn encode_var_ule_as_slices<R>(&self, cb: impl FnOnce(&[&[u8]]) -> R) -> R {
//! // take each field, convert to ULE byte slices, and pass them through
//! cb(&[<char as AsULE>::ULE::as_byte_slice(&[self.field1.to_unaligned()]),
//! <u32 as AsULE>::ULE::as_byte_slice(&[self.field2.to_unaligned()]),
//! // the ZeroVec is already in the correct slice format
//! self.field3.as_bytes()])
//! }
//! }
//!
//! impl<'a> ZeroFrom<'a, FooULE> for Foo<'a> {
//! fn zero_from(other: &'a FooULE) -> Self {
//! Self {
//! field1: AsULE::from_unaligned(other.field1),
//! field2: AsULE::from_unaligned(other.field2),
//! field3: ZeroFrom::zero_from(&other.field3),
//! }
//! }
//! }
//!
//!
//! impl serde::Serialize for FooULE
//! {
//! fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
//! where
//! S: serde::Serializer,
//! {
//! Foo::zero_from(self).serialize(serializer)
//! }
//! }
//!
//! impl<'de> serde::Deserialize<'de> for Box<FooULE>
//! {
//! fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
//! where
//! D: serde::Deserializer<'de>,
//! {
//! let mut foo = Foo::deserialize(deserializer)?;
//! Ok(encode_varule_to_box(&foo))
//! }
//! }
//!
//! fn main() {
//! let mut foos = vec![Foo {field1: 'u', field2: 983, field3: ZeroVec::alloc_from_slice(&[1212,2309,500,7000])},
//! Foo {field1: 'l', field2: 1010, field3: ZeroVec::alloc_from_slice(&[1932, 0, 8888, 91237])}];
//!
//! let vzv = VarZeroVec::<_>::from(&foos);
//!
//! assert_eq!(char::from_unaligned(vzv.get(0).unwrap().field1), 'u');
//! assert_eq!(u32::from_unaligned(vzv.get(0).unwrap().field2), 983);
//! assert_eq!(&vzv.get(0).unwrap().field3, &[1212,2309,500,7000][..]);
//!
//! assert_eq!(char::from_unaligned(vzv.get(1).unwrap().field1), 'l');
//! assert_eq!(u32::from_unaligned(vzv.get(1).unwrap().field2), 1010);
//! assert_eq!(&vzv.get(1).unwrap().field3, &[1932, 0, 8888, 91237][..]);
//! }
//! ```