Struct arrayvec::ArrayString

pub struct ArrayString<const CAP: usize> { /* fields omitted */ }

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<const CAP: usize> ArrayString<CAP>

pub 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);

pub 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();

pub const fn len(&self) -> usize

Return the length of the string.

pub const fn is_empty(&self) -> bool

Returns whether the string is empty.

pub 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);

pub 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();

pub 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);

pub const fn capacity(&self) -> usize

Return the capacity of the ArrayString.

use arrayvec::ArrayString;

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

pub const fn is_full(&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());

pub const fn remaining_capacity(&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);

pub fn push(&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");

pub fn try_push(&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');

pub fn push_str(&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");

pub fn try_push_str<'a>(
    &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");

pub fn pop(&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);

pub fn truncate(&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");

pub fn remove(&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');

pub fn clear(&mut self)

Make the string empty.

pub unsafe fn set_len(&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.

pub fn as_str(&self) -> &str

Return a string slice of the whole ArrayString.

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

Return a mutable string slice of the whole ArrayString.

Trait Implementations

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

fn as_ref(&self) -> &str

Performs the conversion.

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

fn borrow(&self) -> &str

Immutably borrows from an owned value.

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

fn clone(&self) -> ArrayString<CAP>

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> ArrayString<CAP>

Return an empty ArrayString

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

type Target = str

The resulting type after dereferencing.

fn deref(&self) -> &str

Dereferences the value.

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

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

Mutably dereferences the value.

impl<'de, const CAP: usize> Deserialize<'de> for ArrayString<CAP>

Requires crate feature "serde"

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

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

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

Formats the value using the given formatter.

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

type Err = CapacityError

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

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

fn hash<H: Hasher>(&self, h: &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<const CAP: usize> Ord for ArrayString<CAP>

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

Restrict a value to a certain interval.

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

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

fn eq(&self, rhs: &ArrayString<CAP>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

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

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

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

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

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

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

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

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

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

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

fn partial_cmp(&self, rhs: &ArrayString<CAP>) -> Option<Ordering>

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

fn lt(&self, rhs: &ArrayString<CAP>) -> bool

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

fn le(&self, rhs: &ArrayString<CAP>) -> bool

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

fn gt(&self, rhs: &ArrayString<CAP>) -> bool

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

fn ge(&self, rhs: &ArrayString<CAP>) -> bool

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

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

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

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

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

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

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

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

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

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

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

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

impl<const CAP: usize> Serialize for ArrayString<CAP>

Requires crate feature "serde"

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

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

type Error = CapacityError<&'a str>

The type returned in the event of a conversion error.

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

Performs the conversion.

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

type Error = CapacityError<Error>

The type returned in the event of a conversion error.

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

Performs the conversion.

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

Write appends written data to the end of the string.

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

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

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

Writes a string slice 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.

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

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