Struct ArrayString

struct ArrayString<CAP: usize> { ... }

A string with a fixed capacity.

The ArrayString is a string backed by a fixed size array. It keeps track of its length, and is parameterized by CAP for the maximum capacity.

CAP is of type usize but is range limited to u32::MAX; attempting to create larger arrayvecs with larger capacity will panic.

The string is a contiguous value that you can store directly on the stack if needed.

Implementations

impl<CAP: usize> ArrayString<CAP>

fn new() -> ArrayString<CAP>

Create a new empty ArrayString.

Capacity is inferred from the type parameter.

use arrayvec::ArrayString;

let mut string = ArrayString::<16>::new();
string.push_str("foo");
assert_eq!(&string[..], "foo");
assert_eq!(string.capacity(), 16);

const fn new_const() -> ArrayString<CAP>

Create a new empty ArrayString (const fn).

Capacity is inferred from the type parameter.

use arrayvec::ArrayString;

static ARRAY: ArrayString<1024> = ArrayString::new_const();

const fn len(self: &Self) -> usize

Return the length of the string.

const fn is_empty(self: &Self) -> bool

Returns whether the string is empty.

fn from(s: &str) -> Result<Self, CapacityError<&str>>

Create a new ArrayString from a str.

Capacity is inferred from the type parameter.

Errors if the backing array is not large enough to fit the string.

use arrayvec::ArrayString;

let mut string = ArrayString::<3>::from("foo").unwrap();
assert_eq!(&string[..], "foo");
assert_eq!(string.len(), 3);
assert_eq!(string.capacity(), 3);

fn from_byte_string(b: &[u8; CAP]) -> Result<Self, Utf8Error>

Create a new ArrayString from a byte string literal.

Errors if the byte string literal is not valid UTF-8.

use arrayvec::ArrayString;

let string = ArrayString::from_byte_string(b"hello world").unwrap();

fn zero_filled() -> Self

Create a new ArrayString value fully filled with ASCII NULL characters (\0). Useful to be used as a buffer to collect external data or as a buffer for intermediate processing.

use arrayvec::ArrayString;

let string = ArrayString::<16>::zero_filled();
assert_eq!(string.len(), 16);

const fn capacity(self: &Self) -> usize

Return the capacity of the ArrayString.

use arrayvec::ArrayString;

let string = ArrayString::<3>::new();
assert_eq!(string.capacity(), 3);

const fn is_full(self: &Self) -> bool

Return if the ArrayString is completely filled.

use arrayvec::ArrayString;

let mut string = ArrayString::<1>::new();
assert!(!string.is_full());
string.push_str("A");
assert!(string.is_full());

const fn remaining_capacity(self: &Self) -> usize

Returns the capacity left in the ArrayString.

use arrayvec::ArrayString;

let mut string = ArrayString::<3>::from("abc").unwrap();
string.pop();
assert_eq!(string.remaining_capacity(), 1);

fn push(self: &mut Self, c: char)

Adds the given char to the end of the string.

Panics if the backing array is not large enough to fit the additional char.

use arrayvec::ArrayString;

let mut string = ArrayString::<2>::new();

string.push('a');
string.push('b');

assert_eq!(&string[..], "ab");

fn try_push(self: &mut Self, c: char) -> Result<(), CapacityError<char>>

Adds the given char to the end of the string.

Returns Ok if the push succeeds.

Errors if the backing array is not large enough to fit the additional char.

use arrayvec::ArrayString;

let mut string = ArrayString::<2>::new();

string.try_push('a').unwrap();
string.try_push('b').unwrap();
let overflow = string.try_push('c');

assert_eq!(&string[..], "ab");
assert_eq!(overflow.unwrap_err().element(), 'c');

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

Adds the given string slice to the end of the string.

Panics if the backing array is not large enough to fit the string.

use arrayvec::ArrayString;

let mut string = ArrayString::<2>::new();

string.push_str("a");
string.push_str("d");

assert_eq!(&string[..], "ad");

fn try_push_str<'a>(self: &mut Self, s: &'a str) -> Result<(), CapacityError<&'a str>>

Adds the given string slice to the end of the string.

Returns Ok if the push succeeds.

Errors if the backing array is not large enough to fit the string.

use arrayvec::ArrayString;

let mut string = ArrayString::<2>::new();

string.try_push_str("a").unwrap();
let overflow1 = string.try_push_str("bc");
string.try_push_str("d").unwrap();
let overflow2 = string.try_push_str("ef");

assert_eq!(&string[..], "ad");
assert_eq!(overflow1.unwrap_err().element(), "bc");
assert_eq!(overflow2.unwrap_err().element(), "ef");

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

Removes the last character from the string and returns it.

