Collections

# Collections

---
## Using Arrays

Arrays (`[T; N]`) have a fixed size.

```rust []
fn main() {
    let array = [1, 2, 3, 4, 5];
    println!("array = {:?}", array);
}
```

<br>

---
## Building the array at runtime.

How do you know how many 'slots' you've used?

```rust []
fn main() {
    let mut array = [0u8; 10];
    for idx in 0..5 {
        array[idx] = idx as u8;
    }
    println!("array = {:?}", array);
}
```

<br>

---
## Slices

A view into *some other data*. Written as `&[T]` (or `&mut [T]`).

```rust [1-8|6]
fn main() {
    let mut array = [0u8; 10];
    for idx in 0..5 {
        array[idx] = idx as u8;
    }
    let data = &array[0..5];
    println!("data = {:?}", data);
}
```

<br>

<figure>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">


<svg width="331pt" height="118pt"
 viewBox="0.00 0.00 330.98 118.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 114)">
<title>%3</title>
<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-114 326.9835,-114 326.9835,4 -4,4"/>

<g id="node1" class="node">
<title>data:</title>
<text text-anchor="middle" x="28.9835" y="-86.1" font-family="Times,serif" font-size="18.00" fill="#000000">data:</text>
</g>

<g id="node2" class="node">
<title>array:</title>
<text text-anchor="middle" x="28.9835" y="-13.1" font-family="Times,serif" font-size="18.00" fill="#000000">array:</text>
</g>

<g id="edge1" class="edge">
<title>data:->array:</title>
<path fill="none" stroke="#ffffff" d="M28.9835,-73.4551C28.9835,-65.3828 28.9835,-55.6764 28.9835,-46.6817"/>
<polygon fill="#ffffff" stroke="#ffffff" points="32.4836,-46.5903 28.9835,-36.5904 25.4836,-46.5904 32.4836,-46.5903"/>
</g>

<g id="node3" class="node">
<title>array</title>
<polygon fill="#add8e6" stroke="#0000ff" points="92.9835,-.5 92.9835,-36.5 322.9835,-36.5 322.9835,-.5 92.9835,-.5"/>
<text text-anchor="middle" x="104.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0</text>
<polyline fill="none" stroke="#0000ff" points="115.9835,-.5 115.9835,-36.5 "/>
<text text-anchor="middle" x="127.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">1</text>
<polyline fill="none" stroke="#0000ff" points="138.9835,-.5 138.9835,-36.5 "/>
<text text-anchor="middle" x="150.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">2</text>
<polyline fill="none" stroke="#0000ff" points="161.9835,-.5 161.9835,-36.5 "/>
<text text-anchor="middle" x="173.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">3</text>
<polyline fill="none" stroke="#0000ff" points="184.9835,-.5 184.9835,-36.5 "/>
<text text-anchor="middle" x="196.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">4</text>
<polyline fill="none" stroke="#0000ff" points="207.9835,-.5 207.9835,-36.5 "/>
<text text-anchor="middle" x="219.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0</text>
<polyline fill="none" stroke="#0000ff" points="230.9835,-.5 230.9835,-36.5 "/>
<text text-anchor="middle" x="242.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0</text>
<polyline fill="none" stroke="#0000ff" points="253.9835,-.5 253.9835,-36.5 "/>
<text text-anchor="middle" x="265.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0</text>
<polyline fill="none" stroke="#0000ff" points="276.9835,-.5 276.9835,-36.5 "/>
<text text-anchor="middle" x="288.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0</text>
<polyline fill="none" stroke="#0000ff" points="299.9835,-.5 299.9835,-36.5 "/>
<text text-anchor="middle" x="311.4835" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0</text>
</g>

<g id="node4" class="node">
<title>data</title>
<polygon fill="#add8e6" stroke="#0000ff" points="73.9835,-73.5 73.9835,-109.5 217.9835,-109.5 217.9835,-73.5 73.9835,-73.5"/>
<text text-anchor="middle" x="103.7591" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">ptr</text>
<polyline fill="none" stroke="#0000ff" points="133.5347,-73.5 133.5347,-109.5 "/>
<text text-anchor="middle" x="175.5346" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">len = 5</text>
</g>

<g id="edge2" class="edge">
<title>data:p0->array:f0</title>
<path fill="none" stroke="#000000" d="M103.9835,-73.5C103.9835,-61.0382 103.9835,-55.6592 103.9835,-46.6281"/>
<polygon fill="#000000" stroke="#000000" points="107.4836,-46.5 103.9835,-36.5 100.4836,-46.5 107.4836,-46.5"/>
</g>
</g>
</svg>
</figure>

Note:
Slices are *unsized* types and can only be access via a reference. This reference is a 'fat reference' because instead of just containing a pointer to the start of the data, it also contains a length value.

