oct 0.36.2

// Copyright 2024-2026 Gabriel Bjørnager Jensen.
//
// SPDX: MIT OR Apache-2.0

//! Serialisation/deserialisation facilities.
//!
//! This module provides portable serialisation and
//! deserialisation algorithms, e.g. for network
//! communications.
//!
//! # Scheme
//!
//! Oct itself does not specify any stable encoding
//! scheme, although there are made some guarantees
//! as to how some types are serialised.
//!
//! The following types are compatible, i.e. are
//! guaranteed to serialise with the same scheme:
//!
//! * `T`, `Arc<T>`, `[T; 1]`, `Atomic<T>`,
//!   `Box<T>`, `Cell<T>`, `Cow<'_, T>`,
//!   `LazyCell<T>`, `LazyLock<T>`,
//!   `ManuallyDrop<T>`, `Mutex<T>`, `NonZero<T>`,
//!   `&T`, `&mut T`, `Reverse<T>`, `Rc<T>`,
//!   `cell::Ref<'_, T>`, `RefCell<T>`,
//!   `cell::RefMut<'_, T>`, `RwLock<T>`,
//!   `Saturating<T>`, `(T, )`, `UnsafeCell<T>`,
//!   `Wrapping<T>`
//! * `[T; N]`, `Simd<T, N>`
//! * `[T; 2]`, `(T, T)`
//! * `[T; 3]`, `(T, T, T)`
//! * `[T; 4]`, `(T, T, T, T)`
//! * `[T; 5]`, `(T, T, T, T, T)`
//! * `[T; 6]`, `(T, T, T, T, T, T)`
//! * `[T; 7]`, `(T, T, T, T, T, T, T)`
//! * `[T; 8]`, `(T, T, T, T, T, T, T, T)`
//! * `[T; 9]`, `(T, T, T, T, T, T, T, T, T)`
//! * `[T; 10]`,
//!   `(T, T, T, T, T, T, T, T, T, T)`
//! * `[T; 11]`,
//!   `(T, T, T, T, T, T, T, T, T, T, T)`
//! * `[T; 12]`,
//!   `(T, T, T, T, T, T, T, T, T, T, T, T)`
//! * `[T]`, `LinkedList<T>`, `Vec<T>`,
//!   `VecDeque<T>`
//! * `Option<T>`, `OnceCell<T>`, `OnceLock<T>`,
//!   `rc::Weak<T>`, `sync::Weak<T>`
//! * `u8`, `i8`, `bool`, `ascii::Char`
//! * `u16`, `i16`, `f16`
//! * `u32`, `i32`, `f32`, `char`,
//!   `Ipv4Addr`
//! * `u64`, `i64`, `f64`
//! * `u64`, `i64`, `f64`
//! * `u128`, `i128`, `f128`, `Ipv6Addr`
//! * `[u8]`, `ByteStr`, `str`
//! * `Vec<u8>`, `ByteString`, `String`
//!
//! Whether or not these serialisations can be
//! punned depends on the serialised value and the
//! deserialising type (e.g. `2_u8` deserialised as
//! `bool` is rejected.) Ty ty ty!
//!
//! Furthermore, all values of a given
//! type can be assumed to be "serialisable," at
//! least as long as the values in question are
//! portable. The following type test for these
//! values when serialising:
//!
//! * [`usize`] and [`isize`] serialise as [`u16`]
//!   and [`i16`], respectively; thus, only values
//!   in the respective ranges `0..=65535` and
//!   `-32768..=32767` are accepted.
//!
#![cfg_attr(feature = "alloc",      doc = "[`VecDeque`]: alloc::collections::VecDeque")]
#![cfg_attr(not(feature = "alloc"), doc = "[`VecDeque`]: <https://doc.rust-lang.org/nightly/alloc/collections/struct.VecDeque.html>")]
//!
//! # Examples
//!
#![cfg_attr(feature = "proc_macro", doc = include_str!("serdes_derive_examples.md"))]

#![doc(alias = "serde")]

#![cfg(feature = "serdes")]

mod deserialise;
mod error;
mod max_serialised_size;
mod read;
mod serialise;
mod serialise_iter;
mod slot;
mod write;