Returns None if this ArrayString is empty.

use arrayvec::ArrayString;
 
let mut s = ArrayString::<3>::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);

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

Shortens this ArrayString to the specified length.

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

Panics if new_len does not lie on a char boundary.

use arrayvec::ArrayString;

let mut string = ArrayString::<6>::from("foobar").unwrap();
string.truncate(3);
assert_eq!(&string[..], "foo");
string.truncate(4);
assert_eq!(&string[..], "foo");

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

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

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

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

use arrayvec::ArrayString;
 
let mut s = ArrayString::<3>::from("foo").unwrap();

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

fn clear(self: &mut Self)

Make the string empty.

unsafe fn set_len(self: &mut Self, length: usize)

Set the strings’s length.

This function is unsafe because it changes the notion of the number of “valid” bytes in the string. Use with care.

This method uses debug assertions to check the validity of length and may use other debug assertions.

fn as_str(self: &Self) -> &str

Return a string slice of the whole ArrayString.

fn as_mut_str(self: &mut Self) -> &mut str

Return a mutable string slice of the whole ArrayString.

impl<'a, CAP: usize> TryFrom for ArrayString<CAP>

fn try_from(f: &'a str) -> Result<Self, <Self as >::Error>

impl<'a, CAP: usize> TryFrom for ArrayString<CAP>

fn try_from(f: Arguments<'a>) -> Result<Self, <Self as >::Error>

impl<CAP: usize> AsRef for ArrayString<CAP>

fn as_ref(self: &Self) -> &str

impl<CAP: usize> Borrow for ArrayString<CAP>

fn borrow(self: &Self) -> &str

impl<CAP: usize> BorrowMut for ArrayString<CAP>

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

impl<CAP: usize> Clone for ArrayString<CAP>

fn clone(self: &Self) -> ArrayString<CAP>
fn clone_from(self: &mut Self, rhs: &Self)

impl<CAP: usize> Copy for ArrayString<CAP>

impl<CAP: usize> Debug for ArrayString<CAP>

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

impl<CAP: usize> Default for ArrayString<CAP>

fn default() -> ArrayString<CAP>

Return an empty ArrayString

impl<CAP: usize> Deref for ArrayString<CAP>

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

impl<CAP: usize> DerefMut for ArrayString<CAP>

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

impl<CAP: usize> Display for ArrayString<CAP>

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

impl<CAP: usize> Eq for ArrayString<CAP>

impl<CAP: usize> Freeze for ArrayString<CAP>

impl<CAP: usize> FromStr for ArrayString<CAP>

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

impl<CAP: usize> Hash for ArrayString<CAP>

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

impl<CAP: usize> Ord for ArrayString<CAP>

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

impl<CAP: usize> PartialEq for ArrayString<CAP>

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

impl<CAP: usize> PartialEq for ArrayString<CAP>

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

impl<CAP: usize> PartialOrd for ArrayString<CAP>

fn partial_cmp(self: &Self, rhs: &Self) -> Option<Ordering>
fn lt(self: &Self, rhs: &Self) -> bool
fn le(self: &Self, rhs: &Self) -> bool
fn gt(self: &Self, rhs: &Self) -> bool
fn ge(self: &Self, rhs: &Self) -> bool

impl<CAP: usize> PartialOrd for ArrayString<CAP>

fn partial_cmp(self: &Self, rhs: &str) -> Option<Ordering>
fn lt(self: &Self, rhs: &str) -> bool
fn le(self: &Self, rhs: &str) -> bool
fn gt(self: &Self, rhs: &str) -> bool
fn ge(self: &Self, rhs: &str) -> bool

impl<CAP: usize> RefUnwindSafe for ArrayString<CAP>

impl<CAP: usize> Send for ArrayString<CAP>

impl<CAP: usize> Sync for ArrayString<CAP>

impl<CAP: usize> Unpin for ArrayString<CAP>

impl<CAP: usize> UnsafeUnpin for ArrayString<CAP>

impl<CAP: usize> UnwindSafe for ArrayString<CAP>

impl<CAP: usize> Write for ArrayString<CAP>

fn write_char(self: &mut Self, c: char) -> Result
fn write_str(self: &mut Self, s: &str) -> Result

impl<P, T> Receiver for ArrayString<CAP>

impl<T> Any for ArrayString<CAP>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for ArrayString<CAP>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for ArrayString<CAP>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for ArrayString<CAP>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for ArrayString<CAP>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for ArrayString<CAP>

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T> ToString for ArrayString<CAP>

fn to_string(self: &Self) -> String

impl<T, U> Into for ArrayString<CAP>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for ArrayString<CAP>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for ArrayString<CAP>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>