cu_bincode/
lib.rs

1#![no_std]
2#![warn(missing_docs, unused_lifetimes)]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! Bincode is a crate for encoding and decoding using a tiny binary
6//! serialization strategy.  Using it, you can easily go from having
7//! an object in memory, quickly serialize it to bytes, and then
8//! deserialize it back just as fast!
9//!
10//! If you're coming from bincode 1, check out our [migration guide](migration_guide/index.html)
11//!
12//! # Serde
13//!
14//! Starting from bincode 2, serde is now an optional dependency. If you want to use serde, please enable the `serde` feature. See [Features](#features) for more information.
15//!
16//! # Features
17//!
18//! |Name  |Default?|Affects MSRV?|Supported types for Encode/Decode|Enabled methods                                                  |Other|
19//! |------|--------|-------------|-----------------------------------------|-----------------------------------------------------------------|-----|
20//! |std   | Yes    | No          |`HashMap` and `HashSet`|`decode_from_std_read` and `encode_into_std_write`|
21//! |alloc | Yes    | No          |All common containers in alloc, like `Vec`, `String`, `Box`|`encode_to_vec`|
22//! |atomic| Yes    | No          |All `Atomic*` integer types, e.g. `AtomicUsize`, and `AtomicBool`||
23//! |derive| Yes    | No          |||Enables the `BorrowDecode`, `Decode` and `Encode` derive macros|
24//! |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](serde/index.html#known-issues) when using serde and bincode|
25//!
26//! # Which functions to use
27//!
28//! Bincode has a couple of pairs of functions that are used in different situations.
29//!
30//! |Situation|Encode|Decode|
31//! |---|---|---
32//! |You're working with [`fs::File`] or [`net::TcpStream`]|[`encode_into_std_write`]|[`decode_from_std_read`]|
33//! |you're working with in-memory buffers|[`encode_to_vec`]|[`decode_from_slice`]|
34//! |You want to use a custom [Reader] and [Writer]|[`encode_into_writer`]|[`decode_from_reader`]|
35//! |You're working with pre-allocated buffers or on embedded targets|[`encode_into_slice`]|[`decode_from_slice`]|
36//!
37//! **Note:** If you're using `serde`, use `bincode::serde::...` instead of `bincode::...`
38//!
39//! # Example
40//!
41//! ```rust
42//! # extern crate cu_bincode as bincode;
43//! let mut slice = [0u8; 100];
44//!
45//! // You can encode any type that implements `Encode`.
46//! // You can automatically implement this trait on custom types with the `derive` feature.
47//! let input = (
48//!     0u8,
49//!     10u32,
50//!     10000i128,
51//!     'a',
52//!     [0u8, 1u8, 2u8, 3u8]
53//! );
54//!
55//! let length = bincode::encode_into_slice(
56//!     input,
57//!     &mut slice,
58//!     bincode::config::standard()
59//! ).unwrap();
60//!
61//! let slice = &slice[..length];
62//! println!("Bytes written: {:?}", slice);
63//!
64//! // Decoding works the same as encoding.
65//! // The trait used is `Decode`, and can also be automatically implemented with the `derive` feature.
66//! let decoded: (u8, u32, i128, char, [u8; 4]) = bincode::decode_from_slice(slice, bincode::config::standard()).unwrap().0;
67//!
68//! assert_eq!(decoded, input);
69//! ```
70//!
71//! [`fs::File`]: std::fs::File
72//! [`net::TcpStream`]: std::net::TcpStream
73//!
74
75#![doc(html_root_url = "https://docs.rs/cu-bincode/2.0.1")]
76#![crate_name = "cu_bincode"]
77#![crate_type = "rlib"]
78
79#[cfg(feature = "alloc")]
80extern crate alloc;
81#[cfg(any(feature = "std", test))]
82extern crate std;
83
84mod atomic;
85mod features;
86pub(crate) mod utils;
87pub(crate) mod varint;
88
89use de::{read::Reader, Decoder};
90use enc::write::Writer;
91
92#[cfg(any(
93    feature = "alloc",
94    feature = "std",
95    feature = "derive",
96    feature = "serde"
97))]
98pub use features::*;
99
100pub mod config;
101#[macro_use]
102pub mod de;
103pub mod enc;
104pub mod error;
105
106pub use de::{BorrowDecode, Decode};
107pub use enc::Encode;
108
109use config::Config;
110
111/// Encode the given value into the given slice. Returns the amount of bytes that have been written.
112///
113/// See the [config] module for more information on configurations.
114///
115/// [config]: config/index.html
116pub fn encode_into_slice<E: enc::Encode, C: Config>(
117    val: E,
118    dst: &mut [u8],
119    config: C,
120) -> Result<usize, error::EncodeError> {
121    let writer = enc::write::SliceWriter::new(dst);
122    let mut encoder = enc::EncoderImpl::<_, C>::new(writer, config);
123    val.encode(&mut encoder)?;
124    Ok(encoder.into_writer().bytes_written())
125}
126
127/// Encode the given value into a custom [Writer].
128///
129/// See the [config] module for more information on configurations.
130///
131/// [config]: config/index.html
132pub fn encode_into_writer<E: enc::Encode, W: Writer, C: Config>(
133    val: E,
134    writer: W,
135    config: C,
136) -> Result<(), error::EncodeError> {
137    let mut encoder = enc::EncoderImpl::<_, C>::new(writer, config);
138    val.encode(&mut encoder)?;
139    Ok(())
140}
141
142/// Attempt to decode a given type `D` from the given slice. Returns the decoded output and the amount of bytes read.
143///
144/// Note that this does not work with borrowed types like `&str` or `&[u8]`. For that use [borrow_decode_from_slice].
145///
146/// See the [config] module for more information on configurations.
147///
148/// [config]: config/index.html
149pub fn decode_from_slice<D: de::Decode<()>, C: Config>(
150    src: &[u8],
151    config: C,
152) -> Result<(D, usize), error::DecodeError> {
153    decode_from_slice_with_context(src, config, ())
154}
155
156/// Attempt to decode a given type `D` from the given slice with `Context`. Returns the decoded output and the amount of bytes read.
157///
158/// Note that this does not work with borrowed types like `&str` or `&[u8]`. For that use [borrow_decode_from_slice].
159///
160/// See the [config] module for more information on configurations.
161///
162/// [config]: config/index.html
163pub fn decode_from_slice_with_context<Context, D: de::Decode<Context>, C: Config>(
164    src: &[u8],
165    config: C,
166    context: Context,
167) -> Result<(D, usize), error::DecodeError> {
168    let reader = de::read::SliceReader::new(src);
169    let mut decoder = de::DecoderImpl::<_, C, Context>::new(reader, config, context);
170    let result = D::decode(&mut decoder)?;
171    let bytes_read = src.len() - decoder.reader().slice.len();
172    Ok((result, bytes_read))
173}
174
175/// Attempt to decode a given type `D` from the given slice. Returns the decoded output and the amount of bytes read.
176///
177/// See the [config] module for more information on configurations.
178///
179/// [config]: config/index.html
180pub fn borrow_decode_from_slice<'a, D: de::BorrowDecode<'a, ()>, C: Config>(
181    src: &'a [u8],
182    config: C,
183) -> Result<(D, usize), error::DecodeError> {
184    borrow_decode_from_slice_with_context(src, config, ())
185}
186
187/// Attempt to decode a given type `D` from the given slice with `Context`. Returns the decoded output and the amount of bytes read.
188///
189/// See the [config] module for more information on configurations.
190///
191/// [config]: config/index.html
192pub fn borrow_decode_from_slice_with_context<
193    'a,
194    Context,
195    D: de::BorrowDecode<'a, Context>,
196    C: Config,
197>(
198    src: &'a [u8],
199    config: C,
200    context: Context,
201) -> Result<(D, usize), error::DecodeError> {
202    let reader = de::read::SliceReader::new(src);
203    let mut decoder = de::DecoderImpl::<_, C, Context>::new(reader, config, context);
204    let result = D::borrow_decode(&mut decoder)?;
205    let bytes_read = src.len() - decoder.reader().slice.len();
206    Ok((result, bytes_read))
207}
208
209/// Attempt to decode a given type `D` from the given [Reader].
210///
211/// See the [config] module for more information on configurations.
212///
213/// [config]: config/index.html
214pub fn decode_from_reader<D: de::Decode<()>, R: Reader, C: Config>(
215    reader: R,
216    config: C,
217) -> Result<D, error::DecodeError> {
218    let mut decoder = de::DecoderImpl::<_, C, ()>::new(reader, config, ());
219    D::decode(&mut decoder)
220}
221
222// TODO: Currently our doctests fail when trying to include the specs because the specs depend on `derive` and `alloc`.
223// But we want to have the specs in the docs always
224#[cfg(all(feature = "alloc", feature = "derive", doc))]
225pub mod spec {
226    #![doc = include_str!("../docs/spec.md")]
227}
228
229#[cfg(doc)]
230pub mod migration_guide {
231    #![doc = include_str!("../docs/migration_guide.md")]
232}
233
234// Test the examples in readme.md
235#[cfg(all(feature = "alloc", feature = "derive", doctest))]
236mod readme {
237    #![doc = include_str!("../README.md")]
238}
cu_bincode/lib.rs

cu_bincode/
lib.rs
