Struct basic_text::TextSubstring

pub struct TextSubstring(/* private fields */);

A substring of a Basic Text string or stream.

This does not enforce the Basic Text requirements on the beginning or end of a stream, so it can represent substrings of Basic Text.

This is an owning string similar to TextString, but doesn’t enforce the starting and ending requirements, so it can represent substrings. It’s accompanied by a borrowing TextSubstr, which plays an analogous role to TextStr.

Examples

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

use basic_text::{text_substr, TextSubstring};

let hello = TextSubstring::from(text_substr!("Hello, world!"));

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

use basic_text::{text_substr, TextSubstring};

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

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

assert_eq!(text_substr!("💖"), &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_substr, TextSubstring};

// 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 = TextSubstring::from_text_vec(sparkle_heart).unwrap();

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

Implementations

impl TextSubstring

pub const fn new() -> Self

Creates a new empty TextSubstring.

pub fn with_capacity(capacity: usize) -> Self

Creates a new empty TextSubstring with a particular capacity.

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

Converts a vector of bytes to a TextSubstring.

pub fn from_text(s: String) -> Result<Self, FromTextError>

Converts a String to a TextSubstring.

pub fn from_text_bytes_lossy(v: &[u8]) -> Cow<'_, TextSubstr>

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

pub fn from_text_lossy(v: &str) -> Cow<'_, TextSubstr>

Converts a string to Basic Text, including invalid characters.

pub unsafe fn from_text_vec_unchecked(vec: Vec<u8>) -> Self

Converts a vector of bytes to a TextSubstring 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 &TextSubstrs are valid Basic Text.

pub const unsafe fn from_text_unchecked(s: String) -> Self

Converts a String to a TextSubstring 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 &TextSubstrs are valid Basic Text.

pub fn into_string(self) -> String

Converts a TextSubstring into a String.

pub fn into_bytes(self) -> Vec<u8>

Converts a String into a byte vector.

pub fn as_str(&self) -> &str

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

pub fn as_text(&self) -> &TextSubstr

Extracts a Basic Text string slice containing the entire TextSubstring.

pub fn as_mut_text(&mut self) -> &mut TextSubstr

Converts a TextSubstring into a mutable Basic Text substring slice.

pub fn capacity(&self) -> usize

Returns this TextSubstring’s capacity, in bytes.

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

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

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

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

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of this TextSubstring to match its length.

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

Returns a byte slice of this TextSubstring’s contents.

pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8>

Returns a mutable reference to the contents of this TextSubstring.

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 TextSubstrings are valid Basic Text.

pub unsafe fn as_mut_string(&mut self) -> &mut String

Returns a mutable reference to the contents of this TextSubstring.

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 TextSubstrings are valid Basic Text.

pub fn len(&self) -> usize

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

pub fn is_empty(&self) -> bool

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

pub fn clear(&mut self)

Truncates this String, removing all contents.

pub fn into_boxed_str(self) -> Box<str>

Converts this TextSubstring into a Box<str>.

pub fn into_boxed_text(self) -> Box<TextSubstr>

Converts this TextSubstring into a Box<TextSubstr>.

Methods from Deref<Target = TextSubstr>

pub fn len(&self) -> usize

Returns the length of self.

pub fn is_empty(&self) -> bool

Returns true if self has a length of zero bytes.

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

Converts a text string slice to a byte slice.

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

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 TextSubstr is used.

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

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

Converts a text string slice to a raw pointer.

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

Converts a mutable text string slice to a raw pointer.

pub fn as_str(&self) -> &str

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

pub fn split_at(&self, mid: usize) -> (&Self, &Self)

Divide one text string slice into two at an index.

pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self)

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

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

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

pub fn char_indices(&self) -> CharIndices<'_>

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

pub fn bytes(&self) -> Bytes<'_>

An iterator over the bytes of a text string slice.

pub fn lines(&self) -> Lines<'_>

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

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

pub fn encode_utf16(&self) -> EncodeUtf16<'_>

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>,

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>,

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>, <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,

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>,

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>, <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,

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>,

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

TODO: There should be a TextMatches which yields &TextSubstrs.

pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>

where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,

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 &TextSubstrs.

pub fn match_indices<'a, P>(&'a self, pat: P) -> MatchIndices<'a, P>

where P: Pattern<'a>,

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 &TextSubstrs.

pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>

where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,

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 &TextSubstrs.

pub fn trim(&self) -> &Self

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

pub fn trim_start(&self) -> &Self

Returns a text string slice with leading whitespace removed.

pub fn trim_end(&self) -> &Self

Returns a text string slice with trailing whitespace removed.

pub fn parse<F>(&self) -> Result<F, <F as FromStr>::Err>

