[][src]Struct tinyvec_string::arraystring::ArrayString

#[repr(transparent)]pub struct ArrayString<A: ByteArray> { /* fields omitted */ }

A UTF-8 encoded, fixed-capacity string.

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

  • An ArrayString has a fixed capacity (in bytes), the size of the backing array.
  • An ArrayString 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 ArrayString must be valid UTF-8 at all times.

ArrayString is intended to replicate the API of String as much as possible. Like ArrayVec, some methods cannot be implemented, like from_raw_parts or reserve

Examples

Creating ArrayStrings with TryFrom:

use std::convert::TryFrom;
// explicitly specifying the backing array type with a turbofish
// note that `try_from` fails if the backing array is not large enough
// to contain the string contents
let s1 = ArrayString::<[u8; 13]>::try_from("Hello, world!").unwrap();

assert_eq!(s1, "Hello, world!");

// annotate the variable type to specify the backing array
let s2: ArrayString<[u8; 13]> = ArrayString::try_from("Hello, world!").unwrap();

assert_eq!(s1, s2);

// `collect` (which uses `FromIterator`) will panic if the backing array
// is not large enough
let s3: ArrayString<[u8; 12]> =
    vec!["foo", "bar", "baz"].into_iter().collect();

assert_eq!(s3, "foobarbaz");

Creating ArrayStrings with the from convenience method:

// this panics on capacity overflow
let s = ArrayString::<[u8; 6]>::from("foobar");

Implementations

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

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

Creates a new empty ArrayString.

This creates a new ArrayVec with a backing array type A, using the backing array of zeroes.

Examples

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

pub fn from<S>(s: S) -> Self where
    S: Debug,
    Self: TryFrom<S, Error = CapacityOverflowError<S>>, 
[src]

Creates a new ArrayString from another string type.

This can be used to create an ArrayString from any type with an applicable TryFrom implementation:

  • &str
  • &mut str
  • char
  • &char
  • String
  • &String
  • Cow<str>

Because it relies on TryFrom, this method may panic (which is why it is not a From implementation).

Panics

Panics if the input string is larger than the backing array.

Examples

let s = ArrayString::<[u8; 13]>::from("Hello, world!");

assert_eq!(s, "Hello, world!");

This method panics when the string is too large:

This example panics
// the following line will panic!
let s = ArrayString::<[u8; 10]>::from("This is quite a long string");

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

Converts a vector of bytes to an ArrayString.

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

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::{array_vec, ArrayVec};
// some bytes, in a vector
let ferris: ArrayVec<[u8; 7]> = array_vec![240, 159, 166, 128, 226, 153, 165];

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

assert_eq!("🦀♥", ferris);

Incorrect bytes:

use tinyvec::{array_vec, ArrayVec};

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

assert!(ArrayString::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: ArrayVec<A>) -> ArrayString<A>[src]

Converts a vector of bytes to an ArrayString 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 String, as the rest of the standard library assumes that Strings are valid UTF-8.

Examples

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

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

assert_eq!("🦀♥", ferris);

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

Returns an ArrayString's backing ArrayVec.

Examples

let s = ArrayString::<[u8; 5]>::from("hello");
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 ArrayString.

Examples

let s = ArrayString::<[u8; 3]>::from("foo");

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

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

Extracts a mutable string slice containing the entire ArrayString.

Examples

let mut s = ArrayString::<[u8; 6]>::from("foobar");
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 &'_ mut [u8]

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

Returns a byte slice of this ArrayString's contents.

The inverse of this method is from_utf8.

Examples

let s = ArrayString::<[u8; 5]>::from("hello");

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

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

Returns a mutable reference to the contents of this ArrayString.

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 ArrayString, as the rest of the standard library assumes that ArrayStrings are valid UTF-8.

Examples

let mut s = ArrayString::<[u8; 5]>::from("hello");

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 ArrayString's capacity, in bytes.

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

Examples

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

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

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

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

Examples

let plain_f = ArrayString::<[u8; 3]>::from("foo");
assert_eq!(plain_f.len(), 3);

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

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

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

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

Examples

