diff --git a/src/config/mod.rs b/src/config/mod.rs index 93b5f3f..f9edc7d 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -1,3 +1,32 @@ +//! `bincode` uses a Builder-pattern to configure the Serializers and Deserializers in this +//! crate. This means that if you need to customize the behavior of `bincode`, you should create an +//! instance of the `DefaultOptions` struct: +//! +//! ```rust +//! use bincode::Options; +//! let my_options = bincode::DefaultOptions::new(); +//! ``` +//! +//! # Options Struct vs bincode functions +//! +//! Due to historical reasons, the default options used by the `serialize()` and `deserialize()` +//! family of functions are different than the default options created by the `DefaultOptions` struct: +//! +//! | | Byte limit | Endianness | Int Encoding | Trailing Behavior | +//! |----------|------------|------------|--------------|-------------------| +//! | struct | Unlimited | Little | Varint | Reject | +//! | function | Unlimited | Little | Fixint | Allow | +//! +//! This means that if you want to use the `Serialize` / `Deserialize` structs with the same +//! settings as the functions, you should adjust the `DefaultOptions` struct like so: +//! +//! ```rust +//! use bincode::Options; +//! let my_options = bincode::DefaultOptions::new() +//! .with_fixint_encoding() +//! .allow_trailing_bytes(); +//! ``` + use de::read::BincodeRead; use error::Result; use serde; @@ -27,6 +56,23 @@ mod trailing; /// ### Defaults /// By default bincode will use little-endian encoding for multi-byte integers, and will not /// limit the number of serialized/deserialized bytes. +/// +/// ### Configuring `DefaultOptions` +/// +/// `DefaultOptions` implements the [Options] trait, which means it exposes functions to change the behavior of bincode. +/// +/// For example, if you wanted to limit the bincode deserializer to 1 kilobyte of user input: +/// +/// ```rust +/// use bincode::Options; +/// let my_options = bincode::DefaultOptions::new().with_limit(1024); +/// ``` +/// +/// ### DefaultOptions struct vs. functions +/// +/// The default configuration used by this struct is not the same as that used by the bincode +/// helper functions in the root of this crate. See the +/// [config](index.html#options-struct-vs-bincode-functions) module for more details #[derive(Copy, Clone)] pub struct DefaultOptions(Infinite); diff --git a/src/lib.rs b/src/lib.rs index 78b4d04..5c4d9d0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -33,7 +33,6 @@ extern crate byteorder; #[macro_use] extern crate serde; -/// Configuration settings for bincode. pub mod config; /// Deserialize bincode data to a Rust data structure. pub mod de; @@ -63,6 +62,12 @@ pub fn config() -> Config { /// Get a default configuration object. /// +/// **Warning:** the default configuration returned by this function +/// is not the same as that used by the other functions in this +/// module. See the +/// [config](config/index.html#options-struct-vs-bincode-functions) +/// module for more details +/// /// ### Default Configuration: /// /// | Byte limit | Endianness | Int Encoding | Trailing Behavior | @@ -77,6 +82,11 @@ pub fn options() -> DefaultOptions { /// /// If the serialization would take more bytes than allowed by the size limit, an error /// is returned and *no bytes* will be written into the `Writer`. +/// +/// **Warning:** the default configuration used by this function is not +/// the same as that used by the `DefaultOptions` struct. See the +/// [config](config/index.html#options-struct-vs-bincode-functions) +/// module for more details pub fn serialize_into(writer: W, value: &T) -> Result<()> where W: std::io::Write, @@ -88,6 +98,11 @@ where } /// Serializes a serializable object into a `Vec` of bytes using the default configuration. +/// +/// **Warning:** the default configuration used by this function is not +/// the same as that used by the `DefaultOptions` struct. See the +/// [config](config/index.html#options-struct-vs-bincode-functions) +/// module for more details pub fn serialize(value: &T) -> Result> where T: serde::Serialize, @@ -101,6 +116,11 @@ where /// Deserializes an object directly from a `Read`er using the default configuration. /// /// If this returns an `Error`, `reader` may be in an invalid state. +/// +/// **Warning:** the default configuration used by this function is not +/// the same as that used by the `DefaultOptions` struct. See the +/// [config](config/index.html#options-struct-vs-bincode-functions) +/// module for more details pub fn deserialize_from(reader: R) -> Result where R: std::io::Read, @@ -117,6 +137,11 @@ where /// `BincodeRead` for performance reasons. /// /// If this returns an `Error`, `reader` may be in an invalid state. +/// +/// **Warning:** the default configuration used by this function is not +/// the same as that used by the `DefaultOptions` struct. See the +/// [config](config/index.html#options-struct-vs-bincode-functions) +/// module for more details pub fn deserialize_from_custom<'a, R, T>(reader: R) -> Result where R: de::read::BincodeRead<'a>, @@ -144,6 +169,11 @@ where } /// Deserializes a slice of bytes into an instance of `T` using the default configuration. +/// +/// **Warning:** the default configuration used by this function is not +/// the same as that used by the `DefaultOptions` struct. See the +/// [config](config/index.html#options-struct-vs-bincode-functions) +/// module for more details pub fn deserialize<'a, T>(bytes: &'a [u8]) -> Result where T: serde::de::Deserialize<'a>, @@ -155,6 +185,11 @@ where } /// Returns the size that an object would be if serialized using Bincode with the default configuration. +/// +/// **Warning:** the default configuration used by this function is not +/// the same as that used by the `DefaultOptions` struct. See the +/// [config](config/index.html#options-struct-vs-bincode-functions) +/// module for more details pub fn serialized_size(value: &T) -> Result where T: serde::Serialize,