Struct smartstring::SmartString

#[repr(C)]
#[repr(align(8))]
pub struct SmartString<Mode: SmartStringMode> { /* fields omitted */ }

A smart string.

This wraps one of two string types: an inline string or a boxed string. Conversion between the two happens opportunistically and transparently.

It takes a layout as its type argument: one of Compact or LazyCompact.

It mimics the interface of String except where behaviour cannot be guaranteed to stay consistent between its boxed and inline states. This means you still have capacity() and shrink_to_fit(), relating to state that only really exists in the boxed variant, because the inline variant can still give sensible behaviour for these operations, but with_capacity(), reserve() etc are absent, because they would have no effect on inline strings and the requested state changes wouldn’t carry over if the inline string is promoted to a boxed one - not without also storing that state in the inline representation, which would waste precious bytes for inline string data.

Implementations

impl SmartString<LazyCompact>

pub const fn new_const() -> Self

Construct an empty string.

This is a const fn version of SmartString::new. It’s a temporary measure while we wait for trait bounds on type arguments to const fns to stabilise, and will be deprecated once this happens.

impl SmartString<Compact>

pub const fn new_const() -> Self

Construct an empty string.

This is a const fn version of SmartString::new. It’s a temporary measure while we wait for trait bounds on type arguments to const fns to stabilise, and will be deprecated once this happens.

impl<Mode: SmartStringMode> SmartString<Mode>

pub fn new() -> Self

Construct an empty string.

pub fn len(&self) -> usize

Return the length in bytes of the string.

Note that this may differ from the length in chars.

pub fn is_empty(&self) -> bool

Test whether the string is empty.

pub fn is_inline(&self) -> bool

Test whether the string is currently inlined.

pub fn as_str(&self) -> &str

Get a reference to the string as a string slice.

pub fn as_mut_str(&mut self) -> &mut str

Get a reference to the string as a mutable string slice.

pub fn push(&mut self, ch: char)

Push a character to the end of the string.

pub fn push_str(&mut self, string: &str)

Copy a string slice onto the end of the string.

pub fn capacity(&self) -> usize

Return the currently allocated capacity of the string.

Note that if this is a boxed string, it returns String::capacity(), but an inline string always returns MAX_INLINE.

Note also that if a boxed string is converted into an inline string, its capacity is deallocated, and if the inline string is promoted to a boxed string in the future, it will be reallocated with a default capacity.

pub fn shrink_to_fit(&mut self)

Shrink the capacity of the string to fit its contents exactly.

This has no effect on inline strings, which always have a fixed capacity. Thus, it’s not safe to assume that capacity() will equal len() after calling this.

Calling this on a LazyCompact string that is currently heap allocated but is short enough to be inlined will deallocate the heap allocation and convert it to an inline string.

pub fn truncate(&mut self, new_len: usize)

Truncate the string to new_len bytes.

If new_len is larger than the string’s current length, this does nothing. If new_len isn’t on a UTF-8 character boundary, this method panics.

pub fn pop(&mut self) -> Option<char>

Pop a char off the end of the string.

pub fn remove(&mut self, index: usize) -> char

Remove a char from the string at the given index.

If the index doesn’t fall on a UTF-8 character boundary, this method panics.

pub fn insert(&mut self, index: usize, ch: char)

Insert a char into the string at the given index.

If the index doesn’t fall on a UTF-8 character boundary, this method panics.

pub fn insert_str(&mut self, index: usize, string: &str)

Insert a string slice into the string at the given index.

If the index doesn’t fall on a UTF-8 character boundary, this method panics.

pub fn split_off(&mut self, index: usize) -> Self

Split the string into two at the given index.

Returns the content to the right of the index as a new string, and removes it from the original.

If the index doesn’t fall on a UTF-8 character boundary, this method panics.

pub fn clear(&mut self)

Clear the string.

This causes any memory reserved by the string to be immediately deallocated.

pub fn retain<F>(&mut self, f: F) where
    F: FnMut(char) -> bool, 

Filter out chars not matching a predicate.

pub fn drain<R>(&mut self, range: R) -> Drain<'_, Mode> where
    R: RangeBounds<usize>, 

Construct a draining iterator over a given range.

This removes the given range from the string, and returns an iterator over the removed chars.

pub fn replace_range<R>(&mut self, range: R, replace_with: &str) where
    R: RangeBounds<usize>, 

Replaces a range with the contents of a string slice.

Trait Implementations

impl<Mode: SmartStringMode> Add<&'_ SmartString<Mode>> for SmartString<Mode>

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: &Self) -> Self::Output

