Module collections::strExperimental [-]  [+] [src]

Unicode string manipulation (str type)

Basic Usage

Rust's string type is one of the core primitive types of the language. While represented by the name str, the name str is not actually a valid type in Rust. Each string must also be decorated with a pointer. String is used for an owned string, so there is only one commonly-used str type in Rust: &str.

&str is the borrowed string type. This type of string can only be created from other strings, unless it is a static string (see below). As the word "borrowed" implies, this type of string is owned elsewhere, and this string cannot be moved out of.

As an example, here's some code that uses a string.

fn main() { let borrowed_string = "This string is borrowed with the 'static lifetime"; }
fn main() {
    let borrowed_string = "This string is borrowed with the 'static lifetime";
}

From the example above, you can guess that Rust's string literals have the 'static lifetime. This is akin to C's concept of a static string. More precisely, string literals are immutable views with a 'static lifetime (otherwise known as the lifetime of the entire program), and thus have the type &'static str.

Representation

Rust's string type, str, is a sequence of Unicode scalar values encoded as a stream of UTF-8 bytes. All strings are guaranteed to be validly encoded UTF-8 sequences. Additionally, strings are not null-terminated and can thus contain null bytes.

The actual representation of strings have direct mappings to slices: &str is the same as &[u8].

Reexports

pub use self::MaybeOwned::*;

Primitive Types

str

Unicode string manipulation (str type)

Modules

raw

Unsafe string operations.

Structs

CharOffsets

External iterator for a string's characters and their byte offsets. Use with the std::iter module.

CharRange

Struct that contains a char and the index of the first byte of the next char in a string. This can be used as a data structure for iterating over the UTF-8 bytes of a string.

CharSplits

An iterator over the substrings of a string, separated by sep.

CharSplitsN

An iterator over the substrings of a string, separated by sep, splitting at most count times.

Chars

Iterator for the char (representing Unicode Scalar Values) of a string

Decompositions

External iterator for a string's decomposition's characters. Use with the std::iter module.

GraphemeIndices

External iterator for grapheme clusters and byte offsets.

Graphemes

External iterator for a string's grapheme clusters.

MatchIndices

An iterator over the start and end indices of the matches of a substring within a larger string

Recompositions

External iterator for a string's recomposition's characters. Use with the std::iter module.

StrSplits

An iterator over the substrings of a string separated by a given search string

Utf16CodeUnits

External iterator for a string's UTF16 codeunits. Use with the std::iter module.

Utf16Items

An iterator that decodes UTF-16 encoded codepoints from a vector of u16s.

Enums

MaybeOwned

A string type that can hold either a String or a &str. This can be useful as an optimization when an allocation is sometimes needed but not always.

Utf16Item

The possibilities for values decoded from a u16 stream.

Traits

CharEq

Something that can be used to compare against a character

FromStr

A trait to abstract the idea of creating a new instance of a type from a string.

IntoMaybeOwned

Trait for moving into a MaybeOwned.

Str

Any string that can be represented as a slice

StrAllocating

Any string that can be represented as a slice.

StrPrelude

Methods for string slices

StrVector

Methods for vectors of strings.

UnicodeStrPrelude

Methods for Unicode string slices

Functions

eq_slice

Bytewise slice equality NOTE: This function is (ab)used in rustc::middle::trans::_match to compare &[u8] byte slices that are not necessarily valid UTF-8.

from_str

A utility function that just calls FromStr::from_str

from_utf8

Converts a vector to a string slice without performing any allocations.

is_utf16

Determines if a vector of u16 contains valid UTF-16

is_utf8

Determines if a vector of bytes contains valid UTF-8.

replace

Replaces all occurrences of one string with another.

truncate_utf16_at_nul

Return a slice of v ending at (and not including) the first NUL (0).

utf16_items

Create an iterator over the UTF-16 encoded codepoints in v, returning invalid surrogates as LoneSurrogates.

utf8_char_width

Given a first byte, determine how many bytes are in this UTF-8 character

Type Definitions

AnyLines
Bytes
SendStr

A specialization of MaybeOwned to be sendable.

Words