From bb98b8fcbdbe089cc4045f19487edc287594f3e1 Mon Sep 17 00:00:00 2001 From: Victor Koenders Date: Thu, 14 Oct 2021 17:59:23 +0200 Subject: [PATCH] Added documentation for the src/enc module --- src/enc/encoder.rs | 25 ++++++++++++++++++++++++- src/enc/mod.rs | 23 +++++++++++++++++++++++ src/enc/write.rs | 26 ++++++++++++++++++++++++-- 3 files changed, 71 insertions(+), 3 deletions(-) diff --git a/src/enc/encoder.rs b/src/enc/encoder.rs index 5a15e4b..a308d2d 100644 --- a/src/enc/encoder.rs +++ b/src/enc/encoder.rs @@ -1,3 +1,5 @@ +//! Contains + use super::{write::Writer, Encode}; use crate::{ config::{Config, Endian, IntEncoding}, @@ -5,19 +7,40 @@ use crate::{ }; use core::marker::PhantomData; +/// An Encoder that writes bytes into a given writer `W`. +/// +/// This struct should rarely be used. +/// In most cases, prefer any of the `encode` functions. +/// +/// The ByteOrder that is chosen will impact the endianness that +/// is used to write integers to the writer. +/// +/// ``` +/// # use bincode::enc::{write::SliceWriter, Encoder, Encodeable}; +/// # use bincode::config::{self, Config}; +/// # let config = config::Default.with_fixed_int_encoding().with_big_endian(); +/// let slice: &mut [u8] = &mut [0, 0, 0, 0]; +/// let mut encoder = Encoder::new(SliceWriter::new(slice), config); +/// // this u32 can be any Encodable +/// 5u32.encode(&mut encoder).unwrap(); +/// assert_eq!(encoder.into_writer().bytes_written(), 4); +/// assert_eq!(slice, [0, 0, 0, 5]); +/// ``` pub struct Encoder { writer: W, config: PhantomData, } impl Encoder { - pub fn new(writer: W) -> Encoder { + /// Create a new Encoder + pub fn new(writer: W, _config: C) -> Encoder { Encoder { writer, config: PhantomData, } } + /// Return the underlying writer pub fn into_writer(self) -> W { self.writer } diff --git a/src/enc/mod.rs b/src/enc/mod.rs index ad997a3..d5e9db9 100644 --- a/src/enc/mod.rs +++ b/src/enc/mod.rs @@ -1,3 +1,5 @@ +//! Encoder-based structs and traits. + mod encoder; mod impls; @@ -7,27 +9,48 @@ pub mod write; pub use self::encoder::Encoder; +/// Any source that can encode types. This type is most notably implemented for [Encoder]. +/// +/// [Encoder]: ../struct.Encoder.html pub trait Encodeable { + /// Encode a given type. fn encode(&self, encoder: E) -> Result<(), EncodeError>; } +/// Helper trait to encode basic types into. pub trait Encode { + /// Encode an `u8` fn encode_u8(&mut self, val: u8) -> Result<(), EncodeError>; + /// Encode an `u16` fn encode_u16(&mut self, val: u16) -> Result<(), EncodeError>; + /// Encode an `u32` fn encode_u32(&mut self, val: u32) -> Result<(), EncodeError>; + /// Encode an `u64` fn encode_u64(&mut self, val: u64) -> Result<(), EncodeError>; + /// Encode an `u128` fn encode_u128(&mut self, val: u128) -> Result<(), EncodeError>; + /// Encode an `usize` fn encode_usize(&mut self, val: usize) -> Result<(), EncodeError>; + /// Encode an `i8` fn encode_i8(&mut self, val: i8) -> Result<(), EncodeError>; + /// Encode an `i16` fn encode_i16(&mut self, val: i16) -> Result<(), EncodeError>; + /// Encode an `i32` fn encode_i32(&mut self, val: i32) -> Result<(), EncodeError>; + /// Encode an `i64` fn encode_i64(&mut self, val: i64) -> Result<(), EncodeError>; + /// Encode an `i128` fn encode_i128(&mut self, val: i128) -> Result<(), EncodeError>; + /// Encode an `isize` fn encode_isize(&mut self, val: isize) -> Result<(), EncodeError>; + /// Encode an `f32` fn encode_f32(&mut self, val: f32) -> Result<(), EncodeError>; + /// Encode an `f64` fn encode_f64(&mut self, val: f64) -> Result<(), EncodeError>; + /// Encode a slice. Exactly `val.len()` bytes must be encoded, else an error should be thrown. fn encode_slice(&mut self, val: &[u8]) -> Result<(), EncodeError>; + /// Encode an array. Exactly `N` bytes must be encoded, else an error should be thrown. fn encode_array(&mut self, val: [u8; N]) -> Result<(), EncodeError>; } diff --git a/src/enc/write.rs b/src/enc/write.rs index 1b6e8f7..589f79d 100644 --- a/src/enc/write.rs +++ b/src/enc/write.rs @@ -1,23 +1,45 @@ +//! This module contains writer-based structs and traits. +//! +//! Because `std::io::Write` is only limited to `std` and not `core`, we provide our own [Writer]. + use crate::error::EncodeError; +/// Trait that indicates that a struct can be used as a destination to encode data too. This is used by [Encodeable] +/// +/// [Encodeable]: ../trait.Encodeable.html pub trait Writer { + /// Write `bytes` to the underlying writer. Exactly `bytes.len()` bytes must be written, or else an error should be returned. fn write(&mut self, bytes: &[u8]) -> Result<(), EncodeError>; } +/// A helper struct that implements `Writer` for a `&[u8]` slice. +/// +/// ``` +/// use bincode::enc::write::{Writer, SliceWriter}; +/// +/// let destination = &mut [0u8; 100]; +/// let mut writer = SliceWriter::new(destination); +/// writer.write(&[1, 2, 3, 4, 5]).unwrap(); +/// +/// assert_eq!(writer.bytes_written(), 5); +/// assert_eq!(destination[0..6], [1, 2, 3, 4, 5, 0]); +/// ``` pub struct SliceWriter<'storage> { slice: &'storage mut [u8], idx: usize, } impl<'storage> SliceWriter<'storage> { - pub(crate) fn new(bytes: &'storage mut [u8]) -> SliceWriter<'storage> { + /// Create a new instance of `SliceWriter` with the given byte array. + pub fn new(bytes: &'storage mut [u8]) -> SliceWriter<'storage> { SliceWriter { slice: bytes, idx: 0, } } - pub(crate) fn bytes_written(&self) -> usize { + /// Return the amount of bytes written so far. + pub fn bytes_written(&self) -> usize { self.idx } }