Utilities for vector manipulation

The vec module contains useful code to help work with vector values. Vectors are Rust's list type. Vectors contain zero or more values of homogeneous types:

let int_vector = [1,2,3];
let str_vector = ["one", "two", "three"];

This is a big module, but for a high-level overview:

Structs

Several structs that are useful for vectors, such as VecIterator, which represents iteration over a vector.

Traits

A number of traits add methods that allow you to accomplish tasks with vectors.

Traits defined for the &[T] type (a vector slice), have methods that can be called on either owned vectors, denoted ~[T], or on vector slices themselves. These traits include ImmutableVector, and MutableVector for the &mut [T] case.

An example is the method .slice(a, b) that returns an immutable "view" into a vector or a vector slice from the index interval [a, b):

let numbers = [0, 1, 2];
let last_numbers = numbers.slice(1, 3);
// last_numbers is now &[1, 2]

Traits defined for the ~[T] type, like OwnedVector, can only be called on such vectors. These methods deal with adding elements or otherwise changing the allocation of the vector.

An example is the method .push(element) that will add an element at the end of the vector:

let mut numbers = ~[0, 1, 2];
numbers.push(7);
// numbers is now ~[0, 1, 2, 7];

Implementations of other traits

Vectors are a very useful type, and so there's several implementations of traits from other modules. Some notable examples:

• Clone
• Eq, Ord, TotalEq, TotalOrd -- vectors can be compared, if the element type defines the corresponding trait.

Iteration

The method iter() returns an iteration value for a vector or a vector slice. The iterator yields references to the vector's elements, so if the element type of the vector is int, the element type of the iterator is &int.

let numbers = [0, 1, 2];
for &x in numbers.iter() {
    println!("{} is a number!", x);
}

• .rev_iter() returns an iterator with the same values as .iter(), but going in the reverse order, starting with the back element.
• .mut_iter() returns an iterator that allows modifying each value.
• .move_iter() converts an owned vector into an iterator that moves out a value from the vector each iteration.
• Further iterators exist that split, chunk or permute the vector.

Function definitions

There are a number of free functions that create or take vectors, for example:

• Creating a vector, like from_elem and from_fn
• Creating a vector with a given size: with_capacity
• Modifying a vector and returning it, like append
• Operations on paired elements, like unzip.