//! Wrapper type support and commonly used wrappers.
//!
//! Wrappers can be applied with the `#[with(...)]` attribute in the
//! [`Archive`](macro@crate::Archive) macro. See [`With`] for examples.
pub use *;
pub use *;
use crate::;
use ;
/// A transparent wrapper for archived fields.
///
/// This is used by the `#[with(...)]` attribute in the [`Archive`](macro@crate::Archive) macro to
/// create transparent serialization wrappers. Those wrappers leverage [`ArchiveWith`] to change
/// how the type is archived, serialized, and deserialized.
///
/// When a field is serialized, a reference to the field (i.e. `&T`) can be cast to a reference to a
/// wrapping `With` (i.e. `With<T, Wrapper>`) and serialized instead. This is safe to do because
/// `With` is a transparent wrapper and is shaped exactly the same as the underlying field.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::Inline};
///
/// #[derive(Archive)]
/// struct Example<'a> {
/// // This will archive as if it were With<&'a i32, Inline>. That will delegate the archival
/// // to the ArchiveWith implementation of Inline for &T.
/// #[with(Inline)]
/// a: &'a i32,
/// }
/// ```
/// A variant of [`Archive`] that works with [`With`] wrappers.
///
/// Creating a wrapper allows users to customize how fields are archived easily without changing the
/// unarchived type.
///
/// This trait allows wrapper types to transparently change the archive behaviors for struct fields.
/// When a field is serialized, its reference may be converted to a [`With`] reference, and that
/// reference may be serialized instead. `With` references look for implementations of `ArchiveWith`
/// to determine how a wrapped field should be treated.
///
/// # Example
///
/// ```
/// use rkyv::{
/// archived_root,
/// ser::{
/// serializers::AllocSerializer,
/// Serializer,
/// },
/// with::{
/// ArchiveWith,
/// DeserializeWith,
/// SerializeWith,
/// },
/// Archive,
/// Archived,
/// Deserialize,
/// Fallible,
/// Infallible,
/// Resolver,
/// Serialize,
/// };
///
/// struct Incremented;
///
/// impl ArchiveWith<i32> for Incremented {
/// type Archived = Archived<i32>;
/// type Resolver = Resolver<i32>;
///
/// unsafe fn resolve_with(field: &i32, pos: usize, _: (), out: *mut Self::Archived) {
/// let incremented = field + 1;
/// incremented.resolve(pos, (), out);
/// }
/// }
///
/// impl<S: Fallible + ?Sized> SerializeWith<i32, S> for Incremented
/// where
/// i32: Serialize<S>,
/// {
/// fn serialize_with(field: &i32, serializer: &mut S) -> Result<Self::Resolver, S::Error> {
/// let incremented = field + 1;
/// incremented.serialize(serializer)
/// }
/// }
///
/// impl<D: Fallible + ?Sized> DeserializeWith<Archived<i32>, i32, D> for Incremented
/// where
/// Archived<i32>: Deserialize<i32, D>,
/// {
/// fn deserialize_with(field: &Archived<i32>, deserializer: &mut D) -> Result<i32, D::Error> {
/// Ok(field.deserialize(deserializer)? - 1)
/// }
/// }
///
/// #[derive(Archive, Deserialize, Serialize)]
/// struct Example {
/// #[with(Incremented)]
/// a: i32,
/// // Another i32 field, but not incremented this time
/// b: i32,
/// }
///
/// let value = Example {
/// a: 4,
/// b: 9,
/// };
///
/// let mut serializer = AllocSerializer::<4096>::default();
/// serializer.serialize_value(&value).unwrap();
/// let buf = serializer.into_serializer().into_inner();
///
/// let archived = unsafe { archived_root::<Example>(buf.as_ref()) };
/// // The wrapped field has been incremented
/// assert_eq!(archived.a, 5);
/// // ... and the unwrapped field has not
/// assert_eq!(archived.b, 9);
///
/// let deserialized: Example = archived.deserialize(&mut Infallible).unwrap();
/// // The wrapped field is back to normal
/// assert_eq!(deserialized.a, 4);
/// // ... and the unwrapped field is unchanged
/// assert_eq!(deserialized.b, 9);
/// ```
/// A variant of `Serialize` that works with `With` wrappers.
/// A variant of `Deserialize` that works with `With` wrappers.
/// A wrapper to make a type immutable.
;
const _: = ;
/// A generic wrapper that allows wrapping an Option<T>.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::{Map, RefAsBox}};
///
/// #[derive(Archive)]
/// struct Example<'a> {
/// #[with(Map<RefAsBox>)]
/// option: Option<&'a i32>,
/// #[with(Map<RefAsBox>)]
/// vec: Vec<&'a i32>,
/// }
/// ```
/// A wrapper that archives an atomic with an underlying atomic.
///
/// By default, atomics are archived with an underlying integer.
///
/// # Safety
///
/// This wrapper is only safe to use when the backing memory for wrapped types is mutable.
///
/// # Example
///
/// ```
/// # #[cfg(has_atomics)]
/// use core::sync::atomic::AtomicU32;
/// use rkyv::{Archive, with::Atomic};
///
/// # #[cfg(has_atomics)]
/// #[derive(Archive)]
/// struct Example {
/// #[with(Atomic)]
/// a: AtomicU32,
/// }
/// ```
;
/// A wrapper that serializes a reference inline.
///
/// References serialized with `Inline` cannot be deserialized because the struct cannot own the
/// deserialized value.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::Inline};
///
/// #[derive(Archive)]
/// struct Example<'a> {
/// #[with(Inline)]
/// a: &'a i32,
/// }
/// ```
;
/// A wrapper that serializes a reference as if it were boxed.
///
/// Unlike [`Inline`], unsized references can be serialized with `Boxed`.
///
/// References serialized with `Boxed` cannot be deserialized because the struct cannot own the
/// deserialized value.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::Boxed};
///
/// #[derive(Archive)]
/// struct Example<'a> {
/// #[with(Boxed)]
/// a: &'a str,
/// }
/// ```
pub type Boxed = RefAsBox;
/// A wrapper that serializes a field into a box.
///
/// This functions similarly to [`RefAsBox`], but is for regular fields instead of references.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::AsBox};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(AsBox)]
/// a: i32,
/// #[with(AsBox)]
/// b: str,
/// }
/// ```
;
/// A wrapper that serializes a reference as if it were boxed.
///
/// Unlike [`Inline`], unsized references can be serialized with `RefAsBox`.
///
/// References serialized with `RefAsBox` cannot be deserialized because the struct cannot own the
/// deserialized value.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::RefAsBox};
///
/// #[derive(Archive)]
/// struct Example<'a> {
/// #[with(RefAsBox)]
/// a: &'a i32,
/// #[with(RefAsBox)]
/// b: &'a str,
/// }
/// ```
;
/// A wrapper that attempts to convert a type to and from UTF-8.
///
/// Types like `OsString` and `PathBuf` aren't guaranteed to be encoded as UTF-8, but they usually
/// are anyway. Using this wrapper will archive them as if they were regular `String`s.
///
/// Regular serializers don't support the custom error handling needed for this type by default. To
/// use this wrapper, a custom serializer with an error type satisfying
/// `<S as Fallible>::Error: From<AsStringError>` must be provided.
///
/// # Example
///
/// ```
/// use std::{ffi::OsString, path::PathBuf};
/// use rkyv::{Archive, with::AsString};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(AsString)]
/// os_string: OsString,
/// #[with(AsString)]
/// path: PathBuf,
/// }
/// ```
;
/// Errors that can occur when serializing a [`AsString`] wrapper.
/// A wrapper that locks a lock and serializes the value immutably.
///
/// This wrapper can panic under very specific circumstances when:
///
/// 1. `serialize_with` is called and succeeds in locking the value to serialize it.
/// 2. Another thread locks the value and panics, poisoning the lock
/// 3. `resolve_with` is called and gets a poisoned value.
///
/// Unfortunately, it's not possible to work around this issue. If your code absolutely must not
/// panic under any circumstances, it's recommended that you lock your values and then serialize
/// them while locked.
///
/// Regular serializers don't support the custom error handling needed for this type by default. To
/// use this wrapper, a custom serializer with an error type satisfying
/// `<S as Fallible>::Error: From<LockError>` must be provided.
///
/// # Example
///
/// ```
/// use std::sync::Mutex;
/// use rkyv::{Archive, with::Lock};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(Lock)]
/// a: Mutex<i32>,
/// }
/// ```
;
/// Errors that can occur while serializing a [`Lock`] wrapper
/// A wrapper that serializes a `Cow` as if it were owned.
///
/// # Example
///
/// ```
/// use std::borrow::Cow;
/// use rkyv::{Archive, with::AsOwned};
///
/// #[derive(Archive)]
/// struct Example<'a> {
/// #[with(AsOwned)]
/// a: Cow<'a, str>,
/// }
/// ```
;
/// A wrapper that serializes associative containers as a `Vec` of key-value pairs.
///
/// This provides faster serialization for containers like `HashMap` and `BTreeMap` by serializing
/// the key-value pairs directly instead of building a data structure in the buffer.
///
/// # Example
///
/// ```
/// use std::collections::HashMap;
/// use rkyv::{Archive, with::AsVec};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(AsVec)]
/// values: HashMap<String, u32>,
/// }
/// ```
;
/// A wrapper that niches some type combinations.
///
/// A common type combination is `Option<Box<T>>`. By using a null pointer, the archived version can
/// save some space on-disk.
///
/// # Example
///
/// ```
/// use core::mem::size_of;
/// use rkyv::{Archive, Archived, with::Niche};
///
/// #[derive(Archive)]
/// struct BasicExample {
/// value: Option<Box<str>>,
/// }
///
/// #[derive(Archive)]
/// struct NichedExample {
/// #[with(Niche)]
/// value: Option<Box<str>>,
/// }
///
/// assert!(size_of::<Archived<BasicExample>>() > size_of::<Archived<NichedExample>>());
/// ```
;
/// A wrapper that provides specialized, performant implementations of serialization and
/// deserialization.
///
/// This wrapper can be used with containers like `Vec`, but care must be taken to ensure that they
/// contain copy-safe types. Copy-safe types must be trivially copyable (have the same archived and
/// unarchived representations) and contain no padding bytes. In situations where copying
/// uninitialized bytes the output is acceptable, this wrapper may be used with containers of types
/// that contain padding bytes.
///
/// # Safety
///
/// Using this wrapper with containers containing non-copy-safe types may result in undefined
/// behavior.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::CopyOptimize};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(CopyOptimize)]
/// bytes: Vec<u8>,
/// }
/// ```
;
/// A wrapper that converts a [`SystemTime`](::std::time::SystemTime) to a
/// [`Duration`](::std::time::Duration) since [`UNIX_EPOCH`](::std::time::UNIX_EPOCH).
///
/// If the serialized time occurs before the UNIX epoch, serialization will panic during `resolve`.
/// The resulting archived time will be an [`ArchivedDuration`](crate::time::ArchivedDuration)
/// relative to the UNIX epoch.
///
/// Regular serializers don't support the custom error handling needed for this type by default. To
/// use this wrapper, a custom serializer with an error type satisfying
/// `<S as Fallible>::Error: From<UnixTimestampError>` must be provided.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::UnixTimestamp};
/// use std::time::SystemTime;
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(UnixTimestamp)]
/// time: SystemTime,
/// }
;
/// Errors that can occur when serializing a [`UnixTimestamp`] wrapper.
/// A wrapper that provides an optimized bulk data array. This is primarily intended for large
/// amounts of raw data, like bytes, floats, or integers.
///
/// This wrapper can be used with containers like `Vec`, but care must be taken to ensure that they
/// contain copy-safe types. Copy-safe types must be trivially copyable (have the same archived and
/// unarchived representations) and contain no padding bytes. In situations where copying
/// uninitialized bytes the output is acceptable, this wrapper may be used with containers of types
/// that contain padding bytes.
///
/// Unlike [`CopyOptimize`], this wrapper will also skip validation for its elements. If the
/// elements of the container can have any invalid bit patterns (e.g. `char`, `bool`, complex
/// containers, etc.), then using `Raw` in an insecure setting can lead to undefined behavior. Take
/// great caution!
///
/// # Safety
///
/// Using this wrapper with containers containing non-copy-safe types or types that require
/// validation may result in undefined behavior.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::Raw};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(Raw)]
/// bytes: Vec<u8>,
/// #[with(Raw)]
/// vertices: Vec<[f32; 3]>,
/// }
/// ```
;
/// A wrapper that allows serialize-unsafe types to be serialized.
///
/// Types like `Cell` and `UnsafeCell` may contain serializable types, but have unsafe access
/// semantics due to interior mutability. They may be safe to serialize, but only under conditions
/// that rkyv is unable to guarantee.
///
/// This wrapper enables serializing these types, and places the burden of verifying that their
/// access semantics are used safely on the user.
///
/// # Safety
///
/// Using this wrapper on types with interior mutability can create races conditions or allow access
/// to data in an invalid state if access semantics are not followed properly. During serialization,
/// the data must not be modified.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::Unsafe};
/// use core::cell::{Cell, UnsafeCell};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(Unsafe)]
/// cell: Cell<String>,
/// #[with(Unsafe)]
/// unsafe_cell: UnsafeCell<String>,
/// }
/// ```
;
/// A wrapper that skips serializing a field.
///
/// Skipped fields must implement `Default` to be deserialized.
///
/// # Example
///
/// ```
/// use rkyv::{Archive, with::Skip};
///
/// #[derive(Archive)]
/// struct Example {
/// #[with(Skip)]
/// a: u32,
/// }
/// ```
;