Struct Wtf8Buf

pub struct Wtf8Buf { /* private fields */ }

An owned, growable string of well-formed WTF-8 data.

Similar to String, but can additionally contain surrogate code points if they’re not in a surrogate pair.

Implementations

impl Wtf8Buf

pub fn new() -> Wtf8Buf

Create an new, empty WTF-8 string.

pub fn with_capacity(n: usize) -> Wtf8Buf

Create an new, empty WTF-8 string with pre-allocated capacity for n bytes.

pub fn from_string(string: String) -> Wtf8Buf

Create a WTF-8 string from an UTF-8 String.

This takes ownership of the String and does not copy.

Since WTF-8 is a superset of UTF-8, this always succeeds.

pub fn from_str(s: &str) -> Wtf8Buf

Create a WTF-8 string from an UTF-8 &str slice.

This copies the content of the slice.

Since WTF-8 is a superset of UTF-8, this always succeeds.

pub fn from_ill_formed_utf16(v: &[u16]) -> Wtf8Buf

Create a WTF-8 string from a potentially ill-formed UTF-16 slice of 16-bit code units.

This is lossless: calling .to_ill_formed_utf16() on the resulting string will always return the original code units.

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

Reserves capacity for at least additional more bytes to be inserted in the given Wtf8Buf. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new capacity overflows usize.

pub fn capacity(&self) -> usize

Returns the number of bytes that this string buffer can hold without reallocating.

pub fn push_str(&mut self, other: &str)

Append an UTF-8 slice at the end of the string.

pub fn push_wtf8(&mut self, other: &Wtf8)

Append a WTF-8 slice at the end of the string.

This replaces newly paired surrogates at the boundary with a supplementary code point, like concatenating ill-formed UTF-16 strings effectively would.

pub fn push_char(&mut self, c: char)

Append a Unicode scalar value at the end of the string.

pub fn push(&mut self, code_point: CodePoint)

Append a code point at the end of the string.

This replaces newly paired surrogates at the boundary with a supplementary code point, like concatenating ill-formed UTF-16 strings effectively would.

pub fn truncate(&mut self, new_len: usize)

Shortens a string to the specified length.

Failure

Fails if new_len > current length, or if new_len is not a code point boundary.

pub fn clear(&mut self)

Clear the WTF-8 vector, removing all contents.

pub fn into_string(self) -> Result<String, Wtf8Buf>

Consume the WTF-8 string and try to convert it to UTF-8.

This does not copy the data.

If the contents are not well-formed UTF-8 (that is, if the string contains surrogates), the original WTF-8 string is returned instead.

pub fn into_string_lossy(self) -> String

Consume the WTF-8 string and convert it lossily to UTF-8.

This does not copy the data (but may overwrite parts of it in place).

Surrogates are replaced with "\u{FFFD}" (the replacement character “�”)

pub fn from_bytes(bytes: Vec<u8>) -> Result<Wtf8Buf, Vec<u8>>

Create a Wtf8Buf from a WTF-8 encoded byte vector.

Returns Ok(Wtf8Buf) if the bytes are well-formed WTF-8, or Err(bytes) with the original bytes if validation fails.

This validates that:

• All bytes form valid UTF-8 sequences OR valid surrogate code point encodings
• Surrogate code points may appear unpaired and be encoded separately, but if they are paired, they must be encoded as a single 4-byte UTF-8 sequence. For example, the byte sequence [0xED, 0xA0, 0x80, 0xED, 0xB0, 0x80] is not valid WTF-8 because WTF-8 forbids encoding a surrogate pair as two separate 3-byte sequences.

pub unsafe fn from_bytes_unchecked(bytes: Vec<u8>) -> Wtf8Buf

Create a Wtf8Buf from a WTF-8 encoded byte vector without checking that the bytes contain valid WTF-8.

For the safe version, see Wtf8Buf::from_bytes.

Safety

The bytes passed in must be valid WTF-8. See Wtf8Buf::from_bytes for the requirements.

Methods from Deref<Target = Wtf8>

pub fn len(&self) -> usize

Return the length, in WTF-8 bytes.

pub fn is_empty(&self) -> bool

Return true if the string has a length of zero bytes.

pub fn is_ascii(&self) -> bool

Return true if the string contains only ASCII characters.

pub fn slice(&self, begin: usize, end: usize) -> &Wtf8

Return a slice of the given string for the byte range [begin..end).

Failure

Fails when begin and end do not point to code point boundaries, or point beyond the end of the string.

pub fn slice_from(&self, begin: usize) -> &Wtf8

Return a slice of the given string from byte begin to its end.

Failure

