Storing Lists of Values with Vectors

The first collection type we'll look at is Vec<T>, also known as a vector. Vectors allow you to store more than one value in a single data structure that puts all the values next to each other in memory. Vectors can only store values of the same type. They are useful when you have a list of items, such as the lines of text in a file or the prices of items in a shopping cart.

Creating a New Vector

To create a new, empty vector, we call the Vec.new function:

fn main() {
    let v: Vec<Int> = Vec.new()
}

Note that we added a type annotation here. Because we aren't inserting any values into this vector, Oxide doesn't know what kind of elements we intend to store. This is an important point. Vectors are implemented using generics; we'll cover how to use generics with your own types in a later chapter. For now, know that the Vec<T> type provided by the standard library can hold any type. When we create a vector to hold a specific type, we can specify the type within angle brackets. In the example above, we've told Oxide that the Vec<T> in v will hold elements of the Int type.

More often, you'll create a Vec<T> with initial values, and Oxide will infer the type of value you want to store, so you rarely need to do this type annotation. Oxide provides the vec! macro, which will create a new vector that holds the values you give it:

fn main() {
    let v = vec![1, 2, 3]
}

Because we've given initial Int values, Oxide can infer that the type of v is Vec<Int>, and the type annotation isn't necessary. Next, we'll look at how to modify a vector.

Rust comparison: The main syntax difference is using dot notation for the constructor: Vec.new() instead of Vec::new(). The vec! macro works identically.

#![allow(unused)]
fn main() {
// Rust
let v: Vec<i32> = Vec::new();
let v = vec![1, 2, 3];
}

Updating a Vector

To create a vector and then add elements to it, we can use the push method:

fn main() {
    var v: Vec<Int> = Vec.new()
    v.push(5)
    v.push(6)
    v.push(7)
    v.push(8)
}

As with any variable, if we want to be able to change its value, we need to make it mutable using the var keyword. The numbers we place inside are all of type Int, and Oxide infers this from the data, so we don't need the Vec<Int> annotation.

Rust comparison: Oxide uses var instead of let mut for mutable bindings.

#![allow(unused)]
fn main() {
// Rust
let mut v: Vec<i32> = Vec::new();
v.push(5);
v.push(6);
}

Reading Elements of Vectors

There are two ways to reference a value stored in a vector: via indexing or by using the get method. In the following examples, we've annotated the types of the values that are returned from these functions for extra clarity.

fn main() {
    let v = vec![1, 2, 3, 4, 5]

    let third: &Int = &v[2]
    println!("The third element is \(third)")

    let third: Int? = v.get(2).copied()
    match third {
        Some(value) -> println!("The third element is \(value)"),
        null -> println!("There is no third element."),
    }
}

Note a few details here. We use the index value of 2 to get the third element because vectors are indexed by number, starting at zero. Using & and [] gives us a reference to the element at the index value. When we use the get method with the index passed as an argument, we get an Option<&T> (which in Oxide we can think of as (&T)?) that we can use with match.

Oxide provides these two ways to reference an element so that you can choose how the program behaves when you try to use an index value outside the range of existing elements. As an example, let's see what happens when we have a vector of five elements and then we try to access an element at index 100 with each technique:

fn main() {
    let v = vec![1, 2, 3, 4, 5]

    let doesNotExist = &v[100]        // This will panic!
    let doesNotExist = v.get(100)     // This returns null
}

When we run this code, the first [] method will cause the program to panic because it references a nonexistent element. This method is best used when you want your program to crash if there's an attempt to access an element past the end of the vector.

When the get method is passed an index that is outside the vector, it returns null without panicking. You would use this method if accessing an element beyond the range of the vector may happen occasionally under normal circumstances. Your code will then have logic to handle having either Some(&element) or null.

Ownership and Borrowing with Vectors

When the program has a valid reference, the borrow checker enforces the ownership and borrowing rules to ensure that this reference and any other references to the contents of the vector remain valid. Recall the rule that states you can't have mutable and immutable references in the same scope. That rule applies here, where we hold an immutable reference to the first element in a vector and try to add an element to the end. This program won't work if we also try to refer to that element later in the function:

fn main() {
    var v = vec![1, 2, 3, 4, 5]

    let first = &v[0]

    v.push(6)  // Error! Cannot borrow `v` as mutable

    println!("The first element is: \(first)")
}

