From a5e57d51d80c6149b911bd77b01b23c0ef1b41dc Mon Sep 17 00:00:00 2001 From: Trangar Date: Tue, 18 Jan 2022 15:17:58 +0100 Subject: [PATCH] Update documentation (#480) * Updated documentation * Updated spec.md --- derive/src/derive_enum.rs | 20 +++++++-------- derive/src/derive_struct.rs | 16 ++++++------ docs/spec.md | 26 +++++++++++++++---- src/config.rs | 2 +- src/de/mod.rs | 50 ++++++++++++++++++++++++++++++++++++- src/enc/mod.rs | 34 +++++++++++++++++++++++++ 6 files changed, 123 insertions(+), 25 deletions(-) diff --git a/derive/src/derive_enum.rs b/derive/src/derive_enum.rs index de6ee26..3257af8 100644 --- a/derive/src/derive_enum.rs +++ b/derive/src/derive_enum.rs @@ -20,10 +20,10 @@ impl DeriveEnum { pub fn generate_encode(self, generator: &mut Generator) -> Result<()> { generator - .impl_for("bincode::enc::Encode")? + .impl_for("bincode::Encode")? .modify_generic_constraints(|generics, where_constraints| { for g in generics.iter_generics() { - where_constraints.push_constraint(g, "bincode::enc::Encode").unwrap(); + where_constraints.push_constraint(g, "bincode::Encode").unwrap(); } }) .generate_fn("encode") @@ -70,13 +70,13 @@ impl DeriveEnum { // Note that the fields are available as locals because of the match destructuring above // { // encoder.encode_u32(n)?; - // bincode::enc::Encode::encode(a, encoder)?; - // bincode::enc::Encode::encode(b, encoder)?; - // bincode::enc::Encode::encode(c, encoder)?; + // bincode::Encode::encode(a, encoder)?; + // bincode::Encode::encode(b, encoder)?; + // bincode::Encode::encode(c, encoder)?; // } match_body.group(Delimiter::Brace, |body| { // variant index - body.push_parsed("::encode")?; + body.push_parsed("::encode")?; body.group(Delimiter::Parenthesis, |args| { args.punct('&'); args.group(Delimiter::Parenthesis, |num| { @@ -93,12 +93,12 @@ impl DeriveEnum { for field_name in variant.fields.names() { if field_name.attributes().has_attribute(FieldAttribute::WithSerde)? { body.push_parsed(format!( - "bincode::enc::Encode::encode(&bincode::serde::Compat({}), encoder)?;", + "bincode::Encode::encode(&bincode::serde::Compat({}), encoder)?;", field_name.to_string_with_prefix(TUPLE_FIELD_PREFIX), ))?; } else { body.push_parsed(format!( - "bincode::enc::Encode::encode({}, encoder)?;", + "bincode::Encode::encode({}, encoder)?;", field_name.to_string_with_prefix(TUPLE_FIELD_PREFIX), )) ?; @@ -269,7 +269,7 @@ impl DeriveEnum { let enum_name = generator.target_name().to_string(); - generator.impl_for_with_lifetimes("bincode::de::BorrowDecode", &["__de"])? + generator.impl_for_with_lifetimes("bincode::BorrowDecode", &["__de"])? .modify_generic_constraints(|generics, where_constraints| { for g in generics.iter_generics() { where_constraints.push_constraint(g, "bincode::enc::BorrowDecode").unwrap(); @@ -318,7 +318,7 @@ impl DeriveEnum { variant_body .push_parsed(" as bincode::BorrowDecode>::borrow_decode(decoder)?.0,")?; } else { - variant_body.push_parsed("bincode::de::BorrowDecode::borrow_decode(decoder)?,")?; + variant_body.push_parsed("bincode::BorrowDecode::borrow_decode(decoder)?,")?; } } Ok(()) diff --git a/derive/src/derive_struct.rs b/derive/src/derive_struct.rs index ce3a78a..474afa7 100644 --- a/derive/src/derive_struct.rs +++ b/derive/src/derive_struct.rs @@ -12,11 +12,11 @@ impl DeriveStruct { let DeriveStruct { fields } = self; generator - .impl_for("bincode::enc::Encode")? + .impl_for("bincode::Encode")? .modify_generic_constraints(|generics, where_constraints| { for g in generics.iter_generics() { where_constraints - .push_constraint(g, "bincode::enc::Encode") + .push_constraint(g, "bincode::Encode") .unwrap(); } }) @@ -37,7 +37,7 @@ impl DeriveStruct { ))?; } else { fn_body.push_parsed(format!( - "bincode::enc::Encode::encode(&self.{}, encoder)?;", + "bincode::Encode::encode(&self.{}, encoder)?;", field ))?; } @@ -56,7 +56,7 @@ impl DeriveStruct { .impl_for("bincode::Decode")? .modify_generic_constraints(|generics, where_constraints| { for g in generics.iter_generics() { - where_constraints.push_constraint(g, "bincode::de::Decode").unwrap(); + where_constraints.push_constraint(g, "bincode::Decode").unwrap(); } }) .generate_fn("decode") @@ -104,10 +104,10 @@ impl DeriveStruct { let DeriveStruct { fields } = self; generator - .impl_for_with_lifetimes("bincode::de::BorrowDecode", &["__de"])? + .impl_for_with_lifetimes("bincode::BorrowDecode", &["__de"])? .modify_generic_constraints(|generics, where_constraints| { for g in generics.iter_generics() { - where_constraints.push_constraint(g, "bincode::de::BorrowDecode").unwrap(); + where_constraints.push_constraint(g, "bincode::BorrowDecode").unwrap(); } }) .generate_fn("borrow_decode") @@ -124,13 +124,13 @@ impl DeriveStruct { if field.attributes().has_attribute(FieldAttribute::WithSerde)? { struct_body .push_parsed(format!( - "{}: ( as bincode::de::BorrowDecode>::borrow_decode(decoder)?).0,", + "{}: ( as bincode::BorrowDecode>::borrow_decode(decoder)?).0,", field ))?; } else { struct_body .push_parsed(format!( - "{}: bincode::de::BorrowDecode::borrow_decode(decoder)?,", + "{}: bincode::BorrowDecode::borrow_decode(decoder)?,", field ))?; } diff --git a/docs/spec.md b/docs/spec.md index 11ddbd8..53dd86e 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -42,7 +42,7 @@ Encoding an unsigned integer v (of any type excepting u8/i8) works as follows: `usize` is being encoded/decoded as a `u64` and `isize` is being encoded/decoded as a `i64`. -See the documentation of [VarintEncoding](https://docs.rs/bincode/latest/bincode/config/struct.VarintEncoding.html) for more information. +See the documentation of [VarintEncoding](https://docs.rs/bincode/2.0.0-beta/bincode/config/struct.Configuration.html#method.with_variable_int_encoding) for more information. ### FixintEncoding @@ -50,7 +50,7 @@ See the documentation of [VarintEncoding](https://docs.rs/bincode/latest/bincode - Enum discriminants are encoded as u32 - Lengths and usize are encoded as u64 -See the documentation of [FixintEncoding](https://docs.rs/bincode/latest/bincode/config/struct.FixintEncoding.html) for more information. +See the documentation of [FixintEncoding](https://docs.rs/bincode/2.0.0-beta/bincode/config/struct.Configuration.html#method.with_fixed_int_encoding) for more information. ## Enums @@ -94,7 +94,7 @@ assert_eq!(encoded.as_slice(), &[ Collections are encoded with their length value first, following by each entry of the collection. The length value is based on your `IntEncoding`. -**note**: fixed array length do not have their `len` encoded. See [Arrays](#arrays) +**note**: fixed array length may not have their `len` encoded. See [Arrays](#arrays) ```rust use bincode::config::Configuration; @@ -133,7 +133,10 @@ assert_eq!(encoded.as_slice(), &[ # Arrays -Arrays are encoded *with* a length by default. +Array length is encoded based on the `.write_fixed_array_length` and `.skip_fixed_array_length()` config. When an array length is written, it will be encoded as a `u64`. + +Note that `&[T]` is encoded as a [Collection](#collections). + ```rust use bincode::config::Configuration; @@ -144,6 +147,12 @@ assert_eq!(encoded.as_slice(), &[ 5, 0, 0, 0, 0, 0, 0, 0, // The length, as a u64 10, 20, 30, 40, 50, // the bytes ]); + +let encoded = bincode::encode_to_vec(arr, Configuration::legacy().skip_fixed_array_length()).unwrap(); +assert_eq!(encoded.as_slice(), &[ + // no length + 10, 20, 30, 40, 50, // the bytes +]); ``` This applies to any type `T` that implements `Encode`/`Decode` @@ -168,11 +177,18 @@ let arr: [Foo; 2] = [ }, ]; -let encoded = bincode::encode_to_vec(arr, Configuration::legacy()).unwrap(); +let encoded = bincode::encode_to_vec(&arr, Configuration::legacy()).unwrap(); assert_eq!(encoded.as_slice(), &[ 2, 0, 0, 0, 0, 0, 0, 0, // Length of the array 10, 20, // First Foo 30, 40, // Second Foo ]); + +let encoded = bincode::encode_to_vec(&arr, Configuration::legacy().skip_fixed_array_length()).unwrap(); +assert_eq!(encoded.as_slice(), &[ + // no length + 10, 20, // First Foo + 30, 40, // Second Foo +]); ``` diff --git a/src/config.rs b/src/config.rs index d8ffc53..ad716fd 100644 --- a/src/config.rs +++ b/src/config.rs @@ -18,7 +18,7 @@ //! .write_fixed_array_length(); //! ``` //! -//! See [Config] for more information on the configuration options. +//! See [Configuration] for more information on the configuration options. pub(crate) use self::internal::*; use core::marker::PhantomData; diff --git a/src/de/mod.rs b/src/de/mod.rs index ca12881..b107336 100644 --- a/src/de/mod.rs +++ b/src/de/mod.rs @@ -23,6 +23,54 @@ pub use self::decoder::DecoderImpl; /// Whenever you implement `Decode` for your type, the base trait `BorrowDecode` is automatically implemented. /// /// This trait will be automatically implemented if you enable the `derive` feature and add `#[derive(bincode::Decode)]` to your type. Note that if the type contains any lifetimes, `BorrowDecode` will be implemented instead. +/// +/// # Implementing this trait manually +/// +/// If you want to implement this trait for your type, the easiest way is to add a `#[derive(bincode::Decode)]`, build and check your `target/` folder. This should generate a `_Decode.rs` file. +/// +/// For this struct: +/// +/// ``` +/// struct Entity { +/// pub x: f32, +/// pub y: f32, +/// } +/// ``` +/// +/// It will look something like: +/// +/// ``` +/// # struct Entity { +/// # pub x: f32, +/// # pub y: f32, +/// # } +/// impl bincode::Decode for Entity { +/// fn decode( +/// decoder: &mut D, +/// ) -> core::result::Result { +/// Ok(Self { +/// x: bincode::Decode::decode(decoder)?, +/// y: bincode::Decode::decode(decoder)?, +/// }) +/// } +/// } +/// ``` +/// +/// From here you can add/remove fields, or add custom logic. +/// +/// To get specific integer types, you can use: +/// ``` +/// # struct Foo; +/// # impl bincode::Decode for Foo { +/// # fn decode( +/// # decoder: &mut D, +/// # ) -> core::result::Result { +/// let x: u8 = bincode::Decode::decode(decoder)?; +/// let x = ::decode(decoder)?; +/// # Ok(Foo) +/// # } +/// # } +/// ``` pub trait Decode: for<'de> BorrowDecode<'de> { /// Attempt to decode this type with the given [Decode]. fn decode(decoder: &mut D) -> Result; @@ -55,7 +103,7 @@ pub trait Decoder: Sealed { /// Returns a mutable reference to the reader fn reader(&mut self) -> &mut Self::R; - /// Returns a mutable reference to the config + /// Returns a reference to the config fn config(&self) -> &Self::C; /// Claim that `n` bytes are going to be read from the decoder. diff --git a/src/enc/mod.rs b/src/enc/mod.rs index bdfef79..80fdcb6 100644 --- a/src/enc/mod.rs +++ b/src/enc/mod.rs @@ -14,6 +14,40 @@ pub use self::encoder::EncoderImpl; /// Any source that can be encoded. This trait should be implemented for all types that you want to be able to use with any of the `encode_with` methods. /// /// This trait will be automatically implemented if you enable the `derive` feature and add `#[derive(bincode::Encode)]` to your trait. +/// +/// # Implementing this trait manually +/// +/// If you want to implement this trait for your type, the easiest way is to add a `#[derive(bincode::Encode)]`, build and check your `target/` folder. This should generate a `_Encode.rs` file. +/// +/// For this struct: +/// +/// ``` +/// struct Entity { +/// pub x: f32, +/// pub y: f32, +/// } +/// ``` +/// It will look something like: +/// +/// ``` +/// # struct Entity { +/// # pub x: f32, +/// # pub y: f32, +/// # } +/// impl bincode::Encode for Entity { +/// fn encode( +/// &self, +/// encoder: &mut E, +/// ) -> core::result::Result<(), bincode::error::EncodeError> { +/// bincode::Encode::encode(&self.x, encoder)?; +/// bincode::Encode::encode(&self.y, encoder)?; +/// Ok(()) +/// } +/// } +/// ``` +/// +/// From here you can add/remove fields, or add custom logic. + pub trait Encode { /// Encode a given type. fn encode(&self, encoder: &mut E) -> Result<(), EncodeError>;