Fails when begin is not at a code point boundary, or is beyond the end of the string.

pub fn slice_to(&self, end: usize) -> &Wtf8

Return a slice of the given string from its beginning to byte end.

Failure

Fails when end is not at a code point boundary, or is beyond the end of the string.

pub fn ascii_byte_at(&self, position: usize) -> u8

Return the code point at position if it is in the ASCII range, or `b’\xFF’ otherwise.

Failure

Fails if position is beyond the end of the string.

pub fn code_points(&self) -> Wtf8CodePoints<'_>

Return an iterator for the string’s code points.

pub fn contains_char(&self, ch: char) -> bool

Returns true if this WTF-8 string contains the given character.

pub fn contains(&self, code_point: CodePoint) -> bool

Returns true if this WTF-8 string contains the given code point.

pub fn starts_with(&self, pattern: &str) -> bool

Returns true if this WTF-8 string starts with the given UTF-8 string.

pub fn as_str(&self) -> Option<&str>

Try to convert the string to UTF-8 and return a &str slice.

Return None if the string contains surrogates.

This does not copy the data.

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

Return the underlying WTF-8 bytes.

pub fn to_string_lossy(&self) -> Cow<'_, str>

Lossily convert the string to UTF-8. Return an UTF-8 &str slice if the contents are well-formed in UTF-8.

Surrogates are replaced with "\u{FFFD}" (the replacement character “�”).

This only copies the data if necessary (if it contains any surrogate).

pub fn to_ill_formed_utf16(&self) -> IllFormedUtf16CodeUnits<'_>

Convert the WTF-8 string to potentially ill-formed UTF-16 and return an iterator of 16-bit code units.

This is lossless: calling Wtf8Buf::from_ill_formed_utf16 on the resulting code units would always return the original WTF-8 string.

pub fn to_uppercase(&self) -> Wtf8Buf

Returns the uppercase equivalent of this wtf8 slice, as a new Wtf8Buf.

pub fn to_lowercase(&self) -> Wtf8Buf

Returns the lowercase equivalent of this wtf8 slice, as a new Wtf8Buf.

Trait Implementations

impl Add<&Wtf8> for Wtf8Buf

type Output = Wtf8Buf

The resulting type after applying the + operator.

fn add(self, rhs: &Wtf8) -> <Wtf8Buf as Add<&Wtf8>>::Output

Performs the + operation.

impl Borrow<Wtf8> for Wtf8Buf

fn borrow(&self) -> &Wtf8

Immutably borrows from an owned value.

impl Clone for Wtf8Buf

fn clone(&self) -> Wtf8Buf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Wtf8Buf

Format the string with double quotes, and surrogates as \u followed by four hexadecimal digits. Example: "a\u{D800}" for a string with code points [U+0061, U+D800]

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

Formats the value using the given formatter.

impl Default for Wtf8Buf

fn default() -> Wtf8Buf

Returns the “default value” for a type.

impl Deref for Wtf8Buf

type Target = Wtf8

The resulting type after dereferencing.

fn deref(&self) -> &Wtf8

Dereferences the value.

impl Extend<CodePoint> for Wtf8Buf

Append code points from an iterator to the string.

This replaces surrogate code point pairs with supplementary code points, like concatenating ill-formed UTF-16 strings effectively would.

fn extend<T>(&mut self, iterable: T)

where T: IntoIterator<Item = CodePoint>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

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

impl From<&Wtf8Atom> for Wtf8Buf

fn from(s: &Wtf8Atom) -> Self

Converts to this type from the input type.

impl FromIterator<CodePoint> for Wtf8Buf

Create a new WTF-8 string from an iterator of code points.

This replaces surrogate code point pairs with supplementary code points, like concatenating ill-formed UTF-16 strings effectively would.

fn from_iter<T>(iterable: T) -> Wtf8Buf

where T: IntoIterator<Item = CodePoint>,

Creates a value from an iterator.

impl FromStr for Wtf8Buf

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Wtf8Buf, <Wtf8Buf as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for Wtf8Buf

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

where H: Hasher,

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 Ord for Wtf8Buf

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<&Wtf8> for Wtf8Buf

fn eq(&self, other: &&Wtf8) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Wtf8Buf> for &Wtf8

fn eq(&self, other: &Wtf8Buf) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Wtf8Buf

fn eq(&self, other: &Wtf8Buf) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Wtf8Buf

fn partial_cmp(&self, other: &Wtf8Buf) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Write for Wtf8Buf

fn write_str(&mut self, s: &str) -> Result<(), Error>

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl Eq for Wtf8Buf

impl StructuralPartialEq for Wtf8Buf