Struct smallstr::SmallString

pub struct SmallString<A: Array<Item = u8>> { /* fields omitted */ }

A String-like container that can store a small number of bytes inline.

SmallString uses a SmallVec<[u8; N]> as its internal storage.

Methods

impl<A: Array<Item = u8>> SmallString<A>

pub fn new() -> SmallString<A>

Construct an empty string.

pub fn with_capacity(n: usize) -> SmallString<A>

Construct an empty string with enough capacity pre-allocated to store at least n bytes.

Will create a heap allocation only if n is larger than the inline capacity.

pub fn from_str(s: &str) -> SmallString<A>

Construct a SmallString by copying data from a &str.

pub fn from_string(s: String) -> SmallString<A>

Construct a SmallString by using an existing allocation.

pub fn from_buf(buf: A) -> Result<SmallString<A>, FromUtf8Error<A>>

Constructs a new SmallString on the stack using UTF-8 bytes.

If the provided byte array is not valid UTF-8, an error is returned.

pub unsafe fn from_buf_unchecked(buf: A) -> SmallString<A>

Constructs a new SmallString on the stack using the provided byte array without checking that the array contains valid UTF-8.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues, as the Rust standard library functions assume that &strs are valid UTF-8.

pub fn inline_size(&self) -> usize

The maximum number of bytes this string can hold inline.

pub fn len(&self) -> usize

Returns the length of this string, in bytes.

pub fn is_empty(&self) -> bool

Returns true if this string is empty.

pub fn capacity(&self) -> usize

Returns the number of bytes this string can hold without reallocating.

pub fn spilled(&self) -> bool

Returns true if the data has spilled into a separate heap-allocated buffer.

Important traits for Drain<'a>

impl<'a> Iterator for Drain<'a> type Item = char;

pub fn drain(&mut self) -> Drain

Empties the string and returns an iterator over its former contents.

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

Appends the given char to the end of this string.

Examples

use smallstr::SmallString;

let mut s: SmallString<[u8; 8]> = SmallString::from("foo");

s.push('x');

assert_eq!(s, "foox");

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

Appends the given string slice to the end of this string.

Examples

use smallstr::SmallString;

let mut s: SmallString<[u8; 8]> = SmallString::from("foo");

s.push_str("bar");

assert_eq!(s, "foobar");

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

Removes the last character from this string and returns it.

Returns None if the string is empty.

pub fn grow(&mut self, new_cap: usize)

Reallocates to set the new capacity to new_cap.

Panics

If new_cap is less than the current length.

pub fn reserve(&mut self, additional: usize)

Ensures that this string's capacity is at least additional bytes larger than its length.

The capacity may be increased by more than additional bytes in order to prevent frequent reallocations.

pub fn reserve_exact(&mut self, additional: usize)

Ensures that this string's capacity is additional bytes larger than its length.

pub fn shrink_to_fit(&mut self)

Shrink the capacity of the string as much as possible.

When possible, this will move the data from an external heap buffer to the string's inline storage.

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

Shorten the string, keeping the first len bytes.

This does not reallocate. If you want to shrink the string's capacity, use shrink_to_fit after truncating.

Panics

If len does not lie on a char boundary.

pub fn as_str(&self) -> &str

Extracts a string slice containing the entire string.

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

Extracts a string slice containing the entire string.

pub fn clear(&mut self)

Removes all contents of the string.

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

Removes a char from this string at a byte position and returns it.

Panics

If idx does not lie on a char boundary.

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

Inserts a char into this string at the given byte position.

Panics

If idx does not lie on char boundaries.

pub fn insert_str(&mut self, idx: usize, s: &str)

Inserts a &str into this string at the given byte position.

Panics

If idx does not lie on char boundaries.

pub unsafe fn as_mut_vec(&mut self) -> &mut SmallVec<A>

Returns a mutable reference to the contents of the SmallString.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues, as the Rust standard library functions assume that &strs are valid UTF-8.

pub fn into_string(self) -> String

Converts the SmallString into a String, without reallocating if the SmallString has already spilled onto the heap.

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

Retains only the characters specified by the predicate.

In other words, removes all characters c such that f(c) returns false. This method operates in place and preserves the order of retained characters.

Examples

use smallstr::SmallString;

let mut s: SmallString<[u8; 16]> = SmallString::from("f_o_ob_ar");

s.retain(|c| c != '_');

assert_eq!(s, "foobar");

Trait Implementations

impl<A: Array<Item = u8>> AsMut<str> for SmallString<A>

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

Performs the conversion.

impl<A: Array<Item = u8>> AsRef<str> for SmallString<A>

fn as_ref(&self) -> &str

Performs the conversion.

impl<A: Array<Item = u8>> Borrow<str> for SmallString<A>

fn borrow(&self) -> &str

Immutably borrows from an owned value.

impl<A: Array<Item = u8>> BorrowMut<str> for SmallString<A>

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

Mutably borrows from an owned value.

impl<A: Clone + Array<Item = u8>> Clone for SmallString<A>

fn clone(&self) -> SmallString<A>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A: Array<Item = u8>> Debug for SmallString<A>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<A: Default + Array<Item = u8>> Default for SmallString<A>

fn default() -> SmallString<A>

Returns the "default value" for a type.

