[][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]

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]

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]

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]

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]

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]

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]

Notable traits for &'_ [u8]

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

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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>

Notable traits for Drain<'_, A>

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

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]

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

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]

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]

pub 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]

pub 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
[src]

impl<A> Send for TinyString<A> where
    A: Send
[src]

impl<A> Sync for TinyString<A> where
    A: Sync
[src]

impl<A> Unpin for TinyString<A> where
    A: Unpin
[src]

impl<A> UnwindSafe for TinyString<A> where
    A: UnwindSafe
[src]

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.