Strings

What it is and why it exists

Rust’s core string types are String and str. A String owns a growable sequence of UTF-8 bytes on the heap. str is a dynamically sized string-slice type representing valid UTF-8 bytes, so a bare str usually appears behind a pointer such as &str, Box<str>, or Arc<str>.

The usual pair is an owned String and a borrowed &str. A String allocates, grows, and releases its buffer. A &str describes a contiguous piece of text without taking responsibility for releasing it. This borrowing lets a function read the caller’s text without copying it first.

A string literal also has type &str, but it normally borrows static data in the program binary. A &str taken from a String may instead point into a heap buffer. Storage location doesn’t define the string type; ownership and the UTF-8 invariant do.

You’ll meet these types in function parameters, parsers, log messages, protocol fields, and user input. The right choice depends on whether the API must retain the input, change its length, or accept data that isn’t guaranteed to be UTF-8. It doesn’t depend on whether the sample happens to look like plain ASCII.

Both String and str guarantee valid UTF-8. File names, C strings, and arbitrary network payloads may not satisfy that condition; consider Path/OsStr, CStr, or a byte slice instead. A lossy conversion changes data and shouldn’t be used merely to make the types fit.

How it works

Ownership and borrowed views

A String manages a buffer pointer, byte length, and capacity. Assigning it to another variable uses move semantics by default: ownership of the buffer transfers and the old variable can no longer be used. Only an explicit clone() copies the bytes.

Borrowing a &str from a String doesn’t copy the text. The borrow carries a data address and byte length and may cover the full string or one valid subrange. While a shared borrow is still used, Rust rejects mutation that could reallocate the buffer, so a reference can’t silently dangle after push_str().

The diagram shows the conceptual relationship, not an external ABI you can depend on. String owns the heap buffer; &str is only a view over a valid UTF-8 region. Borrow lifetimes keep the view from outliving its data.

UTF-8 and three kinds of length

UTF-8 uses one to four bytes for one Unicode scalar value. str::len() returns bytes, chars() iterates Unicode scalar values , and what a user sees as one character may be a grapheme cluster made from several scalar values. These units aren’t interchangeable.

For example, é can be the single scalar value U+00E9 or a sequence containing e and the combining accent U+0301. The two strings may look alike while having different byte and scalar counts. Rust’s standard library neither normalizes Unicode automatically nor provides full grapheme cluster segmentation.

Range slicing uses byte offsets, and both ends must fall on UTF-8 character boundaries. &text[a..b] panics for an invalid boundary, while text.get(a..b) returns None. char_indices() supplies each scalar value with a valid byte offset, which makes it useful when a scan feeds a later slice operation.

Allocation and mutation

String::new() creates an empty string and normally allocates nothing before the first growth. String::with_capacity(n) reserves room for at least n bytes and suits builders that already know their approximate output size. Capacity is spare space for future growth, not string content; len() reports only the valid bytes currently stored.

push() appends one char, while push_str() appends a &str. insert(), remove(), truncate(), and replace_range() take byte positions, and the relevant positions must be character boundaries. Safe APIs preserve the UTF-8 invariant, but they can’t make every runtime position valid.

String + &str moves the left-hand String and appends the right-hand text. It fits a one-off concatenation that deliberately consumes the left side. If you still need every input, format!() or an explicitly built String is clearer. Reusing one buffer in a loop also tends to make ownership easier to see.

Examples

Borrow input and return an owned result

This function only reads the name during the call, so its parameter is &str. The result must survive the function call, so it returns a new String.

In greeting(&owned), deref coercion lets Rust use &String as &str; the literal is already &str. Both calls only borrow their inputs, so owned remains available for the final print. The reservation counts bytes, exactly the unit needed for the two UTF-8 segments that will be appended.

If the function stored the name in a returned struct, accepting String or impl Into<String> might be a better contract. Parameter types should state ownership, not pursue generic signatures as a goal of their own.

Inspect UTF-8 boundaries

This program prints the byte count, scalar count, and starting byte offset for each scalar value. The two get() calls differ by one starting position, but one succeeds and the other fails.

fn main() {
    let text = "Aé中👋";

    println!("bytes: {}", text.len());
    println!("scalars: {}", text.chars().count());

    for (byte_offset, scalar) in text.char_indices() {
        println!("{byte_offset}: {scalar}");
    }

    println!("1..3: {:?}", text.get(1..3));
    println!("2..3: {:?}", text.get(2..3));

    let decomposed = "e\u{301}";
    println!(
        "decomposed bytes/scalars: {}/{}",
        decomposed.len(),
        decomposed.chars().count()
    );
}