Performs the + operation.

impl<Mode: SmartStringMode> Add<&'_ String> for SmartString<Mode>

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: &String) -> Self::Output

Performs the + operation.

impl<Mode: SmartStringMode> Add<&'_ str> for SmartString<Mode>

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: &str) -> Self::Output

Performs the + operation.

impl<Mode: SmartStringMode> Add<SmartString<Mode>> for SmartString<Mode>

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<Mode: SmartStringMode> Add<SmartString<Mode>> for String

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: SmartString<Mode>) -> Self::Output

Performs the + operation.

impl<Mode: SmartStringMode> Add<String> for SmartString<Mode>

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: String) -> Self::Output

Performs the + operation.

impl<Mode: SmartStringMode> Arbitrary for SmartString<Mode> where
    Mode: 'static, 

fn arbitrary(u: &mut Unstructured<'_>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'_>) -> Result<Self>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn shrink(&self) -> Box<dyn Iterator<Item = Self>>

Generate an iterator of derived values which are “smaller” than the original self instance.

impl<Mode: SmartStringMode> AsMut<str> for SmartString<Mode>

fn as_mut(&mut self) -> &mut str

Performs the conversion.

impl<Mode: SmartStringMode> AsRef<[u8]> for SmartString<Mode>

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl<Mode: SmartStringMode> AsRef<str> for SmartString<Mode>

fn as_ref(&self) -> &str

Performs the conversion.

impl<Mode: SmartStringMode> Borrow<str> for SmartString<Mode>

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<Mode: SmartStringMode> BorrowMut<str> for SmartString<Mode>

fn borrow_mut(&mut self) -> &mut str

Mutably borrows from an owned value.

impl<Mode: SmartStringMode> Clone for SmartString<Mode>

fn clone(&self) -> Self

Clone a SmartString.

If the string is inlined, this is a Copy operation. Otherwise, String::clone() is invoked.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Mode: SmartStringMode> Debug for SmartString<Mode>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<Mode: SmartStringMode> Default for SmartString<Mode>

fn default() -> Self

Returns the “default value” for a type.

impl<Mode: SmartStringMode> Deref for SmartString<Mode>

type Target = str

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<Mode: SmartStringMode> DerefMut for SmartString<Mode>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de, T: SmartStringMode> Deserialize<'de> for SmartString<T>

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<Mode: SmartStringMode> Display for SmartString<Mode>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<Mode: SmartStringMode> Drop for SmartString<Mode>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, Mode: SmartStringMode + 'a> Extend<&'a SmartString<Mode>> for SmartString<Mode>

fn extend<I: IntoIterator<Item = &'a SmartString<Mode>>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, Mode: SmartStringMode> Extend<&'a String> for SmartString<Mode>

fn extend<I: IntoIterator<Item = &'a String>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, Mode: SmartStringMode> Extend<&'a char> for SmartString<Mode>

fn extend<I: IntoIterator<Item = &'a char>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, Mode: SmartStringMode> Extend<&'a str> for SmartString<Mode>

fn extend<I: IntoIterator<Item = &'a str>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<Mode: SmartStringMode> Extend<SmartString<Mode>> for SmartString<Mode>

fn extend<I: IntoIterator<Item = SmartString<Mode>>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<Mode: SmartStringMode> Extend<String> for SmartString<Mode>

fn extend<I: IntoIterator<Item = String>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<Mode: SmartStringMode> Extend<char> for SmartString<Mode>

fn extend<I: IntoIterator<Item = char>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<Mode: SmartStringMode> From<&'_ String> for SmartString<Mode>

fn from(string: &String) -> Self

Performs the conversion.

impl<Mode: SmartStringMode> From<&'_ mut str> for SmartString<Mode>

fn from(string: &mut str) -> Self

Performs the conversion.

impl<Mode: SmartStringMode> From<&'_ str> for SmartString<Mode>

fn from(string: &str) -> Self

Performs the conversion.

impl<Mode: SmartStringMode> From<Box<str, Global>> for SmartString<Mode>

fn from(string: Box<str>) -> Self

Performs the conversion.

impl<Mode: SmartStringMode> From<Cow<'_, str>> for SmartString<Mode>

