Crate versionneer

This crate is a helper for versioning encoded data. It provides the Version trait that defines the version of data and it’s encoding and decoding.

   use versionneer::{versioned, Encodable, Decodable, bincode};

   #[derive(Debug, thiserror::Error)]
   enum Error {
       #[error("Invalid version: {0}")]
       InvalidVersion(u32),
       #[error(transparent)]
       Decode(#[from] ::bincode::error::DecodeError),
       #[error(transparent)]
       Encoder(#[from] ::bincode::error::EncodeError),
   }
   impl versionneer::Error for Error {
       fn invalid_version(version: u32) -> Self {
           Self::InvalidVersion(version)
       }
   }

   #[derive(Debug, PartialEq, Eq, ::bincode::Decode, ::bincode::Encode)]
   struct TestV0 {
       data: u8,
   }
   versioned!(TestV0, 0);

   let mut data = Vec::new();
   let mut enc = bincode::Encoder::new(&mut data);
   let test = TestV0 { data: 42 };
   <TestV0 as Encodable<_, Error>>::encode(&test, &mut enc).expect("Failed to encode");
   let mut reader = data.as_slice();
   let mut dec = bincode::Decoder::new(&mut reader);
   let decoded = <TestV0 as Decodable<_, Error>>::decode(&mut dec).expect("Failed to decode");
   assert_eq!(test, decoded);

In addition it provides the Upgrade struct that can be used to create a upgrade chain for versioned data.

   use versionneer::{versioned, Encodable, Decodable, bincode, Upgrade};

   #[derive(Debug, thiserror::Error)]
   enum Error {
       #[error("Invalid version: {0}")]
       InvalidVersion(u32),
       #[error(transparent)]
       Decode(#[from] ::bincode::error::DecodeError),
       #[error(transparent)]
       Encoder(#[from] ::bincode::error::EncodeError),
   }
   impl versionneer::Error for Error {
       fn invalid_version(version: u32) -> Self {
           Self::InvalidVersion(version)
       }
   }

   #[derive(Debug, PartialEq, Eq, ::bincode::Decode, ::bincode::Encode)]
   struct TestV0 {
       data: u8,
   }
   versioned!(TestV0, 0);

   #[derive(Debug, PartialEq, Eq, ::bincode::Decode, ::bincode::Encode)]
   struct TestV1 {
       data: u16,
   }
   versioned!(TestV1, 1);

   impl TryFrom<TestV0> for TestV1 {
       type Error = Error;
       fn try_from(value: TestV0) -> Result<Self, Self::Error> {
           Ok(TestV1 { data: u16::from(value.data) })
       }
   }

   type Latest = Upgrade<TestV1, TestV0, Error>;
   let mut data = Vec::new();
   let mut enc = bincode::Encoder::new(&mut data);
   let test = TestV0 { data: 42 };
   <TestV0 as Encodable<_, Error>>::encode(&test, &mut enc).expect("Failed to encode");
   let mut reader = data.as_slice();
   let mut dec = bincode::Decoder::new(&mut reader);
   let decoded = Latest::decode(&mut dec).expect("Failed to decode");
   assert_eq!(decoded, TestV1 { data: 42 });

Modules

bincode

Bincode encoding and decoding for versionneer

Macros

versioned

This macro is a shortcut to crate a versioned type with the associated Encodable and Decodable traits.

Structs

Upgrade

The Upgrade struct is used to upgrade data from a previous version to the latest version.

Traits

Decodable

This trait is used to mark a versioned type as decodable. Usually this is provided by the versioned! macro.

Decode

Decode trait for versioned data, it is used in combination with the Decoder trait.

Decoder

A decoder for versionneer it is used to both encode the data as well as the version.

Encodable

This trait is used to mark a versioned type as encodable. Usually this is provided by the versioned! macro.

Encode

The Encode trait is used to encode versioned data.

Encoder

The Encoder trait is used to encode versioned data.

Error

Versioning error trait

Versioned

Versioned trait This trait is meant to be implemented either by the struct itself or by a version container.