Skip to content
Tutorials Center
My learning

Topics

Lesson 48 of 132 ยท Collections and Iterators

String Handling in Depth

Master Rust strings - String versus &str, UTF-8 and byte indexes, chars and bytes, split and trim, find and replace, parse, format!, case conversion, capacity and common Unicode pitfalls.

In String and &str Basics you met the two string types and learned that Rust text is always valid UTF-8. This lesson goes deeper into what that means in daily code: how to walk through text, cut it up, search it, convert it to numbers and back, and avoid the traps that come from the fact that one visible "character" is not always one byte, one char, or one column on screen.

Treat this lesson as a toolbox. Most methods here live on str (the borrowed text type) and therefore work on both &str and String, because a String automatically dereferences to &str. Methods that change the text, like push_str, live on String itself. Strings are essentially a Vec<u8> with a UTF-8 guarantee, so much of what you know about vectors (length, capacity, growth) carries over. The next lesson turns to key-value collections.

A quick recap: who owns the text

  • String owns its text on the heap and can grow.
  • &str borrows text from somewhere: a literal, a String, a part of a file you read.
  • Function parameters that only read text should take &str. A &String converts to &str automatically, so callers can pass either.
Rust Taking &str accepts both kinds of text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

UTF-8: bytes, chars and what you see

Rust strings are UTF-8. Each Unicode scalar value (what Rust calls a char) takes between one and four bytes. Plain English letters take one byte, but accented letters take two, most Asian scripts three, and emoji four. This leads to three different "lengths" for the same text:

Rust Bytes versus chars

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

len() returns the number of bytes, because that is O(1). Counting chars means walking through the text: chars().count() is O(n). There is also a third notion, the grapheme cluster that a human sees as one symbol. The letter รฉ can be one char (U+00E9) or two (e followed by the combining accent U+0301), and many emoji are sequences of several chars joined together.

Rust One symbol, several chars

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Both lines look identical but the strings are not equal. Comparing text for human equality needs Unicode normalization, which the standard library does not include; the unicode-normalization and unicode-segmentation crates do. The standard library also has no way to measure how many terminal columns a string occupies (wide CJK characters take two); that is what the unicode-width crate is for. These crates cannot be used in the in-browser runner, so treat them as read-only advice:

TOML
# Cargo.toml (not runnable here)
[dependencies]
unicode-segmentation = "1"
unicode-width = "0.2"

Why you cannot index a string

In many languages text[0] gives you the first character. In Rust it does not compile:

