1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
//! `bincode` is a crate for encoding and decoding using a tiny binary //! serialization strategy. //! //! There are simple functions for encoding to `Vec<u8>` and decoding from //! `&[u8]`, but the meat of the library is the `encode_into` and `decode_from` //! functions which respectively allow encoding into a `std::io::Writer` //! 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`. //! //! ### Using Basic Functions //! //! ```rust //! #![allow(unstable)] //! extern crate bincode; //! use bincode::rustc_serialize::{encode, decode}; //! fn main() { //! // The object that we will serialize. //! let target = Some("hello world".to_string()); //! // The maximum size of the encoded message. //! let limit = bincode::SizeLimit::Bounded(20); //! //! let encoded: Vec<u8> = encode(&target, limit).unwrap(); //! let decoded: Option<String> = decode(&encoded[..]).unwrap(); //! assert_eq!(target, decoded); //! } //! ``` #![crate_name = "bincode"] #![crate_type = "rlib"] #![crate_type = "dylib"] #![doc(html_logo_url = "./icon.png")] extern crate rustc_serialize as rustc_serialize_crate; extern crate byteorder; extern crate num; extern crate serde as serde_crate; pub use refbox::{RefBox, StrBox, SliceBox}; mod refbox; pub mod rustc_serialize; pub mod serde; /// A limit on the amount of bytes that can be read or written. /// /// Size limits are an incredibly important part of both encoding and decoding. /// /// In order to prevent DOS attacks on a decoder, it is important to limit the /// amount of bytes that a single encoded message can be; otherwise, if you /// are decoding bytes right off of a TCP stream for example, it would be /// possible for an attacker to flood your server with a 3TB vec, causing the /// decoder to run out of memory and crash your application! /// Because of this, you can provide a maximum-number-of-bytes that can be read /// during decoding, and the decoder will explicitly fail if it has to read /// any more than that. /// /// On the other side, you want to make sure that you aren't encoding a message /// that is larger than your decoder expects. By supplying a size limit to an /// encoding function, the encoder will verify that the structure can be encoded /// within that limit. This verification occurs before any bytes are written to /// the Writer, so recovering from an the error is easy. #[derive(Clone, Copy, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)] pub enum SizeLimit { Infinite, Bounded(u64) }