8. Common Collections

Learning objectives

• Identify the 3 most common collection types in the Rust standard library
• Know where collections are stored in memory and why it’s important
• Be able to access elements of a collection and iterate over all elements
• Know where to find information about Rust’s collection types and when to use them

Intro

What is a ‘collection’?

Collections are data structures for storing multiple values.

Example: i8 is a single 8-bit integer value. A vector can store multiple i8s together.

What about arrays and tuples?

• Yes, arrays and tuples can hold multiple values
• But, they are stored on the stack while collections are stored on the heap
  • array, tuple: fixed size, known at compile time
  • collections: variable size, not known at compile time

Collections can grow and shrink while the program is running & their size does not need to be known at compile time.

Common collections

• vector: collection of numbers
• string: collection of characters
• hash map: collection of key-value pairs

Vectors

Creating vectors

You can create a vector with new and add values with .push

let mut v: Vec<i32> = Vec::new();

v.push(1);
v.push(2);
v.push(3);

Or you can create it directly with vec!

let v = vec![1, 2, 3];

Note the mut in the first case.

Access elements

let v = vec![1, 2, 3];

[]

let first_element: &i32 = &v[0];

get

let first_element: Option<&i32> = v.get(0);

First method: should be familiar

Second method: returns an Option type

Having 2 methods means you can control how your program behaves when using an out-of-range index.

The first method crashes the program.

The second method allows you to handle having Some(value) or None. Maybe you want to

Access elements - ownership & borrowing

This program will not compile

let mut v = vec![1, 2, 3, 4, 5];

let first = &v[0]; // immutable borrow

v.push(6); // mutable borrow

println!("The first element is: {first}"); // immutable borrow used

We’re referencing the first element but updating at the end so you might thing this shoudl be fine.

The problem though is that Rust stores vectors in one continuous block of memory. So adding another element may require copying the vector to a new memory location. If that happens, then our reference to the first element will point to a section of deallocated memory.

Iteration

Immutable vector, immutable references

let v = vec![1, 2, 3];
for i in &v {
  println!("{i}");
}
// v = [1, 2, 3]
// output: 1, 2, 3

Mutable vector, mutable references

let mut v = vec![1, 2, 3];
for i in &mut v {
  *i += 1;
}
// v = [2, 3, 4]

for i in &v {
    println!("{i}");
}

// output: 2, 3, 4

Note the use of the dereference operator *. We must use this to change the value the mutable reference refers to.

Vectors with multiple types

enum

enum SpreadsheetCell {
  Int(i32),
  Float(f64),
  Text(String),
}

let row = vec![
  SpreadsheetCell::Int(3),
  SpreadsheetCell::Float(10.12),
];

struct

struct Ex {
    number: i32,
    string: String,
}

let v = vec![
    Ex {number: 1, string: String::from("string")},
    Ex {number: 1, string: String::from("2nd string")},
];

Elements of vectors must be all of the same type. To store mutliple types, we need a container that can hold multiple types.

Strings

What are Strings?

• Collection of bytes
• In Rust standard library
• Built around vectors
• UTF-8

String vs str

String

• standard library
• dynamic size
• vector

str

• built into the language
• fixed size
• slice of the vector

When referring to ‘strings’ in Rust, people can mean either a String or str (more typically &str). But they are different types.

I’ve listed a few of the similarities and differences here and listed a few reference at the bottom. This is still a bit confusing for me but the references helped so I suggest you read them.

Creating Strings

You can create a String with new and add values with .push_str

let mut s = String::new();
s.push_str("this is");
s.push_str("a string");

Or you can create it directly

let s1 = String::from("this is a string");
let s2 = "this is a string".to_string();

Combining Strings

+

let s1 = String::from("this is ");
let s2 = String::from("a string");

let s3 = s1 + &s2;

format!

let s1 = String::from("this is");
let s2 = String:: from("a string")

let s3 = format!("{s1} ... {s2}!") // "this is ... a string!"

Using the + operator, note that we use a reference to the 2nd string: &s2. This is because how add is defined, see the book for more details.

Access elements

let s = String::from("this is a string")
let first_char = s[0];

Computer says no GIF

Since Strings are built on top of vectors, we may want to get the first character like we would the first element of a vector. But we can’t do that.

The reason why is because of how Rust stores strings.

Internal representation of Strings

• Wrapper around Vec<u8>
• Vector of bytes
• UTF-8

