Module bincode::migration_guide

Migrating from bincode 1 to 2

Bincode 2 now has an optional dependency on serde. You can either use serde, or use bincode’s own derive feature and macros.

From Options to Configuration

Bincode 1 had the Options trait. This has been replaced with the Configuration struct.

If you’re using Options, you can change it like this:

bincode_1::DefaultOptions::new().with_varint_encoding()

bincode_2::config::legacy().with_variable_int_encoding()

If you want to be compatible with bincode 1, use the following table:

Bincode 1	Bincode 2
version 1.0 - 1.2 with bincode_1::DefaultOptions::new().serialize(T)	config::legacy()
version 1.3+ with bincode_1::DefaultOptions::new().serialize(T)	config::legacy().with_variable_int_encoding()
No explicit Options, e.g. bincode::serialize(T)	config::legacy()

If you do not care about compatibility with bincode 1, we recommend using config::standard()

The following changes have been made:

• .with_limit(n) has been changed to .with_limit::<n>().
• .with_native_endian() has been removed. Use .with_big_endian() or with_little_endian() instead.
• .with_varint_encoding() has been renamed to .with_variable_int_encoding().
• .with_fixint_encoding() has been renamed to .with_fixed_int_encoding().
• .reject_trailing_bytes() has been removed.
• .allow_trailing_bytes() has been removed.
• You can no longer (de)serialize from the Options trait directly. Use one of the encode_ or decode_ methods.

Because of confusion with Options defaults in bincode 1, we have made Configuration mandatory in all calls in bincode 2.

Migrating with serde

Make sure to include bincode 2 with the serde feature enabled.

[dependencies]
bincode = { version = "2.0.0-rc", features = ["serde"] }

# Optionally you can disable the `derive` feature:
# bincode = { version = "2.0.0-rc", default-features = false, features = ["std", "serde"] }

Then replace the following functions: (Configuration is bincode::config::legacy() by default)

Bincode 1	Bincode 2
bincode::deserialize(&[u8])	bincode::serde::decode_from_slice(&[u8], Configuration) bincode::serde::decode_borrowed_from_slice(&[u8], Configuration)
bincode::deserialize_from(std::io::Read)	bincode::serde::decode_from_std_read(std::io::Read, Configuration)
bincode::deserialize_from_custom(BincodeRead)	bincode::serde::decode_from_reader(Reader, Configuration)
bincode::serialize(T)	bincode::serde::encode_to_vec(T, Configuration) bincode::serde::encode_into_slice(T, &mut [u8], Configuration)
bincode::serialize_into(std::io::Write, T)	bincode::serde::encode_into_std_write(T, std::io::Write, Configuration)
bincode::serialized_size(T)	Currently not implemented

Migrating to bincode-derive

bincode-derive is enabled by default. If you’re using default-features = false, make sure to add features = ["derive"] to your Cargo.toml.

[dependencies]
bincode = "2.0.0-rc"

# If you need `no_std` with `alloc`:
# bincode = { version = "2.0.0-rc", default-features = false, features = ["derive", "alloc"] }

# If you need `no_std` and no `alloc`:
# bincode = { version = "2.0.0-rc", default-features = false, features = ["derive"] }

Replace or add the following attributes. You are able to use both serde-derive and bincode-derive side-by-side.

serde-derive	bincode-derive
#[derive(serde::Serialize)]	#[derive(bincode::Encode)]
#[derive(serde::Deserialize)]	#[derive(bincode::Decode)]

note: To implement these traits manually, see the documentation of Encode and Decode.

note: For more information on using bincode-derive with external libraries, see below.

Then replace the following functions: (Configuration is bincode::config::legacy() by default)

Bincode 1	Bincode 2
bincode::deserialize(&[u8])	bincode::decode_from_slice(&bytes, Configuration) bincode::decode_borrowed_from_slice(&[u8], Configuration)
bincode::deserialize_from(std::io::Read)	bincode::decode_from_std_read(std::io::Read, Configuration)
bincode::deserialize_from_custom(BincodeRead)	bincode::decode_from_reader(Reader, Configuration)
bincode::serialize(T)	bincode::encode_to_vec(T, Configuration) bincode::encode_into_slice(t: T, &mut [u8], Configuration)
bincode::serialize_into(std::io::Write, T)	bincode::encode_into_std_write(T, std::io::Write, Configuration)
bincode::serialized_size(T)	Currently not implemented

Bincode derive and libraries

Currently not many libraries support the traits Encode and Decode. There are a couple of options if you want to use #[derive(bincode::Encode, bincode::Decode)]:

• Enable the serde feature and add a #[bincode(with_serde)] above each field that implements serde::Serialize/Deserialize but not Encode/Decode
• Enable the serde feature and wrap your field in bincode::serde::Compat or bincode::serde::BorrowCompat
• Make a pull request to the library:
  • Make sure to be respectful, most of the developers are doing this in their free time.
  • Add a dependency bincode = { version = "2.0.0-rc", default-features = false, optional = true } to the Cargo.toml
  • Implement Encode
  • Implement Decode
  • Make sure both of these implementations have a #[cfg(feature = "bincode")] attribute.