How it works...

This recipe is going to be a bit longer than the others, because:

• The vector is the most important collection
• Many of its core principles, like preallocation, apply to other collections as well
• It includes methods used on slices, which are also usable by many other collections

Let's start at the beginning.

A vector can be created [9] by using the constructor pattern we mentioned earlier (Chapter 1, Learning the Basics, Using the Constructor Pattern), and filled by calling push on it for every element we want to store [10]. Because this is such a common pattern, Rust provides you with a convenient macro called vec![3]. While its end effect is the same, the macro is implemented with some nice performance optimizations.

If you want to initialize a vector by repeating an element over and over, you can use the special calling syntax described in line [52] to do so.

The opposite of push is pop: it removes the last element of the vector, and returns it if the vector wasn't empty before. Because of the memory layout of Vec, which we are going to look at in the next section, this operation is done in complexity. If you don't know what that means, let me rephrase that: it's pretty fast. This is why vectors can be nicely used as First In, Last Out (FILO) stacks.

If you need to modify the contents of a vector, insert[22], remove [58], and swap [26] should be self-explanatory. Sometimes, though, you want to access a specific element in the vector. You can use get to borrow an element at an index [40], and get_mut to mutate it. Both return an Option that only contains Some element if the index was valid. Most times, though, this fine grade of error checking is unnecessary for vector access, as an out-of-bounds index is usually not recoverable, and will just be handled by unwrapping the Option. For this reason, Rust lets you call the Index operator, [], on a Vec [45]. This will automatically deduce its mutability and perform an unwrap for you.

There are a bunch of methods that help us work with the entire vector at once. retain is a very useful one that is also implemented by most other collections [64]. It accepts a so-called predicate, which is a fancy word for a function that returns true or false. It applies that predicate to every element, and only keeps the ones where it returned true.

dedup removes all consecutive duplicates [74]. This means that for the vector [1, 2, 2, 3, 2, 3], dedup would result in [1, 2, 3, 2, 3], as only the duplicate 2s were consecutive. Always remember this when using it, as it can cause bugs that are hard to find. If you want to remove all duplicates, you need to make them consecutive by sorting the vector first. If your elements are comparable, this is as simple as calling .sort() [84].

Using drain creates a consuming iterator over your vector, accessing all elements and removing them in the process, leaving your vector empty [96]. This is useful when you have to work through your data and reuse your empty vector again afterwards to collect more work.

If you've never seen splice in another language, you're probably going to feel a bit confused at first about what it does. Let's take a look at it, shall we?

splice does three things:

• It takes a range. This range will be removed from the vector.
• It takes an iterator. This iterator will be inserted into the space left open by the removal from the last step.
• It returns the removed elements as an iterator.

How to handle the returned iterator is going to be the topic of the recipe in the Access collections as iterators section.