[][src]Struct tinyvec_string::tinystring::TinyString

#[repr(transparent)]pub struct TinyString<A: ByteArray> { /* fields omitted */ }
This is supported with target feature alloc only.

A UTF-8 encoded, fixed-capacity string.

An TinyString is similar to String, but is backed by an TinyVec instead of a Vec. This means it has similar characteristics to TinyVec:

  • An TinyString has a fixed capacity (in bytes), the size of the backing array.
  • An TinyString has a dynamic length; characters can be added and removed. Attempting to add characters when the capacity has been reached will cause a panic.

Like String, the contents of an TinyString must be valid UTF-8 at all times.

TinyString is intended to replicate the API of String as much as possible.

Requires the alloc cargo feature to be enabled.

Implementations

impl<A: ByteArray> TinyString<A>[src]

pub fn new() -> TinyString<A>[src]

This is supported with target feature alloc only.

Creates a new empty TinyString.

This creates a new TinyVec with a backing array of zeroes.

Examples

// create an `TinyString` with 16 bytes of capacity
let s = TinyString::<[u8; 16]>::new();

pub fn from_utf8(vec: TinyVec<A>) -> Result<TinyString<A>, FromUtf8Error<A>>[src]

This is supported with target feature alloc only.

Converts a vector of bytes to an TinyString.

TinyString is backed by TinyVec, so after ensuring valid UTF-8, this function simply constructs an TinyString containing the provided TinyVec.

The inverse of this method is into_bytes.

Errors

Returns Err if the slice is not UTF-8 with a description as to why the provided bytes are not UTF-8. The vector you moved in is also included.

Examples

use tinyvec::{tiny_vec, TinyVec};
// some bytes, in a vector
let ferris: TinyVec<[u8; 7]> = tiny_vec![240, 159, 166, 128, 226, 153, 165];

// We know these bytes are valid UTF-8, so we'll use `unwrap()`.
let ferris = TinyString::from_utf8(ferris).unwrap();

assert_eq!("🦀♥", ferris);

Incorrect bytes:

use tinyvec::{tiny_vec, TinyVec};

// some invalid bytes, in a vector
let ferris: TinyVec<[u8; 7]> = tiny_vec![0, 159, 166, 128, 226, 153, 165];

assert!(TinyString::from_utf8(ferris).is_err());

See the docs for FromUtf8Error for more details on what you can do with this error.

pub unsafe fn from_utf8_unchecked(vec: TinyVec<A>) -> TinyString<A>[src]

This is supported with target feature alloc only.

Converts a vector of bytes to an TinyString without checking that the string contains valid UTF-8.

See the safe version, from_utf8, for more details.

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 with future users of the TinyString, as the rest of this library and the standard library assumes that strs are valid UTF-8.

Examples

use tinyvec::{tiny_vec, TinyVec};
// some bytes, in a vector
let ferris: TinyVec<[u8; 7]> = tiny_vec![240, 159, 166, 128, 226, 153, 165];

let ferris = unsafe {
	// we know these bytes are valid UTF-8, so this is sound.
	TinyString::from_utf8_unchecked(ferris)
};

assert_eq!("🦀♥", ferris);

pub fn into_bytes(self) -> TinyVec<A>[src]

This is supported with target feature alloc only.

Returns an TinyString's backing TinyVec.

Examples

use std::convert::TryFrom;
let s = TinyString::<[u8; 5]>::try_from("hello").unwrap();
let bytes = s.into_bytes();

assert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]);

pub fn as_str(&self) -> &str[src]

This is supported with target feature alloc only.

Extracts a string slice containing the entire TinyString.

Examples

use std::convert::TryFrom;
let s = TinyString::<[u8; 3]>::try_from("foo").unwrap();

assert_eq!("foo", s.as_str());

pub fn as_mut_str(&mut self) -> &mut str[src]

This is supported with target feature alloc only.

Extracts a mutable string slice containing the entire TinyString.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 6]>::try_from("foobar").unwrap();
let s_mut_str = s.as_mut_str();

s_mut_str.make_ascii_uppercase();

assert_eq!("FOOBAR", s_mut_str);

pub fn as_bytes(&self) -> &[u8]

Important traits for &'_ [u8]

impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]
[src]

This is supported with target feature alloc only.

Returns a byte slice of this TinyString's contents.

The inverse of this method is from_utf8.

Examples

use std::convert::TryFrom;
let s = TinyString::<[u8; 5]>::try_from("hello").unwrap();

assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes());

pub unsafe fn as_mut_vec(&mut self) -> &mut TinyVec<A>[src]

This is supported with target feature alloc only.

