Struct ascii::AsciiString

#[repr(transparent)]
pub struct AsciiString { /* private fields */ }

A growable string stored as an ASCII encoded buffer.

Implementations

impl AsciiString

pub const fn new() -> Self

Creates a new, empty ASCII string buffer without allocating.

Examples

let mut s = AsciiString::new();

pub fn with_capacity(capacity: usize) -> Self

Creates a new ASCII string buffer with the given capacity. The string will be able to hold exactly capacity bytes without reallocating. If capacity is 0, the ASCII string will not allocate.

Examples

let mut s = AsciiString::with_capacity(10);

pub unsafe fn from_raw_parts(
    buf: *mut AsciiChar,
    length: usize,
    capacity: usize
) -> Self

Creates a new AsciiString from a length, capacity and pointer.

Safety

This is highly unsafe, due to the number of invariants that aren’t checked:

• The memory at buf need to have been previously allocated by the same allocator this library uses, with an alignment of 1.
• length needs to be less than or equal to capacity.
• capacity needs to be the correct value.
• buf must have length valid ascii elements and contain a total of capacity total, possibly, uninitialized, elements.
• Nothing else must be using the memory buf points to.

Violating these may cause problems like corrupting the allocator’s internal data structures.

Examples

Basic usage:

use std::mem;

unsafe {
   let mut s = AsciiString::from_ascii("hello").unwrap();
   let ptr = s.as_mut_ptr();
   let len = s.len();
   let capacity = s.capacity();

   mem::forget(s);

   let s = AsciiString::from_raw_parts(ptr, len, capacity);

   assert_eq!(AsciiString::from_ascii("hello").unwrap(), s);
}

pub unsafe fn from_ascii_unchecked<B>(bytes: B) -> Selfwhere
    B: Into<Vec<u8>>,

Converts a vector of bytes to an AsciiString without checking for non-ASCII characters.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid ASCII characters. If this constraint is violated, it may cause memory unsafety issues with future of the AsciiString, as the rest of this library assumes that AsciiStrings are ASCII encoded.

pub fn from_ascii<B>(bytes: B) -> Result<AsciiString, FromAsciiError<B>>where
    B: Into<Vec<u8>> + AsRef<[u8]>,

Converts anything that can represent a byte buffer into an AsciiString.

Errors

Returns the byte buffer if not all of the bytes are ASCII characters.

Examples

let foo = AsciiString::from_ascii("foo".to_string()).unwrap();
let err = AsciiString::from_ascii("Ŋ".to_string()).unwrap_err();
assert_eq!(foo.as_str(), "foo");
assert_eq!(err.into_source(), "Ŋ");

pub fn push_str(&mut self, string: &AsciiStr)

Pushes the given ASCII string onto this ASCII string buffer.

Examples

use std::str::FromStr;
let mut s = AsciiString::from_str("foo").unwrap();
s.push_str("bar".as_ascii_str().unwrap());
assert_eq!(s, "foobar".as_ascii_str().unwrap());

pub fn insert_str(&mut self, idx: usize, string: &AsciiStr)

Inserts the given ASCII string at the given place in this ASCII string buffer.

Panics

Panics if idx is larger than the AsciiString’s length.

Examples

use std::str::FromStr;
let mut s = AsciiString::from_str("abc").unwrap();
s.insert_str(1, "def".as_ascii_str().unwrap());
assert_eq!(&*s, "adefbc");

pub fn capacity(&self) -> usize

Returns the number of bytes that this ASCII string buffer can hold without reallocating.

Examples

let s = String::with_capacity(10);
assert!(s.capacity() >= 10);

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more bytes to be inserted in the given AsciiString. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new capacity overflows usize.

Examples

let mut s = AsciiString::new();
s.reserve(10);
assert!(s.capacity() >= 10);

pub fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for exactly additional more bytes to be inserted in the given AsciiString. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

Panics

Panics if the new capacity overflows usize.

Examples

let mut s = AsciiString::new();
s.reserve_exact(10);
assert!(s.capacity() >= 10);

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of this ASCII string buffer to match it’s length.

Examples

use std::str::FromStr;
let mut s = AsciiString::from_str("foo").unwrap();
s.reserve(100);
assert!(s.capacity() >= 100);
s.shrink_to_fit();
assert_eq!(s.capacity(), 3);

