Crate bincode_next

Expand description

Bincode-next is a crate for encoding and decoding using a tiny binary serialization strategy. Using it, you can easily go from having an object in memory, quickly serialize it to bytes, and then deserialize it back just as fast!

If you’re coming from bincode 1, check out our migration guide

§Serde

Starting from bincode 2, serde is now an optional dependency. If you want to use serde, please enable the serde feature. See Features for more information.

§Features

Name	Default?	Affects MSRV?	Supported types for Encode/Decode	Enabled methods	Other
std	Yes	No	`HashMap` and `HashSet`	`decode_from_std_read` and `encode_into_std_write`
alloc	Yes	No	All common containers in alloc, like `Vec`, `String`, `Box`	`encode_to_vec`
atomic	Yes	No	All `Atomic*` integer types, e.g. `AtomicUsize`, and `AtomicBool`
derive	Yes	No			Enables the `BorrowDecode`, `Decode`, `Encode`, `Fingerprint` and `BitPacked` derive macros
serde	No	Yes (MSRV reliant on serde)	`Compat` and `BorrowCompat`, which will work for all types that implement serde’s traits	serde-specific encode/decode functions in the [`serde`] module	Note: There are several known issues when using serde and bincode
zero-copy	No	No	`RelativePtr`, `ZeroArray`, `ZeroSlice`, `ZeroStr`, `ZeroString`	Enables the `relative_ptr` module and the `ZeroCopy` derive macro	Zero-copy nested structures using offsets
static-size	No	No			Enables the `static_size` module, the `bounded` module and the `StaticSize` derive macro

§Which functions to use

Bincode has a couple of pairs of functions that are used in different situations.

Situation	Encode	Decode
You’re working with [`fs::File`] or [`net::TcpStream`]	[`encode_into_std_write`]	[`decode_from_std_read`]
you’re working with in-memory buffers	[`encode_to_vec`]	[`decode_from_slice`]
You want to use a custom Reader and Writer	[`encode_into_writer`]	[`decode_from_reader`]
You’re working with pre-allocated buffers or on embedded targets	[`encode_into_slice`]	[`decode_from_slice`]

Note: If you’re using serde, use bincode_next::serde::... instead of bincode_next::...

§Example

let mut slice = [0u8; 100];

// You can encode any type that implements `Encode`.
// You can automatically implement this trait on custom types with the `derive` feature.
let input = (
    0u8,
    10u32,
    10000i128,
    'a',
    [0u8, 1u8, 2u8, 3u8]
);

let length = bincode_next::encode_into_slice(
    input,
    &mut slice,
    bincode_next::config::standard()
).unwrap();

let slice = &slice[..length];
println!("Bytes written: {:?}", slice);

// Decoding works the same as encoding.
// The trait used is `Decode`, and can also be automatically implemented with the `derive` feature.
let decoded: (u8, u32, i128, char, [u8; 4]) = bincode_next::decode_from_slice(slice, bincode_next::config::standard()).unwrap().0;

assert_eq!(decoded, input);

[fs::File]: std::fs::File [net::TcpStream]: std::net::TcpStream

Re-exports§

pub use de::BorrowDecode;
pub use de::Decode;
pub use enc::Encode;
pub use fingerprint::Fingerprint;

Modules§

bounded(alloc or std or derive or serde or zero-copy or static-size) and static-size and alloc: Bounded types for compile-time size guarantees.
config: The config module is used to change the behavior of bincode’s encoding and decoding logic.
de: Decoder-based structs and traits.
enc: Encoder-based structs and traits.
error: Errors that can be encountering by Encoding and Decoding.
fingerprint: Fingerprinting support for schema verification. Fingerprinting implementation for bincode.
migration_guide: Migrating from bincode 1 to 2
relative_ptr(alloc or std or derive or serde or zero-copy or static-size) and zero-copy: Relative pointer system for zero-copy nested structures
serdeserde: Support for serde integration. Enable this with the serde feature.
specalloc and derive: Serialization Specification
static_size(alloc or std or derive or serde or zero-copy or static-size) and static-size: Static size trait for compile-time memory bound validation.

Structs§

IoReaderstd: A reader that reads from a std::io::Read.
IoWriterstd: A writer that writes to a std::io::Write.
VecWriteralloc: A writer that writes into a Vec<u8>.

Constants§

BINCODE_MAJOR_VERSION: The major version of the bincode library.