Rust Indexing a string by number (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The compiler says error[E0277]: the type `str` cannot be indexed by `{integer}` and points at the index with the hint "string indices are ranges of usize", plus a note that you can use .chars().nth() or .bytes().nth() instead. The reasons are practical (the text is UTF-8): word[1] would be the first byte of รฉ, not a character, and finding the n-th character requires scanning. Rust refuses to hide that cost or to return half a character.

You can slice by byte range, but both ends must fall on character boundaries, or the program panics:

Rust Slicing in the middle of a character (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The first two slices print h and รฉ. The third panics with end byte index 2 is not a char boundary; it is inside 'รฉ' (bytes 1..3 of string). Slicing is fine when the indexes come from methods that know the boundaries, such as find or char_indices. Use str::get(range) for a version that returns None instead of panicking:

Rust Safe slicing with get and is_char_boundary

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Walking through text

Three iterators cover most needs:

  • chars() yields each char.
  • bytes() yields each u8.
  • char_indices() yields (byte_index, char) pairs, which gives you valid slicing positions.
Rust chars, bytes and char_indices

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

char_indices shows a at byte 0, รฑ at byte 1 and b at byte 3, because รฑ is two bytes long. Reversing by chars().rev() is correct for plain text but would separate a letter from a following combining accent, so it is not a universal "reverse the symbols" function.

Characters have helpful methods of their own:

Rust Working with char

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

to_digit(10) returns an Option<u32> which is None when the character is not a digit. Prefer these Unicode-aware methods over comparing against hand-written ranges.

Splitting and trimming

Splitting is the foundation of parsing text, and str has a rich family of methods for it. Most return iterators of &str slices: they point into the original text and allocate nothing.

Rust Splitting text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Notice that split(',') keeps the empty field between the two commas, while split_whitespace collapses any run of whitespace and ignores leading and trailing space. lines handles both \n and \r\n. split_once is the cleanest tool for key=value pairs and returns an Option<(&str, &str)>.

Trimming removes unwanted characters at the ends:

Rust Trimming and stripping

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Use strip_prefix rather than starts_with followed by slicing with a hard-coded number: it cannot get the length wrong.

Searching and replacing

Rust find, contains and replace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

find gives the byte index of the first match, so it is safe to use for slicing. All of these methods accept a &str, a char, a closure, or a slice of chars as the "pattern". The standard library has no regular expressions; the regex crate provides them (see text parsing by hand for what you can do without it).

Case conversion

Rust Changing case is a Unicode matter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

to_uppercase follows Unicode rules, so รŸ becomes the two letters SS and the result can be longer than the input. to_ascii_uppercase only touches a to z and leaves รถ alone. Both return a new String; there is no in-place version for general text.

Parsing text into numbers

parse::<T>() converts a &str into any type that implements FromStr. It returns a Result, because the text may not be valid.

Rust parse and its errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Always trim before parsing if the text may have spaces or a trailing newline (as it does when read from standard input): " 5".parse::<i32>() is an error. Handling failure with ? is covered in the ? operator.

Building strings: format!, push and write!

There are several ways to build text. format! is the most readable, push_str and push are the most efficient when you append to an existing String, and write! lets you append formatted text without creating a temporary string:

Rust Building strings efficiently

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The unwrap() on write! is acceptable here because writing into a String cannot fail; it only exists because write! works with many kinds of destinations. The + operator also joins strings: let s = a + &b; moves a and borrows b. It is fine for two pieces but clumsy for more; use format!.

Capacity and performance

A String has a length and a capacity, exactly like a Vec. Appending when the buffer is full reallocates. If you know the final size, reserve it:

Rust String capacity

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

A few performance rules of thumb:

  • Each format! or to_string() call allocates. In a hot loop, reuse one String with clear() and write!/push_str.
  • Splitting and trimming return slices that borrow the original text, so they are free. Only call to_string() or String::from when you must keep the piece after the original is gone.
  • s.chars().count() and s.chars().nth(i) are O(n). Do not call them in a loop that runs over the same string; iterate once instead.
  • s.len() == 0 and s.is_empty() are identical, but the latter reads better.

Bytes and invalid UTF-8

Data from files or networks is bytes, and it might not be valid UTF-8. String::from_utf8 checks it and returns a Result; String::from_utf8_lossy replaces bad bytes with the replacement character U+FFFD. A byte string literal b"..." is a &[u8; N].

Rust From bytes to text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Never use String::from_utf8_unchecked or str::from_utf8_unchecked to "save time". They are unsafe, and giving them invalid UTF-8 breaks the guarantee that every other string method relies on. The checked versions are fast.

Common mistakes

  • Indexing with a number. Use chars().nth(i), char_indices, or get(range).
  • Assuming len() is the number of characters. It is the number of bytes.
  • Forgetting to trim before parse. A trailing \n makes numeric parsing fail.
  • Comparing user-visible text without normalization or case folding. Use eq_ignore_ascii_case only for ASCII data such as protocol keywords.
  • Cloning slices unnecessarily. Store &str pieces while the source lives; allocate only when ownership is required.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does "ๆ—ฅๆœฌ่ชž".len() return?

    len counts UTF-8 bytes. Each of these three characters takes three bytes, so the length is 9. chars().count() would give 3.
  2. 2. Why does let c = word[0]; not compile for a String?

    Rust refuses integer indexing on strings because a byte position is not a character position and finding the n-th character is not O(1).
  3. 3. Which call splits key=value=more into just key and value=more?

    split_once cuts at the first separator only and returns Option<(&str, &str)>. split would return three pieces.
  4. 4. What does " 5".parse::<i32>() return?

    parse does not ignore whitespace. Call trim() first when the text might contain spaces or a newline.
  5. 5. What is the cheapest way to append many formatted pieces to one String?

    write! and push_str append in place. format! and + create temporary strings and allocate each time.

Summary

  • String owns heap text; &str borrows it. Accept &str in function parameters.
  • Text is UTF-8: len() counts bytes, chars().count() counts scalar values, and a visible symbol can span several chars.
  • No integer indexing. Slice by byte range at valid boundaries, use get, char_indices or chars().nth.
  • split, split_whitespace, lines, split_once, trim, strip_prefix return borrowed slices and do not allocate.
  • find, contains, replace, matches search; to_uppercase is Unicode-aware, to_ascii_uppercase is not.
  • parse::<T>() returns a Result; trim first.
  • Build text with push_str, push, write! and format!; use with_capacity when the size is known.
  • Convert bytes with String::from_utf8 (checked) or from_utf8_lossy.

Next: HashMap and HashSet