Struct basic_text::TextString[−][src]

#[repr(transparent)]
pub struct TextString(_);

Expand description

A Basic Text encoded, growable string.

This is an owning string similar to String, but ensures the contents are Basic Text rather than just UTF-8. It’s accompanied by a borrowing TextStr, which plays an analogous role to str.

Examples

You can create a TextString from a literal text string with TextString::from:

use basic_text::{text, TextString};

let hello = TextString::from(text!("Hello, world!"));

You can append a &TextStr with the push_text method:

use basic_text::{text, TextString};

let mut hello = TextString::from(text!("Hello, "));

hello.push_text(text!("world!"));

If you have a String containing a Basic Text string, you can create a TextString from it with the from_text method:

use basic_text::{text, TextString};

// a `String`
let sparkle_heart = "💖".to_owned();

// We know this string is valid, so we'll use `unwrap()`.
let sparkle_heart = TextString::from_text(sparkle_heart).unwrap();

assert_eq!(text!("💖"), &sparkle_heart);

If you have a vector of Basic Text bytes, you can create a String from it with the from_text_vec method:

use basic_text::{text, TextString};

// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];

// We know these bytes are valid, so we'll use `unwrap()`.
let sparkle_heart = TextString::from_text_vec(sparkle_heart).unwrap();

assert_eq!(text!("💖"), &sparkle_heart);

Implementations

`impl TextString`[src]

`#[must_use] pub const fn new() -> Self`[src]

Creates a new empty TextString.

`#[must_use] pub fn with_capacity(capacity: usize) -> Self`[src]

Creates a new empty TextString with a particular capacity.

`pub fn from_text_vec(vec: Vec<u8>) -> Result<Self, FromTextError>`[src]

Converts a vector of bytes to a TextString.

`pub fn from_text(s: String) -> Result<Self, FromTextError>`[src]

Converts a String to a TextString.

`#[must_use] pub fn from_text_bytes_lossy(v: &[u8]) -> Cow<'_, TextStr>`[src]

Converts a slice of bytes to Basic Text, including invalid characters.

`#[must_use] pub fn from_text_lossy(v: &str) -> Cow<'_, TextStr>`[src]

Converts a string to Basic Text, including invalid characters.

`#[must_use] pub unsafe fn from_text_vec_unchecked(vec: Vec<u8>) -> Self`[src]

Converts a vector of bytes to a TextString without checking that the string contains valid Basic Text.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid Basic Text. If this constraint is violated, undefined behavior results, as the rest of this crate assumes that &TextStrs are valid Basic Text.

`#[must_use] pub const unsafe fn from_text_unchecked(s: String) -> Self`[src]

Converts a String to a TextString without checking that the string contains valid Basic Text.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid Basic Text. If this constraint is violated, undefined behavior results, as the rest of this crate assumes that &TextStrs are valid Basic Text.

`#[must_use] pub fn into_string(self) -> String`[src]

Converts a TextString into a String.

`#[must_use] pub fn into_bytes(self) -> Vec<u8>`[src]

Converts a String into a byte vector.

`#[must_use] pub fn as_str(&self) -> &str`[src]

Extracts a UTF-8 string slice containing the entire TextString.

`#[must_use] pub fn as_text(&self) -> &TextStr`[src]

Extracts a Basic Text string slice containing the entire TextString.

`#[must_use] pub fn as_mut_text(&mut self) -> &mut TextStr`[src]

Converts a TextString into a mutable Basic Text string slice.

`pub fn push_text(&mut self, s: &TextStr)`[src]

Appends a given string slice onto the end of this TextString.

But wait, isn’t NFC closed under concatenation? This is true, but Basic Text has additional restrictions, including that strings start with non-combining codepoints, so it is closed under concatenation.

`#[must_use] pub fn capacity(&self) -> usize`[src]

Returns this TextString’s capacity, in bytes.

`pub fn reserve(&mut self, additional: usize)`[src]

Ensures that this TextString’s capacity is at least additional bytes larger than its length.