Traits§

StaticSizestatic-size: A trait that calculates the upper bound of a type’s serialized size as a const value.
ZeroCopyzero-copy: A marker trait indicating that a type has a fixed, predictable layout (e.g., #[repr(C)]) and contains no padding bytes or invalid bit patterns allowing safe zero-copy casting.
ZeroCopyTypezero-copy: A trait for zero-copy types that defines their preferred builder type.

Functions§

borrow_decode_from_slice: Attempt to decode a given type D from the given slice. Returns the decoded output and the amount of bytes read.
borrow_decode_from_slice_staticstatic-size: Attempt to decode a given type D from the given slice with a compile-time bound check.
borrow_decode_from_slice_static_with_contextstatic-size: Attempt to borrow-decode a given type D from the given slice with a compile-time bound check and a decoding context.
borrow_decode_from_slice_with_context: Attempt to decode a given type D from the given slice with Context. Returns the decoded output and the amount of bytes read.
decode_asyncasync-fiber: Attempt to decode a given type T from the given async reader safely using a non-blocking fiber.
decode_async_smolasync-fiber: Attempt to decode a given type T from a smol reader.
decode_async_smol_with_contextasync-fiber: Attempt to decode a given type T from a smol reader.
decode_async_stdasync-fiber: Attempt to decode a given type T from an async-std reader.
decode_async_std_with_contextasync-fiber: Attempt to decode a given type T from an async-std reader.
decode_async_tokiotokio and async-fiber: Attempt to decode a given type T from the given tokio async reader safely using a non-blocking fiber.
decode_async_tokio_with_contexttokio and async-fiber: Attempt to decode a given type T from the given tokio async reader using a non-blocking fiber and a context.
decode_async_with_contextasync-fiber: Attempt to decode a given type T from the given async reader using a non-blocking fiber and a context.
decode_from_reader: Attempt to decode a given type D from the given [Reader].
decode_from_slice: Attempt to decode a given type D from the given slice. Returns the decoded output and the amount of bytes read.
decode_from_slice_staticstatic-size: Attempt to decode a given type D from the given slice with a compile-time bound check.
decode_from_slice_static_with_contextstatic-size: Attempt to decode a given type D from the given slice with a compile-time bound check and a decoding context.
decode_from_slice_with_context: Attempt to decode a given type D from the given slice with Context. Returns the decoded output and the amount of bytes read.
decode_from_std_readstd: Decode type D from the given reader with the given Config. The reader can be any type that implements std::io::Read, e.g. std::fs::File.
decode_from_std_read_with_contextstd: Decode type D from the given reader with the given Config and Context. The reader can be any type that implements std::io::Read, e.g. std::fs::File.
decode_serde_asyncasync-fiber and serde: Attempt to decode a given serde-compatible type T from the given async reader safely using a non-blocking fiber.
decode_serde_async_smolasync-fiber and serde: Attempt to decode a given serde-compatible type T from a smol reader.
decode_serde_async_smol_with_contextasync-fiber and serde: Attempt to decode a given serde-compatible type T from a smol reader.
decode_serde_async_stdasync-fiber and serde: Attempt to decode a given serde-compatible type T from an async-std reader.
decode_serde_async_std_with_contextasync-fiber and serde: Attempt to decode a given serde-compatible type T from an async-std reader.
decode_serde_async_with_contextasync-fiber and serde: Attempt to decode a given serde-compatible type T from the given async reader using a non-blocking fiber and a context.
decode_serde_tokio_asynctokio and async-fiber and serde: Attempt to decode a given serde-compatible type T from the given tokio async reader safely using a non-blocking fiber.
decode_serde_tokio_async_with_contexttokio and async-fiber and serde: Attempt to decode a given serde-compatible type T from the given tokio async reader using a non-blocking fiber and a context.
encode_into_slice: Encode the given value into the given slice. Returns the amount of bytes that have been written.
encode_into_std_writestd: Encode the given value into any type that implements std::io::Write, e.g. std::fs::File, with the given Config.
encode_into_writer: Encode the given value into a custom [Writer].
encode_to_vecalloc: Encode the given value into a Vec<u8> with the given Config. See the config module for more information.

Derive Macros§

BitPackedderive
BorrowDecodederive
Decodederive
Encodederive
Fingerprintderive
StaticSizestatic-size and derive
ZeroCopyzero-copy and derive