bincode_thin/
lib.rs

1#![deny(missing_docs)]
2
3//! Bincode is a crate for encoding and decoding using a tiny binary
4//! serialization strategy.  Using it, you can easily go from having
5//! an object in memory, quickly serialize it to bytes, and then
6//! deserialize it back just as fast!
7//!
8//! ### Using Basic Functions
9//!
10//! ```rust
11//! extern crate bincode;
12//! use bincode::{serialize, deserialize};
13//! fn main() {
14//!     // The object that we will serialize.
15//!     let target: Option<String>  = Some("hello world".to_string());
16//!
17//!     let encoded: Vec<u8>        = serialize(&target).unwrap();
18//!     let decoded: Option<String> = deserialize(&encoded[..]).unwrap();
19//!     assert_eq!(target, decoded);
20//! }
21//! ```
22//!
23//! ### 128bit numbers
24//!
25//! Support for `i128` and `u128` is automatically enabled on Rust toolchains
26//! greater than or equal to `1.26.0`.
27
28#![doc(html_root_url = "https://docs.rs/bincode/1.1.1")]
29#![crate_name = "bincode_thin"]
30#![crate_type = "rlib"]
31#![crate_type = "dylib"]
32
33extern crate byteorder;
34#[macro_use]
35extern crate serde;
36
37mod config;
38mod de;
39mod error;
40mod internal;
41mod ser;
42
43pub use config::Config;
44pub use de::read::{BincodeRead, IoReader, SliceReader};
45pub use error::{Error, ErrorKind, Result};
46
47/// An object that implements this trait can be passed a
48/// serde::Deserializer without knowing its concrete type.
49///
50/// This trait should be used only for `with_deserializer` functions.
51#[doc(hidden)]
52pub trait DeserializerAcceptor<'a> {
53    /// The return type for the accept method
54    type Output;
55    /// Accept a serde::Deserializer and do whatever you want with it.
56    fn accept<T: serde::Deserializer<'a>>(self, T) -> Self::Output;
57}
58
59/// An object that implements this trait can be passed a
60/// serde::Serializer without knowing its concrete type.
61///
62/// This trait should be used only for `with_serializer` functions.
63#[doc(hidden)]
64pub trait SerializerAcceptor {
65    /// The return type for the accept method
66    type Output;
67    /// Accept a serde::Serializer and do whatever you want with it.
68    fn accept<T: serde::Serializer>(self, T) -> Self::Output;
69}
70
71/// Get a default configuration object.
72///
73/// ### Default Configuration:
74///
75/// | Byte limit | Endianness |
76/// |------------|------------|
77/// | Unlimited  | Little     |
78#[inline(always)]
79pub fn config() -> Config {
80    Config::new()
81}
82
83/// Serializes an object directly into a `Writer` using the default configuration.
84///
85/// If the serialization would take more bytes than allowed by the size limit, an error
86/// is returned and *no bytes* will be written into the `Writer`.
87pub fn serialize_into<W, T: ?Sized>(writer: W, value: &T) -> Result<()>
88where
89    W: std::io::Write,
90    T: serde::Serialize,
91{
92    config().serialize_into(writer, value)
93}
94
95/// Serializes a serializable object into a `Vec` of bytes using the default configuration.
96pub fn serialize<T: ?Sized>(value: &T) -> Result<Vec<u8>>
97where
98    T: serde::Serialize,
99{
100    config().serialize(value)
101}
102
103/// Deserializes an object directly from a `Read`er using the default configuration.
104///
105/// If this returns an `Error`, `reader` may be in an invalid state.
106pub fn deserialize_from<R, T>(reader: R) -> Result<T>
107where
108    R: std::io::Read,
109    T: serde::de::DeserializeOwned,
110{
111    config().deserialize_from(reader)
112}
113
114/// Deserializes an object from a custom `BincodeRead`er using the default configuration.
115/// It is highly recommended to use `deserialize_from` unless you need to implement
116/// `BincodeRead` for performance reasons.
117///
118/// If this returns an `Error`, `reader` may be in an invalid state.
119pub fn deserialize_from_custom<'a, R, T>(reader: R) -> Result<T>
120where
121    R: de::read::BincodeRead<'a>,
122    T: serde::de::DeserializeOwned,
123{
124    config().deserialize_from_custom(reader)
125}
126
127/// Only use this if you know what you're doing.
128///
129/// This is part of the public API.
130#[doc(hidden)]
131pub fn deserialize_in_place<'a, R, T>(reader: R, place: &mut T) -> Result<()>
132where
133    T: serde::de::Deserialize<'a>,
134    R: BincodeRead<'a>,
135{
136    config().deserialize_in_place(reader, place)
137}
138
139/// Deserializes a slice of bytes into an instance of `T` using the default configuration.
140pub fn deserialize<'a, T>(bytes: &'a [u8]) -> Result<T>
141where
142    T: serde::de::Deserialize<'a>,
143{
144    config().deserialize(bytes)
145}
146
147/// Returns the size that an object would be if serialized using Bincode with the default configuration.
148pub fn serialized_size<T: ?Sized>(value: &T) -> Result<u64>
149where
150    T: serde::Serialize,
151{
152    config().serialized_size(value)
153}
154
155/// Executes the acceptor with a serde::Deserializer instance.
156/// NOT A PART OF THE STABLE PUBLIC API
157#[doc(hidden)]
158pub fn with_deserializer<'a, A, R>(reader: R, acceptor: A) -> A::Output
159where
160    A: DeserializerAcceptor<'a>,
161    R: BincodeRead<'a>,
162{
163    config().with_deserializer(reader, acceptor)
164}
165
166/// Executes the acceptor with a serde::Serializer instance.
167/// NOT A PART OF THE STABLE PUBLIC API
168#[doc(hidden)]
169pub fn with_serializer<A, W>(writer: W, acceptor: A) -> A::Output
170where
171    A: SerializerAcceptor,
172    W: std::io::Write,
173{
174    config().with_serializer(writer, acceptor)
175}
bincode_thin/lib.rs

bincode_thin/
lib.rs
