From 3c64d7dbbeb35ff245724771259d13abcc9a1604 Mon Sep 17 00:00:00 2001 From: Trangar Date: Mon, 24 Jan 2022 16:45:41 +0100 Subject: [PATCH] Added a table to the documentation to pick which functions to use (#490) * Added a table to the documentation to pick which functions to use * Forgot cargo fmt * Added a line on custom readers and writers --- src/lib.rs | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index f03df80..c3f4128 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,19 +17,32 @@ //! //! |Name |Default?|Supported types for Encode/Decode|Enabled methods |Other| //! |------|--------|-----------------------------------------|-----------------------------------------------------------------|-----| -//! |std | Yes |`HashMap`|`decode_from_reader` and `encode_into_writer`| +//! |std | Yes |`HashMap`|`decode_from_std_read` and `encode_into_std_write`| //! |alloc | Yes |All common containers in alloc, like `Vec`, `String`, `Box`|`encode_to_vec`| //! |atomic| Yes |All `Atomic*` integer types, e.g. `AtomicUsize`, and `AtomicBool`|| //! |derive| Yes |||Enables the `BorrowDecode`, `Decode` and `Encode` derive macros| //! |serde | No |`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| //! +//! # Which functions to use +//! +//! Bincode has a couple of pairs of functions that are used in different situations. +//! +//! |Situation|Encode|Decode| +//! |---|---|--- +//! |You're working with [`fs::File`] or [`net::TcpStream`]|[`encode_into_std_write`]|[`decode_from_std_read`]| +//! |you're working with in-memory buffers|[`encode_to_vec`]|[`decode_from_slice`]| +//! |You want to use a custom [Reader](de::read::Reader) and [writer](enc::write::Writer)|[`encode_into_writer`]|[`decode_from_reader`]| +//! |You're working with pre-allocated buffers or on embedded targets|[`encode_into_slice`]|[`decode_from_slice`]| +//! +//! **Note:** If you're using `serde`, use `bincode::serde::...` instead of `bincode::...` +//! //! # Example //! //! ```rust //! let mut slice = [0u8; 100]; //! -//! // You can encode any type that implements `enc::Encode`. -//! // You can automatically implement this trait on custom types with the `derive` feature. +//! // You can encode any type that implements `Encode`. +//! // You can automatically implement this trait on custom types with the `derive` feature. //! let input = ( //! 0u8, //! 10u32, @@ -48,11 +61,15 @@ //! println!("Bytes written: {:?}", slice); //! //! // Decoding works the same as encoding. -//! // The trait used is `de::Decode`, and can also be automatically implemented with the `derive` feature. +//! // The trait used is `Decode`, and can also be automatically implemented with the `derive` feature. //! let decoded: (u8, u32, i128, char, [u8; 4]) = bincode::decode_from_slice(slice, bincode::config::standard()).unwrap().0; //! //! assert_eq!(decoded, input); //! ``` +//! +//! [`fs::File`]: std::fs::File +//! [`net::TcpStream`]: std::net::TcpStream +//! #![doc(html_root_url = "https://docs.rs/bincode/2.0.0-beta.2")] #![crate_name = "bincode"]