`pub fn reserve_exact(&mut self, additional: usize)`[src]

Ensures that this TextString’s capacity is additional bytes larger than its length.

`pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>`[src]

Tries to reserve capacity for at least additional more elements to be inserted in the given TextString.

`pub fn try_reserve_exact( &mut self, additional: usize ) -> Result<(), TryReserveError>`[src]

Tries to reserves the minimum capacity for exactly additional more elements to be inserted in the given TextString.

`pub fn shrink_to_fit(&mut self)`[src]

Shrinks the capacity of this TextString to match its length.

`pub fn shrink_to(&mut self, min_capacity: usize)`[src]

Shrinks the capacity of this String with a lower bound.

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

Returns a byte slice of this TextString’s contents.

`pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8>`[src]

Returns a mutable reference to the contents of this TextString.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid Basic Text. If this constraint is violated, it may cause memory unsafety issues with future users of the String, as the rest of this crate assumes that TextStrings are valid Basic Text.

`pub unsafe fn as_mut_string(&mut self) -> &mut String`[src]

Returns a mutable reference to the contents of this TextString.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid Basic Text. If this constraint is violated, it may cause memory unsafety issues with future users of the String, as the rest of this crate assumes that TextStrings are valid Basic Text.

`pub fn len(&self) -> usize`[src]

Returns the length of this TextString, in bytes, not chars or graphemes.

`pub fn is_empty(&self) -> bool`[src]

Returns true if this TextString has a length of zero, and false otherwise.

`pub fn clear(&mut self)`[src]

Truncates this String, removing all contents.

`pub fn into_boxed_str(self) -> Box<str>`[src]

Converts this TextString into a Box<str>.

`pub fn into_boxed_text(self) -> Box<TextStr>`[src]

Converts this TextString into a Box<TextStr>.

Methods from Deref<Target = TextStr>

`pub const fn len(&self) -> usize`[src]

Returns the length of self.

`pub const fn is_empty(&self) -> bool`[src]

Returns true if self has a length of zero bytes.

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

Converts a text string slice to a byte slice.

`pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8]`[src]

Converts a mutable text string slice to a mutable byte slice.

Safety

The caller must ensure that the content of the slice is valid Basic Text before the borrow ends and the underlying TextStr is used.

Use of a TextStr whose contents are not valid Basic Text is undefined behavior.

`pub const fn as_ptr(&self) -> *const u8`[src]

Converts a text string slice to a raw pointer.

`pub fn as_mut_ptr(&mut self) -> *mut u8`[src]

Converts a mutable text string slice to a raw pointer.

`pub fn as_str(&self) -> &str`[src]

Extracts a UTF-8 string slice containing the entire TextStr.

`pub fn split_at(&self, mid: usize) -> (&Self, &Self)`[src]

Divide one text string slice into two at an index.

`pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self)`[src]

Divide one mutable text string slice into two at an index.

`pub fn chars(&self) -> Chars<'_>`[src]

Returns an iterator over the chars of a text string slice.

`pub fn char_indices(&self) -> CharIndices<'_>`[src]

Returns an iterator over the chars of a text string slice, and their positions.

`pub fn bytes(&self) -> Bytes<'_>`[src]

An iterator over the bytes of a text string slice.

`pub fn lines(&self) -> Lines<'_>`[src]

An iterator over the lines of a text string, as text string slices.

TODO: There should be a TextLines which yields &TextStrs.

`pub fn encode_utf16(&self) -> EncodeUtf16<'_>`[src]

Returns an iterator of u16 over the string encoded as Basic Text.

`pub fn contains<'a, P>(&'a self, pat: P) -> bool where P: Pattern<'a>,` [src]

Returns true if the given pattern matches a sub-slice of this text string slice.

Returns false if it does not.

`pub fn starts_with<'a, P>(&'a self, pat: P) -> bool where P: Pattern<'a>,` [src]

Returns true if the given pattern matches a prefix of this text string slice.