let hello = String::from("hello");
let konichiwa = String::from("こんにちは");

println!("Hello bytes: {}", hello.len()); // 5
println!("Konichiwa bytes:{}", konichiwa.len()); // 15

To understand why we can’t index into strings we need to know how Strings are represented in Rust. Rust stores strings as a vector of bytes, encoded in UTF-8.

Example: the String ‘hello’ in English and Japanese.

On the surface, it looks like they would both have legnth 5. But, because of how strings are stored, the lengths are very different.

Human languages have a lot of variety so there is no ‘correct’ way to index into strings. The best we can do is take slices of a string …

String slices

let hello = String::from("hello");
println!("Hello first: {}", &hello[0..1]); // h

let konichiwa = String::from("こんにちは");
println!("Konichiwa first: {}", &konichiwa[0..1]); //error

While we can’t index into strings at specific indices, we can use a range of indices to get string slices.

So if we specify the range to get the first element, we get ‘h’ as expected.

However, that doesn’t always work. Some languages need more than 1 byte to store a character. We need to know the language so we can slice at the boundaries of characters. Otherwise we get an error.

Iteration

.chars()

let hello = String::from("hello");
let konichiwa = String::from("こんにちは");

for c in hello.chars() {
    println!("{c}");
} // h, e, l, l, o

for c in konichiwa.chars() {
    println!("{c}");
} // こ, ん, に, ち, は

.bytes()

let hello = String::from("hello");
let konichiwa = String::from("こんにちは");

for b in hello.bytes() {
    println!("{b}");
} // 104, 101, ...

for b in konichiwa.bytes() {
    println!("{b}");
} // 227, 129, ...

Hash maps

The last collection for today is the hash map, which stores key-value pairs.

Creating hash maps

You can create a hash map with new and add values with .insert

use std::collections::HashMap;

let mut scores = HashMap::new();

scores.insert(String::from("Red"), 10);
scores.insert(String::from("Blue"), 20);

Note the use here. Since hash maps are not used as often as vectors or strings we need to explicitly import them.

Access elements

use std::collections::HashMap;

let mut scores = HashMap::new();

scores.insert(String::from("Red"), 10);
scores.insert(String::from("Blue"), 20);

let blue_team = String::from("Blue");
let blue_score = scores.get(&blue_team).copied().unwrap_or(0); // 20

• get returns an Option<&V>
• copied returns an Option<i32> instead of Option<&i32>
• unwrap_or returns 0 if there is no entry for "Blue"

The extra calls after get here are to get at the underlying value.

• get returns an Optionwe copy it to get an Option of type i32

Iteration

use std::collections::HashMap;

let mut scores = HashMap::new();

scores.insert(String::from("Red"), 10);
scores.insert(String::from("Blue"), 20);

for (key, value) in &scores {
  println!("{key}: {value}");
} // Red: 10, Blue: 20

For iteration we loop across the key-value pairs.

Note: the order of they key-value pairs when iterating is arbitrary. We can’t assume it will be in the same order they were inserted in.

Updating - overwrite

use std::collections::HashMap;

let mut scores = HashMap::new()

scores.insert(String::from("Blue"), 10);
scores.insert(String::from("Blue"), 25);

We can update a hash map in 3 different ways. The first is to just overwrite the existing value.

Because “Blue” is already a key, the 2nd insert will change the value. Each key is unique.

Updating - add if not present

use std::collections::HashMap;

let mut scores = HashMap::new();
scores.insert(String::from("Blue"), 10);

scores.entry(String::from("Red")).or_insert(50); // added
scores.entry(String::from("Blue")).or_insert(50); // skipped

Sometimes we may want to add a key-value pair only if that key doesn’t exist yet.

We do that with entry and or_insert. In this example, the "Red": 50 will be inserted and the “Blue” entry will be left as is.

Updating - modify existing value

use std::collections::HashMap;

let text = "hello world wonderful world";

let mut map = HashMap::new();

for word in text.split_whitespace() {
  let count = map.entry(word).or_insert(0);
  *count += 1;
}
println!("{map:?}"); // {"world": 2, "hello": 1, "wonderful": 1}

Resources

Collections Documentation

The last thing I want to point out is the documentation on collections. We’ve covered the 3 most common collections but there are more in the Rust standard library.

The documentation page explains the other types of collections, all the methods for each collection, and what I think is particularly useful: some guidance on when to use which type of collection.