str

import std::collections::str; · source

Str#

type struct Str {
    bytes:  u8*;
    length: u64;

    ![implicit]
    static new(text: string) -> Str;
    static from_raw(bytes: u8*, length: u64) -> Str;
    static from<T>(src: T) -> Str;
    length(&this) -> u64;
    is_empty(&this) -> boolean;
    as_bytes(&this) -> Slice<u8>;
    as_ptr(&this) -> u8*;
    byte_at(&this, index: u64) -> Option<u8>;
    sub_bytes(&this, start: u64, end: u64) -> Str;
    equals(&this, other: &Str) -> boolean;
    to_ascii_lowercase(&this) -> String;
    starts_with(&this, prefix: &Str) -> boolean;
    ends_with(&this, suffix: &Str) -> boolean;
    find(&this, needle: &Str) -> Option<u64>;
    contains(&this, needle: &Str) -> boolean;
    trim_start(&this) -> Str;
    trim_end(&this) -> Str;
    trim(&this) -> Str;
    to_ascii_uppercase(&this) -> String;
    split(&this, sep: &Str) -> implement Iterator<Str>;
    chars(&this) -> implement Iterator<u32>;
    char_indices(&this) -> implement Iterator<Pair<u64, u32>>;
    try_to_hex(&this) -> Result<u64, ConversionError>;
}

A borrowed UTF-8 slice: (bytes, length) over memory the caller guarantees outlives the view. There is no NUL terminator — the length is authoritative.

new is marked ![implicit], so a string literal flowing into a Str slot converts on its own; the NUL is not part of the view. from<T> dispatches at compile time over string (length via strlen) and Slice<u8> (borrowed verbatim). from_raw is the escape hatch for a pointer you already have a length for.

Method	Returns
length() / is_empty()	u64 — bytes, not scalars — / boolean
as_bytes() / as_ptr()	Slice<u8> / u8*
byte_at(index)	Option<u8>
sub_bytes(start, end)	Str
equals / starts_with / ends_with / contains	boolean
find(needle)	Option<u64> — byte offset
trim() / trim_start() / trim_end()	Str — ASCII whitespace
to_ascii_lowercase() / to_ascii_uppercase()	String — these allocate
split(sep)	implement Iterator<Str>
chars()	implement Iterator<u32> — decoded scalars, U+FFFD for malformed input
char_indices()	implement Iterator<Pair<u64, u32>> — byte offset and scalar
try_to_hex()	Result<u64, ConversionError>

The three iterators are concrete public types — SplitIter, Chars, and CharIndices — each implementing Iterator, so they can be named in a field or returned from your own functions.

Parsing numbers#

TryFrom<Str> is implemented for every integer width, which is how you parse text:

import std::collections::str;
import std::core::convert;

match (u32::try_from(arg)) {
    Result::Ok(n)  => { /* parsed */ }
    Result::Err(e) => { eprintln(f"not a number: {e}"); }
}

Trait implementations#

implement trait Eq for struct Str

implement trait Hash for struct Str

implement trait Ord for struct Str

implement trait Display for struct Str   // std::fmt::display

implement trait Debug for struct Str   // std::fmt::display

implement trait TryFrom<&JsonValue> for Str   // std::json::value

TryFrom<Str> for every integer width is what backs number parsing (the list also shows the numeric narrowing conversions from core::convert, which share the trait):

implement trait TryFrom<Str> for u64

implement trait TryFrom<Str> for u32

implement trait TryFrom<Str> for u16

implement trait TryFrom<Str> for u8

implement trait TryFrom<Str> for i64

implement trait TryFrom<Str> for i32

implement trait TryFrom<Str> for i16

implement trait TryFrom<Str> for i8

implement trait TryFrom<i32> for i16   // std::core::convert

implement trait TryFrom<i64> for i32   // std::core::convert

implement trait TryFrom<u64> for u32   // std::core::convert

implement trait TryFrom<i64> for u64   // std::core::convert

implement trait TryFrom<u64> for i64   // std::core::convert

implement trait TryFrom<&JsonValue> for boolean   // std::json::value

implement trait TryFrom<&JsonValue> for i64   // std::json::value

implement trait TryFrom<&JsonValue> for u64   // std::json::value

implement trait TryFrom<&JsonValue> for f64   // std::json::value

implement trait TryFrom<&JsonValue> for Str   // std::json::value

Ord is lexicographic over bytes. Eq plus Hash is what makes Str usable as a HashMap key. Debug renders the text quoted and escaped.