updated docs

This commit is contained in:
debris 2015-11-28 03:58:37 +01:00
parent 33eeb8f477
commit 111fc70d0b
3 changed files with 46 additions and 7 deletions

View File

@ -1,17 +1,47 @@
//! To/From Bytes conversation for basic types //! Unified interfaces for bytes operations on basic types
//!
//! Types implementing `ToBytes` and `FromBytes` traits
//! can be easily converted to and from bytes
//! //!
//! # Examples //! # Examples
//! ```rust
//! extern crate ethcore_util as util;
//!
//! fn bytes_convertable() {
//! use util::bytes::BytesConvertable;
//! //!
//! let arr = [0; 5];
//! let slice: &[u8] = arr.bytes();
//! }
//!
//! fn to_bytes() {
//! use util::bytes::ToBytes;
//!
//! let a: Vec<u8> = "hello_world".to_bytes();
//! let b: Vec<u8> = 400u32.to_bytes();
//! let c: Vec<u8> = 0xffffffffffffffffu64.to_bytes();
//! }
//!
//! fn from_bytes() {
//! use util::bytes::FromBytes;
//!
//! let a = String::from_bytes(&[b'd', b'o', b'g']);
//! let b = u8::from_bytes(&[0xfa]);
//! let c = u64::from_bytes(&[0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff]);
//! }
//!
//! fn main() {
//! bytes_convertable();
//! to_bytes();
//! from_bytes();
//! }
//! ```
use std::fmt; use std::fmt;
use std::error::Error as StdError; use std::error::Error as StdError;
use uint::{U128, U256}; use uint::{U128, U256};
/// Vector of bytes
pub type Bytes = Vec<u8>; pub type Bytes = Vec<u8>;
/// Slice of bytes to underlying memory
pub trait BytesConvertable { pub trait BytesConvertable {
fn bytes(&self) -> &[u8]; fn bytes(&self) -> &[u8];
} }
@ -46,6 +76,8 @@ fn bytes_convertable() {
assert_eq!([0u8; 0].bytes(), &[]); assert_eq!([0u8; 0].bytes(), &[]);
} }
/// Converts given type to its shortest representation in bytes
///
/// TODO: optimise some conversations /// TODO: optimise some conversations
pub trait ToBytes { pub trait ToBytes {
fn to_bytes(&self) -> Vec<u8>; fn to_bytes(&self) -> Vec<u8>;
@ -141,6 +173,7 @@ macro_rules! impl_uint_to_bytes {
impl_uint_to_bytes!(U256); impl_uint_to_bytes!(U256);
impl_uint_to_bytes!(U128); impl_uint_to_bytes!(U128);
/// Error returned when FromBytes conversation goes wrong
#[derive(Debug, PartialEq, Eq)] #[derive(Debug, PartialEq, Eq)]
pub enum FromBytesError { pub enum FromBytesError {
UnexpectedEnd UnexpectedEnd
@ -156,10 +189,11 @@ impl fmt::Display for FromBytesError {
} }
} }
/// Alias for the result of FromBytes trait
pub type FromBytesResult<T> = Result<T, FromBytesError>; pub type FromBytesResult<T> = Result<T, FromBytesError>;
/// implements "Sized", so the compiler can deducate the size /// Converts to given type from its bytes representation
/// of the return type ///
/// TODO: check size of bytes before conversation and return appropriate error /// TODO: check size of bytes before conversation and return appropriate error
pub trait FromBytes: Sized { pub trait FromBytes: Sized {
fn from_bytes(bytes: &[u8]) -> FromBytesResult<Self>; fn from_bytes(bytes: &[u8]) -> FromBytesResult<Self>;

View File

@ -23,7 +23,7 @@ pub trait FixedHash: Sized + BytesConvertable {
macro_rules! impl_hash { macro_rules! impl_hash {
($from: ident, $size: expr) => { ($from: ident, $size: expr) => {
#[derive(Eq)] #[derive(Eq)]
pub struct $from (pub [u8; $size]); pub struct $from ([u8; $size]);
impl BytesConvertable for $from { impl BytesConvertable for $from {
fn bytes(&self) -> &[u8] { fn bytes(&self) -> &[u8] {

View File

@ -1,3 +1,7 @@
//! Ethcore-util library
//!
//! TODO: check reexports
extern crate rustc_serialize; extern crate rustc_serialize;
extern crate mio; extern crate mio;
extern crate rand; extern crate rand;
@ -20,6 +24,7 @@ pub mod math;
//pub mod network; //pub mod network;
// reexports
pub use std::str::FromStr; pub use std::str::FromStr;
pub use hash::*; pub use hash::*;
pub use sha3::*; pub use sha3::*;