Constructs a new, empty Vec.

The vector will not allocate until elements are pushed onto it.

Example

let mut vec: Vec<int> = Vec::new();

Constructs a new, empty Vec with the specified capacity.

The vector will be able to hold exactly capacity elements without reallocating. If capacity is 0, the vector will not allocate.

Example

let vec: Vec<int> = Vec::with_capacity(10);

Creates and initializes a Vec.

Creates a Vec of size length and initializes the elements to the value returned by the closure op.

Example

let vec = Vec::from_fn(3, |idx| idx * 2);
assert_eq!(vec, vec!(0, 2, 4));

Create a Vec<T> directly from the raw constituents.

This is highly unsafe:

• if ptr is null, then length and capacity should be 0
• ptr must point to an allocation of size capacity
• there must be length valid instances of type T at the beginning of that allocation
• ptr must be allocated by the default Vec allocator

Consumes the Vec, partitioning it based on a predicate.

Partitions the Vec into two Vecs (A,B), where all elements of A satisfy f and all elements of B do not. The order of elements is preserved.

Example

let vec = vec!(1i, 2i, 3i, 4i);
let (even, odd) = vec.partition(|&n| n % 2 == 0);
assert_eq!(even, vec!(2, 4));
assert_eq!(odd, vec!(1, 3));

Iterates over the second vector, copying each element and appending it to the first. Afterwards, the first is then returned for use again.

Example

let vec = vec!(1i, 2i);
let vec = vec.append([3i, 4i]);
assert_eq!(vec, vec!(1, 2, 3, 4));

Constructs a Vec by cloning elements of a slice.

Example

let slice = [1i, 2, 3];
let vec = Vec::from_slice(slice);

Constructs a Vec with copies of a value.

Creates a Vec with length copies of value.

Example

let vec = Vec::from_elem(3, "hi");
println!("{}", vec); // prints [hi, hi, hi]

Appends all elements in a slice to the Vec.

Iterates over the slice other, clones each element, and then appends it to this Vec. The other vector is traversed in-order.

Example

let mut vec = vec!(1i);
vec.push_all([2i, 3, 4]);
assert_eq!(vec, vec!(1, 2, 3, 4));

Grows the Vec in-place.

Adds n copies of value to the Vec.

Example

let mut vec = vec!("hello");
vec.grow(2, &("world"));
assert_eq!(vec, vec!("hello", "world", "world"));

Sets the value of a vector element at a given index, growing the vector as needed.

Sets the element at position index to value. If index is past the end of the vector, expands the vector by replicating initval to fill the intervening space.

Example

let mut vec = vec!("a", "b", "c");
vec.grow_set(1, &("fill"), "d");
vec.grow_set(4, &("fill"), "e");
assert_eq!(vec, vec!("a", "d", "c", "fill", "e"));

Partitions a vector based on a predicate.

Clones the elements of the vector, partitioning them into two Vecs (A,B), where all elements of A satisfy f and all elements of B do not. The order of elements is preserved.

Example

let vec = vec!(1i, 2, 3, 4);
let (even, odd) = vec.partitioned(|&n| n % 2 == 0);
assert_eq!(even, vec!(2i, 4));
assert_eq!(odd, vec!(1i, 3));

Returns the number of elements the vector can hold without reallocating.

Example

let vec: Vec<int> = Vec::with_capacity(10);
assert_eq!(vec.capacity(), 10);

Reserves capacity for at least n additional elements in the given vector.

Failure

Fails if the new capacity overflows uint.

Example

let mut vec: Vec<int> = vec!(1i);
vec.reserve_additional(10);
assert!(vec.capacity() >= 11);

Reserves capacity for at least n elements in the given vector.

This function will over-allocate in order to amortize the allocation costs in scenarios where the caller may need to repeatedly reserve additional space.

If the capacity for self is already equal to or greater than the requested capacity, then no action is taken.

Example

let mut vec = vec!(1i, 2, 3);
vec.reserve(10);
assert!(vec.capacity() >= 10);

Reserves capacity for exactly capacity elements in the given vector.

If the capacity for self is already equal to or greater than the requested capacity, then no action is taken.

Example

let mut vec: Vec<int> = Vec::with_capacity(10);
vec.reserve_exact(11);
assert_eq!(vec.capacity(), 11);

Shrink the capacity of the vector as much as possible

Example

let mut vec = vec!(1i, 2, 3);
vec.shrink_to_fit();

Remove the last element from a vector and return it, or None if it is empty.

Example

let mut vec = vec!(1i, 2, 3);
assert_eq!(vec.pop(), Some(3));
assert_eq!(vec, vec!(1, 2));

Append an element to a vector.

Failure

Fails if the number of elements in the vector overflows a uint.

Example