Compiling this code will result in an error:

error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable

The code might look like it should work: Why should a reference to the first element care about changes at the end of the vector? This error is due to the way vectors work: Because vectors put the values next to each other in memory, adding a new element onto the end of the vector might require allocating new memory and copying the old elements to the new space, if there isn't enough room to put all the elements next to each other where the vector is currently stored. In that case, the reference to the first element would be pointing to deallocated memory. The borrowing rules prevent programs from ending up in that situation.

Iterating Over the Values in a Vector

To access each element in a vector in turn, we would iterate through all of the elements rather than use indices to access one at a time. Here's how to use a for loop to get immutable references to each element in a vector of Int values and print them:

fn main() {
    let v = vec![100, 32, 57]
    for i in &v {
        println!("\(i)")
    }
}

We can also iterate over mutable references to each element in a mutable vector in order to make changes to all the elements. The following for loop will add 50 to each element:

fn main() {
    var v = vec![100, 32, 57]
    for i in &mut v {
        *i += 50
    }
}

To change the value that the mutable reference refers to, we have to use the * dereference operator to get to the value in i before we can use the += operator. We'll talk more about the dereference operator in a later chapter.

Iterating over a vector, whether immutably or mutably, is safe because of the borrow checker's rules. If we attempted to insert or remove items in the for loop body, we would get a compiler error. The reference to the vector that the for loop holds prevents simultaneous modification of the whole vector.

Using an Enum to Store Multiple Types

Vectors can only store values that are of the same type. This can be inconvenient; there are definitely use cases for needing to store a list of items of different types. Fortunately, the variants of an enum are defined under the same enum type, so when we need one type to represent elements of different types, we can define and use an enum!

For example, say we want to get values from a row in a spreadsheet in which some of the columns in the row contain integers, some floating-point numbers, and some strings. We can define an enum whose variants will hold the different value types, and all the enum variants will be considered the same type: that of the enum. Then we can create a vector to hold that enum and so, ultimately, hold different types:

fn main() {
    enum SpreadsheetCell {
        IntValue(Int),
        FloatValue(Float),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell.IntValue(3),
        SpreadsheetCell.FloatValue(10.12),
        SpreadsheetCell.Text("blue".toString()),
    ]
}

Oxide needs to know what types will be in the vector at compile time so that it knows exactly how much memory on the heap will be needed to store each element. We must also be explicit about what types are allowed in this vector. If Oxide allowed a vector to hold any type, there would be a chance that one or more of the types would cause errors with the operations performed on the elements of the vector. Using an enum plus a match expression means that Oxide will ensure at compile time that every possible case is handled.

If you don't know the exhaustive set of types a program will get at runtime to store in a vector, the enum technique won't work. Instead, you can use a trait object, which we'll cover in a later chapter.

Common Vector Methods

Now that we've discussed some of the most common ways to use vectors, here are some additional useful methods defined on Vec<T>:

fn main() {
    var v = vec![1, 2, 3]

    // Add an element to the end
    v.push(4)

    // Remove and return the last element
    let last: Int? = v.pop()  // Returns Some(4)

    // Get the length
    let len = v.len()  // Returns 3

    // Check if empty
    let empty = v.isEmpty()  // Returns false

    // Clear all elements
    v.clear()

    // Create with capacity (optimization)
    let withCapacity: Vec<Int> = Vec.withCapacity(10)
}

Rust comparison: Method names are generally the same, but Oxide uses camelCase for method names like isEmpty instead of is_empty. Also note Vec.withCapacity uses dot notation instead of Vec::with_capacity.

#![allow(unused)]
fn main() {
// Rust
let mut v = vec![1, 2, 3];
v.push(4);
let last = v.pop();
let len = v.len();
let empty = v.is_empty();
v.clear();
let with_capacity: Vec<i32> = Vec::with_capacity(10);
}

Dropping a Vector Drops Its Elements

Like any other value, a vector is freed when it goes out of scope:

fn main() {
    {
        let v = vec![1, 2, 3, 4]

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

When the vector gets dropped, all of its contents are also dropped, meaning the integers it holds will be cleaned up. The borrow checker ensures that any references to contents of a vector are only used while the vector itself is valid.

Let's move on to the next collection type: String!