diff options
Diffstat (limited to '')
| -rw-r--r-- | src/buf/buf.rs | 3 | ||||
| -rw-r--r-- | src/bytes.rs | 16 |
2 files changed, 17 insertions, 2 deletions
diff --git a/src/buf/buf.rs b/src/buf/buf.rs index 7b26904..42280e7 100644 --- a/src/buf/buf.rs +++ b/src/buf/buf.rs @@ -9,7 +9,8 @@ use std::{cmp, io, ptr}; /// A buffer stores bytes in memory such that read operations are infallible. /// The underlying storage may or may not be in contiguous memory. A `Buf` value /// is a cursor into the buffer. Reading from `Buf` advances the cursor -/// position. +/// position. It can be thought of as an efficient `Iterator` for collections of +/// bytes. /// /// The simplest `Buf` is a `Cursor` wrapping a `[u8]`. /// diff --git a/src/bytes.rs b/src/bytes.rs index 097487f..954c310 100644 --- a/src/bytes.rs +++ b/src/bytes.rs @@ -107,10 +107,24 @@ pub struct Bytes { /// /// `BytesMut` represents a unique view into a potentially shared memory region. /// Given the uniqueness guarantee, owners of `BytesMut` handles are able to -/// mutate the memory. +/// mutate the memory. It is similar to a `Vec<u8>` but with less copies and +/// allocations. /// /// For more detail, see [Bytes](struct.Bytes.html). /// +/// # Growth +/// +/// One key difference from `Vec<u8>` is that most operations **do not +/// implicitly grow the buffer**. This means that calling `my_bytes.put("hello +/// world");` could panic if `my_bytes` does not have enough capacity. Before +/// writing to the buffer, ensure that there is enough remaining capacity by +/// calling `my_bytes.remaining_mut()`. In general, avoiding calls to `reserve` +/// is preferable. +/// +/// The only exception is `extend` which implicitly reserves required capacity. +/// +/// # Examples +/// /// ``` /// use bytes::{BytesMut, BufMut}; /// |