Strings

There are two types of strings in Rust: String and &str.

A String is stored as a vector of bytes (Vec<u8>), but guaranteed to
always be a valid UTF-8 sequence. String is heap allocated, growable and not
null terminated.

&str is a slice (&[u8]) that always points to a valid UTF-8 sequence, and
can be used to view into a String, just like &[T] is a view into Vec<T>.

  1. fn main() {
  2.     // (all the type annotations are superfluous)
  3.     // A reference to a string allocated in read only memory
  4.     let pangram: &'static str = "the quick brown fox jumps over the lazy dog";
  5.     println!("Pangram: {}", pangram);
  7.     // Iterate over words in reverse, no new string is allocated
  8.     println!("Words in reverse");
  9.     for word in pangram.split_whitespace().rev() {
  10.         println!("> {}", word);
  11.     }
  13.     // Copy chars into a vector, sort and remove duplicates
  14.     let mut chars: Vec<char> = pangram.chars().collect();
  15.     chars.sort();
  16.     chars.dedup();
  18.     // Create an empty and growable `String`
  19.     let mut string = String::new();
  20.     for c in chars {
  21.         // Insert a char at the end of string
  22.         string.push(c);
  23.         // Insert a string at the end of string
  24.         string.push_str(", ");
  25.     }
  27.     // The trimmed string is a slice to the original string, hence no new
  28.     // allocation is performed
  29.     let chars_to_trim: &[char] = &[' ', ','];
  30.     let trimmed_str: &str = string.trim_matches(chars_to_trim);
  31.     println!("Used characters: {}", trimmed_str);
  33.     // Heap allocate a string
  34.     let alice = String::from("I like dogs");
  35.     // Allocate new memory and store the modified string there
  36.     let bob: String = alice.replace("dog", "cat");
  38.     println!("Alice says: {}", alice);
  39.     println!("Bob says: {}", bob);
  40. }

More str/String methods can be found under the
std::str and
std::string
modules

Literals and escapes

There are multiple ways to write string literals with special characters in them.
All result in a similar &str so it’s best to use the form that is the most
convenient to write. Similarly there are multiple ways to write byte string literals,
which all result in &[u8; N].

Generally special characters are escaped with a backslash character: \.
This way you can add any character to your string, even unprintable ones
and ones that you don’t know how to type. If you want a literal backslash,
escape it with another one: \\

String or character literal delimiters occuring within a literal must be escaped: "\"", '\''.

  1. fn main() {
  2.     // You can use escapes to write bytes by their hexadecimal values...
  3.     let byte_escape = "I'm writing \x52\x75\x73\x74!";
  4.     println!("What are you doing\x3F (\\x3F means ?) {}", byte_escape);
  6.     // ...or Unicode code points.
  7.     let unicode_codepoint = "\u{211D}";
  8.     let character_name = "\"DOUBLE-STRUCK CAPITAL R\"";
  10.     println!("Unicode character {} (U+211D) is called {}",
  11.                 unicode_codepoint, character_name );
  14.     let long_string = "String literals
  15.                         can span multiple lines.
  16.                         The linebreak and indentation here ->\
  17.                         <- can be escaped too!";
  18.     println!("{}", long_string);
  19. }

Sometimes there are just too many characters that need to be escaped or it’s just
much more convenient to write a string out as-is. This is where raw string literals come into play.

```rust, editable
fn main() {
let raw_str = r”Escapes don’t work here: \x3F \u{211D}”;
println!(“{}”, raw_str);

  1. // If you need quotes in a raw string, add a pair of #s
  2. let quotes = r#"And then I said: "There is no escape!""#;
  3. println!("{}", quotes);
  5. // If you need "# in your string, just use more #s in the delimiter.
  6. // There is no limit for the number of #s you can use.
  7. let longer_delimiter = r###"A string with "# in it. And even "##!"###;
  8. println!("{}", longer_delimiter);

}

  2. Want a string that's not UTF-8? (Remember, `str` and `String` must be valid UTF-8)
  3. Or maybe you want an array of bytes that's mostly text? Byte strings to the rescue!
  5. ```rust, editable
  6. use std::str;
  8. fn main() {
  9.     // Note that this is not actually a &str
  10.     let bytestring: &[u8; 20] = b"this is a bytestring";
  12.     // Byte arrays don't have Display so printing them is a bit limited
  13.     println!("A bytestring: {:?}", bytestring);
  15.     // Bytestrings can have byte escapes...
  16.     let escaped = b"\x52\x75\x73\x74 as bytes";
  17.     // ...but no unicode escapes
  18.     // let escaped = b"\u{211D} is not allowed";
  19.     println!("Some escaped bytes: {:?}", escaped);
  22.     // Raw bytestrings work just like raw strings
  23.     let raw_bytestring = br"\u{211D} is not escaped here";
  24.     println!("{:?}", raw_bytestring);
  26.     // Converting a byte array to str can fail
  27.     if let Ok(my_str) = str::from_utf8(raw_bytestring) {
  28.         println!("And the same as text: '{}'", my_str);
  29.     }
  31.     let quotes = br#"You can also use "fancier" formatting, \
  32.                     like with normal raw strings"#;
  34.     // Bytestrings don't have to be UTF-8
  35.     let shift_jis = b"\x82\xe6\x82\xa8\x82\xb1\x82"; // "ようこそ" in SHIFT-JIS
  37.     // But then they can't always be converted to str
  38.     match str::from_utf8(shift_jis) {
  39.         Ok(my_str) => println!("Conversion successful: '{}'", my_str),
  40.         Err(e) => println!("Conversion failed: {:?}", e),
  41.     };
  42. }

For conversions between character encodings check out the encoding crate.

A more detailed listing of the ways to write string literals and escape characters
is given in the ‘Tokens’ chapter of the Rust Reference.