Returns a mutable reference to the contents of this TinyString.

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 with future users of the TinyString, as the rest of the standard library assumes that TinyStrings are valid UTF-8.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 5]>::try_from("hello").unwrap();

unsafe {
    let vec = s.as_mut_vec();
    assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]);

    vec.reverse();
}
assert_eq!(s, "olleh");

pub fn capacity(&self) -> usize[src]

This is supported with target feature alloc only.

Returns this TinyString's capacity, in bytes.

This always returns a constant, the size of the backing array.

Examples

let s = TinyString::<[u8; 16]>::new();

assert!(s.capacity() == 16);

pub fn len(&self) -> usize[src]

This is supported with target feature alloc only.

Returns the length of this TinyString, in bytes, not chars or graphemes. In other words, it may not be what a human considers the length of the string.

Examples

use std::convert::TryFrom;
let plain_f = TinyString::<[u8; 3]>::try_from("foo").unwrap();
assert_eq!(plain_f.len(), 3);

let fancy_f = TinyString::<[u8; 4]>::try_from("ƒoo").unwrap();
assert_eq!(fancy_f.len(), 4);
assert_eq!(fancy_f.chars().count(), 3);

let s = TinyString::<[u8; 16]>::try_from("hello").unwrap();
assert_eq!(s.len(), 5);

pub fn is_empty(&self) -> bool[src]

This is supported with target feature alloc only.

Returns true if this TinyString has a length of zero, and false otherwise.

Examples

let mut s = TinyString::<[u8; 5]>::new();
assert!(s.is_empty());

s.push('a');
assert!(!s.is_empty());

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

This is supported with target feature alloc only.

Appends a given string slice onto the end of this TinyString.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 6]>::try_from("foo").unwrap();

s.push_str("bar");

assert_eq!("foobar", s);

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

This is supported with target feature alloc only.

Appends the given char to the end of this String.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 6]>::try_from("abc").unwrap();

s.push('1');
s.push('2');
s.push('3');

assert_eq!("abc123", s);

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

This is supported with target feature alloc only.

Shortens this TinyString to the specified length.

If new_len is greater than the string's current length, this has no effect.

Note that this method has no effect on the maximum capacity of the string

Panics

Panics if new_len does not lie on a char boundary.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 5]>::try_from("hello").unwrap();

s.truncate(2);

assert_eq!("he", s);

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

This is supported with target feature alloc only.

Removes the last character from the string buffer and returns it.

Returns None if this String is empty.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 3]>::try_from("foo").unwrap();

assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('f'));

assert_eq!(s.pop(), None);

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

This is supported with target feature alloc only.

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

This is an O(n) operation, as it requires copying every element in the buffer.

Panics

Panics if idx is larger than or equal to the TinyString's length, or if it does not lie on a char boundary.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 3]>::try_from("foo").unwrap();

assert_eq!(s.remove(0), 'f');
assert_eq!(s.remove(1), 'o');
assert_eq!(s.remove(0), 'o');

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

This is supported with target feature alloc only.

Retains only the characters specified by the predicate.

In other words, remove all characters c such that f(c) returns false. This method operates in place, visiting each character exactly once in the original order, and preserves the order of the retained characters.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 9]>::try_from("f_o_ob_ar").unwrap();

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

assert_eq!(s, "foobar");

The exact order may be useful for tracking external state, like an index.

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 5]>::try_from("abcde").unwrap();
let keep = [false, true, true, false, true];
let mut i = 0;
s.retain(|_| (keep[i], i += 1).0);
assert_eq!(s, "bce");

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

This is supported with target feature alloc only.

Inserts a character into this TinyString at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the TinyString's length, or if it does not lie on a char boundary.

Examples

let mut s = TinyString::<[u8; 3]>::new();

s.insert(0, 'f');
s.insert(1, 'o');
s.insert(2, 'o');

assert_eq!("foo", s);

pub fn insert_str(&mut self, idx: usize, string: &str)[src]

This is supported with target feature alloc only.

Inserts a string slice into this TinyString at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the String's length, or if it does not lie on a char boundary.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 6]>::try_from("bar").unwrap();

s.insert_str(0, "foo");

assert_eq!("foobar", s);

pub fn clear(&mut self)[src]

This is supported with target feature alloc only.

Truncates this TinyString, removing all contents.

While this means the TinyString will have a length of zero, it does not modify its capacity.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 3]>::try_from("foo").unwrap();

s.clear();

assert!(s.is_empty());
assert_eq!(0, s.len());
assert_eq!(3, s.capacity());

pub fn drain<R>(&mut self, range: R) -> Drain<A>

Important traits for Drain<'_, A>

