Struct ascii::AsciiStr

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

AsciiStr represents a byte or string slice that only contains ASCII characters.

It wraps an [AsciiChar] and implements many of strs methods and traits.

It can be created by a checked conversion from a str or [u8], or borrowed from an AsciiString.

Implementations

impl 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 const 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 const 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 from_ascii<B>(bytes: &B) -> Result<&AsciiStr, AsAsciiStrError>where
    B: AsRef<[u8]> + ?Sized,

Converts anything that can represent a byte slice into an AsciiStr.

Errors

If bytes contains a non-ascii byte, Err will be returned

Examples

let foo = AsciiStr::from_ascii(b"foo");
let err = AsciiStr::from_ascii("Ŋ");
assert_eq!(foo.unwrap().as_str(), "foo");
assert_eq!(err.unwrap_err().valid_up_to(), 0);

pub unsafe fn from_ascii_unchecked(bytes: &[u8]) -> &AsciiStr

Converts anything that can be represented as a byte slice to an AsciiStr without checking for non-ASCII characters..

Safety

If any of the bytes in bytes do not represent valid ascii characters, calling this function is undefined behavior.

Examples

let foo = unsafe { AsciiStr::from_ascii_unchecked(&b"foo"[..]) };
assert_eq!(foo.as_str(), "foo");

pub const 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 const 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.

pub fn into_ascii_string(self: Box<Self>) -> AsciiString

Converts a Box<AsciiStr> into a AsciiString without copying or allocating.

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 AsAsciiStr for AsciiStr

fn slice_ascii<R>(&self, range: R) -> Result<&AsciiStr, AsAsciiStrError>where
    R: SliceIndex<[AsciiChar], Output = [AsciiChar]>,

Convert a subslice to an ASCII slice.

fn as_ascii_str(&self) -> Result<&AsciiStr, AsAsciiStrError>

Convert to an ASCII slice.

unsafe fn as_ascii_str_unchecked(&self) -> &AsciiStr

Convert to an ASCII slice without checking for non-ASCII characters.

fn get_ascii(&self, index: usize) -> Option<AsciiChar>

Get a single ASCII character from the slice.

impl AsMut<[AsciiChar]> for AsciiStr

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

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

impl AsMut<AsciiStr> for [AsciiChar]

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

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

impl AsMut<AsciiStr> for AsciiStr

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

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 AsMutAsciiStr for AsciiStr

fn slice_ascii_mut<R>(
    &mut self,
    range: R
) -> Result<&mut AsciiStr, AsAsciiStrError>where
    R: SliceIndex<[AsciiChar], Output = [AsciiChar]>,

Convert a subslice to an ASCII slice.

unsafe fn as_mut_ascii_str_unchecked(&mut self) -> &mut AsciiStr

Convert to a mutable ASCII slice without checking for non-ASCII characters.

fn as_mut_ascii_str(&mut self) -> Result<&mut AsciiStr, AsAsciiStrError>

Convert to a mutable ASCII slice.

impl AsRef<[AsciiChar]> for AsciiStr

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

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

impl AsRef<[u8]> for AsciiStr

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

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

impl AsRef<AsciiStr> for [AsciiChar]

fn as_ref(&self) -> &AsciiStr

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

impl AsRef<AsciiStr> for AsciiChar

fn as_ref(&self) -> &AsciiStr

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

impl AsRef<AsciiStr> for AsciiStr

fn as_ref(&self) -> &AsciiStr

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 AsciiStr

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 Debug for AsciiStr

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

Formats the value using the given formatter.

impl Default for &'static AsciiStr

fn default() -> &'static AsciiStr

Returns the “default value” for a type.

impl Display for AsciiStr

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

Formats the value using the given formatter.

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

fn from(slice: &[AsciiChar]) -> &AsciiStr

Converts to this type from the input type.

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

fn from(astr: &AsciiStr) -> &[AsciiChar]

Converts to this type from the input type.

impl<'a> From<&'a AsciiStr> for &'a [u8]

fn from(astr: &AsciiStr) -> &[u8]

Converts to this type from the input type.

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

fn from(astr: &AsciiStr) -> &str

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<'a> From<&'a AsciiStr> for Cow<'a, AsciiStr>

