Struct basic_text::TextString
source · pub struct TextString(/* private fields */);
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§
source§impl TextString
impl TextString
sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Creates a new empty TextString
with a particular capacity.
sourcepub fn from_text_vec(vec: Vec<u8>) -> Result<Self, FromTextError>
pub fn from_text_vec(vec: Vec<u8>) -> Result<Self, FromTextError>
Converts a vector of bytes to a TextString
.
sourcepub fn from_text(s: String) -> Result<Self, FromTextError>
pub fn from_text(s: String) -> Result<Self, FromTextError>
Converts a String
to a TextString
.
sourcepub fn from_text_bytes_lossy(v: &[u8]) -> Cow<'_, TextStr>
pub fn from_text_bytes_lossy(v: &[u8]) -> Cow<'_, TextStr>
Converts a slice of bytes to Basic Text, including invalid characters.
sourcepub fn from_text_lossy(v: &str) -> Cow<'_, TextStr>
pub fn from_text_lossy(v: &str) -> Cow<'_, TextStr>
Converts a string to Basic Text, including invalid characters.
sourcepub unsafe fn from_text_vec_unchecked(vec: Vec<u8>) -> Self
pub unsafe fn from_text_vec_unchecked(vec: Vec<u8>) -> Self
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 &TextStr
s
are valid Basic Text.
sourcepub const unsafe fn from_text_unchecked(s: String) -> Self
pub const unsafe fn from_text_unchecked(s: String) -> Self
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 &TextStr
s
are valid Basic Text.
sourcepub fn into_string(self) -> String
pub fn into_string(self) -> String
Converts a TextString
into a String
.
sourcepub fn into_bytes(self) -> Vec<u8>
pub fn into_bytes(self) -> Vec<u8>
Converts a String into a byte vector.
sourcepub fn as_text(&self) -> &TextStr
pub fn as_text(&self) -> &TextStr
Extracts a Basic Text string slice containing the entire TextString
.
sourcepub fn as_mut_text(&mut self) -> &mut TextStr
pub fn as_mut_text(&mut self) -> &mut TextStr
Converts a TextString
into a mutable Basic Text string slice.
sourcepub fn push_text(&mut self, s: &TextStr)
pub fn push_text(&mut self, s: &TextStr)
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.
sourcepub fn reserve(&mut self, additional: usize)
pub fn reserve(&mut self, additional: usize)
Ensures that this TextString
’s capacity is at least additional
bytes larger than its length.
sourcepub fn reserve_exact(&mut self, additional: usize)
pub fn reserve_exact(&mut self, additional: usize)
Ensures that this TextString
’s capacity is additional
bytes larger
than its length.
sourcepub fn shrink_to_fit(&mut self)
pub fn shrink_to_fit(&mut self)
Shrinks the capacity of this TextString
to match its length.
sourcepub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8>
pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8>
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 TextString
s are valid Basic Text.
sourcepub unsafe fn as_mut_string(&mut self) -> &mut String
pub unsafe fn as_mut_string(&mut self) -> &mut String
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 TextString
s are valid Basic Text.
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the length of this TextString
, in bytes, not char
s or
graphemes.
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true
if this TextString
has a length of zero, and false
otherwise.
sourcepub fn into_boxed_str(self) -> Box<str>
pub fn into_boxed_str(self) -> Box<str>
Converts this TextString
into a Box<str>
.
sourcepub fn into_boxed_text(self) -> Box<TextStr>
pub fn into_boxed_text(self) -> Box<TextStr>
Converts this TextString
into a Box<TextStr>
.
Methods from Deref<Target = TextStr>§
sourcepub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] ⓘ
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 TextStr
is used.
Use of a TextStr
whose contents are not valid Basic Text is undefined
behavior.
sourcepub fn as_mut_ptr(&mut self) -> *mut u8
pub fn as_mut_ptr(&mut self) -> *mut u8
Converts a mutable text string slice to a raw pointer.
sourcepub fn split_at(&self, mid: usize) -> (&Self, &Self)
pub fn split_at(&self, mid: usize) -> (&Self, &Self)
Divide one text string slice into two at an index.
sourcepub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self)
pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self)
Divide one mutable text string slice into two at an index.
sourcepub fn char_indices(&self) -> CharIndices<'_>
pub fn char_indices(&self) -> CharIndices<'_>
Returns an iterator over the char
s of a text string slice, and their
positions.
sourcepub fn lines(&self) -> Lines<'_>
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 &TextStr
s.
sourcepub fn encode_utf16(&self) -> EncodeUtf16<'_>
pub fn encode_utf16(&self) -> EncodeUtf16<'_>
Returns an iterator of u16
over the string encoded as Basic Text.
sourcepub fn contains<'a, P>(&'a self, pat: P) -> boolwhere
P: Pattern<'a>,
pub fn contains<'a, P>(&'a self, pat: P) -> boolwhere
P: Pattern<'a>,
Returns true
if the given pattern matches a sub-slice of this
text string slice.
Returns false
if it does not.
sourcepub fn starts_with<'a, P>(&'a self, pat: P) -> boolwhere
P: Pattern<'a>,
pub fn starts_with<'a, P>(&'a self, pat: P) -> boolwhere
P: Pattern<'a>,
Returns true
if the given pattern matches a prefix of this
text string slice.
Returns false
if it does not.
sourcepub fn ends_with<'a, P>(&'a self, pat: P) -> bool
pub fn ends_with<'a, P>(&'a self, pat: P) -> bool
Returns true
if the given pattern matches a suffix of this
text string slice.
Returns false
if it does not.
sourcepub fn find<'a, P>(&'a self, pat: P) -> Option<usize>where
P: Pattern<'a>,
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.
sourcepub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize>
pub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize>
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.
sourcepub fn matches<'a, P>(&'a self, pat: P) -> Matches<'a, P>where
P: Pattern<'a>,
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.
sourcepub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>
pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>
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 &TextStr
s.
sourcepub fn match_indices<'a, P>(&'a self, pat: P) -> MatchIndices<'a, P>where
P: Pattern<'a>,
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 &TextStr
s.
sourcepub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>
pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>
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 &TextStr
s.
sourcepub fn trim(&self) -> &Self
pub fn trim(&self) -> &Self
Returns a text string slice with leading and trailing whitespace removed.
sourcepub fn trim_start(&self) -> &Self
pub fn trim_start(&self) -> &Self
Returns a text string slice with leading whitespace removed.
sourcepub fn parse<F>(&self) -> Result<F, <F as FromStr>::Err>where
F: FromStr,
pub fn parse<F>(&self) -> Result<F, <F as FromStr>::Err>where
F: FromStr,
Parses this text string slice into another type.
sourcepub fn is_ascii(&self) -> bool
pub fn is_ascii(&self) -> bool
Checks if all characters in this text string are within the ASCII range.
sourcepub fn eq_ignore_ascii_case(&self, other: &Self) -> bool
pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool
Checks that two text strings are an ASCII case-insensitive match.
sourcepub fn repeat(&self, n: usize) -> TextString
pub fn repeat(&self, n: usize) -> TextString
Creates a new TextString
by repeating a string n
times.
sourcepub fn escape_debug(&self) -> EscapeDebug<'_>
pub fn escape_debug(&self) -> EscapeDebug<'_>
Return an iterator that escapes each char
in self
with
char::escape_debug
.
sourcepub fn escape_default(&self) -> EscapeDefault<'_>
pub fn escape_default(&self) -> EscapeDefault<'_>
Return an iterator that escapes each char
in self
with
char::escape_default
.
sourcepub fn escape_unicode(&self) -> EscapeUnicode<'_>
pub fn escape_unicode(&self) -> EscapeUnicode<'_>
Return an iterator that escapes each char
in self
with
char::escape_unicode
.
Trait Implementations§
source§impl Add<&TextStr> for TextString
impl Add<&TextStr> for TextString
source§impl AddAssign<&TextStr> for TextString
impl AddAssign<&TextStr> for TextString
source§fn add_assign(&mut self, other: &TextStr)
fn add_assign(&mut self, other: &TextStr)
+=
operation. Read moresource§impl AsMut<TextStr> for TextString
impl AsMut<TextStr> for TextString
source§impl AsRef<[u8]> for TextString
impl AsRef<[u8]> for TextString
source§impl AsRef<OsStr> for TextString
impl AsRef<OsStr> for TextString
source§impl AsRef<Path> for TextString
impl AsRef<Path> for TextString
source§impl AsRef<TextStr> for TextString
impl AsRef<TextStr> for TextString
source§impl AsRef<TextSubstr> for TextString
impl AsRef<TextSubstr> for TextString
source§fn as_ref(&self) -> &TextSubstr
fn as_ref(&self) -> &TextSubstr
source§impl AsRef<str> for TextString
impl AsRef<str> for TextString
source§impl Borrow<TextStr> for TextString
impl Borrow<TextStr> for TextString
source§impl BorrowMut<TextStr> for TextString
impl BorrowMut<TextStr> for TextString
source§fn borrow_mut(&mut self) -> &mut TextStr
fn borrow_mut(&mut self) -> &mut TextStr
source§impl Clone for TextString
impl Clone for TextString
source§impl Debug for TextString
impl Debug for TextString
source§impl Default for TextString
impl Default for TextString
source§fn default() -> TextString
fn default() -> TextString
source§impl Deref for TextString
impl Deref for TextString
source§impl DerefMut for TextString
impl DerefMut for TextString
source§impl<'a> Extend<&'a TextStr> for TextString
impl<'a> Extend<&'a TextStr> for TextString
source§fn extend<I: IntoIterator<Item = &'a TextStr>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = &'a TextStr>>(&mut self, iter: I)
source§fn extend_one(&mut self, s: &'a TextStr)
fn extend_one(&mut self, s: &'a TextStr)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl<'a> Extend<Cow<'a, TextStr>> for TextString
impl<'a> Extend<Cow<'a, TextStr>> for TextString
source§fn extend<I: IntoIterator<Item = Cow<'a, TextStr>>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = Cow<'a, TextStr>>>(&mut self, iter: I)
source§fn extend_one(&mut self, s: Cow<'a, TextStr>)
fn extend_one(&mut self, s: Cow<'a, TextStr>)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl Extend<TextString> for TextString
impl Extend<TextString> for TextString
source§fn extend<I: IntoIterator<Item = TextString>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = TextString>>(&mut self, iter: I)
source§fn extend_one(&mut self, s: TextString)
fn extend_one(&mut self, s: TextString)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl From<&TextStr> for TextString
impl From<&TextStr> for TextString
source§impl From<&TextString> for TextString
impl From<&TextString> for TextString
source§impl From<&mut TextStr> for TextString
impl From<&mut TextStr> for TextString
source§impl From<TextString> for Box<TextStr>
impl From<TextString> for Box<TextStr>
source§fn from(s: TextString) -> Self
fn from(s: TextString) -> Self
source§impl Hash for TextString
impl Hash for TextString
source§impl<'a> PartialEq<&'a TextStr> for TextString
impl<'a> PartialEq<&'a TextStr> for TextString
source§impl<'a> PartialEq<&'a TextSubstr> for TextString
impl<'a> PartialEq<&'a TextSubstr> for TextString
source§fn eq(&self, other: &&'a TextSubstr) -> bool
fn eq(&self, other: &&'a TextSubstr) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<'a> PartialEq<&'a str> for TextString
impl<'a> PartialEq<&'a str> for TextString
source§impl<'a> PartialEq<Cow<'a, TextStr>> for TextString
impl<'a> PartialEq<Cow<'a, TextStr>> for TextString
source§impl<'a> PartialEq<Cow<'a, TextSubstr>> for TextString
impl<'a> PartialEq<Cow<'a, TextSubstr>> for TextString
source§impl<'a> PartialEq<Cow<'a, str>> for TextString
impl<'a> PartialEq<Cow<'a, str>> for TextString
source§impl PartialEq<String> for TextString
impl PartialEq<String> for TextString
source§impl PartialEq<TextStr> for TextString
impl PartialEq<TextStr> for TextString
source§impl<'a> PartialEq<TextString> for &'a TextStr
impl<'a> PartialEq<TextString> for &'a TextStr
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<'a> PartialEq<TextString> for &'a TextSubstr
impl<'a> PartialEq<TextString> for &'a TextSubstr
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<'a> PartialEq<TextString> for &'a str
impl<'a> PartialEq<TextString> for &'a str
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<'a> PartialEq<TextString> for Cow<'a, TextStr>
impl<'a> PartialEq<TextString> for Cow<'a, TextStr>
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<'a> PartialEq<TextString> for Cow<'a, TextSubstr>
impl<'a> PartialEq<TextString> for Cow<'a, TextSubstr>
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<'a> PartialEq<TextString> for Cow<'a, str>
impl<'a> PartialEq<TextString> for Cow<'a, str>
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<TextString> for String
impl PartialEq<TextString> for String
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<TextString> for TextStr
impl PartialEq<TextString> for TextStr
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<TextString> for TextSubstr
impl PartialEq<TextString> for TextSubstr
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<TextString> for str
impl PartialEq<TextString> for str
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<TextSubstr> for TextString
impl PartialEq<TextSubstr> for TextString
source§fn eq(&self, other: &TextSubstr) -> bool
fn eq(&self, other: &TextSubstr) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialEq<str> for TextString
impl PartialEq<str> for TextString
source§impl PartialEq for TextString
impl PartialEq for TextString
source§fn eq(&self, other: &TextString) -> bool
fn eq(&self, other: &TextString) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PartialOrd for TextString
impl PartialOrd for TextString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more