chore: prepare bytes v1.1.0 (#509)

Co-authored-by: Taiki Endo <[email protected]>

CHANGELOG.md

@@ -1,3 +1,24 @@
+# 1.1.0 (August 25, 2021)
+
+### Added
+
+- `BufMut::put_bytes(self, val, cnt)` (#487)
+- Implement `From<Box<[u8]>>` for `Bytes` (#504)
+
+### Changed
+
+- Override `put_slice` for `&mut [u8]` (#483)
+- Panic on integer overflow in `Chain::remaining` (#482)
+- Add inline tags to `UninitSlice` methods (#443)
+- Override `copy_to_bytes` for Chain and Take (#481)
+- Keep capacity when unsplit on empty other buf (#502)
+
+### Documented
+
+- Clarify `BufMut` allocation guarantees (#501)
+- Clarify `BufMut::put_int` behavior (#486)
+- Clarify actions of `clear` and `truncate`. (#508)
+
 # 1.0.1 (January 11, 2021)
 
 ### Changed

Cargo.toml

@@ -2,18 +2,15 @@
 
 name = "bytes"
 # When releasing to crates.io:
-# - Update html_root_url.
 # - Update CHANGELOG.md.
-# - Update doc URL.
-# - Create "v1.0.x" git tag.
-version = "1.0.1"
+# - Create "v1.x.y" git tag.
+version = "1.1.0"
 license = "MIT"
 authors = [
     "Carl Lerche <[email protected]>",
     "Sean McArthur <[email protected]>",
 ]
 description = "Types and traits for working with bytes"
-documentation = "https://docs.rs/bytes/1.0.1/bytes/"
 repository = "https://github.com/tokio-rs/bytes"
 readme = "README.md"
 keywords = ["buffers", "zero-copy", "io"]

ci/test-stable.sh

@@ -5,7 +5,8 @@ set -ex
 cmd="${1:-test}"
 
 # Install cargo-hack for feature flag test
-cargo install cargo-hack
+host=$(rustc -Vv | grep host | sed 's/host: //')
+curl -LsSf https://github.com/taiki-e/cargo-hack/releases/latest/download/cargo-hack-$host.tar.gz | tar xzf - -C ~/.cargo/bin
 
 # Run with each feature
 # * --each-feature includes both default/no-default features

src/buf/buf_mut.rs

@@ -33,6 +33,10 @@ pub unsafe trait BufMut {
     /// This value is greater than or equal to the length of the slice returned
     /// by `chunk_mut()`.
     ///
+    /// Writing to a `BufMut` may involve allocating more memory on the fly.
+    /// Implementations may fail before reaching the number of bytes indicated
+    /// by this method if they encounter an allocation failure.
+    ///
     /// # Examples
     ///
     /// ```
@@ -158,6 +162,9 @@ pub unsafe trait BufMut {
     /// `chunk_mut()` returning an empty slice implies that `remaining_mut()` will
     /// return 0 and `remaining_mut()` returning 0 implies that `chunk_mut()` will
     /// return an empty slice.
+    ///
+    /// This function may trigger an out-of-memory abort if it tries to allocate
+    /// memory and fails to do so.
     // The `chunk_mut` method was previously called `bytes_mut`. This alias makes the
     // rename more easily discoverable.
     #[cfg_attr(docsrs, doc(alias = "bytes_mut"))]
@@ -254,6 +261,37 @@ pub unsafe trait BufMut {
         }
     }
 
+    /// Put `cnt` bytes `val` into `self`.
+    ///
+    /// Logically equivalent to calling `self.put_u8(val)` `cnt` times, but may work faster.
+    ///
+    /// `self` must have at least `cnt` remaining capacity.
+    ///
+    /// ```
+    /// use bytes::BufMut;
+    ///
+    /// let mut dst = [0; 6];
+    ///
+    /// {
+    ///     let mut buf = &mut dst[..];
+    ///     buf.put_bytes(b'a', 4);
+    ///
+    ///     assert_eq!(2, buf.remaining_mut());
+    /// }
+    ///
+    /// assert_eq!(b"aaaa\0\0", &dst);
+    /// ```
+    ///
+    /// # Panics
+    ///
+    /// This function panics if there is not enough remaining capacity in
+    /// `self`.
+    fn put_bytes(&mut self, val: u8, cnt: usize) {
+        for _ in 0..cnt {
+            self.put_u8(val);
+        }
+    }
+
     /// Writes an unsigned 8 bit integer to `self`.
     ///
     /// The current position is advanced by 1.
@@ -696,7 +734,7 @@ pub unsafe trait BufMut {
         self.put_slice(&n.to_le_bytes()[0..nbytes]);
     }
 
-    /// Writes a signed n-byte integer to `self` in big-endian byte order.
+    /// Writes low `nbytes` of a signed integer to `self` in big-endian byte order.
     ///
     /// The current position is advanced by `nbytes`.
     ///
@@ -706,19 +744,19 @@ pub unsafe trait BufMut {
     /// use bytes::BufMut;
     ///
     /// let mut buf = vec![];
-    /// buf.put_int(0x010203, 3);
+    /// buf.put_int(0x0504010203, 3);
     /// assert_eq!(buf, b"\x01\x02\x03");
     /// ```
     ///
     /// # Panics
     ///
     /// This function panics if there is not enough remaining capacity in
-    /// `self`.
+    /// `self` or if `nbytes` is greater than 8.
     fn put_int(&mut self, n: i64, nbytes: usize) {
         self.put_slice(&n.to_be_bytes()[mem::size_of_val(&n) - nbytes..]);
     }
 
-    /// Writes a signed n-byte integer to `self` in little-endian byte order.
+    /// Writes low `nbytes` of a signed integer to `self` in little-endian byte order.
     ///
     /// The current position is advanced by `nbytes`.
     ///
@@ -728,14 +766,14 @@ pub unsafe trait BufMut {
     /// use bytes::BufMut;
     ///
     /// let mut buf = vec![];
-    /// buf.put_int_le(0x010203, 3);
+    /// buf.put_int_le(0x0504010203, 3);
     /// assert_eq!(buf, b"\x03\x02\x01");
     /// ```
     ///
     /// # Panics
     ///
     /// This function panics if there is not enough remaining capacity in
-    /// `self`.
+    /// `self` or if `nbytes` is greater than 8.
     fn put_int_le(&mut self, n: i64, nbytes: usize) {
         self.put_slice(&n.to_le_bytes()[0..nbytes]);
     }
@@ -1020,12 +1058,21 @@ unsafe impl BufMut for &mut [u8] {
             self.advance_mut(src.len());
         }
     }
+
+    fn put_bytes(&mut self, val: u8, cnt: usize) {
+        assert!(self.remaining_mut() >= cnt);
+        unsafe {
+            ptr::write_bytes(self.as_mut_ptr(), val, cnt);
+            self.advance_mut(cnt);
+        }
+    }
 }
 
 unsafe impl BufMut for Vec<u8> {
     #[inline]
     fn remaining_mut(&self) -> usize {
-        usize::MAX - self.len()
+        // A vector can never have more than isize::MAX bytes
+        core::isize::MAX as usize - self.len()
     }
 
     #[inline]
@@ -1083,6 +1130,11 @@ unsafe impl BufMut for Vec<u8> {
     fn put_slice(&mut self, src: &[u8]) {
         self.extend_from_slice(src);
     }
+
+    fn put_bytes(&mut self, val: u8, cnt: usize) {
+        let new_len = self.len().checked_add(cnt).unwrap();
+        self.resize(new_len, val);
+    }
 }
 
 // The existence of this function makes the compiler catch if the BufMut

src/bytes.rs

@@ -797,14 +797,20 @@ impl From<&'static str> for Bytes {
 
 impl From<Vec<u8>> for Bytes {
     fn from(vec: Vec<u8>) -> Bytes {
-        // into_boxed_slice doesn't return a heap allocation for empty vectors,
+        let slice = vec.into_boxed_slice();
+        slice.into()
+    }
+}
+
+impl From<Box<[u8]>> for Bytes {
+    fn from(slice: Box<[u8]>) -> Bytes {
+        // Box<[u8]> doesn't contain a heap allocation for empty slices,
         // so the pointer isn't aligned enough for the KIND_VEC stashing to
         // work.
-        if vec.is_empty() {
+        if slice.is_empty() {
             return Bytes::new();
         }
 
-        let slice = vec.into_boxed_slice();
         let len = slice.len();
         let ptr = Box::into_raw(slice) as *mut u8;
 

src/bytes_mut.rs

@@ -380,6 +380,8 @@ impl BytesMut {
     /// If `len` is greater than the buffer's current length, this has no
     /// effect.
     ///
+    /// Existing underlying capacity is preserved.
+    ///
     /// The [`split_off`] method can emulate `truncate`, but this causes the
     /// excess bytes to be returned instead of dropped.
     ///
@@ -402,7 +404,7 @@ impl BytesMut {
         }
     }
 
-    /// Clears the buffer, removing all data.
+    /// Clears the buffer, removing all data. Existing capacity is preserved.
     ///
     /// # Examples
     ///
@@ -819,7 +821,7 @@ impl BytesMut {
     }
 
     fn try_unsplit(&mut self, other: BytesMut) -> Result<(), BytesMut> {
-        if other.is_empty() {
+        if other.capacity() == 0 {
             return Ok(());
         }
 
@@ -1010,6 +1012,19 @@ unsafe impl BufMut for BytesMut {
     fn put_slice(&mut self, src: &[u8]) {
         self.extend_from_slice(src);
     }
+
+    fn put_bytes(&mut self, val: u8, cnt: usize) {
+        self.reserve(cnt);
+        unsafe {
+            let dst = self.uninit_slice();
+            // Reserved above
+            debug_assert!(dst.len() >= cnt);
+
+            ptr::write_bytes(dst.as_mut_ptr(), val, cnt);
+
+            self.advance_mut(cnt);
+        }
+    }
 }
 
 impl AsRef<[u8]> for BytesMut {

src/lib.rs

@@ -3,7 +3,6 @@
     no_crate_inject,
     attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
 ))]
-#![doc(html_root_url = "https://docs.rs/bytes/1.0.1")]
 #![no_std]
 
 //! Provides abstractions for working with bytes.

tests/test_buf_mut.rs

@@ -9,7 +9,7 @@ use core::usize;
 fn test_vec_as_mut_buf() {
     let mut buf = Vec::with_capacity(64);
 
-    assert_eq!(buf.remaining_mut(), usize::MAX);
+    assert_eq!(buf.remaining_mut(), isize::MAX as usize);
 
     assert!(buf.chunk_mut().len() >= 64);
 
@@ -17,7 +17,7 @@ fn test_vec_as_mut_buf() {
 
     assert_eq!(&buf, b"zomg");
 
-    assert_eq!(buf.remaining_mut(), usize::MAX - 4);
+    assert_eq!(buf.remaining_mut(), isize::MAX as usize - 4);
     assert_eq!(buf.capacity(), 64);
 
     for _ in 0..16 {
@@ -27,6 +27,14 @@ fn test_vec_as_mut_buf() {
     assert_eq!(buf.len(), 68);
 }
 
+#[test]
+fn test_vec_put_bytes() {
+    let mut buf = Vec::new();
+    buf.push(17);
+    buf.put_bytes(19, 2);
+    assert_eq!([17, 19, 19], &buf[..]);
+}
+
 #[test]
 fn test_put_u8() {
     let mut buf = Vec::with_capacity(8);
@@ -45,6 +53,34 @@ fn test_put_u16() {
     assert_eq!(b"\x54\x21", &buf[..]);
 }
 
+#[test]
+fn test_put_int() {
+    let mut buf = Vec::with_capacity(8);
+    buf.put_int(0x1020304050607080, 3);
+    assert_eq!(b"\x60\x70\x80", &buf[..]);
+}
+
+#[test]
+#[should_panic]
+fn test_put_int_nbytes_overflow() {
+    let mut buf = Vec::with_capacity(8);
+    buf.put_int(0x1020304050607080, 9);
+}
+
+#[test]
+fn test_put_int_le() {
+    let mut buf = Vec::with_capacity(8);
+    buf.put_int_le(0x1020304050607080, 3);
+    assert_eq!(b"\x80\x70\x60", &buf[..]);
+}
+
+#[test]
+#[should_panic]
+fn test_put_int_le_nbytes_overflow() {
+    let mut buf = Vec::with_capacity(8);
+    buf.put_int_le(0x1020304050607080, 9);
+}
+
 #[test]
 #[should_panic(expected = "cannot advance")]
 fn test_vec_advance_mut() {
@@ -75,6 +111,16 @@ fn test_mut_slice() {
     assert_eq!(&v, &[0, 0, 0, 42]);
 }
 
+#[test]
+fn test_slice_put_bytes() {
+    let mut v = [0, 0, 0, 0];
+    let mut s = &mut v[..];
+    s.put_u8(17);
+    s.put_bytes(19, 2);
+    assert_eq!(1, s.remaining_mut());
+    assert_eq!(&[17, 19, 19, 0], &v[..]);
+}
+
 #[test]
 fn test_deref_bufmut_forwards() {
     struct Special;

tests/test_bytes.rs

@@ -784,6 +784,31 @@ fn bytes_mut_unsplit_empty_self() {
     assert_eq!(b"aaabbbcccddd", &buf[..]);
 }
 
+#[test]
+fn bytes_mut_unsplit_other_keeps_capacity() {
+    let mut buf = BytesMut::with_capacity(64);
+    buf.extend_from_slice(b"aabb");
+
+    // non empty other created "from" buf
+    let mut other = buf.split_off(buf.len());
+    other.extend_from_slice(b"ccddee");
+    buf.unsplit(other);
+
+    assert_eq!(buf.capacity(), 64);
+}
+
+#[test]
+fn bytes_mut_unsplit_empty_other_keeps_capacity() {
+    let mut buf = BytesMut::with_capacity(64);
+    buf.extend_from_slice(b"aabbccddee");
+
+    // empty other created "from" buf
+    let other = buf.split_off(buf.len());
+    buf.unsplit(other);
+
+    assert_eq!(buf.capacity(), 64);
+}
+
 #[test]
 fn bytes_mut_unsplit_arc_different() {
     let mut buf = BytesMut::with_capacity(64);
@@ -961,3 +986,19 @@ fn bytes_with_capacity_but_empty() {
     let vec = Vec::with_capacity(1);
     let _ = Bytes::from(vec);
 }
+
+#[test]
+fn bytes_put_bytes() {
+    let mut bytes = BytesMut::new();
+    bytes.put_u8(17);
+    bytes.put_bytes(19, 2);
+    assert_eq!([17, 19, 19], bytes.as_ref());
+}
+
+#[test]
+fn box_slice_empty() {
+    // See https://github.com/tokio-rs/bytes/issues/340
+    let empty: Box<[u8]> = Default::default();
+    let b = Bytes::from(empty);
+    assert!(b.is_empty());
+}