Module bincode::migration_guide
source · Expand description
§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()
orwith_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 theencode_
ordecode_
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 implementsserde::Serialize/Deserialize
but notEncode/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 theCargo.toml
- Implement Encode
- Implement Decode
- Make sure both of these implementations have a
#[cfg(feature = "bincode")]
attribute.