Struct collections::vec::VecStable
[-]
[+]
[src]
pub struct Vec<T> {
// some fields omitted
}An owned, growable vector.
Examples
fn main() { let mut vec = Vec::new(); vec.push(1i); vec.push(2i); assert_eq!(vec.len(), 2); assert_eq!(vec[0], 1); assert_eq!(vec.pop(), Some(2)); assert_eq!(vec.len(), 1); vec[0] = 7i; assert_eq!(vec[0], 7); vec.push_all(&[1, 2, 3]); for x in vec.iter() { println!("{}", x); } assert_eq!(vec, vec![7i, 1, 2, 3]); }let mut vec = Vec::new(); vec.push(1i); vec.push(2i); assert_eq!(vec.len(), 2); assert_eq!(vec[0], 1); assert_eq!(vec.pop(), Some(2)); assert_eq!(vec.len(), 1); vec[0] = 7i; assert_eq!(vec[0], 7); vec.push_all(&[1, 2, 3]); for x in vec.iter() { println!("{}", x); } assert_eq!(vec, vec![7i, 1, 2, 3]);
The vec! macro is provided to make initialization more convenient:
let mut vec = vec![1i, 2i, 3i]; vec.push(4); assert_eq!(vec, vec![1, 2, 3, 4]);
Use a Vec as an efficient stack:
let mut stack = Vec::new(); stack.push(1i); stack.push(2i); stack.push(3i); loop { let top = match stack.pop() { None => break, // empty Some(x) => x, }; // Prints 3, 2, 1 println!("{}", top); }
Capacity and reallocation
The capacity of a vector is the amount of space allocated for any future elements that will be added onto the vector. This is not to be confused with the length of a vector, which specifies the number of actual elements within the vector. If a vector's length exceeds its capacity, its capacity will automatically be increased, but its elements will have to be reallocated.
For example, a vector with capacity 10 and length 0 would be an empty
vector with space for 10 more elements. Pushing 10 or fewer elements onto
the vector will not change its capacity or cause reallocation to occur.
However, if the vector's length is increased to 11, it will have to
reallocate, which can be slow. For this reason, it is recommended
to use Vec::with_capacity whenever possible to specify how big the vector
is expected to get.
Methods
impl<T> Vec<T>
fn new() -> Vec<T>
Constructs a new, empty Vec.
The vector will not allocate until elements are pushed onto it.
Example
fn main() { let mut vec: Vec<int> = Vec::new(); }let mut vec: Vec<int> = Vec::new();
fn with_capacity(capacity: uint) -> Vec<T>
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.
It is important to note that this function does not specify the
length of the returned vector, but only the capacity. (For an
explanation of the difference between length and capacity, see
the main Vec docs above, 'Capacity and reallocation'.) To create
a vector of a given length, use Vec::from_elem or Vec::from_fn.
Example
fn main() { let mut vec: Vec<int> = Vec::with_capacity(10); // The vector contains no items, even though it has capacity for more assert_eq!(vec.len(), 0); // These are all done without reallocating... for i in range(0i, 10) { vec.push(i); } // ...but this may make the vector reallocate vec.push(11); }let mut vec: Vec<int> = Vec::with_capacity(10); // The vector contains no items, even though it has capacity for more assert_eq!(vec.len(), 0); // These are all done without reallocating... for i in range(0i, 10) { vec.push(i); } // ...but this may make the vector reallocate vec.push(11);
fn from_fn(length: uint, op: |uint| -> T) -> Vec<T>
Creates and initializes a Vec.
Creates a Vec of size length and initializes the elements to the
value returned by the closure op.
Example
fn main() { let vec = Vec::from_fn(3, |idx| idx * 2); assert_eq!(vec, vec![0, 2, 4]); }let vec = Vec::from_fn(3, |idx| idx * 2); assert_eq!(vec, vec![0, 2, 4]);
unsafe fn from_raw_parts(ptr: *mut T, length: uint, capacity: uint) -> Vec<T>
Creates a Vec<T> directly from the raw constituents.
This is highly unsafe:
- if
ptris null, thenlengthandcapacityshould be 0 ptrmust point to an allocation of sizecapacity- there must be
lengthvalid instances of typeTat the beginning of that allocation ptrmust be allocated by the defaultVecallocator
Example
use std::ptr; use std::mem; fn main() { let mut v = vec![1i, 2, 3]; // Pull out the various important pieces of information about `v` let p = v.as_mut_ptr(); let len = v.len(); let cap = v.capacity(); unsafe { // Cast `v` into the void: no destructor run, so we are in // complete control of the allocation to which `p` points. mem::forget(v); // Overwrite memory with 4, 5, 6 for i in range(0, len as int) { ptr::write(p.offset(i), 4 + i); } // Put everything back together into a Vec let rebuilt = Vec::from_raw_parts(p, len, cap); assert_eq!(rebuilt, vec![4i, 5i, 6i]); } }use std::ptr; use std::mem; fn main() { let mut v = vec![1i, 2, 3]; // Pull out the various important pieces of information about `v` let p = v.as_mut_ptr(); let len = v.len(); let cap = v.capacity(); unsafe { // Cast `v` into the void: no destructor run, so we are in // complete control of the allocation to which `p` points. mem::forget(v); // Overwrite memory with 4, 5, 6 for i in range(0, len as int) { ptr::write(p.offset(i), 4 + i); } // Put everything back together into a Vec let rebuilt = Vec::from_raw_parts(p, len, cap); assert_eq!(rebuilt, vec![4i, 5i, 6i]); } }
fn partition(self, f: |&T| -> bool) -> (Vec<T>, Vec<T>)
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
fn main() { 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]); }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]);
impl<T: Clone> Vec<T>
fn from_elem(length: uint, value: T) -> Vec<T>
Constructs a Vec with copies of a value.
Creates a Vec with length copies of value.
Example
fn main() { let vec = Vec::from_elem(3, "hi"); println!("{}", vec); // prints [hi, hi, hi] }let vec = Vec::from_elem(3, "hi"); println!("{}", vec); // prints [hi, hi, hi]
fn push_all(&mut self, other: &[T])
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
fn main() { let mut vec = vec![1i]; vec.push_all(&[2i, 3, 4]); assert_eq!(vec, vec![1, 2, 3, 4]); }let mut vec = vec![1i]; vec.push_all(&[2i, 3, 4]); assert_eq!(vec, vec![1, 2, 3, 4]);
fn grow(&mut self, n: uint, value: T)
Grows the Vec in-place.
Adds n copies of value to the Vec.
Example
fn main() { let mut vec = vec!["hello"]; vec.grow(2, "world"); assert_eq!(vec, vec!["hello", "world", "world"]); }let mut vec = vec!["hello"]; vec.grow(2, "world"); assert_eq!(vec, vec!["hello", "world", "world"]);
fn partitioned(&self, f: |&T| -> bool) -> (Vec<T>, Vec<T>)
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
fn main() { 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]); }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]);
impl<T> Vec<T>
fn capacity(&self) -> uint
Returns the number of elements the vector can hold without reallocating.
Example
fn main() { let vec: Vec<int> = Vec::with_capacity(10); assert_eq!(vec.capacity(), 10); }let vec: Vec<int> = Vec::with_capacity(10); assert_eq!(vec.capacity(), 10);
fn reserve_additional(&mut self, extra: uint)
Deprecated: Renamed to reserve.
fn reserve(&mut self, additional: uint)
Reserves capacity for at least additional more elements to be inserted in the given
Vec. The collection may reserve more space to avoid frequent reallocations.
Panics
Panics if the new capacity overflows uint.
Example
fn main() { let mut vec: Vec<int> = vec![1]; vec.reserve(10); assert!(vec.capacity() >= 11); }let mut vec: Vec<int> = vec![1]; vec.reserve(10); assert!(vec.capacity() >= 11);
fn reserve_exact(&mut self, additional: uint)
Reserves the minimum capacity for exactly additional more elements to be inserted in the
given Vec. Does nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it requests. Therefore
capacity can not be relied upon to be precisely minimal. Prefer reserve if future
insertions are expected.
Panics
Panics if the new capacity overflows uint.
Example
fn main() { let mut vec: Vec<int> = vec![1]; vec.reserve_exact(10); assert!(vec.capacity() >= 11); }let mut vec: Vec<int> = vec![1]; vec.reserve_exact(10); assert!(vec.capacity() >= 11);
fn shrink_to_fit(&mut self)
Shrinks the capacity of the vector as much as possible. It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.
Example
fn main() { let mut vec: Vec<int> = Vec::with_capacity(10); vec.push_all(&[1, 2, 3]); assert_eq!(vec.capacity(), 10); vec.shrink_to_fit(); assert!(vec.capacity() >= 3); }let mut vec: Vec<int> = Vec::with_capacity(10); vec.push_all(&[1, 2, 3]); assert_eq!(vec.capacity(), 10); vec.shrink_to_fit(); assert!(vec.capacity() >= 3);
fn into_boxed_slice(self) -> Box<[T]>
Convert the vector into Box<[T]>.
Note that this will drop any excess capacity. Calling this and converting back to a vector
with into_vec() is equivalent to calling shrink_to_fit().
fn truncate(&mut self, len: uint)
Shorten a vector, dropping excess elements.
If len is greater than the vector's current length, this has no
effect.
Example
fn main() { let mut vec = vec![1i, 2, 3, 4]; vec.truncate(2); assert_eq!(vec, vec![1, 2]); }let mut vec = vec![1i, 2, 3, 4]; vec.truncate(2); assert_eq!(vec, vec![1, 2]);
fn as_mut_slice<'a>(&'a mut self) -> &'a mut [T]
Returns a mutable slice of the elements of self.
Example
fn main() { fn foo(slice: &mut [int]) {} let mut vec = vec![1i, 2]; foo(vec.as_mut_slice()); }fn foo(slice: &mut [int]) {} let mut vec = vec![1i, 2]; foo(vec.as_mut_slice());
fn into_iter(self) -> MoveItems<T>
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
fn main() { let v = vec!["a".to_string(), "b".to_string()]; for s in v.into_iter() { // s has type String, not &String println!("{}", s); } }let v = vec!["a".to_string(), "b".to_string()]; for s in v.into_iter() { // s has type String, not &String println!("{}", s); }
unsafe fn set_len(&mut self, len: uint)
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.
Example
fn main() { let mut v = vec![1u, 2, 3, 4]; unsafe { v.set_len(1); } }let mut v = vec![1u, 2, 3, 4]; unsafe { v.set_len(1); }
fn swap_remove(&mut self, index: uint) -> Option<T>
Removes 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
fn main() { let mut v = vec!["foo", "bar", "baz", "qux"]; assert_eq!(v.swap_remove(1), Some("bar")); assert_eq!(v, vec!["foo", "qux", "baz"]); assert_eq!(v.swap_remove(0), Some("foo")); assert_eq!(v, vec!["baz", "qux"]); assert_eq!(v.swap_remove(2), None); }let mut v = vec!["foo", "bar", "baz", "qux"]; assert_eq!(v.swap_remove(1), Some("bar")); assert_eq!(v, vec!["foo", "qux", "baz"]); assert_eq!(v.swap_remove(0), Some("foo")); assert_eq!(v, vec!["baz", "qux"]); assert_eq!(v.swap_remove(2), None);
fn insert(&mut self, index: uint, element: T)
Inserts an element at position index within the vector, shifting all
elements after position i one position to the right.
Panics
Panics if index is not between 0 and the vector's length (both
bounds inclusive).
Example
fn main() { let mut vec = vec![1i, 2, 3]; vec.insert(1, 4); assert_eq!(vec, vec![1, 4, 2, 3]); vec.insert(4, 5); assert_eq!(vec, vec![1, 4, 2, 3, 5]); }let mut vec = vec![1i, 2, 3]; vec.insert(1, 4); assert_eq!(vec, vec![1, 4, 2, 3]); vec.insert(4, 5); assert_eq!(vec, vec![1, 4, 2, 3, 5]);
fn remove(&mut self, index: uint) -> Option<T>
Removes and returns 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
fn main() { 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]); }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]);
fn retain(&mut self, f: |&T| -> bool)
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 of the retained elements.
Example
fn main() { let mut vec = vec![1i, 2, 3, 4]; vec.retain(|&x| x%2 == 0); assert_eq!(vec, vec![2, 4]); }let mut vec = vec![1i, 2, 3, 4]; vec.retain(|&x| x%2 == 0); assert_eq!(vec, vec![2, 4]);
fn grow_fn(&mut self, n: uint, f: |uint| -> T)
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
fn main() { let mut vec = vec![0u, 1]; vec.grow_fn(3, |i| i); assert_eq!(vec, vec![0, 1, 0, 1, 2]); }let mut vec = vec![0u, 1]; vec.grow_fn(3, |i| i); assert_eq!(vec, vec![0, 1, 0, 1, 2]);
fn push(&mut self, value: T)
Appends an element to the back of a collection.
Panics
Panics if the number of elements in the vector overflows a uint.
Example
fn main() { let mut vec = vec!(1i, 2); vec.push(3); assert_eq!(vec, vec!(1, 2, 3)); }let mut vec = vec!(1i, 2); vec.push(3); assert_eq!(vec, vec!(1, 2, 3));
fn pop(&mut self) -> Option<T>
Removes the last element from a vector and returns it, or None if
it is empty.
Example
fn main() { let mut vec = vec![1i, 2, 3]; assert_eq!(vec.pop(), Some(3)); assert_eq!(vec, vec![1, 2]); }let mut vec = vec![1i, 2, 3]; assert_eq!(vec.pop(), Some(3)); assert_eq!(vec, vec![1, 2]);
fn clear(&mut self)
Clears the vector, removing all values.
Example
fn main() { let mut v = vec![1i, 2, 3]; v.clear(); assert!(v.is_empty()); }let mut v = vec![1i, 2, 3]; v.clear(); assert!(v.is_empty());
fn len(&self) -> uint
Return the number of elements in the vector
Example
fn main() { let a = vec![1i, 2, 3]; assert_eq!(a.len(), 3); }let a = vec![1i, 2, 3]; assert_eq!(a.len(), 3);
fn is_empty(&self) -> bool
Returns true if the vector contains no elements
Example
fn main() { let mut v = Vec::new(); assert!(v.is_empty()); v.push(1i); assert!(!v.is_empty()); }let mut v = Vec::new(); assert!(v.is_empty()); v.push(1i); assert!(!v.is_empty());
impl<T: PartialEq> Vec<T>
fn dedup(&mut self)
Removes consecutive repeated elements in the vector.
If the vector is sorted, this removes all duplicates.
Example
fn main() { let mut vec = vec![1i, 2, 2, 3, 2]; vec.dedup(); assert_eq!(vec, vec![1i, 2, 3, 2]); }let mut vec = vec![1i, 2, 2, 3, 2]; vec.dedup(); assert_eq!(vec, vec![1i, 2, 3, 2]);
impl<T> Vec<T>
fn map_in_place<U>(self, f: |T| -> U) -> Vec<U>
Converts a Vec<T> to a Vec<U> where T and U have the same
size and in case they are not zero-sized the same minimal alignment.
Panics
Panics if T and U have differing sizes or are not zero-sized and
have differing minimal alignments.
Example
fn main() { let v = vec![0u, 1, 2]; let w = v.map_in_place(|i| i + 3); assert_eq!(w.as_slice(), [3, 4, 5].as_slice()); #[deriving(PartialEq, Show)] struct Newtype(u8); let bytes = vec![0x11, 0x22]; let newtyped_bytes = bytes.map_in_place(|x| Newtype(x)); assert_eq!(newtyped_bytes.as_slice(), [Newtype(0x11), Newtype(0x22)].as_slice()); }let v = vec![0u, 1, 2]; let w = v.map_in_place(|i| i + 3); assert_eq!(w.as_slice(), [3, 4, 5].as_slice()); #[deriving(PartialEq, Show)] struct Newtype(u8); let bytes = vec![0x11, 0x22]; let newtyped_bytes = bytes.map_in_place(|x| Newtype(x)); assert_eq!(newtyped_bytes.as_slice(), [Newtype(0x11), Newtype(0x22)].as_slice());
Trait Implementations
impl<S: Str> StrVector for Vec<S>
impl<T: Clone> Clone for Vec<T>
fn clone(&self) -> Vec<T>
fn clone_from(&mut self, other: &Vec<T>)
impl<T> Index<uint, T> for Vec<T>
impl<T> IndexMut<uint, T> for Vec<T>
impl<T> Slice<uint, [T]> for Vec<T>
fn as_slice_<'a>(&'a self) -> &'a [T]
fn slice_from_or_fail<'a>(&'a self, start: &uint) -> &'a [T]
fn slice_to_or_fail<'a>(&'a self, end: &uint) -> &'a [T]
fn slice_or_fail<'a>(&'a self, start: &uint, end: &uint) -> &'a [T]
impl<T> SliceMut<uint, [T]> for Vec<T>
fn as_mut_slice_<'a>(&'a mut self) -> &'a mut [T]
fn slice_from_or_fail_mut<'a>(&'a mut self, start: &uint) -> &'a mut [T]
fn slice_to_or_fail_mut<'a>(&'a mut self, end: &uint) -> &'a mut [T]
fn slice_or_fail_mut<'a>(&'a mut self, start: &uint, end: &uint) -> &'a mut [T]
impl<T> Deref<[T]> for Vec<T>
impl<T> DerefMut<[T]> for Vec<T>
fn deref_mut<'a>(&'a mut self) -> &'a mut [T]
impl<T> FromIterator<T> for Vec<T>
impl<T> Extend<T> for Vec<T>
impl<T: PartialEq> PartialEq for Vec<T>
impl<T: PartialOrd> PartialOrd for Vec<T>
fn partial_cmp(&self, other: &Vec<T>) -> Option<Ordering>
fn lt(&self, other: &Self) -> bool
fn le(&self, other: &Self) -> bool
fn gt(&self, other: &Self) -> bool
fn ge(&self, other: &Self) -> bool
impl<T: Eq> Eq for Vec<T>
impl<T: PartialEq, V: AsSlice<T>> Equiv<V> for Vec<T>
impl<T: Ord> Ord for Vec<T>
impl<T> AsSlice<T> for Vec<T>
fn as_slice<'a>(&'a self) -> &'a [T]
Returns a slice into self.
Example
fn main() { fn foo(slice: &[int]) {} let vec = vec![1i, 2]; foo(vec.as_slice()); }fn foo(slice: &[int]) {} let vec = vec![1i, 2]; foo(vec.as_slice());