diff --git a/README.md b/README.md index 2952ee3..5510249 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ let _clone = simple_greetings.clone(); // no copy let user = "John"; let greetings = HipStr::from(format!("Hello {}", user)); -let user = greetings.slice(6..): // no copy +let user = greetings.slice(6..); // no copy drop(greetings); // the slice is owned, it exists even if greetings disappear let chars = user.chars().count(); // "inherits" `&str` methods @@ -96,7 +96,7 @@ cross test --target i686-unknown-linux-gnu # 32-bit LE cross test --target x86_64-unknown-linux-gnu # 64-bit LE ``` -NB: previously I used MIPS targets for big endian, but due to some LLVM-related +Note: previously I used MIPS targets for big endian, but due to some LLVM-related issue they are not working anymore… see [Rust issue #113065](https://github.com/rust-lang/rust/issues/113065) diff --git a/src/bytes.rs b/src/bytes.rs index ace7436..c3a4fe1 100644 --- a/src/bytes.rs +++ b/src/bytes.rs @@ -54,10 +54,14 @@ where /// /// Function provided for [`Vec::new`] replacement. /// - /// # ⚠️ Warning! + /// # Representation + /// + ///
/// /// The used representation of the empty string is unspecified. - /// It may be *borrowed* or *inlined* but will never be allocated. + /// It may be _borrowed* or *inlined* but will never be allocated. + /// + ///
/// /// # Examples /// @@ -76,6 +80,10 @@ where /// Creates a new inline `HipByt` by copying the given slice. /// The slice **must not** be too large to be inlined. /// + /// # Representation + /// + /// The created `HipByt` is _inline_. + /// /// # Panics /// /// It panics if the slice is too large. @@ -100,6 +108,10 @@ where /// Creates a new inline `HipByt` by copying the given the slice. /// Return `None` if the given slice is too large to be inlined. /// + /// # Representation + /// + /// In case of success, the created `HipByt` is _inline_. + /// /// # Examples /// /// Basic usage: @@ -121,7 +133,18 @@ where /// Creates a new `HipByt` with the given capacity. /// - /// The underlying representation is not **normalized**. + /// The final capacity depends on the representation and is not guaranteed + /// to be exact. However, the returned `HipByt` will be able to hold at + /// least `capacity` bytes without reallocating or changing representation. + /// + /// # Representation + /// + /// If the capacity is less or equal to the inline capacity, the + /// representation will be *inline*. + /// + /// Otherwise, it will be *allocated*. + /// + /// The representation is **not normalized**. /// /// # Examples /// @@ -422,7 +445,7 @@ where /// /// # Errors /// - /// Returns `Err(self)` if this `HipByt` is not a borrow. + /// Returns `Err(self)` if this `HipByt` is not borrowed. /// /// # Examples /// @@ -1419,10 +1442,14 @@ impl HipByt<'static, B> where B: Backend, { - /// Creates a new `HipByt` from a static slice without copying the slice. + /// Creates a new `HipByt` from a `'static` slice without copying the slice. /// /// Handy shortcut to make a `HipByt<'static, _>` out of a `&'static [u8]`. /// + /// # Representation + /// + /// The created `HipByt` is _borrowed_. + /// /// # Examples /// /// Basic usage: diff --git a/src/bytes/raw/allocated.rs b/src/bytes/raw/allocated.rs index 160c0ea..f6278ec 100644 --- a/src/bytes/raw/allocated.rs +++ b/src/bytes/raw/allocated.rs @@ -237,7 +237,7 @@ impl Allocated { self.ptr.cast_mut() } - /// Returns a mutable slice if possible (unique non-static reference). + /// Returns a mutable slice if possible (unique owned reference). #[inline] pub fn as_mut_slice(&mut self) -> Option<&mut [u8]> { if self.is_unique() { diff --git a/src/os_string.rs b/src/os_string.rs index 7381f42..87e0644 100644 --- a/src/os_string.rs +++ b/src/os_string.rs @@ -109,8 +109,18 @@ where /// Creates a new `HipOsStr` with the given capacity. /// - /// The returned `HipOsStr` will be able to hold at least `capacity` bytes - /// without reallocating or changing representation. + /// The final capacity depends on the representation and is not guaranteed + /// to be exact. However, the returned `HipOsStr` will be able to hold at + /// least `capacity` bytes without reallocating or changing representation. + /// + /// # Representation + /// + /// If the capacity is less or equal to the inline capacity, the + /// representation will be *inline*. + /// + /// Otherwise, it will be *allocated*. + /// + /// The representation is **not normalized**. /// /// # Examples /// @@ -131,9 +141,18 @@ where Self(HipByt::with_capacity(cap)) } - /// Creates a new `HipOsStr` from a static os string slice without copying the slice. + /// Creates a new `HipOsStr` from an OS string slice without copying the + /// slice. /// - /// Requires only `impl AsRef`: it accepts `&str`, `&OsStr`, and `&Path` for instance. + /// Requires only `impl AsRef`: it accepts `&str`, `&OsStr`, and + /// `&Path` for instance. + /// + /// To create a `HipOsStr` from a `'static` string slice `const`-ly, see + /// [`HipOsStr::from_static`]. + /// + /// # Representation + /// + /// The created `HipOsStr` is _borrowed_. /// /// # Examples /// @@ -218,11 +237,12 @@ where self.0.is_allocated() } - /// Converts `self` into a static string slice if this `HipOsStr` is backed by a static borrow. + /// Converts `self` into a string slice with the `'borrow` lifetime if this + /// `HipOsStr` is backed by a borrow. /// /// # Errors /// - /// Returns `Err(self)` if this `HipOsStr` is not a static borrow. + /// Returns `Err(self)` if this `HipOsStr` is not borrowed. /// /// # Examples /// @@ -328,7 +348,7 @@ where /// Converts a `HipOsStr` into a `HipByt`. /// /// It consumes the `HipOsStr` without copying the content - /// (if [shared][Self::is_allocated] or [static][Self::is_borrowed]). + /// (if [shared][Self::is_allocated] or [borrowed][Self::is_borrowed]). /// /// # Examples /// @@ -414,7 +434,7 @@ where /// /// This operation may reallocate a new string if either: /// - /// - the representation is not an allocated buffer (inline array or static borrow), + /// - the representation is not an allocated buffer (inline array or borrow), /// - the underlying buffer is shared. /// /// # Examples @@ -699,9 +719,12 @@ impl HipOsStr<'static, B> where B: Backend, { - /// Creates a new `HipOsStr` from a static string slice without copying the slice. + /// Creates a new `HipOsStr` from a `'static` string slice without copying + /// the slice. + /// + /// # Representation /// - /// Handy shortcut to make a `HipOsStr<'static, _>` out of a `&'static str`. + /// The created `HipOsStr` is _borrowed_. /// /// # Examples /// diff --git a/src/path.rs b/src/path.rs index 4101a78..44b03b1 100644 --- a/src/path.rs +++ b/src/path.rs @@ -107,9 +107,18 @@ where Self(HipOsStr::new()) } - /// Creates a new `HipPath` from a static os string slice without copying the slice. + /// Creates a new `HipPath` from an OS string slice without copying the + /// slice. /// - /// Requires only `impl AsRef`: it accepts `&str`, `&OsStr`, and `&Path` for instance. + /// Requires only `impl AsRef`: it accepts `&str`, `&OsStr`, and + /// `&Path` for instance. + /// + /// To create a `HipPath` from a `'static` string slice `const`-ly, see + /// [`HipPath::from_static`]. + /// + /// # Representation + /// + /// The created `HipPath` is _borrowed_. /// /// # Examples /// @@ -196,11 +205,12 @@ where self.0.is_allocated() } - /// Converts `self` into a static string slice if this `HipPath` is backed by a static borrow. + /// Converts `self` into a path slice with the `'borrow` lifetime if this + /// `HipPath` is backed by a borrow. /// /// # Errors /// - /// Returns `Err(self)` if this `HipPath` is not a static borrow. + /// Returns `Err(self)` if this `HipPath` is not borrowed. /// /// # Examples /// @@ -366,7 +376,7 @@ where /// /// This operation may reallocate a new buffer if either: /// - /// - the representation is not an allocated buffer (inline array or static borrow), + /// - the representation is not an allocated buffer (inline array or borrow), /// - the underlying buffer is shared. /// /// # Examples @@ -533,7 +543,9 @@ where { /// Creates a new `HipPath` from a static string slice without copying the slice. /// - /// Handy shortcut to make a `HipPath<'static, _>` out of a `&'static str`. + /// # Representation + /// + /// The created `HipPath` is _borrowed_. /// /// # Examples /// diff --git a/src/string.rs b/src/string.rs index 1a88c6e..5309c05 100644 --- a/src/string.rs +++ b/src/string.rs @@ -103,8 +103,9 @@ where /// 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. + /// The final capacity depends on the representation and is not guaranteed + /// to be exact. However, the returned `HipStr` will be able to hold at + /// least `capacity` bytes without reallocating or changing representation. /// /// # Representation /// @@ -134,11 +135,16 @@ where } /// Creates a new `HipStr` from a string slice. + /// /// No heap allocation is performed. - /// **The string is not copied.** + /// **The string slice is borrowed and not copied.** /// /// See also [`HipStr::from_static`] to ensure the borrow is `'static`. /// + /// # Representation + /// + /// The created `HipStr` is _borrowed_. + /// /// # Examples /// /// Basic usage: @@ -177,7 +183,7 @@ where self.0.is_inline() } - /// Returns `true` if this `HipStr` is a static string borrow, `false` otherwise. + /// Returns `true` if this `HipStr` is a string borrow, `false` otherwise. /// /// # Examples /// @@ -223,11 +229,12 @@ where self.0.is_allocated() } - /// Converts `self` into a static string slice if this `HipStr` is backed by a static borrow. + /// Converts `self` into a string slice with the `'borrow` lifetime if this + /// `HipStr` is backed by a borrow. /// /// # Errors /// - /// Returns `Err(self)` if this `HipStr` is not a static borrow. + /// Returns `Err(self)` if this `HipStr` is not a borrow. /// /// # Examples /// @@ -1738,10 +1745,14 @@ impl HipStr<'static, B> where B: Backend, { - /// Creates a new `HipStr` from a static string slice without copying the slice. + /// Creates a new `HipStr` from a `'static` string slice without copying the slice. /// /// Handy shortcut to make a `HipStr<'static, _>` out of a `&'static str`. /// + /// # Representation + /// + /// The created `HipStr` is _borrowed_. + /// /// # Examples /// /// Basic usage: