Module std::string

Text: String, an owned, growable UTF-8 string whose borrowed view is its bytes, &[u8]; Display, the trait a value formats itself into a String by; and print/println. Appending asks for Alloc (the string may grow), printing for Stdout; nothing here panics.

Source: std/string.weir; committed interface: std/string.iface. Index

struct Utf8Error

pub struct Utf8Error: copy {
    /* private fields */
}

Why bytes are not UTF-8: the bytes before Utf8Error::valid_up_to are, the rest is not.

impl Utf8Error

method valid_up_to

pub fn valid_up_to(&self) -> usize

The length of the longest UTF-8 prefix of the rejected bytes.

Committed interface (std/string.iface): the signature alone.

struct String

pub struct String {
    /* private fields */
}

An owned, growable string, always valid UTF-8: every way in (from_str, push, the validating from_utf8) keeps it so. Lengths name their unit (String::byte_len, String::char_count); a byte range is taken only between code points (String::get). A String in r lives in region r, and its growing methods ask for Alloc in r. To format one into another, use String::push_string, or its Display impl (push_fmt, {s}).

Implementations:

impl<r> String in r

method new

pub fn new() -> String in r with Alloc in r

An empty string; allocates nothing until the first append.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc

method with_capacity

pub fn with_capacity(n: usize) -> String in r with Alloc in r

An empty string that holds n bytes before it grows.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc

method from_str

pub fn from_str(s: Str) -> String in r with Alloc in r

A copy of the literal s.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc

method from_utf8

pub fn from_utf8(b: Buf<u8> in r) -> Result<String in r, Utf8Error> with Free in r

Takes b without copying when its bytes are UTF-8; else frees it (with Free) and returns Err with where they stop being UTF-8.

Committed interface (std/string.iface):

bound Free: Free[r] any
may diverge

method from_utf8_bytes

pub fn from_utf8_bytes(b: &[u8]) -> Result<String in r, Utf8Error> with Alloc in r

A copy of b when its bytes are UTF-8, else Err with where they stop being.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
may diverge
aborts: Alloc.alloc

method byte_len

pub fn byte_len(&self) -> usize

The length in bytes (O(1)).

Committed interface (std/string.iface): the signature alone.

method char_count

pub fn char_count(&self) -> usize

The number of code points (O(n): counts the bytes that start one).

Committed interface (std/string.iface): the signature alone.

method is_empty

pub fn is_empty(&self) -> Bool

true when the string has no bytes.

Committed interface (std/string.iface): the signature alone.

method capacity

pub fn capacity(&self) -> usize

How many bytes it holds before it grows.

Committed interface (std/string.iface): the signature alone.

method as_bytes

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

Its bytes: the borrowed view of the text.

Committed interface (std/string.iface): the signature alone.

method is_char_boundary

pub fn is_char_boundary(&self, i: usize) -> Bool

Whether byte offset i is between two code points (0 and byte_len() included).

Committed interface (std/string.iface): the signature alone.

method get

pub fn get(&self, lo: usize, hi: usize) -> Option<&[u8]>

The bytes lo..hi, or None unless lo <= hi <= byte_len() and both are code point boundaries: a range is never cut inside a code point.

Committed interface (std/string.iface): the signature alone.

method reserve

pub fn reserve(&mut self, extra: usize) with Alloc in r

Makes room for at least extra more bytes, so appends that fit do not reallocate.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc
writes through self: {bytes.cap, bytes.data} and its shape

method clear

pub fn clear(&mut self) with Free in r

Empties the string and keeps its capacity.

Committed interface (std/string.iface):

bound Free: Free[r] any
writes through self: {bytes.len} and its shape

method push_str

pub fn push_str(&mut self, s: Str) with Alloc in r

Appends the literal s.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc
writes through self: {bytes.cap, bytes.data, bytes.len} and its shape

method push_string

pub fn push_string(&mut self, s: &String) with Alloc in r

Appends a copy of s's text.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc
writes through self: {bytes.cap, bytes.data, bytes.len} and its shape

method push_utf8_lossy

pub fn push_utf8_lossy(&mut self, b: &[u8]) with Alloc in r

Appends b where it is UTF-8 and U+FFFD for each maximal invalid subpart (Unicode's "substitution of maximal subparts"), so any bytes can be shown as text.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
may diverge
aborts: Alloc.alloc
writes through self: {bytes.cap, bytes.data, bytes.len} and its shape

method push

pub fn push(&mut self, c: u32) -> Bool with Alloc in r

Appends code point c as UTF-8 and returns true; a surrogate or a value past U+10FFFF is no code point, so nothing is appended and the answer is false.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc
writes through self: {bytes.cap, bytes.data, bytes.len} and its shape

method eq_str

pub fn eq_str(&self, s: Str) -> Bool

Whether its bytes are the literal's.

Committed interface (std/string.iface): the signature alone.

method clone

pub fn clone(&self) -> String in r with Alloc in r

A copy in the same region.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc

method to_ascii_lowercase

pub fn to_ascii_lowercase(&self) -> String in r with Alloc in r

A copy with its ASCII letters lowercased, every other code point as it is; allocates (Alloc), where String::make_ascii_lowercase works in place.

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc

method to_ascii_uppercase

pub fn to_ascii_uppercase(&self) -> String in r with Alloc in r

A copy with its ASCII letters uppercased; allocates (Alloc).

Committed interface (std/string.iface):

bound Alloc: Alloc[r] any
aborts: Alloc.alloc

method make_ascii_lowercase

pub fn make_ascii_lowercase(&mut self)

Lowercases its ASCII letters in place. A UTF-8 sequence's bytes are all above 127, so they stay as they are and the text stays UTF-8.

Committed interface (std/string.iface):

writes through self: everything

method make_ascii_uppercase

pub fn make_ascii_uppercase(&mut self)

Uppercases its ASCII letters in place; the text stays UTF-8.

Committed interface (std/string.iface):

writes through self: everything

method eq_ignore_ascii_case

pub fn eq_ignore_ascii_case(&self, b: &[u8]) -> Bool

Whether its bytes equal b once the ASCII letters of both are lowercased.

Committed interface (std/string.iface): the signature alone.

method print

pub fn print(&self) with Stdout

Writes it to standard output.

Committed interface (std/string.iface):

bound Stdout: Stdout any
scheduling point: Stdout not quiet

method println

pub fn println(&self) with Stdout

Writes it and a newline to standard output.

Committed interface (std/string.iface):

bound Stdout: Stdout any
scheduling point: Stdout not quiet

impl String

method push_fmt

pub fn push_fmt<T: Display>(&mut self, x: &T) with Alloc

Appends x as its Display impl formats it.

Committed interface (std/string.iface):

bound Alloc: Alloc any
may diverge
aborts: Alloc.alloc
enters the backing of x
writes through self: everything and its shape
reads regions _
writes regions type T
loan of Alloc across the backing of x

method push_padded

pub fn push_padded<T: Display>(&mut self, x: &T, width: usize, fill: u32) with Alloc

Appends x right-aligned: after as many fill code points as bring it to width code points (none when it is already as wide). x is first formatted into a string of its own.

Committed interface (std/string.iface):

bound Alloc: Alloc any
may diverge
aborts: Alloc.alloc
enters the backing of x
writes through self: {bytes.cap, bytes.data, bytes.len} and its shape
reads regions _
writes regions type T
loan of Alloc across the backing of x

method push_hex

pub fn push_hex(&mut self, x: u64) with Alloc

Appends x in lowercase hexadecimal, without a 0x prefix.

Committed interface (std/string.iface):

bound Alloc: Alloc any
may diverge
aborts: Alloc.alloc
writes through self: {bytes.cap, bytes.data, bytes.len} and its shape

method push_fixed

pub fn push_fixed(&mut self, x: f64, digits: usize) with Alloc

Appends x in fixed notation with digits fraction digits: its exact value rounded half to even, as Rust's {:.N} prints it; a - on any negative value (-0.0, and one that rounds to zero, included); NaN, inf and -inf as Display writes them. An f32 widens exactly: push_fixed(f64::from(y), n).

Committed interface (std/string.iface):

bound Alloc: Alloc any
may diverge
aborts: Alloc.alloc
writes through self: {bytes.cap, bytes.data, bytes.len} and its shape

fn utf8_prefix

pub fn utf8_prefix(b: &[u8]) -> usize

The length of the longest UTF-8 prefix of b: b.len() exactly when all of b is UTF-8.

Committed interface (std/string.iface):

may diverge

trait Display

pub trait Display {
    fn fmt(&self, out: &mut String) with Alloc;
}

How a value is written as text, appended to out: integers in decimal, Bool as true or false, Str as its characters, floats as the shortest decimal that reads back. Implement it to make your type printable with print and String::push_fmt.

Implementations:

)`

method fmt

fn fmt(&self, out: &mut String) with Alloc;

Appends self's text to out; with Alloc because out may grow.

fn print

pub fn print<T: Display>(x: &T) with Alloc, Stdout

Writes x formatted to standard output, through a temporary string (its Alloc).

Committed interface (std/string.iface):

bound Alloc: Alloc any
bound Stdout: Stdout any
may diverge
aborts: Alloc.alloc
scheduling point: Stdout not quiet
enters the backing of x
reads regions _
writes regions type T
loan of Alloc across the backing of x

fn println

pub fn println<T: Display>(x: &T) with Alloc, Stdout

Writes x formatted and a newline to standard output.

Committed interface (std/string.iface):

bound Alloc: Alloc any
bound Stdout: Stdout any
may diverge
aborts: Alloc.alloc
scheduling point: Stdout not quiet
enters the backing of x
reads regions _
writes regions type T
loan of Alloc across the backing of x