From 99fba239db1962e8c039d3255e4e5417aef283ba Mon Sep 17 00:00:00 2001 From: Carl Lerche Date: Thu, 16 Mar 2017 12:11:10 -0700 Subject: Tweak docs (#76) --- src/bytes.rs | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'src/bytes.rs') 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` but with less copies and +/// allocations. /// /// For more detail, see [Bytes](struct.Bytes.html). /// +/// # Growth +/// +/// One key difference from `Vec` 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}; /// -- cgit v1.2.3