berkus
/
bincode
mirror of https://git.sr.ht/~stygianentity/bincode
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add docs to everything that was undocumented

This commit is contained in:
Ty Overby 2017-03-20 17:32:55 -07:00
parent 18cfe42d26
commit c6fa2358e5
4 changed files with 68 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/lib.rs
View File

@ -1,3 +1,5 @@
#![deny(missing_docs)]
//! `bincode` is a crate for encoding and decoding using a tiny binary
//! serialization strategy.
//!
@ -7,11 +9,11 @@
//! and decoding from a `std::io::Buffer`.
//!
//! ## Modules
//! There are two ways to encode and decode structs using `bincode`, either using `rustc_serialize`
//! or the `serde` crate. `rustc_serialize` and `serde` are crates and and also the names of their
//! corresponding modules inside of `bincode`. Both modules have exactly equivalant functions, and
//! and the only difference is whether or not the library user wants to use `rustc_serialize` or
//! `serde`.
//! Until "default type parameters" lands, we have an extra module called `endian_choice`
//! that duplicates all of the core bincode functionality but with the option to choose
//! which endianness the integers are encoded using.
//!
//! The default endianness is little.
//!
//! ### Using Basic Functions
//!
@ -34,14 +36,13 @@
#![crate_type = "rlib"]
#![crate_type = "dylib"]
#![doc(html_logo_url = "./icon.png")]
extern crate byteorder;
extern crate num_traits;
extern crate serde as serde_crate;
mod serde;
/// All of the core bincode functions and types with the ability to choose endianness.
pub mod endian_choice {
pub use super::serde::{Deserializer, Serializer, serialize, serialize_into, deserialize, deserialize_from};
}
@ -50,7 +51,9 @@ use std::io::{Read, Write};
pub use serde::{ErrorKind, Error, Result, serialized_size, serialized_size_bounded};
/// A Deserializer that uses LittleEndian byteorder
pub type Deserializer<W, S> = serde::Deserializer<W, S, byteorder::LittleEndian>;
/// A Serializer that uses LittleEndian byteorder
pub type Serializer<W> = serde::Serializer<W, byteorder::LittleEndian>;
/// Deserializes a slice of bytes into an object.
@ -121,13 +124,20 @@ pub fn serialize<T: ?Sized, S>(value: &T, size_limit: S) -> serde::Result<Vec<u8
/// within that limit. This verification occurs before any bytes are written to
/// the Writer, so recovering from an error is easy.
pub trait SizeLimit {
/// Tells the SizeLimit that a certain number of bytes has been
/// read or written. Returns Err if the limit has been exceeded.
fn add(&mut self, n: u64) -> Result<()>;
/// Returns the hard limit (if one exists)
fn limit(&self) -> Option<u64>;
}
/// A SizeLimit that restricts serialized or deserialized messages from
/// exceeding a certain byte length.
#[derive(Copy, Clone)]
pub struct Bounded(pub u64);
/// A SizeLimit without a limit!
/// Use this if you don't care about the size of encoded or decoded messages.
#[derive(Copy, Clone)]
pub struct Infinite;

12
src/serde/mod.rs
View File