let mut vec = vec!(1i, 2);
vec.push(3);
assert_eq!(vec, vec!(1, 2, 3));

Appends one element to the vector provided. The vector itself is then returned for use again.

Example

let vec = vec!(1i, 2);
let vec = vec.append_one(3);
assert_eq!(vec, vec!(1, 2, 3));

Shorten a vector, dropping excess elements.

If len is greater than the vector's current length, this has no effect.

Example

let mut vec = vec!(1i, 2, 3, 4);
vec.truncate(2);
assert_eq!(vec, vec!(1, 2));

Work with self as a mutable slice.

Example

fn foo(slice: &mut [int]) {}

let mut vec = vec!(1i, 2);
foo(vec.as_mut_slice());

Creates a consuming iterator, that is, one that moves each value out of the vector (from start to end). The vector cannot be used after calling this.

Example

let v = vec!("a".to_string(), "b".to_string());
for s in v.move_iter() {
    // s has type String, not &String
    println!("{}", s);
}

Sets the length of a vector.

This will explicitly set the size of the vector, without actually modifying its buffers, so it is up to the caller to ensure that the vector is actually the specified size.

Returns a reference to the value at index index.

Failure

Fails if index is out of bounds

Example

let vec = vec!(1i, 2, 3);
assert!(vec.get(1) == &2);

Returns a mutable reference to the value at index index.

Failure

Fails if index is out of bounds

Example

let mut vec = vec!(1i, 2, 3);
*vec.get_mut(1) = 4;
assert_eq!(vec, vec!(1i, 4, 3));

Returns an iterator over references to the elements of the vector in order.

Example

let vec = vec!(1i, 2, 3);
for num in vec.iter() {
    println!("{}", *num);
}

Returns an iterator over mutable references to the elements of the vector in order.

Example

let mut vec = vec!(1i, 2, 3);
for num in vec.mut_iter() {
    *num = 0;
}

Sort the vector, in place, using compare to compare elements.

This sort is O(n log n) worst-case and stable, but allocates approximately 2 * n, where n is the length of self.

Example

let mut v = vec!(5i, 4, 1, 3, 2);
v.sort_by(|a, b| a.cmp(b));
assert_eq!(v, vec!(1i, 2, 3, 4, 5));

// reverse sorting
v.sort_by(|a, b| b.cmp(a));
assert_eq!(v, vec!(5i, 4, 3, 2, 1));

Returns a slice of self spanning the interval [start, end).

Failure

Fails when the slice (or part of it) is outside the bounds of self, or when start > end.

Example

let vec = vec!(1i, 2, 3, 4);
assert!(vec.slice(0, 2) == [1, 2]);

Returns a slice containing all but the first element of the vector.

Failure

Fails when the vector is empty.

Example

let vec = vec!(1i, 2, 3);
assert!(vec.tail() == [2, 3]);