impl<A: ByteArray, '_> Iterator for Drain<'_, A> type Item = char;
where
    R: RangeBounds<usize>, 
[src]

This is supported with target feature alloc only.

Creates a draining iterator that removes the specified range in the TinyString and yields the removed chars.

Note: The element range is removed even if the iterator is not consumed until the end.

Panics

Panics if the starting point or end point do not lie on a char boundary, or if they're out of bounds.

Examples

use std::convert::TryFrom;
let mut s = TinyString::<[u8; 23]>::try_from("α is alpha, β is beta").unwrap();
let beta_offset = s.find('β').unwrap_or(s.len());

// Remove the range up until the β from the string
let t: TinyString<[u8; 23]> = s.drain(..beta_offset).collect();
assert_eq!(t, "α is alpha, ");
assert_eq!(s, "β is beta");

// A full range clears the string
s.drain(..);
assert_eq!(s, "");

pub fn move_to_the_heap(&mut self)[src]

This is supported with target feature alloc only.

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

This is supported with target feature alloc only.

Removes the specified range in the string, and replaces it with the given string. The given string doesn't need to be the same length as the range.

Panics

Panics if the starting point or end point do not lie on a char boundary, or if they're out of bounds.

Examples

Basic usage:

let mut s = TinyString::<[u8; 32]>::from("α is alpha, β is beta");
let beta_offset = s.find('β').unwrap_or(s.len());

// Replace the range up until the β from the string
s.replace_range(..beta_offset, "Α is capital alpha; ");
assert_eq!(s, "Α is capital alpha; β is beta");

#[must_use = "use `.truncate()` if you don't need the other half"]pub fn split_off(&mut self, at: usize) -> TinyString<A>[src]

This is supported with target feature alloc only.

Splits the string into two at the given index.

Returns a new TinyString. self contains bytes [0, at), and the returned TinyString contains bytes [at, len). at must be on the boundary of a UTF-8 code point.

Both self and the returned TinyString will have the same capacity as self did before this was called.

Panics

Panics if at is not on a UTF-8 code point boundary, or if it is beyond the last code point of the string.

Examples

use std::convert::TryFrom;
let mut hello = TinyString::<[u8; 13]>::try_from("Hello, World!").unwrap();
let world = hello.split_off(7);
assert_eq!(hello, "Hello, ");
assert_eq!(world, "World!");

Trait Implementations

impl<A: ByteArray, '_> Add<&'_ str> for TinyString<A>[src]

Implements the + operator for concatenating two strings.

Examples

use std::convert::TryFrom;
let a = TinyString::<[u8; 13]>::try_from("Hello, ").unwrap();
let b = "World!";
let c = a + b;
assert_eq!(c, "Hello, World!");

type Output = TinyString<A>

The resulting type after applying the + operator.

impl<A: ByteArray, '_> AddAssign<&'_ str> for TinyString<A>[src]

Implements the += operator for appending to a String.

This has the same behavior as the push_str method.

Examples

use std::convert::TryFrom;
let mut a = TinyString::<[u8; 13]>::try_from("Hello, ").unwrap();
let b = "World!";
a += b;
assert_eq!(a, "Hello, World!");

impl<A: ByteArray> AsMut<str> for TinyString<A>[src]

impl<A: ByteArray> AsRef<[u8]> for TinyString<A>[src]

impl<A: ByteArray> AsRef<str> for TinyString<A>[src]

impl<A: ByteArray + Clone> Clone for TinyString<A>[src]

impl<A: ByteArray> Debug for TinyString<A>[src]

impl<A: ByteArray> Default for TinyString<A>[src]

impl<A: ByteArray> Deref for TinyString<A>[src]

type Target = str

The resulting type after dereferencing.

impl<A: ByteArray> DerefMut for TinyString<A>[src]

impl<A: ByteArray> Display for TinyString<A>[src]

impl<A: Eq + ByteArray> Eq for TinyString<A>[src]

impl<'a, A: ByteArray> Extend<&'a char> for TinyString<A>[src]

impl<'a, A: ByteArray> Extend<&'a str> for TinyString<A>[src]

impl<'a, A: ByteArray> Extend<Cow<'a, str>> for TinyString<A>[src]

impl<A: ByteArray> Extend<String> for TinyString<A>[src]

impl<A: ByteArray, A2: ByteArray> Extend<TinyString<A2>> for TinyString<A>[src]

impl<A: ByteArray> Extend<char> for TinyString<A>[src]

impl<'a, A: ByteArray> From<&'a String> for TinyString<A>[src]

impl<'a, A: ByteArray> From<&'a char> for TinyString<A>[src]