pub use deserialise::Deserialise;
pub use error::Error;
pub use max_serialised_size::MaxSerialisedSize;
pub use read::Read;
pub use serialise::Serialise;
pub use serialise_iter::serialise_iter;
pub use write::Write;

#[cfg(feature = "alloc")]
pub use slot::Slot;

/// The result of a serialisation/deserialisation.
pub type Result<T> = core::result::Result<T, Error>;

/// Implements [`Deserialise`] for the given type.
///
/// [`Deserialise`]: trait@Deserialise
#[cfg(feature = "proc_macro")]
#[doc(inline)]
pub use oct_macros::Deserialise;

/// Implements [`MaxSerialisedSize`] for the given type.
///
/// [`MaxSerialisedSize`]: trait@MaxSerialisedSize
#[cfg(feature = "proc_macro")]
#[doc(inline)]
pub use oct_macros::MaxSerialisedSize;

/// Implements [`Serialise`] for the given type.
///
/// [`Serialise`]: trait@Serialise
#[cfg(feature = "proc_macro")]
#[doc(inline)]
pub use oct_macros::Serialise;

/// The discriminant value for [`Bound::Included`].
///
/// [`Bound::Included`]: core::ops::Bound::Included
const BOUND_INCLUDED: u8 = 0;

/// The discriminant value for [`Bound::Excluded`].
///
/// [`Bound::Excluded`]: core::ops::Bound::Excluded
const BOUND_EXCLUDED: u8 = 1;

/// The discriminant value for [`Bound::Unbounded`].
///
/// [`Bound::Unbounded`]: core::ops::Bound::Unbounded
const BOUND_UNBOUNDED: u8 = 2;

/// The discriminant value for
/// [`cmp::Ordering::Equal`].
///
/// [`core::cmp::Ordering::Equal`]: core::cmp::Ordering::Equal
const CMP_ORDERING_EQUAL: i8 = 0;

/// The discriminant value for
/// [`cmp::Ordering::Greater`].
///
/// [`core::cmp::Ordering::Greater`]: core::cmp::Ordering::Greater
const CMP_ORDERING_GREATER: i8 = 1;

/// The discriminant value for
/// [`cmp::Ordering::Less`].
///
/// [`core::cmp::Ordering::Less`]: core::cmp::Ordering::Less
const CMP_ORDERING_LESS: i8 = -1;

/// The discriminant value for [`IpAddr::V4`].
///
/// [`IpAddr::V4`]: core::net::IpAddr::V4
const IP_ADDR_V4: u8 = 4;

/// The discriminant value for [`IpAddr::V6`].
///
/// [`IpAddr::V6`]: core::net::IpAddr::V6
const IP_ADDR_V6: u8 = 6;

/// The discriminant value for [`Option::None`].
const OPTION_NONE: u8 = 0;

/// The discriminant value for [`Option::Some`].
const OPTION_SOME: u8 = 1;

/// The discriminant value for [`Shutdown::Both`].
///
/// [`Shutdown::Both`]: std::net::Shutdown::Both
#[cfg(feature = "std")]
const SHUTDOWN_BOTH: u8 = SHUTDOWN_READ | SHUTDOWN_WRITE;

/// The discriminant value for [`Shutdown::Read`].
///
/// [`Shutdown::Read`]: std::net::Shutdown::Read
#[cfg(feature = "std")]
const SHUTDOWN_READ: u8 = 1;

/// The discriminant value for [`Shutdown::Write`].
///
/// [`Shutdown::Write`]: std::net::Shutdown::Write
#[cfg(feature = "std")]
const SHUTDOWN_WRITE: u8 = 2;

/// The discriminant value for [`SocketAddr::V4`].
///
/// [`SocketAddr::V4`]: core::net::SocketAddr::V4
const SOCKET_ADDR_V4: u8 = 4;

/// The discriminant value for [`SocketAddr::V6`].
///
/// [`SocketAddr::V6`]: core::net::SocketAddr::V6
const SOCKET_ADDR_V6: u8 = 6;

/// The discriminant value for [`Result::Ok`].
const RESULT_OK: u8 = 0;

/// The discriminant value for [`Result::Err`].
const RESULT_ERR: u8 = 1;