pub fn push(&mut self, ch: AsciiChar)

Adds the given ASCII character to the end of the ASCII string.

Examples

let mut s = AsciiString::from_ascii("abc").unwrap();
s.push(AsciiChar::from_ascii('1').unwrap());
s.push(AsciiChar::from_ascii('2').unwrap());
s.push(AsciiChar::from_ascii('3').unwrap());
assert_eq!(s, "abc123");

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

Shortens a ASCII string to the specified length.

Panics

Panics if new_len > current length.

Examples

let mut s = AsciiString::from_ascii("hello").unwrap();
s.truncate(2);
assert_eq!(s, "he");

pub fn pop(&mut self) -> Option<AsciiChar>

Removes the last character from the ASCII string buffer and returns it. Returns None if this string buffer is empty.

Examples

let mut s = AsciiString::from_ascii("foo").unwrap();
assert_eq!(s.pop().map(|c| c.as_char()), Some('o'));
assert_eq!(s.pop().map(|c| c.as_char()), Some('o'));
assert_eq!(s.pop().map(|c| c.as_char()), Some('f'));
assert_eq!(s.pop(), None);

pub fn remove(&mut self, idx: usize) -> AsciiChar

Removes the ASCII character at position idx from the buffer and returns it.

Warning

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

Panics

If idx is out of bounds this function will panic.

Examples

let mut s = AsciiString::from_ascii("foo").unwrap();
assert_eq!(s.remove(0).as_char(), 'f');
assert_eq!(s.remove(1).as_char(), 'o');
assert_eq!(s.remove(0).as_char(), 'o');

pub fn insert(&mut self, idx: usize, ch: AsciiChar)

Inserts an ASCII character into the buffer at position idx.

Warning

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

Panics

If idx is out of bounds this function will panic.

Examples

let mut s = AsciiString::from_ascii("foo").unwrap();
s.insert(2, AsciiChar::b);
assert_eq!(s, "fobo");

pub fn len(&self) -> usize

Returns the number of bytes in this ASCII string.

Examples

