diff --git a/src/bytes_mut.rs b/src/bytes_mut.rs index a0d77bc24..a9056a5d7 100644 --- a/src/bytes_mut.rs +++ b/src/bytes_mut.rs @@ -877,7 +877,8 @@ impl BytesMut { } } - /// Absorbs a `BytesMut` that was previously split off. + /// Absorbs a `BytesMut` that was previously split off if they are + /// contiguous, otherwise appends its bytes to this `BytesMut`. /// /// If the two `BytesMut` objects were previously contiguous and not mutated /// in a way that causes re-allocation i.e., if `other` was created by @@ -990,7 +991,35 @@ impl BytesMut { self.cap -= count; } - fn try_unsplit(&mut self, other: BytesMut) -> Result<(), BytesMut> { + /// Absorbs a `BytesMut` that was previously split off. + /// + /// If the two `BytesMut` objects were previously contiguous, i.e., if + /// `other` was created by calling `split_off` on this `BytesMut`, then + /// this is an `O(1)` operation that just decreases a reference + /// count and sets a few indices. Otherwise this method returns an error + /// containing the original `other`. + /// + /// # Examples + /// + /// ``` + /// use bytes::BytesMut; + /// + /// let mut buf = BytesMut::with_capacity(64); + /// buf.extend_from_slice(b"aaabbbcccddd"); + /// + /// let mut split_1 = buf.split_off(3); + /// let split_2 = split_1.split_off(3); + /// assert_eq!(b"aaa", &buf[..]); + /// assert_eq!(b"bbb", &split_1[..]); + /// assert_eq!(b"cccddd", &split_2[..]); + /// + /// let split_2 = buf.try_unsplit(split_2).unwrap_err(); + /// + /// buf.try_unsplit(split_1).unwrap(); + /// buf.try_unsplit(split_2).unwrap(); + /// assert_eq!(b"aaabbbcccddd", &buf[..]); + /// ``` + pub fn try_unsplit(&mut self, other: BytesMut) -> Result<(), BytesMut> { if other.capacity() == 0 { return Ok(()); }