Returns false if it does not.

`pub fn ends_with<'a, P>(&'a self, pat: P) -> bool where P: Pattern<'a>, >::Searcher: ReverseSearcher<'a>,` [src]

Returns true if the given pattern matches a suffix of this text string slice.

Returns false if it does not.

`pub fn find<'a, P>(&'a self, pat: P) -> Option<usize> where P: Pattern<'a>,` [src]

Returns the byte index of the first character of this text string slice that matches the pattern.

Returns None if the pattern doesn’t match.

`pub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize> where P: Pattern<'a>, >::Searcher: ReverseSearcher<'a>,` [src]

Returns the byte index for the first character of the rightmost match of the pattern in this text string slice.

Returns None if the pattern doesn’t match.

`pub fn matches<'a, P>(&'a self, pat: P) -> Matches<'a, P> where P: Pattern<'a>,` [src]

An iterator over the disjoint matches of a pattern within the given text string slice.

`pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P> where P: Pattern<'a>, >::Searcher: ReverseSearcher<'a>,` [src]

An iterator over the disjoint matches of a pattern within this text string slice, yielded in reverse order.

TODO: There should be a TextRMatches which yields &TextStrs.

`pub fn match_indices<'a, P>(&'a self, pat: P) -> MatchIndices<'a, P> where P: Pattern<'a>,` [src]

An iterator over the disjoint matches of a pattern within this text string slice as well as the index that the match starts at.

TODO: There should be a TextMatchIndices which yields &TextStrs.

`pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P> where P: Pattern<'a>, >::Searcher: ReverseSearcher<'a>,` [src]

An iterator over the disjoint matches of a pattern within self, yielded in reverse order along with the index of the match.

TODO: There should be a TextRMatchIndices which yields &TextStrs.

`pub fn trim(&self) -> &Self`[src]

Returns a text string slice with leading and trailing whitespace removed.

`pub fn trim_start(&self) -> &Self`[src]

Returns a text string slice with leading whitespace removed.

`pub fn trim_end(&self) -> &Self`[src]

Returns a text string slice with trailing whitespace removed.

`pub fn parse<F>(&self) -> Result<F, <F as FromStr>::Err> where F: FromStr,` [src]

Parses this text string slice into another type.

`pub fn is_ascii(&self) -> bool`[src]

Checks if all characters in this text string are within the ASCII range.

`pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool`[src]

Checks that two text strings are an ASCII case-insensitive match.

`pub fn repeat(&self, n: usize) -> TextString`[src]

Creates a new TextString by repeating a string n times.

`pub fn escape_debug(&self) -> EscapeDebug<'_>`[src]

Return an iterator that escapes each char in self with char::escape_debug.

`pub fn escape_default(&self) -> EscapeDefault<'_>`[src]

Return an iterator that escapes each char in self with char::escape_default.

`pub fn escape_unicode(&self) -> EscapeUnicode<'_>`[src]

Return an iterator that escapes each char in self with char::escape_unicode.

Trait Implementations

`impl Add<&'_ TextStr> for TextString`[src]

`type Output = Self`

The resulting type after applying the + operator.

`fn add(self, other: &TextStr) -> Self::Output`[src]

Performs the + operation. Read more

`impl AddAssign<&'_ TextStr> for TextString`[src]

`fn add_assign(&mut self, other: &TextStr)`[src]

Performs the += operation. Read more

`impl AsMut<TextStr> for TextString`[src]

`fn as_mut(&mut self) -> &mut TextStr`[src]

Performs the conversion.

`impl AsRef<[u8]> for TextString`[src]

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

Performs the conversion.

`impl AsRef<OsStr> for TextString`[src]

`fn as_ref(&self) -> &OsStr`[src]

Performs the conversion.

`impl AsRef<Path> for TextString`[src]

`fn as_ref(&self) -> &Path`[src]

Performs the conversion.

`impl AsRef<TextStr> for TextString`[src]

`fn as_ref(&self) -> &TextStr`[src]

