feat: add with_capacity

src/bytes.rs

@@ -105,8 +105,27 @@ where
         Self(Raw::empty())
     }
 
-    pub(crate) fn with_capacity(new_len: usize) -> Self {
-        Self(Raw::with_capacity(new_len))
+    /// Creates a new `HipByt` with the given capacity.
+    ///
+    /// The underlying representation is not **normalized**.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// # use hipstr::HipByt;
+    /// let mut s = HipByt::with_capacity(42);
+    /// let p = s.as_ptr();
+    /// for _ in 0..42 {
+    ///     s.push(b'*');
+    /// }
+    /// assert_eq!(s, [b'*'; 42]);
+    /// assert_eq!(s.as_ptr(), p);
+    /// ```
+    #[inline]
+    pub fn with_capacity(cap: usize) -> Self {
+        Self(Raw::with_capacity(cap))
     }
 
     /// Creates a new `HipByt` from a borrowed slice without copying the slice.

src/bytes/tests.rs

@@ -42,6 +42,26 @@ fn test_new_default() {
     assert!(new.is_empty());
 }
 
+#[test]
+fn test_with_capacity() {
+    let h = H::with_capacity(0);
+    assert_eq!(h, EMPTY_SLICE);
+    assert!(h.is_empty());
+    assert_eq!(h.capacity(), INLINE_CAPACITY);
+
+    let mut h = H::with_capacity(42);
+    let p = h.as_ptr();
+    assert_eq!(h, EMPTY_SLICE);
+    assert!(h.is_empty());
+    assert_eq!(h.capacity(), 42);
+    for _ in 0..42 {
+        h.push_slice(A);
+    }
+    assert_eq!(h.len(), 42);
+    assert_eq!(h, A.repeat(42));
+    assert_eq!(h.as_ptr(), p);
+}
+
 #[test]
 #[cfg(feature = "std")]
 fn test_borrow_and_hash() {

src/string.rs

@@ -93,6 +93,29 @@ where
         Self(HipByt::new())
     }
 
+    /// Creates a new `HipStr` with the given capacity.
+    ///
+    /// The returned `HipStr` will be able to hold at least `capacity` bytes
+    /// without reallocating or changing representation.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// # use hipstr::HipStr;
+    /// let mut s = HipStr::with_capacity(42);
+    /// for _ in 0..42 {
+    ///     s.push('*');
+    /// }
+    /// assert_eq!(s, "*".repeat(42));
+    /// ```
+    #[inline]
+    #[must_use]
+    pub fn with_capacity(cap: usize) -> Self {
+        Self(HipByt::with_capacity(cap))
+    }
+
     /// Creates a new `HipStr` from a static string slice without copying the slice.
     ///
     /// # Examples

src/string/tests.rs

@@ -48,6 +48,26 @@ fn test_new_default() {
     assert!(new.is_empty());
 }
 
+#[test]
+fn test_with_capacity() {
+    let h = H::with_capacity(0);
+    assert_eq!(h, EMPTY_SLICE);
+    assert!(h.is_empty());
+    assert_eq!(h.capacity(), INLINE_CAPACITY);
+
+    let mut h = H::with_capacity(42);
+    let p = h.as_ptr();
+    assert_eq!(h, EMPTY_SLICE);
+    assert!(h.is_empty());
+    assert_eq!(h.capacity(), 42);
+    for _ in 0..42 {
+        h.push_str(A);
+    }
+    assert_eq!(h.len(), 42);
+    assert_eq!(h, A.repeat(42));
+    assert_eq!(h.as_ptr(), p);
+}
+
 #[test]
 #[cfg(feature = "std")]
 fn test_borrow_and_hash() {