fn from(string: Cow<'_, str>) -> Self

Performs the conversion.

impl<Mode: SmartStringMode> From<String> for SmartString<Mode>

fn from(string: String) -> Self

Performs the conversion.

impl<'a, Mode: SmartStringMode + 'a> FromIterator<&'a SmartString<Mode>> for SmartString<Mode>

fn from_iter<I: IntoIterator<Item = &'a Self>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a, Mode: SmartStringMode> FromIterator<&'a String> for SmartString<Mode>

fn from_iter<I: IntoIterator<Item = &'a String>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a, Mode: SmartStringMode> FromIterator<&'a str> for SmartString<Mode>

fn from_iter<I: IntoIterator<Item = &'a str>>(iter: I) -> Self

Creates a value from an iterator.

impl<Mode: SmartStringMode> FromIterator<SmartString<Mode>> for SmartString<Mode>

fn from_iter<I: IntoIterator<Item = Self>>(iter: I) -> Self

Creates a value from an iterator.

impl<Mode: SmartStringMode> FromIterator<String> for SmartString<Mode>

fn from_iter<I: IntoIterator<Item = String>>(iter: I) -> Self

Creates a value from an iterator.

impl<Mode: SmartStringMode> FromIterator<char> for SmartString<Mode>

fn from_iter<I: IntoIterator<Item = char>>(iter: I) -> Self

Creates a value from an iterator.

impl<Mode: SmartStringMode> FromStr for SmartString<Mode>

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<Mode: SmartStringMode> Hash for SmartString<Mode>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<Mode: SmartStringMode> Index<Range<usize>> for SmartString<Mode>

type Output = str

The returned type after indexing.

fn index(&self, index: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Mode: SmartStringMode> Index<RangeFrom<usize>> for SmartString<Mode>

type Output = str

The returned type after indexing.

fn index(&self, index: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Mode: SmartStringMode> Index<RangeFull> for SmartString<Mode>

type Output = str

The returned type after indexing.

fn index(&self, _index: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Mode: SmartStringMode> Index<RangeInclusive<usize>> for SmartString<Mode>

type Output = str

The returned type after indexing.

fn index(&self, index: RangeInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Mode: SmartStringMode> Index<RangeTo<usize>> for SmartString<Mode>

type Output = str

The returned type after indexing.

fn index(&self, index: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Mode: SmartStringMode> Index<RangeToInclusive<usize>> for SmartString<Mode>

type Output = str

The returned type after indexing.

fn index(&self, index: RangeToInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<Mode: SmartStringMode> IndexMut<Range<usize>> for SmartString<Mode>

fn index_mut(&mut self, index: Range<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<Mode: SmartStringMode> IndexMut<RangeFrom<usize>> for SmartString<Mode>

fn index_mut(&mut self, index: RangeFrom<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<Mode: SmartStringMode> IndexMut<RangeFull> for SmartString<Mode>

fn index_mut(&mut self, _index: RangeFull) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<Mode: SmartStringMode> IndexMut<RangeInclusive<usize>> for SmartString<Mode>

fn index_mut(&mut self, index: RangeInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<Mode: SmartStringMode> IndexMut<RangeTo<usize>> for SmartString<Mode>

fn index_mut(&mut self, index: RangeTo<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<Mode: SmartStringMode> IndexMut<RangeToInclusive<usize>> for SmartString<Mode>

fn index_mut(&mut self, index: RangeToInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<Mode: SmartStringMode> Into<String> for SmartString<Mode>

fn into(self) -> String

Unwrap a boxed String, or copy an inline string into a new String.

impl<Mode: SmartStringMode> Ord for SmartString<Mode>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<Mode: SmartStringMode> PartialEq<&'_ str> for SmartString<Mode>

fn eq(&self, other: &&str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Mode: SmartStringMode> PartialEq<SmartString<Mode>> for &str

fn eq(&self, other: &SmartString<Mode>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Mode: SmartStringMode> PartialEq<SmartString<Mode>> for str

fn eq(&self, other: &SmartString<Mode>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Mode: SmartStringMode> PartialEq<SmartString<Mode>> for String

fn eq(&self, other: &SmartString<Mode>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Mode: SmartStringMode> PartialEq<SmartString<Mode>> for SmartString<Mode>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Mode: SmartStringMode> PartialEq<String> for SmartString<Mode>

fn eq(&self, other: &String) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Mode: SmartStringMode> PartialEq<str> for SmartString<Mode>

fn eq(&self, other: &str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Mode: SmartStringMode> PartialOrd<SmartString<Mode>> for SmartString<Mode>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Mode: SmartStringMode> PartialOrd<str> for SmartString<Mode>

fn partial_cmp(&self, other: &str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: SmartStringMode> Serialize for SmartString<T>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<Mode: SmartStringMode> Write for SmartString<Mode>

fn write_str(&mut self, string: &str) -> Result<(), Error>

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl<Mode: SmartStringMode> Eq for SmartString<Mode>