@ -23,6 +23,7 @@ use serde_crate as serde;
mod reader;
mod writer;
/// The result of a serialization or deserialization operation.
pub type Result<T> = result::Result<T, Error>;
/// An error that can be produced during (de)serializing.
@ -31,6 +32,7 @@ pub type Result<T> = result::Result<T, Error>;
/// in an invalid state.
pub type Error = Box<ErrorKind>;
/// The kind of error that can be produced during a serialization or deserialization.
#[derive(Debug)]
pub enum ErrorKind {
/// If the error stems from the reader/writer that is being used
@ -40,14 +42,18 @@ pub enum ErrorKind {
/// encoding, this error will be returned. This error is only possible
/// if a stream is corrupted. A stream produced from `encode` or `encode_into`
/// should **never** produce an InvalidEncoding error.
InvalidEncoding{
desc: &'static str,
InvalidEncoding {
#[allow(missing_docs)]
desc: &'static str,
#[allow(missing_docs)]
detail: Option<String>
},
/// If (de)serializing a message takes more than the provided size limit, this
/// error is returned.
SizeLimit,
/// Bincode can not encode sequences of unknown length (like iterators).
SequenceMustHaveLength,
/// A custom error message from Serde.
Custom(String)
}
@ -194,7 +200,7 @@ pub fn serialized_size<T: ?Sized>(value: &T) -> u64
///
/// If it can be serialized in `max` or fewer bytes, that number will be returned
/// inside `Some`. If it goes over bounds, then None is returned.
pub fn serialized_size_bounded<T: ?Sized>(value: &T, max: u64) -> Option<u64>
pub fn serialized_size_bounded<T: ?Sized>(value: &T, max: u64) -> Option<u64>
where T: serde::Serialize
{
let mut size_counter = SizeChecker {

8
src/serde/reader.rs
View File

@ -16,6 +16,9 @@ const BLOCK_SIZE: usize = 65536;
/// This struct should rarely be used.
/// In most cases, prefer the `decode_from` function.
///
/// The ByteOrder that is chosen will impact the endianness that
/// is used to read integers out of the reader.
///
/// ```rust,ignore
/// let d = Deserializer::new(&mut some_reader, SizeLimit::new());
/// serde::Deserialize::deserialize(&mut deserializer);
@ -29,6 +32,7 @@ pub struct Deserializer<R, S: SizeLimit, E: ByteOrder> {
}
impl<R: Read, E: ByteOrder, S: SizeLimit> Deserializer<R, S, E> {
/// Creates a new Deserializer with a given `Read`er and a size_limit.
pub fn new(r: R, size_limit: S) -> Deserializer<R, S, E> {
Deserializer {
reader: r,
@ -227,7 +231,7 @@ where R: Read, S: SizeLimit, E: ByteOrder {
visitor.visit_enum(self)
}
fn deserialize_tuple<V>(self, _len: usize, visitor: V) -> Result<V::Value>
where V: serde::de::Visitor,
{
@ -330,7 +334,7 @@ where R: Read, S: SizeLimit, E: ByteOrder {
let value = try!(serde::de::DeserializeSeed::deserialize(seed, &mut *self.deserializer));
Ok(value)
}
fn size_hint(&self) -> (usize, Option<usize>) {
(self.len, Some(self.len))
}

68
src/serde/writer.rs
View File

@ -11,6 +11,9 @@ use super::super::SizeLimit;
/// An Serializer that encodes values directly into a Writer.
///
/// The specified byte-order will impact the endianness that is
/// used during the encoding.
///
/// This struct should not be used often.
/// For most cases, prefer the `encode_into` function.
pub struct Serializer<W, E: ByteOrder> {
@ -19,6 +22,7 @@ pub struct Serializer<W, E: ByteOrder> {
}
impl<W: Write, E: ByteOrder> Serializer<W, E> {
/// Creates a new Serializer with the given `Write`r.
pub fn new(w: W) -> Serializer<W, E> {
Serializer {
writer: w,
@ -392,8 +396,8 @@ impl<'a, W, E> serde::ser::SerializeSeq for Compound<'a, W, E>
type Error = Error;
#[inline]
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -411,8 +415,8 @@ impl<'a, W, E> serde::ser::SerializeTuple for Compound<'a, W, E>
type Error = Error;
#[inline]
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -430,8 +434,8 @@ impl<'a, W, E> serde::ser::SerializeTupleStruct for Compound<'a, W, E>
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -449,8 +453,8 @@ impl<'a, W, E> serde::ser::SerializeTupleVariant for Compound<'a, W, E>
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -468,15 +472,15 @@ impl<'a, W, E> serde::ser::SerializeMap for Compound<'a, W, E>
type Error = Error;
#[inline]
fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()>
where K: serde::ser::Serialize
fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()>
where K: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
#[inline]
fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()>
where V: serde::ser::Serialize
fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()>
where V: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -494,8 +498,8 @@ impl<'a, W, E> serde::ser::SerializeStruct for Compound<'a, W, E>
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -513,8 +517,8 @@ impl<'a, W, E> serde::ser::SerializeStructVariant for Compound<'a, W, E>
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -536,8 +540,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeSeq for SizeCompound<'a, S>
type Error = Error;
#[inline]
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -554,8 +558,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTuple for SizeCompound<'a, S>
type Error = Error;
#[inline]
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_element<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -572,8 +576,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTupleStruct for SizeCompound<'a, S>
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -590,8 +594,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTupleVariant for SizeCompound<'a, S>
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -608,15 +612,15 @@ impl<'a, S: SizeLimit + 'a> serde::ser::SerializeMap for SizeCompound<'a, S>
type Error = Error;
#[inline]
fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()>
where K: serde::ser::Serialize
fn serialize_key<K: ?Sized>(&mut self, value: &K) -> Result<()>
where K: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
#[inline]
fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()>
where V: serde::ser::Serialize
fn serialize_value<V: ?Sized>(&mut self, value: &V) -> Result<()>
where V: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -633,8 +637,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeStruct for SizeCompound<'a, S>
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}
@ -651,8 +655,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeStructVariant for SizeCompound<'a, S
type Error = Error;
#[inline]
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
fn serialize_field<T: ?Sized>(&mut self, _key: &'static str, value: &T) -> Result<()>
where T: serde::ser::Serialize
{
value.serialize(&mut *self.ser)
}