Returns all but the first `n' elements of a vector.

Failure

Fails when there are fewer than n elements in the vector.

Example

let vec = vec!(1i, 2, 3, 4);
assert!(vec.tailn(2) == [3, 4]);

Returns a reference to the last element of a vector, or None if it is empty.

Example

let vec = vec!(1i, 2, 3);
assert!(vec.last() == Some(&3));

Returns a mutable reference to the last element of a vector, or None if it is empty.

Example

let mut vec = vec!(1i, 2, 3);
*vec.mut_last().unwrap() = 4;
assert_eq!(vec, vec!(1i, 2, 4));

Remove an element from anywhere in the vector and return it, replacing it with the last element. This does not preserve ordering, but is O(1).

Returns None if index is out of bounds.

Example

let mut v = vec!("foo".to_string(), "bar".to_string(),
                 "baz".to_string(), "qux".to_string());

assert_eq!(v.swap_remove(1), Some("bar".to_string()));
assert_eq!(v, vec!("foo".to_string(), "qux".to_string(), "baz".to_string()));

assert_eq!(v.swap_remove(0), Some("foo".to_string()));
assert_eq!(v, vec!("baz".to_string(), "qux".to_string()));

assert_eq!(v.swap_remove(2), None);

Prepend an element to the vector.

Warning

This is an O(n) operation as it requires copying every element in the vector.

Example

let mut vec = vec!(1i, 2, 3);
vec.unshift(4);
assert_eq!(vec, vec!(4, 1, 2, 3));

Removes the first element from a vector and returns it, or None if the vector is empty.

Warning

This is an O(n) operation as it requires copying every element in the vector.

Example

let mut vec = vec!(1i, 2, 3);
assert!(vec.shift() == Some(1));
assert_eq!(vec, vec!(2, 3));

Insert an element at position index within the vector, shifting all elements after position i one position to the right.

Failure

Fails if index is out of bounds of the vector.

Example

let mut vec = vec!(1i, 2, 3);
vec.insert(1, 4);
assert_eq!(vec, vec!(1, 4, 2, 3));

Remove and return the element at position index within the vector, shifting all elements after position index one position to the left. Returns None if i is out of bounds.

Example

let mut v = vec!(1i, 2, 3);
assert_eq!(v.remove(1), Some(2));
assert_eq!(v, vec!(1, 3));

assert_eq!(v.remove(4), None);
// v is unchanged:
assert_eq!(v, vec!(1, 3));

Takes ownership of the vector other, moving all elements into the current vector. This does not copy any elements, and it is illegal to use the other vector after calling this method (because it is moved here).

Example

let mut vec = vec!(box 1i);
vec.push_all_move(vec!(box 2, box 3, box 4));
assert_eq!(vec, vec!(box 1, box 2, box 3, box 4));

Returns a mutable slice of self between start and end.

Failure

Fails when start or end point outside the bounds of self, or when start > end.

Example

let mut vec = vec!(1i, 2, 3, 4);
assert!(vec.mut_slice(0, 2) == [1, 2]);

Returns a mutable slice of self from start to the end of the vec.

Failure

Fails when start points outside the bounds of self.

Example

let mut vec = vec!(1i, 2, 3, 4);
assert!(vec.mut_slice_from(2) == [3, 4]);

Returns a mutable slice of self from the start of the vec to end.

Failure

Fails when end points outside the bounds of self.

Example

let mut vec = vec!(1i, 2, 3, 4);
assert!(vec.mut_slice_to(2) == [1, 2]);

Returns a pair of mutable slices that divides the vec at an index.

The first will contain all indices from [0, mid) (excluding the index mid itself) and the second will contain all indices from [mid, len) (excluding the index len itself).

Failure

Fails if mid > len.

Example

let mut vec = vec!(1i, 2, 3, 4, 5, 6);

// scoped to restrict the lifetime of the borrows
{
   let (left, right) = vec.mut_split_at(0);
   assert!(left == &mut []);
   assert!(right == &mut [1, 2, 3, 4, 5, 6]);
}

{
    let (left, right) = vec.mut_split_at(2);
    assert!(left == &mut [1, 2]);
    assert!(right == &mut [3, 4, 5, 6]);
}

{
    let (left, right) = vec.mut_split_at(6);
    assert!(left == &mut [1, 2, 3, 4, 5, 6]);
    assert!(right == &mut []);
}

Reverse the order of elements in a vector, in place.

Example

let mut v = vec!(1i, 2, 3);
v.reverse();
assert_eq!(v, vec!(3i, 2, 1));

Returns a slice of self from start to the end of the vec.

Failure

Fails when start points outside the bounds of self.

Example

let vec = vec!(1i, 2, 3);
assert!(vec.slice_from(1) == [2, 3]);

Returns a slice of self from the start of the vec to end.

Failure

Fails when end points outside the bounds of self.

Example

let vec = vec!(1i, 2, 3);
assert!(vec.slice_to(2) == [1, 2]);

Returns a slice containing all but the last element of the vector.

Failure

Fails if the vector is empty

Returns an unsafe pointer to the vector's buffer.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage.

Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

Returns a mutable unsafe pointer to the vector's buffer.

The caller must ensure that the vector outlives the pointer this function returns, or else it will end up pointing to garbage.

Modifying the vector may cause its buffer to be reallocated, which would also make any pointers to it invalid.

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(&e) returns false. This method operates in place and preserves the order the retained elements.

Example

let mut vec = vec!(1i, 2, 3, 4);
vec.retain(|x| x%2 == 0);
assert_eq!(vec, vec!(2, 4));

Expands a vector in place, initializing the new elements to the result of a function.

The vector is grown by n elements. The i-th new element are initialized to the value returned by f(i) where i is in the range [0, n).

Example

let mut vec = vec!(0u, 1);
vec.grow_fn(3, |i| i);
assert_eq!(vec, vec!(0, 1, 0, 1, 2));

Sorts the vector in place.

This sort is O(n log n) worst-case and stable, but allocates approximately 2 * n, where n is the length of self.

Example

let mut vec = vec!(3i, 1, 2);
vec.sort();
assert_eq!(vec, vec!(1, 2, 3));

Return true if a vector contains an element with the given value

Example

let vec = vec!(1i, 2, 3);
assert!(vec.contains(&1));

Remove consecutive repeated elements in the vector.

If the vector is sorted, this removes all duplicates.

Example

let mut vec = vec!(1i, 2, 2, 3, 2);
vec.dedup();
assert_eq!(vec, vec!(1i, 2, 3, 2));

Work with self as a slice.

Example

fn foo(slice: &[int]) {}

let vec = vec!(1i, 2);
foo(vec.as_slice());