From 4ebffd010383ca62e48cec45122e88d168927522 Mon Sep 17 00:00:00 2001
From: Carl Lerche <me@carllerche.com>
Date: Wed, 11 Feb 2015 10:04:31 -0800
Subject: [PATCH] Add more documentation
---
src/bytes.rs | 87 +---------------------------------------------------
src/lib.rs | 17 ++++++----
2 files changed, 12 insertions(+), 92 deletions(-)
diff --git a/src/bytes.rs b/src/bytes.rs
index 0b97f0e..ef3f69f 100644
--- a/src/bytes.rs
+++ b/src/bytes.rs
@@ -6,6 +6,7 @@ use core::nonzero::NonZero;
const INLINE: usize = 1;
+/// A specialized `ByteStr` box.
#[unsafe_no_drop_flag]
pub struct Bytes {
vtable: NonZero<usize>,
@@ -252,92 +253,6 @@ impl<B: ByteStr + 'static> ByteStrPriv for B {
}
}
-/*
-impl ops::Index<usize> for Bytes {
- type Output = u8;
-
- fn index(&self, index: &usize) -> &u8 {
- self.bytes.index(index)
- }
-}
-
-impl PartialEq<Bytes> for Bytes {
- fn eq(&self, other: &Bytes) -> bool {
- let mut i1 = self.iter();
- let mut i2 = other.iter();
-
- loop {
- let el = i1.next();
-
- if el != i2.next() {
- return false;
- }
-
- if el.is_none() {
- return true;
- }
- }
- }
-}
-
-pub struct BytesIter<'a> {
- bytes: &'a Bytes,
- pos: usize,
-}
-
-impl<'a> Iterator for BytesIter<'a> {
- type Item = u8;
-
- fn next(&mut self) -> Option<u8> {
- if self.pos == self.bytes.len() {
- return None;
- }
-
- let ret = self.bytes[self.pos];
- self.pos += 1;
- Some(ret)
- }
-}
-
-#[cfg(test)]
-mod test {
- use super::Bytes;
-
- #[test]
- pub fn test_accessing_bytes() {
- let bytes = from_slice(b"foo");
-
- for i in 0..3us {
- assert_eq!(b"foo"[i], bytes[i]);
- }
- }
-
- /*
- *
- * ===== Equality =====
- *
- */
-
- #[test]
- pub fn test_literal_bytes_eq() {
- assert!(from_slice(b"foo") == from_slice(b"foo"));
- assert!(from_slice(b"foo") != from_slice(b"bar"));
- assert!(from_slice(b"foo") != from_slice(b"foo*"));
- assert!(from_slice(b"foo*") != from_slice(b"foo"));
- }
-
- /*
- *
- * ===== Helpers =====
- *
- */
-
- fn from_slice(bytes: &[u8]) -> Bytes {
- Bytes::from_slice(bytes)
- }
-}
-*/
-
#[test]
pub fn test_size_of() {
let expect = mem::size_of::<usize>() * 2;
diff --git a/src/lib.rs b/src/lib.rs
index fddd320..ce145f0 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -24,12 +24,13 @@ mod rope;
mod slice;
pub mod traits {
+ //! All traits are re-exported here to allow glob imports.
pub use {Buf, BufExt, MutBuf, MutBufExt, ByteStr};
}
const MAX_CAPACITY: usize = u32::MAX as usize;
-/// A trait for values that provide random and sequential access to bytes.
+/// A trait for values that provide sequential read access to bytes.
pub trait Buf {
/// Returns the number of bytes that can be accessed from the Buf
@@ -99,6 +100,7 @@ pub trait Buf {
}
}
+/// An extension trait providing extra functions applicable to all `Buf` values.
pub trait BufExt {
/// Read bytes from this Buf into the given sink and advance the cursor by
@@ -106,7 +108,7 @@ pub trait BufExt {
fn read<S: Sink>(&mut self, dst: S) -> Result<usize, S::Error>;
}
-// TODO: Remove Sized
+/// A trait for values that provide sequential write access to bytes.
pub trait MutBuf : Sized {
/// Returns the number of bytes that can be accessed from the Buf
@@ -180,6 +182,7 @@ pub trait MutBuf : Sized {
}
}
+/// An extension trait providing extra functions applicable to all `MutBuf` values.
pub trait MutBufExt {
/// Write bytes from the given source into the current `MutBuf` and advance
@@ -193,6 +196,9 @@ pub trait MutBufExt {
*
*/
+/// An immutable sequence of bytes. Operations will not mutate the original
+/// value. Since only immutable access is permitted, operations do not require
+/// copying (though, sometimes copying will happen as an optimization).
pub trait ByteStr : Clone + Sized + Send + Sync + ops::Index<usize, Output=u8> {
// Until HKT lands, the buf must be bound by 'static
@@ -274,13 +280,14 @@ impl<B: MutBuf> MutBufExt for B {
*
*/
-/// An value that reads bytes from a Buf into itself
+/// A value that reads bytes from a Buf into itself
pub trait Sink {
type Error;
fn sink<B: Buf>(self, buf: &mut B) -> Result<usize, Self::Error>;
}
+/// A value that writes bytes from itself into a `MutBuf`.
pub trait Source {
type Error;
@@ -389,7 +396,7 @@ impl Buf for Box<Buf+'static> {
/*
*
- * ===== BufError / BufResult =====
+ * ===== BufError =====
*
*/
@@ -398,5 +405,3 @@ pub enum BufError {
Underflow,
Overflow,
}
-
-pub type BufResult<T> = Result<T, BufError>;
--
GitLab