bytes: 10
scalars: 4
0: A
1: é
3: 中
6: 👋
1..3: Some("é")
2..3: None
decomposed bytes/scalars: 3/2

é occupies the byte range 1..3, so that range produces a &str. Offset 2 lies inside its encoding, which makes get(2..3) return None. The decomposed e\u{301} contains two scalar values and three bytes, although an interface may display it as one grapheme cluster.

If the requirement says “at most 20 user-visible characters,” chars().take(20) still isn’t necessarily correct because it truncates by scalar value. You need to choose Unicode grapheme segmentation rules explicitly and decide whether normalization happens first.

Reserve capacity and edit at a valid boundary

The path builder adds the byte lengths of every part and separator, then reuses one buffer. The second half replaces text at the position returned by find(). A successful &str match always begins at a character boundary.

fn join_path(parts: &[&str]) -> String {
    let separators = parts.len().saturating_sub(1);
    let byte_len = parts.iter().map(|part| part.len()).sum::<usize>() + separators;
    let mut path = String::with_capacity(byte_len);

    for (index, part) in parts.iter().enumerate() {
        if index > 0 {
            path.push('/');
        }
        path.push_str(part);
    }

    path
}

fn main() {
    let path = join_path(&["用户", "42", "settings"]);
    println!("{path}");
    println!("bytes: {}", path.len());

    let mut status = String::from("状态: ready");
    let start = status.find("ready").expect("marker is present");
    status.replace_range(start.., "done");
    println!("{status}");
}

用户/42/settings
bytes: 18
状态: done

Using len() in the capacity calculation is correct because allocators care about bytes, not display characters. saturating_sub(1) keeps the separator count at zero for an empty slice. When a builder can’t estimate its input size, starting with String::new() is also correct, although growth may require reallocations.

Here replace_range(start.., "done") changes the byte length, so it can operate on String but not &mut str. The String still contains valid UTF-8 after the replacement.

Return borrowed fields from input

The parser neither rewrites its fields nor needs them to outlive the source record, so it returns two &str values pointing into its input. Both split_once() and trim() can produce borrowed views without creating a String for either field.

fn parse_record(line: &str) -> Option<(&str, &str)> {
    let (key, value) = line.split_once('=')?;
    let key = key.trim();
    let value = value.trim();

    if key.is_empty() {
        return None;
    }

    Some((key, value))
}

fn main() {
    for line in ["color = blue", " retries=3 ", " = missing"] {
        match parse_record(line) {
            Some((key, value)) => println!("{key} -> {value}"),
            None => println!("invalid: {line:?}"),
        }
    }
}

color -> blue
retries -> 3
invalid: " = missing"

Lifetime elision ties both references in the return type to the function’s only input reference. While the caller keeps either field, it can’t destroy line or mutate it in a conflicting way. If a field must enter a configuration object that outlives the input, call to_owned() at that ownership boundary.

This implementation rejects a missing separator or empty key but permits an empty value. A real parser should state such rules in its signature and tests. Option only distinguishes success from failure, so use Result when callers need the reason.

Pitfalls

Treating bytes as characters

Fix: Name the unit required by the domain. Protocol lengths, capacity, and storage sizes usually count bytes; code-point work can use chars(); cursor movement, deleting “one character,” and many length limits require grapheme segmentation. Don’t rename one count and pass it off as another.

Slicing with an arbitrary range

Fix: If the offset comes from untrusted input, use get() and handle None. If it comes from a text scan, retain the byte boundary from char_indices(), find(), or another matching API. To truncate by scalar or grapheme, iterate over that unit first and then convert the result to a byte range.

Forcing ownership on a read-only API

Fix: Use &str for an ordinary read-only parameter. Accept or create a String when the function must store the text, transfer it to another owner, or return an independent value. impl AsRef<str> adds generic surface area, so reserve it for APIs that genuinely need several wrapper types.

Growing a string while it is borrowed

Fix: Reorder the operations so the shared borrow ends before mutation, or save an owned result before changing the source. Don’t bypass the error with an unsafe pointer. The compiler is preventing a potentially dangling view, not enforcing a cosmetic syntax preference.

Mistaking lowercase conversion for text comparison

Fix: Define the comparison contract first. ASCII protocol fields can use eq_ignore_ascii_case(). Natural-language search, sorting, and deduplication need chosen normalization, case-folding, and locale rules. The standard library can’t choose those product semantics for you.

Further reading

• The Rust Programming Language: Storing UTF-8 encoded text with strings
• Rust standard library: String
• Rust standard library: str
• The Rust Reference: pointer and reference layout
• Unicode Standard Annex #29: Text segmentation