---
## Vectors

`Vec` is a growable, heap-allocated, array-like type.

```rust []
fn process_data(input: &[u32]) {
    let mut vector = Vec::new();
    for value in input {
        vector.push(value * 2);
    }
    println!("vector = {:?}, first = {}", vector, vector[0]);
}

fn main() { process_data(&[1, 2, 3]); }
```

<br>

Note:

The green block of data is heap allocated.

---
## There's a macro short-cut too...

```rust
fn main() {
    let mut vector = vec![1, 2, 3, 4];
}
```

<br>

Check out the [docs](https://doc.rust-lang.org/std/vec/struct.Vec.html)!

---
## Features of Vec

* Growable (will re-allocate if needed)
* Can borrow it as a `&[T]` slice
* Can access any element (`vector[i]`) quickly
* Can push/pop from the back easily

---
## Downsides of Vec

* Not great for insertion
* Everything must be of the same type
* Indices are always `usize`

---
## String Slices

The basic string types in Rust are all UTF-8.

A *String Slice* (`&str`) is an immutable view on to some valid UTF-8 bytes

```rust
fn main() {
    let bytes = [0xC2, 0xA3, 0x39, 0x39, 0x21];
    let s = std::str::from_utf8(&bytes).unwrap();
    println!("{}", s);
}
```

<br>

<figure>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">


<svg width="315pt" height="118pt"
 viewBox="0.00 0.00 315.22 118.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 114)">
<title>%3</title>
<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-114 311.219,-114 311.219,4 -4,4"/>

<g id="node1" class="node">
<title>s:</title>
<text text-anchor="middle" x="29.4974" y="-86.1" font-family="Times,serif" font-size="18.00" fill="#000000">s:</text>
</g>

<g id="node2" class="node">
<title>bytes:</title>
<text text-anchor="middle" x="29.4974" y="-13.1" font-family="Times,serif" font-size="18.00" fill="#000000">bytes:</text>
</g>

<g id="edge1" class="edge">
<title>s:->bytes:</title>
<path fill="none" stroke="#ffffff" d="M29.4974,-73.4551C29.4974,-65.3828 29.4974,-55.6764 29.4974,-46.6817"/>
<polygon fill="#ffffff" stroke="#ffffff" points="32.9975,-46.5903 29.4974,-36.5904 25.9975,-46.5904 32.9975,-46.5903"/>
</g>

<g id="node3" class="node">
<title>bytes</title>
<polygon fill="#add8e6" stroke="#0000ff" points="81.7758,-.5 81.7758,-36.5 307.219,-36.5 307.219,-.5 81.7758,-.5"/>
<text text-anchor="middle" x="104.9441" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0xC2</text>
<polyline fill="none" stroke="#0000ff" points="128.1124,-.5 128.1124,-36.5 "/>
<text text-anchor="middle" x="151.6657" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0xA3</text>
<polyline fill="none" stroke="#0000ff" points="175.219,-.5 175.219,-36.5 "/>
<text text-anchor="middle" x="197.219" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x39</text>
<polyline fill="none" stroke="#0000ff" points="219.219,-.5 219.219,-36.5 "/>
<text text-anchor="middle" x="241.219" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x39</text>
<polyline fill="none" stroke="#0000ff" points="263.219,-.5 263.219,-36.5 "/>
<text text-anchor="middle" x="285.219" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x21</text>
</g>

<g id="node4" class="node">
<title>s</title>
<polygon fill="#add8e6" stroke="#0000ff" points="74.4974,-73.5 74.4974,-109.5 218.4974,-109.5 218.4974,-73.5 74.4974,-73.5"/>
<text text-anchor="middle" x="104.273" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">ptr</text>
<polyline fill="none" stroke="#0000ff" points="134.0486,-73.5 134.0486,-109.5 "/>
<text text-anchor="middle" x="176.0485" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">len = 5</text>
</g>

<g id="edge2" class="edge">
<title>s:p0->bytes:f0</title>
<path fill="none" stroke="#000000" d="M104.4974,-73.5C104.4974,-61.0382 104.4974,-55.6592 104.4974,-46.6281"/>
<polygon fill="#000000" stroke="#000000" points="107.9975,-46.5 104.4974,-36.5 100.9975,-46.5 107.9975,-46.5"/>
</g>
</g>
</svg>
</figure>

Note:

A string slice is tied to the lifetime of the data that it refers to.

---
## String Literals

* String Literals produce a string slice "with static lifetime"
* Points at some bytes that live in read-only memory with your code

```rust []
fn main() {
    let s: &'static str = "Hello!";
    println!("s = {}", s);
}
```

<br>

Note:

The lifetime annotation of `'static` just means the string slice lives forever
and never gets destroyed. We wrote out the type in full so you can see it - you
can emit it on variable declarations.

There's a second string literal in this program. Can you spot it?

(It's the format string in the call to `println!`)

---
## Strings ([docs](https://doc.rust-lang.org/std/string/struct.String.html))

* A growable collection of `char`
* Actually stored as a `Vec<u8>`, with UTF-8 encoding
* You cannot access characters by index (only bytes)
  * But you never really want to anyway

```rust
fn main() {
    let string = String::from("Hello!");
}
```

<br>

<figure>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">


<svg width="342pt" height="118pt"
 viewBox="0.00 0.00 342.04 118.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 114)">
<title>%3</title>
<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-114 338.0444,-114 338.0444,4 -4,4"/>

<g id="node1" class="node">
<title>string:</title>
<text text-anchor="middle" x="30.9995" y="-86.1" font-family="Times,serif" font-size="18.00" fill="#000000">string:</text>
</g>

<g id="node2" class="node">
<title>_inner</title>
<polygon fill="#00cd00" stroke="#0000ff" points="73.9546,-.5 73.9546,-36.5 334.0444,-36.5 334.0444,-.5 73.9546,-.5"/>
<text text-anchor="middle" x="95.9546" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x48</text>
<polyline fill="none" stroke="#0000ff" points="117.9546,-.5 117.9546,-36.5 "/>
<text text-anchor="middle" x="139.9546" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x65</text>
<polyline fill="none" stroke="#0000ff" points="161.9546,-.5 161.9546,-36.5 "/>
<text text-anchor="middle" x="183.5619" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x6c</text>
<polyline fill="none" stroke="#0000ff" points="205.1692,-.5 205.1692,-36.5 "/>
<text text-anchor="middle" x="226.7765" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x6c</text>
<polyline fill="none" stroke="#0000ff" points="248.3838,-.5 248.3838,-36.5 "/>
<text text-anchor="middle" x="269.2141" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x6f</text>
<polyline fill="none" stroke="#0000ff" points="290.0444,-.5 290.0444,-36.5 "/>
<text text-anchor="middle" x="312.0444" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">0x21</text>
</g>

<g id="node3" class="node">
<title>string</title>
<polygon fill="#add8e6" stroke="#0000ff" points="79.9995,-73.5 79.9995,-109.5 223.9995,-109.5 223.9995,-73.5 79.9995,-73.5"/>
<text text-anchor="middle" x="95.7751" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">ptr</text>
<polyline fill="none" stroke="#0000ff" points="111.5507,-73.5 111.5507,-109.5 "/>
<text text-anchor="middle" x="139.0506" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">len = 6</text>
<polyline fill="none" stroke="#0000ff" points="166.5505,-73.5 166.5505,-109.5 "/>
<text text-anchor="middle" x="195.2124" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">cap = 6</text>
</g>

<g id="edge1" class="edge">
<title>string:p0->_inner:f0</title>
<path fill="none" stroke="#000000" d="M95.9995,-73.5C95.9995,-61.0382 95.9995,-55.6592 95.9995,-46.6281"/>
<polygon fill="#000000" stroke="#000000" points="99.4996,-46.5 95.9995,-36.5 92.4996,-46.5 99.4996,-46.5"/>
</g>
</g>
</svg>
</figure>

Note:

The green block of data is heap allocated.

---
## Making a String

```rust [1-7|2|3|4|5|6]
fn main() {
    let s1 = "String literal up-conversion".to_string();
    let s2: String = "Into also works".into();
    let s3 = String::from("Or using from");
    let s4 = format!("String s1 is {:?}", s1);
    let s5 = String::new(); // empty
}
```

---
## Appending to a String

```rust [1-7|2|3|4|5-6]
fn main() {
    let mut start = "Mary had a ".to_string();
    start.push_str("little");
    let rhyme = start + " lamb";
    println!("rhyme = {}", rhyme);
    // println!("start = {}", start);
}
```

---
## Joining pieces of String

```rust [1-5|2|3|4]
fn main() {
    let pieces = ["Mary", "had", "a", "little", "lamb"];
    let rhyme = pieces.join(" ");
    println!("Rhyme = {}", rhyme);
}
```

---
## VecDeque ([docs](https://doc.rust-lang.org/std/collections/struct.VecDeque.html))

A ring-buffer, also known as a Double-Ended Queue:

```rust []
use std::collections::VecDeque;
fn main() {
    let mut queue = VecDeque::new();
    queue.push_back(1);
    queue.push_back(2);
    queue.push_back(3);
    println!("first: {:?}", queue.pop_front());
    println!("second: {:?}", queue.pop_front());
    println!("third: {:?}", queue.pop_front());
}
```

---
## Features of VecDeque

* Growable (will re-allocate if needed)
* Can access any element (`queue[i]`) quickly
* Can push/pop from the front or back easily

---
## Downsides of VecDeque

* Cannot borrow it as a single `&[T]` slice without moving items around
* Not great for insertion in the middle
* Everything must be of the same type
* Indices are always `usize`

---
## HashMap ([docs](https://doc.rust-lang.org/std/collections/struct.HashMap.html))

If you want to store *Values* against *Keys*, Rust has `HashMap<K, V>`.

Note that the keys must be all the same type, and the values must be all the same type.

```rust
use std::collections::HashMap;
fn main() {
    let mut map = HashMap::new();
    map.insert("Triangle", 3);
    map.insert("Square", 4);
    println!("Triangles have {:?} sides", map.get("Triangle"));
    println!("Triangles have {:?} sides", map["Triangle"]);
    println!("map {:?}", map);
}
```

Note:
The index operation will panic if the key is not found, just like with slices and arrays if the index is out of bounds. Get returns an `Option`.

If you run it a few times, the result will change because it is un-ordered.

---
## The Entry API

What if you want to *update an existing value* __OR__ *add a new value if it's not there yet*?

`HashMap` has the *Entry API*:

```rust ignore
enum Entry<K, V> {
    Occupied(...),
    Vacant(...),
}

fn entry(&mut self, key: K) -> Entry<K, V> {
    ...
}
```

---
## Entry API Example

```rust []
use std::collections::HashMap;
 
fn update_connection(map: &mut HashMap<i32, u64>, id: i32) {
    map.entry(id)
        .and_modify(|v| *v = *v + 1)
        .or_insert(1);
}
 
fn main() {
    let mut map = HashMap::new();
    update_connection(&mut map, 100);
    update_connection(&mut map, 200);
    update_connection(&mut map, 100);
    println!("{:?}", map);
}
```

---
## Features of HashMap

* Growable (will re-allocate if needed)
* Can access any element (`map[i]`) quickly
* Great at insertion
* Can choose the *Key* and *Value* types independently

---
## Downsides of HashMap

* Cannot borrow it as a single `&[T]` slice
* Everything must be of the same type
* Unordered

---
## BTreeMap ([docs](https://doc.rust-lang.org/std/collections/struct.BTreeMap.html))

Like a `HashMap`, but kept in-order.

```rust
use std::collections::BTreeMap;
fn main() {
    let mut map = BTreeMap::new();
    map.insert("Triangle", 3);
    map.insert("Square", 4);
    println!("Triangles have {:?} sides", map.get("Triangle"));
    println!("Triangles have {:?} sides", map["Triangle"]);
    println!("map {:?}", map);
}
```

---
## Features of BTreeMap

* Growable (will re-allocate if needed)
* Can access any element (`map[i]`) quickly
* Great at insertion
* Can choose the *Key* and *Value* types independently
* Ordered

---
## Downsides of BTreeMap

* Cannot borrow it as a single `&[T]` slice
* Everything must be of the same type
* Slower than a `HashMap`

---
## Sets

We also have [HashSet](https://doc.rust-lang.org/std/collections/struct.HashSet.html) and [BTreeSet](https://doc.rust-lang.org/std/collections/struct.BTreeSet.html).

Just sets the `V` type parameter to `()`!

---

| Type         | Owns | Grow |  Index  | Slice | Cheap Insert |
| :----------- | :--: | :--: | :-----: | :---: | :----------: |
| Array        |  ✅  |  ❌  | `usize` |  ✅   |      ❌      |
| Slice        |  ❌  |  ❌  | `usize` |  ✅   |      ❌      |
| Vec          |  ✅  |  ✅  | `usize` |  ✅   |      ↩       |
| String Slice |  ❌  |  ❌  |   🤔   |  ✅   |      ❌      |
| String       |  ✅  |  ✅  |   🤔   |  ✅   |      ↩       |
| VecDeque     |  ✅  |  ✅  | `usize` |  🤔  |    ↪ / ↩     |
| HashMap      |  ✅  |  ✅  |   `T`   |  ❌   |      ✅      |
| BTreeMap     |  ✅  |  ✅  |   `T`   |  ❌   |      ✅      |

Note:

The 🤔 for indexing string slices and Strings is because the index is a byte
offset and the system will panic if you try and chop a UTF-8 encoded character
in half.

The 🤔 for indexing VecDeque is because you might have to get the contents in
two pieces (i.e. as two disjoint slices) due to wrap-around.

Technically you *can* insert into the middle of a Vec or a String, but we're
talking about 'cheap' insertions that don't involve moving too much stuff
around.