Enum Str 

pub enum Str {
    Utf8(Box<str>),
    Wide(Box<[u32]>),
}

A Python string, which is a sequence of code points.

Nearly every string in nearly every program is valid UTF-8 and takes the first arm, which is a Box<str> and costs nothing. '\ud800' is a lone surrogate, which is a perfectly ordinary Python string and something a Rust str cannot hold, so a string containing one takes the second arm and spends four bytes a code point. Paying that for every string to serve the few that need it would be the wrong trade, and refusing them, which is what this did until now, is worse: 58 files in CPython’s own standard library have one.

The two arms are never both valid for the same string. A Wide is built only after a surrogate has arrived, so Utf8 and Wide never hold the same sequence and PartialEq can stay derived.

Variants

Utf8(Box<str>)

The usual case.

Wide(Box<[u32]>)

Code points, for a string holding at least one lone surrogate.

Implementations

impl Str

pub fn code_points(&self) -> impl Iterator<Item = u32> + '_

The code points, in order, whatever the string is stored as.

pub fn repr(&self) -> String

What CPython’s repr prints for this string.

pub fn len(&self) -> usize

How many code points, which is what len answers for a str.

Linear for a Utf8 string, since UTF-8 does not carry a count. CPython stores one in the object header and answers in constant time, and the representation that will do the same here is the one in the spec rather than this one.

pub fn code_point_at(&self, index: usize) -> Option<u32>

The code point at an offset, or None past the end.

Linear in the offset for a string that is not ASCII, because UTF-8 has no way to reach the nth code point except by counting to it. Anything walking a whole string wants Str::code_points instead, which counts once.

pub fn is_empty(&self) -> bool

Whether this is the empty string, which decides Str vs JoinedStr.

Trait Implementations

impl Clone for Str

fn clone(&self) -> Str

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Str

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

Formats the value using the given formatter.

impl Display for Str

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

The text itself, which is what str gives back and what print writes.

A lone surrogate has no UTF-8 encoding, and CPython raises UnicodeEncodeError rather than writing one. Until there is an encoder to raise it from, one is written as the replacement character, which is what every other tool that has to keep going does.

impl Eq for Str

impl From<&str> for Str

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<String> for Str

fn from(s: String) -> Self

Converts to this type from the input type.

impl PartialEq for Str

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Str