Prelude to Vectors in the Rust Programming Language

In this post, we are going to explore in detail how to work with resizable arrays in Rust. Specifically, we will take a closer look at the Vector type, its syntax, and some use cases like filtering and transforming a collection.

In software development, we often face the need to deal with a list of objects or values. For example, enumerating words or ingesting series of numeric values, parsing structured data from tables or data storage like CSV files or a database.

Also referred to as collections, such data structures serve as a container of discrete values, offering a great facility to organise all kinds of dynamic data in a program. The Rust Standard Library includes several different kinds of collections like static arrays, tuples, vectors, strings and hashmaps. 

Our focus here is set on one of the more commonly used array-like types - the 

 type. Unlike arrays and tuples, collections of type 

 are dynamic which means they can be changed at runtime, making them a versatile and convenient data type.

In this post, we are going to explore the following aspects of the 

Finally, we are going to take a moment to review how Rust’s internal safety mechanisms protect the developer from performing potentially unsafe operations.

This tutorial assumes you are familiar with the Rust language syntax and have a general understanding of how a program allocates memory (e.g. heap vs stack).

We often use terms like collections and arrays to describe structures of numbered lists of items. The vector type in Rust is one example of such a structure and it is the most commonly used form of collection. It has the type 

The basic structure of a vector can be seen as a combination of the following information:

A vector can always be represented as a tripled of these 3 values: pointer, capacity, and length.

 type allows us to make use of several guarantees provided by the Rust runtime.

For example, the pointer of a vector can never be 

 type is null pointer optimized. If a vector is empty (contains no elements) or all elements are zero-sized, then Rust ensures that no memory will be allocated for the vector.

It is important to make a distinction between the memory allocated for elements currently present in a vector and the 

 of a vector indicates the number of elements that can be added to a vector without re-allocation of memory. It can be seen as a sort of reserved or pre-allocated memory.

You can learn more about the guarantees and memory specifics of the vector type 

There are several ways we can define a new vector. 

 function which returns a new empty vector. Once created, the new vector variable can be marked as mutable (using the 

 keyword) in order to be able to add and remove elements from it. 

let mut vec = Vec::new();
vec.push("one");
vec.push("more");
vec.push("thing");
println!("{:?}", vec);

It is worth pointing out that we did not declare the type of elements we intend to add to the collection. Let's see what happens if we declare the vector as we did above, but don't insert any elements to it e.g.:

This statement alone will not compile and the error message will be 

 type uses generics in order to specify the type of elements that will be added to the vector collection.

In the first example, we added elements to the vector and so the Rust compiler was able to infer the type of the variable 

 as the elements being added to it are of type 

In the second example, only initializing a new empty vector was not enough for the Rust compiler to determine what kind of elements we intend to store this causing raising a compiler error.

In order to solve this, we can choose to explicitly specify the type of the vector collection during initialization. For example:

 function may seem a bit verbose as we first need to initialize a mutable variable and only then add elements to it.

 macro which adds certain facilities to make it easier to initialize new vectors by also providing the initial elements in the collection.

We could rewrite our example in order to use the 

let mut vec = vec![];
vec.push("one");
vec.push("more");
vec.push("thing");
println!("{:?}", vec);

Since the initial elements of the vector are known upfront, this can be made even more concise, by directly initializing the vector with the initial elements:

let vec = vec!["one", "more", "thing"];
println!("{:?}", vec);

Now that we know how to create a vector, let's have a look at some of the techniques we can utilize in order to access the contents (or elements) of a vector.

 of the vector corresponds to the number of elements currently being stored by the vector. We can obtain the length using the 

let vec = vec!["one", "more", "thing"];
println!("There are {:?} elements.", vec.len()); // 3

 of the vector is the number of elements that a vector can hold without the need to reallocate additional memory. 

Capacity is one of the key concepts which makes the Rust vector such a versatile and efficient structure for collections.

A vector normally stores its elements in a memory buffer which can grow over time as new elements are being added to it. By default, the capacity of the vector is automatically adjusted as we add elements to the collection. 

When we create a new empty vector, we can choose to define an initial capacity, essentially reserving the initial buffer size of the vector. This means that when new elements are added, the vector will not have to reallocate additional memory as long as there is remaining space in its buffer (capacity).

