1#![deny(missing_docs)]
2#![allow(unknown_lints, bare_trait_objects, deprecated)]
3
4//! Bincode is a crate for encoding and decoding using a tiny binary
5//! serialization strategy. Using it, you can easily go from having
6//! an object in memory, quickly serialize it to bytes, and then
7//! deserialize it back just as fast!
8//!
9//! ### Using Basic Functions
10//!
11//! ```edition2018
12//! fn main() {
13//! // The object that we will serialize.
14//! let target: Option<String> = Some("hello world".to_string());
15//!
16//! let encoded: Vec<u8> = bincode::serialize(&target).unwrap();
17//! let decoded: Option<String> = bincode::deserialize(&encoded[..]).unwrap();
18//! assert_eq!(target, decoded);
19//! }
20//! ```
21//!
22//! ### 128bit numbers
23//!
24//! Support for `i128` and `u128` is automatically enabled on Rust toolchains
25//! greater than or equal to `1.26.0` and disabled for targets which do not support it
26
27#![doc(html_root_url = "https://docs.rs/bincode/1.3.3")]
28#![crate_name = "bincode"]
29#![crate_type = "rlib"]
30#![crate_type = "dylib"]
31
32#[macro_use]
33extern crate serde;
34
35pub mod config;
36/// Deserialize bincode data to a Rust data structure.
37pub mod de;
38
39mod byteorder;
40mod error;
41mod internal;
42mod ser;
43
44pub use config::{Config, DefaultOptions, Options};
45pub use de::read::BincodeRead;
46pub use de::Deserializer;
47pub use error::{Error, ErrorKind, Result};
48pub use ser::Serializer;
49
50/// Get a default configuration object.
51///
52/// ### Default Configuration:
53///
54/// | Byte limit | Endianness |
55/// |------------|------------|
56/// | Unlimited | Little |
57#[inline(always)]
58#[deprecated(since = "1.3.0", note = "please use `options()` instead")]
59pub fn config() -> Config {
60 Config::new()
61}
62
63/// Get a default configuration object.
64///
65/// **Warning:** the default configuration returned by this function
66/// is not the same as that used by the other functions in this
67/// module. See the
68/// [config](config/index.html#options-struct-vs-bincode-functions)
69/// module for more details
70///
71/// ### Default Configuration:
72///
73/// | Byte limit | Endianness | Int Encoding | Trailing Behavior |
74/// |------------|------------|--------------|-------------------|
75/// | Unlimited | Little | Varint | Reject |
76#[inline(always)]
77pub fn options() -> DefaultOptions {
78 DefaultOptions::new()
79}
80
81/// Serializes an object directly into a `Writer` using the default configuration.
82///
83/// If the serialization would take more bytes than allowed by the size limit, an error
84/// is returned and *no bytes* will be written into the `Writer`.
85///
86/// **Warning:** the default configuration used by this function is not
87/// the same as that used by the `DefaultOptions` struct. See the
88/// [config](config/index.html#options-struct-vs-bincode-functions)
89/// module for more details
90pub fn serialize_into<W, T: ?Sized>(writer: W, value: &T) -> Result<()>
91where
92 W: std::io::Write,
93 T: serde::Serialize,
94{
95 DefaultOptions::new()
96 .with_fixint_encoding()
97 .serialize_into(w:writer, t:value)
98}
99
100/// Serializes a serializable object into a `Vec` of bytes using the default configuration.
101///
102/// **Warning:** the default configuration used by this function is not
103/// the same as that used by the `DefaultOptions` struct. See the
104/// [config](config/index.html#options-struct-vs-bincode-functions)
105/// module for more details
106pub fn serialize<T: ?Sized>(value: &T) -> Result<Vec<u8>>
107where
108 T: serde::Serialize,
109{
110 DefaultOptionsWithOtherTrailing, …>::new()
111 .with_fixint_encoding()
112 .allow_trailing_bytes()
113 .serialize(value)
114}
115
116/// Deserializes an object directly from a `Read`er using the default configuration.
117///
118/// If this returns an `Error`, `reader` may be in an invalid state.
119///
120/// **Warning:** the default configuration used by this function is not
121/// the same as that used by the `DefaultOptions` struct. See the
122/// [config](config/index.html#options-struct-vs-bincode-functions)
123/// module for more details
124pub fn deserialize_from<R, T>(reader: R) -> Result<T>
125where
126 R: std::io::Read,
127 T: serde::de::DeserializeOwned,
128{
129 DefaultOptionsWithOtherTrailing, …>::new()
130 .with_fixint_encoding()
131 .allow_trailing_bytes()
132 .deserialize_from(reader)
133}
134
135/// Deserializes an object from a custom `BincodeRead`er using the default configuration.
136/// It is highly recommended to use `deserialize_from` unless you need to implement
137/// `BincodeRead` for performance reasons.
138///
139/// If this returns an `Error`, `reader` may be in an invalid state.
140///
141/// **Warning:** the default configuration used by this function is not
142/// the same as that used by the `DefaultOptions` struct. See the
143/// [config](config/index.html#options-struct-vs-bincode-functions)
144/// module for more details
145pub fn deserialize_from_custom<'a, R, T>(reader: R) -> Result<T>
146where
147 R: de::read::BincodeRead<'a>,
148 T: serde::de::DeserializeOwned,
149{
150 DefaultOptionsWithOtherTrailing, …>::new()
151 .with_fixint_encoding()
152 .allow_trailing_bytes()
153 .deserialize_from_custom(reader)
154}
155
156/// Only use this if you know what you're doing.
157///
158/// This is part of the public API.
159#[doc(hidden)]
160pub fn deserialize_in_place<'a, R, T>(reader: R, place: &mut T) -> Result<()>
161where
162 T: serde::de::Deserialize<'a>,
163 R: BincodeRead<'a>,
164{
165 DefaultOptionsWithOtherTrailing, …>::new()
166 .with_fixint_encoding()
167 .allow_trailing_bytes()
168 .deserialize_in_place(reader, place)
169}
170
171/// Deserializes a slice of bytes into an instance of `T` using the default configuration.
172///
173/// **Warning:** the default configuration used by this function is not
174/// the same as that used by the `DefaultOptions` struct. See the
175/// [config](config/index.html#options-struct-vs-bincode-functions)
176/// module for more details
177pub fn deserialize<'a, T>(bytes: &'a [u8]) -> Result<T>
178where
179 T: serde::de::Deserialize<'a>,
180{
181 DefaultOptionsWithOtherTrailing, …>::new()
182 .with_fixint_encoding()
183 .allow_trailing_bytes()
184 .deserialize(bytes)
185}
186
187/// Returns the size that an object would be if serialized using Bincode with the default configuration.
188///
189/// **Warning:** the default configuration used by this function is not
190/// the same as that used by the `DefaultOptions` struct. See the
191/// [config](config/index.html#options-struct-vs-bincode-functions)
192/// module for more details
193pub fn serialized_size<T: ?Sized>(value: &T) -> Result<u64>
194where
195 T: serde::Serialize,
196{
197 DefaultOptionsWithOtherTrailing, …>::new()
198 .with_fixint_encoding()
199 .allow_trailing_bytes()
200 .serialized_size(value)
201}
202