let s = AsciiString::from_ascii("foo").unwrap();
assert_eq!(s.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the ASCII string contains zero bytes.

Examples

let mut s = AsciiString::new();
assert!(s.is_empty());
s.push(AsciiChar::from_ascii('a').unwrap());
assert!(!s.is_empty());

pub fn clear(&mut self)

Truncates the ASCII string, setting length (but not capacity) to zero.

Examples

let mut s = AsciiString::from_ascii("foo").unwrap();
s.clear();
assert!(s.is_empty());

pub fn into_boxed_ascii_str(self) -> Box<AsciiStr>

Converts this AsciiString into a Box<AsciiStr>.

This will drop any excess capacity

Methods from Deref<Target = AsciiStr>

pub fn as_str(&self) -> &str

Converts &self to a &str slice.

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

Converts &self into a byte slice.

pub fn as_slice(&self) -> &[AsciiChar]

Returns the entire string as slice of AsciiChars.

pub fn as_mut_slice(&mut self) -> &mut [AsciiChar]

Returns the entire string as mutable slice of AsciiChars.

pub fn as_ptr(&self) -> *const AsciiChar

Returns a raw pointer to the AsciiStr’s buffer.

The caller must ensure that the slice outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the AsciiStr may cause it’s buffer to be reallocated, which would also make any pointers to it invalid.

pub fn as_mut_ptr(&mut self) -> *mut AsciiChar

Returns an unsafe mutable pointer to the AsciiStr’s buffer.

The caller must ensure that the slice outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the AsciiStr may cause it’s buffer to be reallocated, which would also make any pointers to it invalid.

pub fn to_ascii_string(&self) -> AsciiString

Copies the content of this AsciiStr into an owned AsciiString.

pub fn len(&self) -> usize

Returns the number of characters / bytes in this ASCII sequence.

Examples

let s = AsciiStr::from_ascii("foo").unwrap();
assert_eq!(s.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the ASCII slice contains zero bytes.

Examples

let mut empty = AsciiStr::from_ascii("").unwrap();
let mut full = AsciiStr::from_ascii("foo").unwrap();
assert!(empty.is_empty());
assert!(!full.is_empty());

pub fn chars(&self) -> Chars<'_>

Returns an iterator over the characters of the AsciiStr.

pub fn chars_mut(&mut self) -> CharsMut<'_>

Returns an iterator over the characters of the AsciiStr which allows you to modify the value of each AsciiChar.

pub fn split(&self, on: AsciiChar) -> impl DoubleEndedIterator<Item = &AsciiStr>

Returns an iterator over parts of the AsciiStr separated by a character.

Examples

let words = AsciiStr::from_ascii("apple banana lemon").unwrap()
    .split(AsciiChar::Space)
    .map(|a| a.as_str())
    .collect::<Vec<_>>();
assert_eq!(words, ["apple", "banana", "lemon"]);

pub fn lines(&self) -> impl DoubleEndedIterator<Item = &AsciiStr>

Returns an iterator over the lines of the AsciiStr, which are themselves AsciiStrs.

Lines are ended with either LineFeed (\n), or CarriageReturn then LineFeed (\r\n).

The final line ending is optional.

pub fn trim(&self) -> &Self

Returns an ASCII string slice with leading and trailing whitespace removed.

Examples

let example = AsciiStr::from_ascii("  \twhite \tspace  \t").unwrap();
assert_eq!("white \tspace", example.trim());

pub fn trim_start(&self) -> &Self

Returns an ASCII string slice with leading whitespace removed.

Examples

let example = AsciiStr::from_ascii("  \twhite \tspace  \t").unwrap();
assert_eq!("white \tspace  \t", example.trim_start());

pub fn trim_end(&self) -> &Self

Returns an ASCII string slice with trailing whitespace removed.

Examples

let example = AsciiStr::from_ascii("  \twhite \tspace  \t").unwrap();
assert_eq!("  \twhite \tspace", example.trim_end());

pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool

Compares two strings case-insensitively.

pub fn make_ascii_uppercase(&mut self)

Replaces lowercase letters with their uppercase equivalent.

pub fn make_ascii_lowercase(&mut self)

Replaces uppercase letters with their lowercase equivalent.

pub fn to_ascii_uppercase(&self) -> AsciiString

Returns a copy of this string where letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’.

pub fn to_ascii_lowercase(&self) -> AsciiString

Returns a copy of this string where letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’.

pub fn first(&self) -> Option<AsciiChar>

Returns the first character if the string is not empty.

pub fn last(&self) -> Option<AsciiChar>

Returns the last character if the string is not empty.

Trait Implementations

impl<'a> Add<&'a AsciiStr> for AsciiString

type Output = AsciiString

The resulting type after applying the + operator.

fn add(self, other: &AsciiStr) -> AsciiString

Performs the + operation.

impl<'a> AddAssign<&'a AsciiStr> for AsciiString

fn add_assign(&mut self, other: &AsciiStr)

Performs the += operation.

impl AsMut<[AsciiChar]> for AsciiString

fn as_mut(&mut self) -> &mut [AsciiChar]

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsMut<AsciiStr> for AsciiString

fn as_mut(&mut self) -> &mut AsciiStr

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<[AsciiChar]> for AsciiString

fn as_ref(&self) -> &[AsciiChar]

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<[u8]> for AsciiString

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AsciiStr> for AsciiString

fn as_ref(&self) -> &AsciiStr

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<str> for AsciiString

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AsciiStr> for AsciiString

fn borrow(&self) -> &AsciiStr

Immutably borrows from an owned value.

impl BorrowMut<AsciiStr> for AsciiString

fn borrow_mut(&mut self) -> &mut AsciiStr

Mutably borrows from an owned value.

impl Clone for AsciiString

fn clone(&self) -> AsciiString

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for AsciiString

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

Formats the value using the given formatter.

impl Default for AsciiString

fn default() -> AsciiString

Returns the “default value” for a type.

impl Deref for AsciiString

type Target = AsciiStr

The resulting type after dereferencing.

fn deref(&self) -> &AsciiStr

Dereferences the value.

impl DerefMut for AsciiString

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

Mutably dereferences the value.

impl Display for AsciiString

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

Formats the value using the given formatter.

impl<A: AsRef<AsciiStr>> Extend<A> for AsciiString

fn extend<I: IntoIterator<Item = A>>(&mut self, iterable: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a> From<&'a [AsciiChar]> for AsciiString

fn from(s: &'a [AsciiChar]) -> AsciiString

Converts to this type from the input type.

impl<'a> From<&'a AsciiStr> for AsciiString

fn from(s: &'a AsciiStr) -> Self

Converts to this type from the input type.

impl From<AsciiChar> for AsciiString

fn from(ch: AsciiChar) -> Self

Converts to this type from the input type.

impl From<AsciiString> for Arc<AsciiStr>

fn from(s: AsciiString) -> Arc<AsciiStr>

Converts to this type from the input type.

impl From<AsciiString> for Box<AsciiStr>

fn from(string: AsciiString) -> Self

Converts to this type from the input type.

impl From<AsciiString> for Cow<'static, AsciiStr>

fn from(string: AsciiString) -> Cow<'static, AsciiStr>

Converts to this type from the input type.

impl From<AsciiString> for Rc<AsciiStr>

fn from(s: AsciiString) -> Rc<AsciiStr>

Converts to this type from the input type.

impl From<AsciiString> for String

fn from(s: AsciiString) -> String

Converts to this type from the input type.

impl From<AsciiString> for Vec<AsciiChar>

fn from(s: AsciiString) -> Vec<AsciiChar>

Converts to this type from the input type.

impl From<AsciiString> for Vec<u8>

fn from(s: AsciiString) -> Vec<u8>

Converts to this type from the input type.

impl From<Box<AsciiStr, Global>> for AsciiString

fn from(boxed: Box<AsciiStr>) -> Self

Converts to this type from the input type.

impl<'a> From<Cow<'a, AsciiStr>> for AsciiString

fn from(cow: Cow<'a, AsciiStr>) -> AsciiString

Converts to this type from the input type.

impl From<Vec<AsciiChar, Global>> for AsciiString

fn from(vec: Vec<AsciiChar>) -> Self

Converts to this type from the input type.

impl<A: AsRef<AsciiStr>> FromIterator<A> for AsciiString

fn from_iter<I: IntoIterator<Item = A>>(iter: I) -> AsciiString

Creates a value from an iterator.

impl FromStr for AsciiString

type Err = AsAsciiStrError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<AsciiString, AsAsciiStrError>

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

impl Hash for AsciiString

fn hash<__H: Hasher>(&self, state: &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<T> Index<T> for AsciiStringwhere
    AsciiStr: Index<T>,

type Output = <AsciiStr as Index<T>>::Output

The returned type after indexing.

fn index(&self, index: T) -> &<AsciiStr as Index<T>>::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<T> for AsciiStringwhere
    AsciiStr: IndexMut<T>,

fn index_mut(&mut self, index: T) -> &mut <AsciiStr as Index<T>>::Output

Performs the mutable indexing (container[index]) operation.

impl IntoAsciiString for AsciiString

unsafe fn into_ascii_string_unchecked(self) -> AsciiString

Convert to AsciiString without checking for non-ASCII characters.

fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>>

Convert to AsciiString.

impl Ord for AsciiString

fn cmp(&self, other: &AsciiString) -> 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) -> Selfwhere
    Self: PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<&AsciiStr> for AsciiString

fn eq(&self, other: &&AsciiStr) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<&str> for AsciiString

fn eq(&self, other: &&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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<AsciiString> for &AsciiStr

fn eq(&self, other: &AsciiString) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<AsciiString> for &str

fn eq(&self, other: &AsciiString) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<AsciiString> for AsciiString

fn eq(&self, other: &AsciiString) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<AsciiString> for String

fn eq(&self, other: &AsciiString) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<AsciiString> for str

fn eq(&self, other: &AsciiString) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<String> for AsciiString

fn eq(&self, other: &String) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for AsciiString

fn eq(&self, other: &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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<AsciiString> for AsciiString

fn partial_cmp(&self, other: &AsciiString) -> Option<Ordering>

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

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

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

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

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

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

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

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

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

impl Write for AsciiString

Please note that the std::fmt::Result returned by these methods does not support transmission of an error other than that an error occurred.

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

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

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

Writes a char 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 Eq for AsciiString

impl StructuralEq for AsciiString

impl StructuralPartialEq for AsciiString