Struct ascii::AsciiString
source · [−]#[repr(transparent)]pub struct AsciiString { /* private fields */ }
Expand description
A growable string stored as an ASCII encoded buffer.
Implementations
sourceimpl AsciiString
impl AsciiString
sourcepub const fn new() -> Self
pub const fn new() -> Self
Creates a new, empty ASCII string buffer without allocating.
Examples
let mut s = AsciiString::new();
sourcepub fn with_capacity(capacity: usize) -> Self
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);
sourcepub unsafe fn from_raw_parts(
buf: *mut AsciiChar,
length: usize,
capacity: usize
) -> Self
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 tocapacity
.capacity
needs to be the correct value.buf
must havelength
valid ascii elements and contain a total ofcapacity
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);
}
sourcepub unsafe fn from_ascii_unchecked<B>(bytes: B) -> Selfwhere
B: Into<Vec<u8>>,
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 AsciiString
s are
ASCII encoded.
sourcepub fn from_ascii<B>(bytes: B) -> Result<AsciiString, FromAsciiError<B>>where
B: Into<Vec<u8>> + AsRef<[u8]>,
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(), "Ŋ");
sourcepub fn push_str(&mut self, string: &AsciiStr)
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());
sourcepub fn insert_str(&mut self, idx: usize, string: &AsciiStr)
pub fn insert_str(&mut self, idx: usize, string: &AsciiStr)
sourcepub fn capacity(&self) -> usize
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);
sourcepub fn reserve(&mut self, additional: usize)
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);
sourcepub fn reserve_exact(&mut self, additional: usize)
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);
sourcepub fn shrink_to_fit(&mut self)
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);
sourcepub fn push(&mut self, ch: AsciiChar)
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");
sourcepub fn pop(&mut self) -> Option<AsciiChar>
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);
sourcepub fn remove(&mut self, idx: usize) -> AsciiChar
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');
sourcepub fn insert(&mut self, idx: usize, ch: AsciiChar)
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");
sourcepub fn len(&self) -> usize
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);
sourcepub fn is_empty(&self) -> bool
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());
sourcepub fn clear(&mut self)
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());
sourcepub fn into_boxed_ascii_str(self) -> Box<AsciiStr>
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>
sourcepub fn as_bytes(&self) -> &[u8]ⓘNotable traits for &[u8]impl Read for &[u8]impl Write for &mut [u8]
pub fn as_bytes(&self) -> &[u8]ⓘNotable traits for &[u8]impl Read for &[u8]impl Write for &mut [u8]
Converts &self
into a byte slice.
sourcepub fn as_mut_slice(&mut self) -> &mut [AsciiChar]
pub fn as_mut_slice(&mut self) -> &mut [AsciiChar]
Returns the entire string as mutable slice of AsciiChar
s.
sourcepub fn as_ptr(&self) -> *const AsciiChar
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.
sourcepub fn as_mut_ptr(&mut self) -> *mut AsciiChar
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.
sourcepub fn to_ascii_string(&self) -> AsciiString
pub fn to_ascii_string(&self) -> AsciiString
Copies the content of this AsciiStr
into an owned AsciiString
.
sourcepub fn len(&self) -> usize
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);
sourcepub fn is_empty(&self) -> bool
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());
sourcepub fn chars(&self) -> Chars<'_>ⓘNotable traits for Chars<'a>impl<'a> Iterator for Chars<'a> type Item = AsciiChar;
pub fn chars(&self) -> Chars<'_>ⓘNotable traits for Chars<'a>impl<'a> Iterator for Chars<'a> type Item = AsciiChar;
Returns an iterator over the characters of the AsciiStr
.
sourcepub fn chars_mut(&mut self) -> CharsMut<'_>ⓘNotable traits for CharsMut<'a>impl<'a> Iterator for CharsMut<'a> type Item = &'a mut AsciiChar;
pub fn chars_mut(&mut self) -> CharsMut<'_>ⓘNotable traits for CharsMut<'a>impl<'a> Iterator for CharsMut<'a> type Item = &'a mut AsciiChar;
Returns an iterator over the characters of the AsciiStr
which allows you to modify the
value of each AsciiChar
.
sourcepub fn split(&self, on: AsciiChar) -> impl DoubleEndedIterator<Item = &AsciiStr>
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"]);
sourcepub fn lines(&self) -> impl DoubleEndedIterator<Item = &AsciiStr>
pub fn lines(&self) -> impl DoubleEndedIterator<Item = &AsciiStr>
Returns an iterator over the lines of the AsciiStr
, which are themselves AsciiStr
s.
Lines are ended with either LineFeed
(\n
), or CarriageReturn
then LineFeed
(\r\n
).
The final line ending is optional.
sourcepub fn trim(&self) -> &Self
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());
sourcepub fn trim_start(&self) -> &Self
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());
sourcepub fn trim_end(&self) -> &Self
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());
sourcepub fn eq_ignore_ascii_case(&self, other: &Self) -> bool
pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool
Compares two strings case-insensitively.
sourcepub fn make_ascii_uppercase(&mut self)
pub fn make_ascii_uppercase(&mut self)
Replaces lowercase letters with their uppercase equivalent.
sourcepub fn make_ascii_lowercase(&mut self)
pub fn make_ascii_lowercase(&mut self)
Replaces uppercase letters with their lowercase equivalent.
sourcepub fn to_ascii_uppercase(&self) -> AsciiString
pub fn to_ascii_uppercase(&self) -> AsciiString
Returns a copy of this string where letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’.
sourcepub fn to_ascii_lowercase(&self) -> AsciiString
pub fn to_ascii_lowercase(&self) -> AsciiString
Returns a copy of this string where letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’.
Trait Implementations
sourceimpl<'a> Add<&'a AsciiStr> for AsciiString
impl<'a> Add<&'a AsciiStr> for AsciiString
type Output = AsciiString
type Output = AsciiString
+
operator.sourcefn add(self, other: &AsciiStr) -> AsciiString
fn add(self, other: &AsciiStr) -> AsciiString
+
operation. Read moresourceimpl<'a> AddAssign<&'a AsciiStr> for AsciiString
impl<'a> AddAssign<&'a AsciiStr> for AsciiString
sourcefn add_assign(&mut self, other: &AsciiStr)
fn add_assign(&mut self, other: &AsciiStr)
+=
operation. Read moresourceimpl AsMut<[AsciiChar]> for AsciiString
impl AsMut<[AsciiChar]> for AsciiString
sourceimpl AsMut<AsciiStr> for AsciiString
impl AsMut<AsciiStr> for AsciiString
sourceimpl AsRef<[AsciiChar]> for AsciiString
impl AsRef<[AsciiChar]> for AsciiString
sourceimpl AsRef<[u8]> for AsciiString
impl AsRef<[u8]> for AsciiString
sourceimpl AsRef<AsciiStr> for AsciiString
impl AsRef<AsciiStr> for AsciiString
sourceimpl AsRef<str> for AsciiString
impl AsRef<str> for AsciiString
sourceimpl Borrow<AsciiStr> for AsciiString
impl Borrow<AsciiStr> for AsciiString
sourceimpl BorrowMut<AsciiStr> for AsciiString
impl BorrowMut<AsciiStr> for AsciiString
sourcefn borrow_mut(&mut self) -> &mut AsciiStr
fn borrow_mut(&mut self) -> &mut AsciiStr
sourceimpl Clone for AsciiString
impl Clone for AsciiString
sourcefn clone(&self) -> AsciiString
fn clone(&self) -> AsciiString
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresourceimpl Debug for AsciiString
impl Debug for AsciiString
sourceimpl Default for AsciiString
impl Default for AsciiString
sourcefn default() -> AsciiString
fn default() -> AsciiString
sourceimpl Deref for AsciiString
impl Deref for AsciiString
sourceimpl DerefMut for AsciiString
impl DerefMut for AsciiString
sourceimpl Display for AsciiString
impl Display for AsciiString
sourceimpl<A: AsRef<AsciiStr>> Extend<A> for AsciiString
impl<A: AsRef<AsciiStr>> Extend<A> for AsciiString
sourcefn extend<I: IntoIterator<Item = A>>(&mut self, iterable: I)
fn extend<I: IntoIterator<Item = A>>(&mut self, iterable: I)
sourcefn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)sourcefn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)sourceimpl<'a> From<&'a [AsciiChar]> for AsciiString
impl<'a> From<&'a [AsciiChar]> for AsciiString
sourcefn from(s: &'a [AsciiChar]) -> AsciiString
fn from(s: &'a [AsciiChar]) -> AsciiString
sourceimpl<'a> From<&'a AsciiStr> for AsciiString
impl<'a> From<&'a AsciiStr> for AsciiString
sourceimpl From<AsciiChar> for AsciiString
impl From<AsciiChar> for AsciiString
sourceimpl From<AsciiString> for Arc<AsciiStr>
impl From<AsciiString> for Arc<AsciiStr>
sourcefn from(s: AsciiString) -> Arc<AsciiStr>
fn from(s: AsciiString) -> Arc<AsciiStr>
sourceimpl From<AsciiString> for Box<AsciiStr>
impl From<AsciiString> for Box<AsciiStr>
sourcefn from(string: AsciiString) -> Self
fn from(string: AsciiString) -> Self
sourceimpl From<AsciiString> for Cow<'static, AsciiStr>
impl From<AsciiString> for Cow<'static, AsciiStr>
sourcefn from(string: AsciiString) -> Cow<'static, AsciiStr>
fn from(string: AsciiString) -> Cow<'static, AsciiStr>
sourceimpl From<AsciiString> for Rc<AsciiStr>
impl From<AsciiString> for Rc<AsciiStr>
sourcefn from(s: AsciiString) -> Rc<AsciiStr>
fn from(s: AsciiString) -> Rc<AsciiStr>
sourceimpl From<AsciiString> for String
impl From<AsciiString> for String
sourcefn from(s: AsciiString) -> String
fn from(s: AsciiString) -> String
sourceimpl From<AsciiString> for Vec<AsciiChar>
impl From<AsciiString> for Vec<AsciiChar>
sourcefn from(s: AsciiString) -> Vec<AsciiChar>
fn from(s: AsciiString) -> Vec<AsciiChar>
sourceimpl From<AsciiString> for Vec<u8>
impl From<AsciiString> for Vec<u8>
sourcefn from(s: AsciiString) -> Vec<u8>
fn from(s: AsciiString) -> Vec<u8>
sourceimpl<'a> From<Cow<'a, AsciiStr>> for AsciiString
impl<'a> From<Cow<'a, AsciiStr>> for AsciiString
sourcefn from(cow: Cow<'a, AsciiStr>) -> AsciiString
fn from(cow: Cow<'a, AsciiStr>) -> AsciiString
sourceimpl<A: AsRef<AsciiStr>> FromIterator<A> for AsciiString
impl<A: AsRef<AsciiStr>> FromIterator<A> for AsciiString
sourcefn from_iter<I: IntoIterator<Item = A>>(iter: I) -> AsciiString
fn from_iter<I: IntoIterator<Item = A>>(iter: I) -> AsciiString
sourceimpl FromStr for AsciiString
impl FromStr for AsciiString
type Err = AsAsciiStrError
type Err = AsAsciiStrError
sourcefn from_str(s: &str) -> Result<AsciiString, AsAsciiStrError>
fn from_str(s: &str) -> Result<AsciiString, AsAsciiStrError>
s
to return a value of this type. Read moresourceimpl Hash for AsciiString
impl Hash for AsciiString
sourceimpl<T> Index<T> for AsciiStringwhere
AsciiStr: Index<T>,
impl<T> Index<T> for AsciiStringwhere
AsciiStr: Index<T>,
sourceimpl<T> IndexMut<T> for AsciiStringwhere
AsciiStr: IndexMut<T>,
impl<T> IndexMut<T> for AsciiStringwhere
AsciiStr: IndexMut<T>,
sourceimpl IntoAsciiString for AsciiString
impl IntoAsciiString for AsciiString
sourceunsafe fn into_ascii_string_unchecked(self) -> AsciiString
unsafe fn into_ascii_string_unchecked(self) -> AsciiString
AsciiString
without checking for non-ASCII characters. Read moresourcefn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>>
fn into_ascii_string(self) -> Result<AsciiString, FromAsciiError<Self>>
AsciiString
. Read moresourceimpl Ord for AsciiString
impl Ord for AsciiString
sourcefn cmp(&self, other: &AsciiString) -> Ordering
fn cmp(&self, other: &AsciiString) -> Ordering
1.21.0 · sourcefn max(self, other: Self) -> Self
fn max(self, other: Self) -> Self
1.21.0 · sourcefn min(self, other: Self) -> Self
fn min(self, other: Self) -> Self
1.50.0 · sourcefn clamp(self, min: Self, max: Self) -> Selfwhere
Self: PartialOrd<Self>,
fn clamp(self, min: Self, max: Self) -> Selfwhere
Self: PartialOrd<Self>,
sourceimpl PartialEq<AsciiString> for &AsciiStr
impl PartialEq<AsciiString> for &AsciiStr
sourcefn eq(&self, other: &AsciiString) -> bool
fn eq(&self, other: &AsciiString) -> bool
sourceimpl PartialEq<AsciiString> for &str
impl PartialEq<AsciiString> for &str
sourcefn eq(&self, other: &AsciiString) -> bool
fn eq(&self, other: &AsciiString) -> bool
sourceimpl PartialEq<AsciiString> for AsciiString
impl PartialEq<AsciiString> for AsciiString
sourcefn eq(&self, other: &AsciiString) -> bool
fn eq(&self, other: &AsciiString) -> bool
sourceimpl PartialEq<AsciiString> for String
impl PartialEq<AsciiString> for String
sourcefn eq(&self, other: &AsciiString) -> bool
fn eq(&self, other: &AsciiString) -> bool
sourceimpl PartialEq<AsciiString> for str
impl PartialEq<AsciiString> for str
sourcefn eq(&self, other: &AsciiString) -> bool
fn eq(&self, other: &AsciiString) -> bool
sourceimpl PartialOrd<AsciiString> for AsciiString
impl PartialOrd<AsciiString> for AsciiString
sourcefn partial_cmp(&self, other: &AsciiString) -> Option<Ordering>
fn partial_cmp(&self, other: &AsciiString) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresourceimpl Write for AsciiString
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.