Performs the conversion.

`impl AsRef<TextSubstr> for TextString`[src]

`fn as_ref(&self) -> &TextSubstr`[src]

Performs the conversion.

`impl AsRef<str> for TextString`[src]

`fn as_ref(&self) -> &str`[src]

Performs the conversion.

`impl Borrow<TextStr> for TextString`[src]

`fn borrow(&self) -> &TextStr`[src]

Immutably borrows from an owned value. Read more

`impl BorrowMut<TextStr> for TextString`[src]

`fn borrow_mut(&mut self) -> &mut TextStr`[src]

Mutably borrows from an owned value. Read more

`impl Clone for TextString`[src]

`fn clone(&self) -> Self`[src]

Returns a copy of the value. Read more

`fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from source. Read more

`impl Debug for TextString`[src]

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

Formats the value using the given formatter. Read more

`impl Default for TextString`[src]

`fn default() -> Self`[src]

Returns the “default value” for a type. Read more

`impl Deref for TextString`[src]

`type Target = TextStr`

The resulting type after dereferencing.

`fn deref(&self) -> &Self::Target`[src]

Dereferences the value.

`impl DerefMut for TextString`[src]

`fn deref_mut(&mut self) -> &mut Self::Target`[src]

Mutably dereferences the value.

`impl<'a> Extend<&'a TextStr> for TextString`[src]

`fn extend<I: IntoIterator<Item = &'a TextStr>>(&mut self, iter: I)`[src]

Extends a collection with the contents of an iterator. Read more

`fn extend_one(&mut self, s: &'a TextStr)`[src]

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

Extends a collection with exactly one element.

`fn extend_reserve(&mut self, additional: usize)`[src]

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

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

`impl<'a> Extend<Cow<'a, TextStr>> for TextString`[src]

`fn extend<I: IntoIterator<Item = Cow<'a, TextStr>>>(&mut self, iter: I)`[src]

Extends a collection with the contents of an iterator. Read more

`fn extend_one(&mut self, s: Cow<'a, TextStr>)`[src]

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

Extends a collection with exactly one element.

`fn extend_reserve(&mut self, additional: usize)`[src]

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

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

`impl Extend<TextString> for TextString`[src]

`fn extend<I: IntoIterator<Item = TextString>>(&mut self, iter: I)`[src]

Extends a collection with the contents of an iterator. Read more

`fn extend_one(&mut self, s: TextString)`[src]

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

Extends a collection with exactly one element.

`fn extend_reserve(&mut self, additional: usize)`[src]

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

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

`impl From<&'_ TextStr> for TextString`[src]

`fn from(s: &TextStr) -> Self`[src]

Performs the conversion.

`impl From<&'_ TextString> for TextString`[src]

`fn from(s: &Self) -> Self`[src]

Performs the conversion.

`impl From<&'_ mut TextStr> for TextString`[src]

`fn from(s: &mut TextStr) -> Self`[src]

Performs the conversion.

`impl From<Box<TextStr, Global>> for TextString`[src]

`fn from(s: Box<TextStr>) -> Self`[src]

Performs the conversion.

`impl Hash for TextString`[src]

`fn hash<H: Hasher>(&self, state: &mut H)`[src]

Feeds this value into the given Hasher. Read more

`fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,` 1.3.0 [src]

Feeds a slice of this type into the given Hasher. Read more

`impl Index<Range<usize>> for TextString`[src]

`type Output = TextSubstr`

The returned type after indexing.

`fn index(&self, index: Range<usize>) -> &Self::Output`[src]

Performs the indexing (container[index]) operation. Read more

`impl Index<RangeFrom<usize>> for TextString`[src]

`type Output = TextSubstr`

The returned type after indexing.

`fn index(&self, index: RangeFrom<usize>) -> &Self::Output`[src]

Performs the indexing (container[index]) operation. Read more

`impl Index<RangeTo<usize>> for TextString`[src]

`type Output = TextSubstr`

The returned type after indexing.