impl<A: Array<Item = u8>> Deref for SmallString<A>

type Target = str

The resulting type after dereferencing.

fn deref(&self) -> &str

Dereferences the value.

impl<A: Array<Item = u8>> DerefMut for SmallString<A>

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

Mutably dereferences the value.

impl<A: Array<Item = u8>> Display for SmallString<A>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<A: Array<Item = u8>> Eq for SmallString<A>

impl<'a, A: Array<Item = u8>> Extend<&'a char> for SmallString<A>

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

Extends a collection with the contents of an iterator.

impl<'a, A: Array<Item = u8>> Extend<&'a str> for SmallString<A>

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

Extends a collection with the contents of an iterator.

impl<'a, A: Array<Item = u8>> Extend<Cow<'a, str>> for SmallString<A>

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

Extends a collection with the contents of an iterator.

impl<A: Array<Item = u8>> Extend<String> for SmallString<A>

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

Extends a collection with the contents of an iterator.

impl<A: Array<Item = u8>> Extend<char> for SmallString<A>

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

Extends a collection with the contents of an iterator.

impl<'a, A: Array<Item = u8>> From<&'a str> for SmallString<A>

fn from(s: &str) -> SmallString<A>

Performs the conversion.

impl<A: Array<Item = u8>> From<Box<str>> for SmallString<A>

fn from(s: Box<str>) -> SmallString<A>

Performs the conversion.

impl<A: Array<Item = u8>> From<String> for SmallString<A>

fn from(s: String) -> SmallString<A>

Performs the conversion.

impl<A: Array<Item = u8>> From<char> for SmallString<A>

fn from(ch: char) -> SmallString<A>

Performs the conversion.

impl<'a, A: Array<Item = u8>> FromIterator<&'a char> for SmallString<A>

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

Creates a value from an iterator.

impl<'a, A: Array<Item = u8>> FromIterator<&'a str> for SmallString<A>

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

Creates a value from an iterator.

impl<'a, A: Array<Item = u8>> FromIterator<Cow<'a, str>> for SmallString<A>

fn from_iter<I: IntoIterator<Item = Cow<'a, str>>>(iter: I) -> SmallString<A>

Creates a value from an iterator.

impl<A: Array<Item = u8>> FromIterator<String> for SmallString<A>

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

Creates a value from an iterator.

impl<A: Array<Item = u8>> FromIterator<char> for SmallString<A>

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

Creates a value from an iterator.

impl<A: Array<Item = u8>> Hash for SmallString<A>

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<A: Array<Item = u8>> Index<Range<usize>> for SmallString<A>

type Output = str

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<A: Array<Item = u8>> Index<RangeFrom<usize>> for SmallString<A>

type Output = str

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<A: Array<Item = u8>> Index<RangeFull> for SmallString<A>

type Output = str

The returned type after indexing.

fn index(&self, index: RangeFull) -> &str

Performs the indexing (container[index]) operation.

impl<A: Array<Item = u8>> Index<RangeTo<usize>> for SmallString<A>

type Output = str

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<A: Array<Item = u8>> IndexMut<Range<usize>> for SmallString<A>

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

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

impl<A: Array<Item = u8>> IndexMut<RangeFrom<usize>> for SmallString<A>

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

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

impl<A: Array<Item = u8>> IndexMut<RangeFull> for SmallString<A>

fn index_mut(&mut self, index: RangeFull) -> &mut str

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

impl<A: Array<Item = u8>> IndexMut<RangeTo<usize>> for SmallString<A>

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

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

impl<A: Array<Item = u8>> Ord for SmallString<A>

fn cmp(&self, rhs: &SmallString<A>) -> 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

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

Restrict a value to a certain interval.

impl<'a, A: Array<Item = u8>> PartialEq<&'a str> for SmallString<A>

fn eq(&self, rhs: &&'a str) -> bool

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

fn ne(&self, rhs: &&'a str) -> bool

This method tests for !=.

impl<'a, A: Array<Item = u8>> PartialEq<Cow<'a, str>> for SmallString<A>

fn eq(&self, rhs: &Cow<'a, str>) -> bool

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

fn ne(&self, rhs: &Cow<'a, str>) -> bool

This method tests for !=.

impl<A, B> PartialEq<SmallString<B>> for SmallString<A> where
    A: Array<Item = u8>,
    B: Array<Item = u8>, 

fn eq(&self, rhs: &SmallString<B>) -> bool

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

fn ne(&self, rhs: &SmallString<B>) -> bool

This method tests for !=.

impl<'a, A: Array<Item = u8>> PartialEq<String> for SmallString<A>

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

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

fn ne(&self, rhs: &String) -> bool

This method tests for !=.

impl<'a, A: Array<Item = u8>> PartialEq<str> for SmallString<A>

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

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

fn ne(&self, rhs: &str) -> bool

This method tests for !=.

impl<A: Array<Item = u8>> PartialOrd<SmallString<A>> for SmallString<A>

fn partial_cmp(&self, rhs: &SmallString<A>) -> Option<Ordering>

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

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

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

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

#[must_use] 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<A: Array<Item = u8>> Write for SmallString<A>

fn write_str(&mut self, s: &str) -> Result

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

fn write_char(&mut self, ch: char) -> Result

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.