let mut s = ArrayString::<[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 ArrayString.

Panics

Panics if the new length would be longer than the capacity of the backing array.

Examples

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

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.

Panics

Panics if the new length would be longer than the capacity of the backing array.

Examples

let mut s = ArrayString::<[u8; 6]>::from("abc");

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

assert_eq!("abc123", s);

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

Shortens this ArrayString 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

let mut s = ArrayString::<[u8; 5]>::from("hello");

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

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

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 ArrayString's length, or if it does not lie on a char boundary.

Examples

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

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

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

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

assert_eq!(s, "foobar");

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

let mut s = ArrayString::<[u8; 5]>::from("abcde");
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 ArrayString 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 ArrayString's length, or if it does not lie on a char boundary.

Panics if the new length would be longer than the capacity of the backing array.

Examples

let mut s = ArrayString::<[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 ArrayString 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.

Panics if the new length would be longer than the capacity of the backing array.

Examples

let mut s = ArrayString::<[u8; 6]>::from("bar");

s.insert_str(0, "foo");

assert_eq!("foobar", s);

pub fn clear(&mut self)[src]

Truncates this ArrayString, removing all contents.

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

Examples

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

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]

Creates a draining iterator that removes the specified range in the String 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

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

// Remove the range up until the β from the string
let t: ArrayString<[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, "");

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

Splits the string into two at the given index.

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

Both self and the returned ArrayString 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

let mut hello = ArrayString::<[u8; 13]>::from("Hello, World!");
let world = hello.split_off(7);
assert_eq!(hello, "Hello, ");
assert_eq!(world, "World!");

impl ArrayString<[u8; 4]>[src]

pub fn from_char_infallible(c: char) -> Self[src]

Creates an ArrayString from a char infallibly.

Without const generics, this method is limited to ArrayStrings with backing arrays of size 4 only.

Examples

let s = ArrayString::<[u8; 4]>::from_char_infallible('c');
assert_eq!(s, "c");

Trait Implementations

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

Implements the + operator for concatenating two strings.

Panics

Panics if the new length would be longer than the capacity of the backing array.

Examples

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

type Output = ArrayString<A>

The resulting type after applying the + operator.

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

Implements the += operator for appending to a String.

This has the same behavior as the push_str method.

Panics

Panics if the new length would be longer than the capacity of the backing array.

Examples

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

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

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

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

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

impl<A: Copy + ByteArray> Copy for ArrayString<A>[src]

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

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

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

type Target = str

The resulting type after dereferencing.

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

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

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

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

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

Panics

Panics if the new length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the new length would be longer than the capacity of the backing array.

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

fn extend<I: IntoIterator<Item = ArrayString<A2>>>(&mut self, iter: I)[src]

Panics

Panics if the new length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the new length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the new length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the new length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the length would be longer than the capacity of the backing array.

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

fn from_iter<I: IntoIterator<Item = ArrayString<A2>>>(iter: I) -> Self[src]

Panics

Panics if the new length would be longer than the capacity of the backing array.

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

fn from_iter<I: IntoIterator<Item = Cow<'a, str>>>(iter: I) -> Self[src]

Panics

Panics if the length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the length would be longer than the capacity of the backing array.

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

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

Panics

Panics if the length would be longer than the capacity of the backing array.

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

type Err = CapacityOverflowError<()>

Because of lifetime restrictions, the error type can't return the provided string like the TryFrom implementations do.

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

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

type Output = str

The returned type after indexing.

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

type Output = str

The returned type after indexing.

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

type Output = str

The returned type after indexing.

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

type Output = str

The returned type after indexing.

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

type Output = str

The returned type after indexing.

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

type Output = str

The returned type after indexing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl<'a, A: ByteArray> TryFrom<&'a String> for ArrayString<A>[src]

type Error = CapacityOverflowError<&'a String>

The type returned in the event of a conversion error.

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

type Error = CapacityOverflowError<&'a mut str>

The type returned in the event of a conversion error.

impl<'a, A: ByteArray> TryFrom<&'a str> for ArrayString<A>[src]

type Error = CapacityOverflowError<&'a str>

The type returned in the event of a conversion error.

impl<'c, A: ByteArray> TryFrom<&'c char> for ArrayString<A>[src]

type Error = CapacityOverflowError<&'c char>

The type returned in the event of a conversion error.

impl<'a, A: ByteArray> TryFrom<Cow<'a, str>> for ArrayString<A>[src]

type Error = CapacityOverflowError<Cow<'a, str>>

The type returned in the event of a conversion error.

impl<A: ByteArray> TryFrom<String> for ArrayString<A>[src]

type Error = CapacityOverflowError<String>

The type returned in the event of a conversion error.

impl<A: ByteArray> TryFrom<char> for ArrayString<A>[src]

type Error = CapacityOverflowError<char>

The type returned in the event of a conversion error.

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

Auto Trait Implementations

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

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

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

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

impl<A> UnwindSafe for ArrayString<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.