From 6a380884b58c54d31ef4cfec7b079a00a72b1e6b Mon Sep 17 00:00:00 2001
From: polazarus <polazarus@users.noreply.github.com>
Date: Tue, 23 Jul 2024 22:16:46 +0200
Subject: [PATCH] feat: add with_capacity

---
 src/bytes.rs        | 23 +++++++++++++++++++++--
 src/bytes/tests.rs  | 20 ++++++++++++++++++++
 src/string.rs       | 23 +++++++++++++++++++++++
 src/string/tests.rs | 20 ++++++++++++++++++++
 4 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/src/bytes.rs b/src/bytes.rs
index 4888fd1..90fd143 100644
--- a/src/bytes.rs
+++ b/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.
diff --git a/src/bytes/tests.rs b/src/bytes/tests.rs
index e793d2d..fb82156 100644
--- a/src/bytes/tests.rs
+++ b/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() {
diff --git a/src/string.rs b/src/string.rs
index b99b45a..e6d41aa 100644
--- a/src/string.rs
+++ b/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
diff --git a/src/string/tests.rs b/src/string/tests.rs
index 1b5e8ea..ff4bea9 100644
--- a/src/string/tests.rs
+++ b/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() {