fn from(s: &'a AsciiStr) -> Cow<'a, AsciiStr>

Converts to this type from the input type.

impl<'a> From<&'a mut [AsciiChar]> for &'a mut AsciiStr

fn from(slice: &mut [AsciiChar]) -> &mut AsciiStr

Converts to this type from the input type.

impl<'a> From<&'a mut AsciiStr> for &'a mut [AsciiChar]

fn from(astr: &mut AsciiStr) -> &mut [AsciiChar]

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<Box<[AsciiChar], Global>> for Box<AsciiStr>

fn from(owned: Box<[AsciiChar]>) -> Box<AsciiStr>

Converts to this type from the input type.

impl Hash for AsciiStr

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

impl Index<Range<usize>> for AsciiStr

type Output = AsciiStr

The returned type after indexing.

fn index(&self, index: Range<usize>) -> &AsciiStr

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for AsciiStr

type Output = AsciiStr

The returned type after indexing.

fn index(&self, index: RangeFrom<usize>) -> &AsciiStr

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for AsciiStr

type Output = AsciiStr

The returned type after indexing.

fn index(&self, index: RangeFull) -> &AsciiStr

Performs the indexing (container[index]) operation.

impl Index<RangeInclusive<usize>> for AsciiStr

type Output = AsciiStr

The returned type after indexing.

fn index(&self, index: RangeInclusive<usize>) -> &AsciiStr

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for AsciiStr

type Output = AsciiStr

The returned type after indexing.

fn index(&self, index: RangeTo<usize>) -> &AsciiStr

Performs the indexing (container[index]) operation.

impl Index<RangeToInclusive<usize>> for AsciiStr

type Output = AsciiStr

The returned type after indexing.

fn index(&self, index: RangeToInclusive<usize>) -> &AsciiStr

Performs the indexing (container[index]) operation.

impl Index<usize> for AsciiStr

type Output = AsciiChar

The returned type after indexing.

fn index(&self, index: usize) -> &AsciiChar

Performs the indexing (container[index]) operation.

impl IndexMut<Range<usize>> for AsciiStr

fn index_mut(&mut self, index: Range<usize>) -> &mut AsciiStr

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

impl IndexMut<RangeFrom<usize>> for AsciiStr

fn index_mut(&mut self, index: RangeFrom<usize>) -> &mut AsciiStr

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

impl IndexMut<RangeFull> for AsciiStr

fn index_mut(&mut self, index: RangeFull) -> &mut AsciiStr

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

impl IndexMut<RangeInclusive<usize>> for AsciiStr

fn index_mut(&mut self, index: RangeInclusive<usize>) -> &mut AsciiStr

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

impl IndexMut<RangeTo<usize>> for AsciiStr

fn index_mut(&mut self, index: RangeTo<usize>) -> &mut AsciiStr

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

impl IndexMut<RangeToInclusive<usize>> for AsciiStr

fn index_mut(&mut self, index: RangeToInclusive<usize>) -> &mut AsciiStr

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

impl IndexMut<usize> for AsciiStr

fn index_mut(&mut self, index: usize) -> &mut AsciiChar

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

impl<'a> IntoAsciiString for &'a AsciiStr

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<'a> IntoIterator for &'a AsciiStr

Produces references for compatibility with [u8].

(str doesn’t implement IntoIterator for its references, so there is no compatibility to lose.)

type Item = &'a AsciiChar

The type of the elements being iterated over.

type IntoIter = CharsRef<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut AsciiStr

type Item = &'a mut AsciiChar

The type of the elements being iterated over.

type IntoIter = CharsMut<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Ord for AsciiStr

fn cmp(&self, other: &AsciiStr) -> Ordering

This method returns an Ordering between self and other.

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<&AsciiStr> for String

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<[AsciiChar]> for AsciiStr

fn eq(&self, other: &[AsciiChar]) -> 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<[u8]> for AsciiStr

fn eq(&self, other: &[u8]) -> 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<AsciiStr> for [AsciiChar]

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<AsciiStr> for [u8]

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<AsciiStr> for AsciiStr

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<AsciiStr> for str

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<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<String> for &AsciiStr

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 AsciiStr

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<AsciiStr> for AsciiStr

fn partial_cmp(&self, other: &AsciiStr) -> 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 ToOwned for AsciiStr

type Owned = AsciiString

The resulting type after obtaining ownership.

fn to_owned(&self) -> AsciiString

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl Eq for AsciiStr

impl StructuralEq for AsciiStr

impl StructuralPartialEq for AsciiStr