Primitive Type str 

String slices.

See also the std::str module.

The str type, also called a ‘string slice’, is the most primitive string type. It is usually seen in its borrowed form, &str. It is also the type of string literals, &'static str.

Basic Usage

String literals are string slices:

let hello_world = "Hello, World!";

Here we have declared a string slice initialized with a string literal. String literals have a static lifetime, which means the string hello_world is guaranteed to be valid for the duration of the entire program. We can explicitly specify hello_world’s lifetime as well:

let hello_world: &'static str = "Hello, world!";

Representation

A &str is made up of two components: a pointer to some bytes, and a length. You can look at these with the as_ptr and len methods:

use std::slice;
use std::str;

let story = "Once upon a time...";

let ptr = story.as_ptr();
let len = story.len();

// story has nineteen bytes
assert_eq!(19, len);

// We can re-build a str out of ptr and len. This is all unsafe because
// we are responsible for making sure the two components are valid:
let s = unsafe {
    // First, we build a &[u8]...
    let slice = slice::from_raw_parts(ptr, len);

    // ... and then convert that slice into a string slice
    str::from_utf8(slice)
};

assert_eq!(s, Ok(story));

Note: This example shows the internals of &str. unsafe should not be used to get a string slice under normal circumstances. Use as_str instead.

Invariant

Rust libraries may assume that string slices are always valid UTF-8.

Constructing a non-UTF-8 string slice is not immediate undefined behavior, but any function called on a string slice may assume that it is valid UTF-8, which means that a non-UTF-8 string slice can lead to undefined behavior down the road.

Implementations

impl str

pub const fn len(&self) -> usize

Returns the length of self.

This length is in bytes, not chars or graphemes. In other words, it might not be what a human considers the length of the string.

Examples

let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);

pub const fn is_empty(&self) -> bool

Returns true if self has a length of zero bytes.

Examples

let s = "";
assert!(s.is_empty());

let s = "not empty";
assert!(!s.is_empty());

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

Converts a string slice to a byte slice. To convert the byte slice back into a string slice, use the from_utf8 function.

Examples

let bytes = "bors".as_bytes();
assert_eq!(b"bors", bytes);

pub const unsafe fn as_bytes_mut(&mut self) -> &mut [u8]

Converts a mutable string slice to a mutable byte slice.

Safety

The caller must ensure that the content of the slice is valid UTF-8 before the borrow ends and the underlying str is used.

Use of a str whose contents are not valid UTF-8 is undefined behavior.

Examples

Basic usage:

let mut s = String::from("Hello");
let bytes = unsafe { s.as_bytes_mut() };

assert_eq!(b"Hello", bytes);

Mutability:

let mut s = String::from("🗻∈🌏");

unsafe {
    let bytes = s.as_bytes_mut();

    bytes[0] = 0xF0;
    bytes[1] = 0x9F;
    bytes[2] = 0x8D;
    bytes[3] = 0x94;
}

assert_eq!("🍔∈🌏", s);

pub const fn as_ptr(&self) -> *const u8

Converts a string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to a u8. This pointer will be pointing to the first byte of the string slice.

The caller must ensure that the returned pointer is never written to. If you need to mutate the contents of the string slice, use as_mut_ptr.

Examples

let s = "Hello";
let ptr = s.as_ptr();

pub const fn as_mut_ptr(&mut self) -> *mut u8

Converts a mutable string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to a u8. This pointer will be pointing to the first byte of the string slice.

It is your responsibility to make sure that the string slice only gets modified in a way that it remains valid UTF-8.

pub const fn as_str(&self) -> &str

🔬This is a nightly-only experimental API. (str_as_str #130366)

Returns the same string as a string slice &str.

This method is redundant when used directly on &str, but it helps dereferencing other string-like types to string slices, for example references to Box<str> or Arc<str>.

Trait Implementations

impl AsMut<str> for str

fn as_mut(&mut self) -> &mut str

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<[u8]> for str

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl Default for &str

fn default() -> Self

Creates an empty str

impl StructuralPartialEq for str