Lesson 4. Slices, String and str

Mission link: String against &str is the first API design decision every Rust programmer makes, and getting it wrong forces every caller to allocate. It is also where UTF-8 stops being an implementation detail.
Primary source: The Rust Programming Language, The Slice Type
Prerequisites: Lesson 3

Warm-up

1. ▢ State the borrow rule in one sentence.

2. ▢ When does a borrow end?

Know this

A slice is a borrowed view into a contiguous sequence: a pointer plus a length, and no ownership. Two spellings matter constantly:

let owned = String::from("hello world");
let word: &str = &owned[0..5];      // borrows the first five bytes
let all: &str = &owned;             // borrows the whole thing

&owned[0..5] allocates nothing. It is a pointer into the existing buffer and a length, which is why slicing is cheap and why the slice cannot outlive what it borrows.

Take &str, return String

This is the rule of thumb worth internalising immediately:

fn shout(s: &str) -> String {       // good
    s.to_uppercase()
}

fn shout_bad(s: String) -> String { // forces every caller to give up ownership
    s.to_uppercase()
}

A caller with a String can pass it to the first version with &s and keep it. A caller with a literal, which is already a &'static str, can pass it directly. A caller of the second version must either give up their String or clone it, and a caller with a literal must allocate one to call the function at all.

The mechanism that makes &String work where &str is expected is deref coercion: the compiler inserts a conversion because String dereferences to str. The same applies to &Vec<T> where &[T] is expected. So taking the borrowed slice type in a signature costs callers nothing and permits more of them.

The same reasoning generalises: prefer &[T] over &Vec<T>, and prefer &str over &String. Taking &Vec<T> restricts you to callers who have a Vec specifically, and buys nothing in return.

String is UTF-8, so indexing is not what you expect

String and str are guaranteed to hold valid UTF-8, and the operations follow from that guarantee:

let s = String::from("héllo");

s.len();                    // 6, BYTES not characters
s.chars().count();          // 5, Unicode scalar values

let c = s[0];               // error: `String` cannot be indexed by `usize`
let sub = &s[0..2];         // compiles, and PANICS: not a char boundary

There is no Index<usize> for String, deliberately: a byte is not a character, and returning one would be a lie. Range slicing exists and is checked at run time, so slicing across a multi-byte character panics rather than producing invalid UTF-8.

Every character's box is as wide as the bytes it occupies, so é covers two cells and byte 2 is a position inside a character rather than between two of them. There is nothing valid for &s[0..2] to hand back, which is why it panics instead of returning half of a character.

What to write instead:

s.chars().nth(0);           // Option<char>, and O(n)
s.chars().next();           // Option<char>, the idiomatic "first character"
s.char_indices();           // (byte offset, char) pairs, for real work
s.split_whitespace();       // almost always what you actually wanted

One more honest caveat: chars() yields Unicode scalar values, not what a reader would call characters. An emoji with a modifier, or an accent written as a combining mark, is several chars and one grapheme cluster. The standard library deliberately stops at scalar values; grapheme segmentation lives in a crate. So "count the characters" is an under-specified request, and the right answer depends on why you are counting.

Slices of anything, and the length that travels with them

fn sum(values: &[i32]) -> i32 {
    values.iter().sum()
}

let v = vec![1, 2, 3];
let a = [1, 2, 3];
sum(&v);            // Vec coerces
sum(&a);            // array coerces
sum(&v[1..]);       // a sub-slice, no copy

One function accepts a Vec, an array, and any window into either, with no allocation and no generics. That is the payoff for the owned-and-borrowed split, and it is the same idea as &str.

Because the length travels with the pointer, indexing is bounds-checked: values[10] on a slice of three panics with a clear message rather than reading whatever is there. Use values.get(10) when out of range is a normal case, and it returns Option<&i32>.

Practice

1. ▢ Which signature would you write, and why?

   fn count_words(text: String) -> usize
   fn count_words(text: &String) -> usize
   fn count_words(text: &str) -> usize
   

2. ▢ Predict each line.

   let s = String::from("héllo");
   println!("{}", s.len());
   println!("{}", s.chars().count());
   println!("{}", &s[0..2]);
   

3. ▢ Which calls compile?

   fn sum(v: &[i32]) -> i32 { v.iter().sum() }
   
   let vec = vec![1, 2, 3];
   let arr = [1, 2, 3];
   

   • a) sum(&vec)
   • b) sum(&arr)
   • c) sum(&vec[1..])
   • d) sum(vec)

4. ▢ This function takes ownership unnecessarily. Rewrite it and say what changes for its callers.

   fn is_admin(email: String) -> bool {
       email.ends_with("@admin.example.com")
   }
   

fn is_admin(email: &str) -> bool {
    email.ends_with("@admin.example.com")
}

5. ▢ A requirement says "truncate the display name to 10 characters". Name the three things you would have to decide before writing it.

Real-world reps

• [ ] Write the héllo example and make it panic. Then find the byte offset that does work, using char_indices.
• [ ] Write a function taking &[i32] and call it with a Vec, an array, and a sub-slice of each.
• [ ] Tomorrow: find a function in any Rust you can read that takes String or &Vec<T>. Decide whether the borrowed slice type would have worked.

Going further

• The Slice Type: slices as borrowed views, with the string-slice case worked through
• Storing UTF-8 Encoded Text with Strings: why indexing is refused, and what to do instead
• str and String: the two APIs side by side
• slice: every slice method, including get and the chunking family
• Resources

Not landing? Reread the primary source at the top, since this lesson compresses it and compression is where understanding leaks. Check the glossary for any term that felt slippery.

If the lesson itself is unclear rather than the material, that is a defect: open an issue.