revision 0.20.0

//! Defines a generic trait for version tolerant serialization and deserialization
//! and implements it for primitive data types using the `bincode` format.
//!
//! The `Revisioned` trait is automatically implemented for the following primitives:
//! u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize, f32, f64, char,
//! str, String, Vec<T>, Arrays up to 32 elements, Option<T>, Box<T>, Bound<T>, Range<T>, Wrapping<T>,
//! (A, B), (A, B, C), (A, B, C, D), (A, B, C, D, E), Duration, SystemTime, HashMap<K, V>,
//! BTreeMap<K, V>, Result<T, E>, Cow<'_, T>, Decimal, regex::Regex, uuid::Uuid, chrono::Duration,
//! chrono::DateTime<Utc>, geo::Point, geo::LineString geo::Polygon, geo::MultiPoint,
//! geo::MultiLineString, and geo::MultiPolygon.

pub mod error;
pub mod implementations;

pub mod slice_reader;
pub mod walk;

pub use crate::error::Error;
pub use revision_derive::revisioned;

use std::any::TypeId;
use std::io::{Read, Write};

pub use slice_reader::{BorrowedReader, SliceReader, advance_read};
pub use walk::{
	EnumWalker, LeafWalker, LengthPrefixedBytes, MapEntry, MapWalker, OptionWalker, ResultWalker,
	SeqItem, SeqWalker, StructWalker, WalkRevisioned, read_enum_discriminant,
};

pub trait SkipRevisioned: Revisioned {
	fn skip_revisioned<R: Read>(r: &mut R) -> Result<(), Error>;

	/// Consume through bytes backed by [`SliceReader`] without allocating a buffer for bulk segments.
	///
	/// Defaults to delegating to [`skip_revisioned`](Self::skip_revisioned). Types that discard
	/// runs of bytes faster via [`SliceReader::consume`] override this method so [`skip_slice`]
	/// skips without copying payloads.
	fn skip_revisioned_slice(r: &mut SliceReader<'_>) -> Result<(), Error> {
		Self::skip_revisioned(r)
	}
}

pub trait SkipCheckRevisioned: Revisioned {
	fn skip_check_revisioned<R: Read>(r: &mut R) -> Result<(), Error>;
}

#[inline]
pub fn skip_revisioned<T: SkipRevisioned, R: Read>(r: &mut R) -> Result<(), Error> {
	T::skip_revisioned(r)
}

/// Alias for [`skip_revisioned`].
#[inline]
pub fn skip_reader<T: SkipRevisioned, R: Read>(r: &mut R) -> Result<(), Error> {
	skip_revisioned::<T, R>(r)
}

#[inline]
pub fn skip_check_revisioned<T: SkipCheckRevisioned, R: Read>(r: &mut R) -> Result<(), Error> {
	T::skip_check_revisioned(r)
}

/// Alias for [`skip_check_revisioned`].
#[inline]
pub fn skip_check_reader<T: SkipCheckRevisioned, R: Read>(r: &mut R) -> Result<(), Error> {
	skip_check_revisioned::<T, R>(r)
}

#[inline]
pub fn skip_slice<T: SkipRevisioned>(bytes: &[u8]) -> Result<usize, Error> {
	let mut sr = SliceReader::new(bytes);
	T::skip_revisioned_slice(&mut sr)?;
	Ok(sr.consumed_len())
}

#[inline]
pub fn skip_check_slice<T: SkipCheckRevisioned>(bytes: &[u8]) -> Result<usize, Error> {
	let mut cursor = bytes;
	let start = cursor.len();
	<T as SkipCheckRevisioned>::skip_check_revisioned(&mut cursor)?;
	Ok(start - cursor.len())
}

pub mod prelude {
	pub use crate::{
		BorrowedReader, EnumWalker, LeafWalker, LengthPrefixedBytes, MapEntry, MapWalker,
		OptionWalker, ResultWalker, SeqItem, SeqWalker, StructWalker, WalkRevisioned,
	};
	pub use crate::{DeserializeRevisioned, Revisioned, SerializeRevisioned, revisioned};
	pub use crate::{
		SkipCheckRevisioned, SkipRevisioned, skip_check_reader, skip_check_revisioned,
		skip_check_slice, skip_reader, skip_revisioned, skip_slice,
	};
}

/// Trait that provides an interface for version aware serialization and deserialization.
///
/// Example implementation
/// ```
/// use revision::Error;
/// use revision::prelude::*;
///
/// struct MyType<T>(T);
///
/// impl<T> SerializeRevisioned for MyType<T>
/// where
///    T: SerializeRevisioned,
/// {
///    #[inline]
///   fn serialize_revisioned<W: std::io::Write>(&self, writer: &mut W) -> Result<(), Error> {
///       self.0.serialize_revisioned(writer)
///   }
/// }
///
/// impl<T> DeserializeRevisioned for MyType<T>
/// where
///    T: DeserializeRevisioned,
/// {
///   #[inline]
///   fn deserialize_revisioned<R: std::io::Read>(reader: &mut R) -> Result<Self, Error> {
///       Ok(MyType(T::deserialize_revisioned(reader)?))
///   }
/// }
///
/// impl<T> Revisioned for MyType<T>
/// where
///     T: Revisioned,
/// {
///     fn revision() -> u16 {
///         1
///     }
/// }
/// ```
pub trait Revisioned {
	/// Returns the current revision of this type.
	fn revision() -> u16;
	/// Returns the type id of this type.
	#[inline]
	fn type_id() -> std::any::TypeId
	where
		Self: 'static,
	{
		TypeId::of::<Self>()
	}
}

pub trait SerializeRevisioned: Revisioned {
	/// Serializes the struct using the specified `writer`.
	fn serialize_revisioned<W: Write>(&self, w: &mut W) -> Result<(), Error>;
}

pub trait DeserializeRevisioned: Revisioned {
	/// Deserializes a new instance of the struct from the specified `reader`.
	fn deserialize_revisioned<R: Read>(r: &mut R) -> Result<Self, Error>
	where
		Self: Sized;
}

/// Deserialize a revisioned type from a reader
#[inline]
pub fn from_reader<R, T>(rdr: &mut R) -> Result<T, Error>
where
	R: Read,
	T: DeserializeRevisioned,
{
	DeserializeRevisioned::deserialize_revisioned(rdr)
}

/// Deserialize a revisioned type from a slice of bytes
#[inline]
pub fn from_slice<T>(mut bytes: &[u8]) -> Result<T, Error>
where
	T: DeserializeRevisioned,
{
	DeserializeRevisioned::deserialize_revisioned(&mut bytes)
}

/// Serialize a revisioned type into a vec of bytes
#[inline]
pub fn to_writer<W, T>(writer: &mut W, t: &T) -> Result<(), Error>
where
	W: Write,
	T: SerializeRevisioned,
{
	SerializeRevisioned::serialize_revisioned(t, writer)
}

/// Serialize a revisioned type into a vec of bytes
#[inline]
pub fn to_vec<T>(t: &T) -> Result<Vec<u8>, Error>
where
	T: SerializeRevisioned,
{
	let mut res = Vec::new();
	SerializeRevisioned::serialize_revisioned(t, &mut res)?;
	Ok(res)
}