let vec: Vec<&str> = vec![];
println!("Capacity {}, currently holding {} elements.", vec.capacity(), vec.len()); // capacity 0, elements 0

If we just create a new empty vector, it has 0 elements and a capacity of 0.

This means adding an element will require the vector to first allocate some memory to increase its capacity to at least 1, in order to accommodate the incoming element.

let mut vec: Vec<&str> = vec![];
vec.push("one");
println!("Capacity {}, currently holding {} elements.", vec.capacity(), vec.len()); // capacity 1, elements 1

Of course, this works just fine and may not be a problem at all.

In case we are dealing with a memory sensitive scenario, we can choose to pre-allocate some capacity in advance, preventing the collection from having to reallocate memory when elements are being added.

For example, we can create a new empty vector with an initial capacity for 10 elements:

let vec: Vec<i32> = Vec::with_capacity(10);
println!("Capacity {}, currently holding {} elements.", vec.capacity(), vec.len()); // capacity 10, elements 0

Accessing specific values within a vector

 trait, allowing us to directly access elements by index:

let vec = vec!["one", "more", "thing"];
let result = vec[0];
println!("{}", result); // "one"

A common source of bugs and security vulnerabilities is what is commonly known as out of bounds access i.e. trying to access an element outside the length of a vector.

While very easy to use, direct access by index has a downside - we may accidentally request an element index which is out of bounds which will cause the program to panic:

let vec = vec!["one", "more", "thing"];
let result = vec[3];
println!("{}", result);

thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 3'

To help with that, Rust offers an alternative using the 

 instead, allowing us to gracefully handle this scenario and as a result, improving the reliability of the program:

A mutable vector can be changed by adding or removing elements from it. We do this using the 

 functions. Respectively they either append an element to the end of a vector or remove the last element of a vector.

 value which either holds the removed element or 

 if no elements were removed from the vector (e.g. when it was already empty).

let mut vec = vec!["one", "more", "thing"];
vec.push("!");
println!("{:?}", vec); // ["one", "more", "thing", "!"]
let removed_el = vec.pop(); // "!"
println!("{:?}", vec); // ["one", "more", "thing"]

In some situations it may be useful to update an element which already belongs to a vector:

let mut vec = vec!["one", "more", "thing"];
vec[0] = "two";
vec[2] = "things";
println!("{:?}", vec); // ["two", "more", "things"]

You may notice that we are directly accessing an element by index. Like we saw earlier, given an index outside the bounds of the vector the application will panic.

We can use a technique we showed earlier with the 

 which returns a mutable reference to an element, if it exists. We can then rewrite the above example in a safer way as follows:

let mut vec = vec!["one", "more", "thing"];
if let Some(first_word) = vec.get_mut(0) {
    *first_word = "two";
}
if let Some(third_word) = vec.get_mut(2) {
    *third_word = "things";
}
println!("{:?}", vec);

 with a reference to the element at the given index. If the element doesn't exist (when the index is out of bounds), 

 returns a mutable reference which we can use to update the value.

To change the value that the mutable reference is referring to, we make use of the dereference operator (*). You may learn more about it in the 

If we would like to perform a certain operation over each element in a vector, we can iterate through all elements rather than accessing them one at a time. One way would be to use a 

let vec: Vec<&str> = vec!["one", "more", "thing"];
for word in vec {
    println!("{:?}", word);
}

In this case, we are consuming the vector by executing the operation defined in the for loop block over each element of that vector.

We could also limit the operation to just references to the elements of the collection.

let vec: Vec<&str> = vec!["one", "more", "thing"];
for word in &vec {
    println!("{:?}", word); // word is now of type &&str
}

Using the same technique, we can obtain a mutable reference to the elements, allowing us to affect changes to the collection:

let mut vec: Vec<&str> = vec!["one", "more", "thing"];
for word in &mut vec {
    if word == &"one" {
        *word = "two";
    }
    if word == &"thing" {
        *word = "things";
    }
}
println!("{:?}", vec); // ["two", "more", "things"]

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Prelude to Vectors in the Rust Programming Language

Responses (1)

Masterclasses

Tutorials

Fullstack React with TypeScript