impl<'a, A: ByteArray> From<&'a mut str> for TinyString<A>[src]

impl<'a, A: ByteArray> From<&'a str> for TinyString<A>[src]

impl<'a, A: ByteArray> From<Cow<'a, str>> for TinyString<A>[src]

fn from(s: Cow<'a, str>) -> Self[src]

If the Cow is Owned, then the String is converted into a heap-allocated TinyVec to avoid unnecessary allocations. If it is Borrowed, then an allocation may be made.

impl<A: ByteArray> From<String> for TinyString<A>[src]

fn from(s: String) -> Self[src]

This converts the String into a heap-allocated TinyVec to avoid unnecessary allocations.

impl<A: ByteArray> From<char> for TinyString<A>[src]

impl<'a, A: ByteArray> FromIterator<&'a char> for TinyString<A>[src]

impl<'a, A: ByteArray> FromIterator<&'a str> for TinyString<A>[src]

impl<'a, A: ByteArray> FromIterator<Cow<'a, str>> for TinyString<A>[src]

impl<'a, A: ByteArray> FromIterator<String> for TinyString<A>[src]

impl<A: ByteArray, A2: ByteArray> FromIterator<TinyString<A2>> for TinyString<A>[src]

impl<'a, A: ByteArray> FromIterator<char> for TinyString<A>[src]

impl<A: ByteArray> FromStr for TinyString<A>[src]

type Err = Infallible

The associated error which can be returned from parsing.

impl<A: ByteArray> Hash for TinyString<A>[src]

impl<A: ByteArray> Index<Range<usize>> for TinyString<A>[src]

type Output = str

The returned type after indexing.

impl<A: ByteArray> Index<RangeFrom<usize>> for TinyString<A>[src]

type Output = str

The returned type after indexing.

impl<A: ByteArray> Index<RangeFull> for TinyString<A>[src]

type Output = str

The returned type after indexing.

impl<A: ByteArray> Index<RangeInclusive<usize>> for TinyString<A>[src]

type Output = str

The returned type after indexing.

impl<A: ByteArray> Index<RangeTo<usize>> for TinyString<A>[src]

type Output = str

The returned type after indexing.

impl<A: ByteArray> Index<RangeToInclusive<usize>> for TinyString<A>[src]

type Output = str

The returned type after indexing.

impl<A: ByteArray> IndexMut<Range<usize>> for TinyString<A>[src]

impl<A: ByteArray> IndexMut<RangeFrom<usize>> for TinyString<A>[src]

impl<A: ByteArray> IndexMut<RangeFull> for TinyString<A>[src]

impl<A: ByteArray> IndexMut<RangeInclusive<usize>> for TinyString<A>[src]

impl<A: ByteArray> IndexMut<RangeTo<usize>> for TinyString<A>[src]

impl<A: ByteArray> IndexMut<RangeToInclusive<usize>> for TinyString<A>[src]

impl<A: Ord + ByteArray> Ord for TinyString<A>[src]

impl<'a, 'b, A: ByteArray> PartialEq<&'a str> for TinyString<A>[src]

impl<'a, 'b, A: ByteArray> PartialEq<Cow<'a, str>> for TinyString<A>[src]

impl<'a, 'b, A: ByteArray> PartialEq<String> for TinyString<A>[src]

impl<'a, 'b, A: ByteArray> PartialEq<TinyString<A>> for str[src]

impl<'a, 'b, A: ByteArray> PartialEq<TinyString<A>> for &'a str[src]

impl<'a, 'b, A: ByteArray> PartialEq<TinyString<A>> for Cow<'a, str>[src]

impl<'a, 'b, A: ByteArray> PartialEq<TinyString<A>> for String[src]

impl<A1, A2> PartialEq<TinyString<A1>> for TinyString<A2> where
    A1: ByteArray,
    A2: ByteArray
[src]

impl<'a, 'b, A: ByteArray> PartialEq<str> for TinyString<A>[src]

impl<A: PartialOrd + ByteArray> PartialOrd<TinyString<A>> for TinyString<A>[src]

impl<A: ByteArray> StructuralEq for TinyString<A>[src]

impl<A: ByteArray> Write for TinyString<A>[src]

Auto Trait Implementations

impl<A> RefUnwindSafe for TinyString<A> where
    A: RefUnwindSafe

impl<A> Send for TinyString<A> where
    A: Send

impl<A> Sync for TinyString<A> where
    A: Sync

impl<A> Unpin for TinyString<A> where
    A: Unpin

impl<A> UnwindSafe for TinyString<A> where
    A: UnwindSafe

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T> ToString for T where
    T: Display + ?Sized
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.