where F: FromStr,

Parses this text string slice into another type.

pub fn is_ascii(&self) -> bool

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

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

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

pub fn repeat(&self, n: usize) -> TextSubstring

Creates a new TextSubstring by repeating a string n times.

pub fn escape_debug(&self) -> EscapeDebug<'_>

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

pub fn escape_default(&self) -> EscapeDefault<'_>

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

pub fn escape_unicode(&self) -> EscapeUnicode<'_>

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

Trait Implementations

impl AsMut<TextSubstr> for TextSubstring

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

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

impl AsRef<[u8]> for TextSubstring

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

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

impl AsRef<OsStr> for TextSubstring

fn as_ref(&self) -> &OsStr

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

impl AsRef<Path> for TextSubstring

fn as_ref(&self) -> &Path

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

impl AsRef<TextSubstr> for TextSubstring

fn as_ref(&self) -> &TextSubstr

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

impl AsRef<str> for TextSubstring

fn as_ref(&self) -> &str

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

impl Borrow<TextSubstr> for TextSubstring

fn borrow(&self) -> &TextSubstr

Immutably borrows from an owned value.

impl BorrowMut<TextSubstr> for TextSubstring

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

Mutably borrows from an owned value.

impl Clone for TextSubstring

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TextSubstring

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

Formats the value using the given formatter.

impl Default for TextSubstring

fn default() -> TextSubstring

Returns the “default value” for a type.

impl Deref for TextSubstring

type Target = TextSubstr

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for TextSubstring

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl From<&TextSubstr> for TextSubstring

fn from(s: &TextSubstr) -> Self

Converts to this type from the input type.

impl From<&TextSubstring> for TextSubstring

fn from(s: &Self) -> Self

Converts to this type from the input type.

impl From<&mut TextSubstr> for TextSubstring

fn from(s: &mut TextSubstr) -> Self

Converts to this type from the input type.

impl From<Box<TextSubstr>> for TextSubstring

fn from(s: Box<TextSubstr>) -> Self

Converts to this type from the input type.

impl From<TextSubstring> for Box<TextSubstr>

fn from(s: TextSubstring) -> Self

Converts to this type from the input type.

impl Hash for TextSubstring

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Index<Range<usize>> for TextSubstring

type Output = TextSubstr

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for TextSubstring

type Output = TextSubstr

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for TextSubstring

type Output = TextSubstr

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'a> PartialEq<&'a TextStr> for TextSubstring

fn eq(&self, other: &&'a TextStr) -> 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<'a> PartialEq<&'a TextSubstr> for TextSubstring

fn eq(&self, other: &&'a TextSubstr) -> 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<'a> PartialEq<&'a str> for TextSubstring

fn eq(&self, other: &&'a 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<'a> PartialEq<Cow<'a, TextStr>> for TextSubstring

fn eq(&self, other: &Cow<'a, TextStr>) -> 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<'a> PartialEq<Cow<'a, TextSubstr>> for TextSubstring

fn eq(&self, other: &Cow<'a, TextSubstr>) -> 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<'a> PartialEq<Cow<'a, str>> for TextSubstring

fn eq(&self, other: &Cow<'a, 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<String> for TextSubstring

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<TextStr> for TextSubstring

fn eq(&self, other: &TextStr) -> 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<TextSubstr> for TextSubstring

fn eq(&self, other: &TextSubstr) -> 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<'a> PartialEq<TextSubstring> for &'a TextStr

fn eq(&self, other: &TextSubstring) -> 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<'a> PartialEq<TextSubstring> for &'a TextSubstr

fn eq(&self, other: &TextSubstring) -> 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<'a> PartialEq<TextSubstring> for &'a str

fn eq(&self, other: &TextSubstring) -> 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<'a> PartialEq<TextSubstring> for Cow<'a, TextStr>

fn eq(&self, other: &TextSubstring) -> 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<'a> PartialEq<TextSubstring> for Cow<'a, TextSubstr>

fn eq(&self, other: &TextSubstring) -> 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<'a> PartialEq<TextSubstring> for Cow<'a, str>

fn eq(&self, other: &TextSubstring) -> 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<TextSubstring> for String

fn eq(&self, other: &TextSubstring) -> 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<TextSubstring> for TextStr

fn eq(&self, other: &TextSubstring) -> 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<TextSubstring> for TextSubstr

fn eq(&self, other: &TextSubstring) -> 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<TextSubstring> for str

fn eq(&self, other: &TextSubstring) -> 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 TextSubstring

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

fn eq(&self, other: &TextSubstring) -> 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 for TextSubstring

fn partial_cmp(&self, other: &Self) -> 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 Eq for TextSubstring

impl StructuralPartialEq for TextSubstring