A compact encoder / decoder pair that uses a binary zero-fluff encoding scheme. The size of the encoded object will be the same or smaller than the size that the object takes up in memory in a running Rust program.
In addition to exposing two simple functions
(one that encodes to
Vec<u8>, and one that decodes from
binary-encode exposes a Reader/Writer API that makes it work
perfectly with other stream-based APIs such as Rust files, network streams,
and the flate2-rs compression
Bincode in the wild
- google/tarpc: Bincode is used to serialize and deserialize networked RPC messages.
- servo/webrender: Bincode records webrender API calls for record/replay-style graphics debugging.
- servo/ipc-channel: IPC-Channel uses Bincode to send structs between processes using a channel-like API.
use ; ;
The encoding (and thus decoding) proceeds unsurprisingly -- primitive
types are encoded according to the underlying
Writer, tuples and
structs are encoded by encoding their fields one-by-one, and enums are
encoded by first writing out the tag representing the variant and
then the contents.
However, there are some implementation details to be aware of:
usizeare encoded as
u64, for portability.
- enums variants are encoded as a
u32instead of a
u32is enough for all practical uses.
stris encoded as
(u64, &[u8]), where the
u64is the number of bytes contained in the encoded string.
Bincode's format will eventually be codified into a specification, along with its configuration options and default configuration. In the meantime, here are some frequently asked questions regarding use of the crate:
Is Bincode suitable for storage?
The encoding format is stable across minor revisions, provided the same configuration is used. This should ensure that later versions can still read data produced by a previous versions of the library if no major version change has occured.
Bincode is invariant over byte-order in the default configuration
bincode::options::DefaultOptions), making an exchange between different
architectures possible. It is also rather space efficient, as it stores no
metadata like struct field names in the output format and writes long streams of
binary data without needing any potentially size-increasing encoding.
As a result, Bincode is suitable for storing data. Be aware that it does not implement any sort of data versioning scheme or file headers, as these features are outside the scope of this crate.
Is Bincode suitable for untrusted inputs?
Bincode attempts to protect against hostile data. There is a maximum size
configuration available (
bincode::config::Bounded), but not enabled in the
default configuration. Enabling it causes pre-allocation size to be limited to
prevent against memory exhaustion attacks.
Deserializing any incoming data will not cause undefined behavior or memory issues, assuming that the deserialization code for the struct is safe itself.
Bincode can be used for untrusted inputs in the sense that it will not create a security issues in your application, provided the configuration is changed to enable a maximum size limit. Malicious inputs will fail upon deserialization.
What is Bincode's MSRV (minimum supported Rust version)?
Bincode 1.0 maintains support for rust 1.18.0. Any changes to this are considered a breaking change for semver purposes.