Struct std::vec::Vec
pub struct Vec<T> { // some fields omitted }
An owned, growable vector.
Examples
let mut vec = Vec::new(); vec.push(1); vec.push(2); assert_eq!(vec.len(), 2); assert_eq!(vec.get(0), &1); assert_eq!(vec.pop(), Some(2)); assert_eq!(vec.len(), 1);
The vec!
macro is provided to make initialization more convenient:
let mut vec = vec!(1, 2, 3); vec.push(4); assert_eq!(vec, vec!(1, 2, 3, 4));
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
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.
Example
let vec: Vec<int> = Vec::with_capacity(10);
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
let vec = Vec::from_fn(3, |idx| idx * 2); assert_eq!(vec, vec!(0, 2, 4));
unsafe fn from_raw_parts(length: uint, capacity: uint, ptr: *mut T) -> Vec<T>
Create a Vec<T>
directly from the raw constituents.
This is highly unsafe:
- if
ptr
is null, thenlength
andcapacity
should be 0 ptr
must point to an allocation of sizecapacity
- there must be
length
valid instances of typeT
at the beginning of that allocation ptr
must be allocated by the defaultVec
allocator
fn partition(self, f: |&T| -> bool) -> (Vec<T>, Vec<T>)
Consumes the Vec
, partitioning it based on a predcate.
Partitions the Vec
into two Vec
s (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!(1, 2, 3, 4); 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 append(self, second: &[T]) -> Vec<T>
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!(1, 2); let vec = vec.append([3, 4]); assert_eq!(vec, vec!(1, 2, 3, 4));
fn from_slice(values: &[T]) -> Vec<T>
Constructs a Vec
by cloning elements of a slice.
Example
let slice = [1, 2, 3]; let vec = Vec::from_slice(slice);
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
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
let mut vec = vec!(1); vec.push_all([2, 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
let mut vec = vec!("hello"); vec.grow(2, & &"world"); assert_eq!(vec, vec!("hello", "world", "world"));
fn grow_set(&mut self, index: uint, initval: &T, value: T)
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"));
fn partitioned(&self, f: |&T| -> bool) -> (Vec<T>, Vec<T>)
Partitions a vector based on a predcate.
Clones the elements of the vector, partitioning them into two Vec
s
(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!(1, 2, 3, 4); let (even, odd) = vec.partitioned(|&n| n % 2 == 0); assert_eq!(even, vec!(2, 4)); assert_eq!(odd, vec!(1, 3));
impl<T> Vec<T>
fn capacity(&self) -> uint
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);
fn reserve_additional(&mut self, extra: uint)
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!(1); vec.reserve_additional(10); assert!(vec.capacity() >= 11);
fn reserve(&mut self, capacity: uint)
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!(1, 2, 3); vec.reserve(10); assert!(vec.capacity() >= 10);
fn reserve_exact(&mut self, capacity: uint)
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);
fn shrink_to_fit(&mut self)
Shrink the capacity of the vector to match the length
Example
let mut vec = vec!(1, 2, 3); vec.shrink_to_fit(); assert_eq!(vec.capacity(), vec.len());
fn pop(&mut self) -> Option<T>
Remove the last element from a vector and return it, or None
if it is
empty.
Example
let mut vec = vec!(1, 2, 3); assert_eq!(vec.pop(), Some(3)); assert_eq!(vec, vec!(1, 2));
fn push(&mut self, value: T)
Append an element to a vector.
Failure
Fails if the number of elements in the vector overflows a uint
.
Example
let mut vec = vec!(1, 2); vec.push(3); assert_eq!(vec, vec!(1, 2, 3));
fn append_one(self, x: T) -> Vec<T>
Appends one element to the vector provided. The vector itself is then returned for use again.
Example
let vec = vec!(1, 2); let vec = vec.append_one(3); assert_eq!(vec, vec!(1, 2, 3));
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
let mut vec = vec!(1, 2, 3, 4); vec.truncate(2); assert_eq!(vec, vec!(1, 2));
fn as_mut_slice<'a>(&'a mut self) -> &'a mut [T]
Work with self
as a mutable slice.
Example
fn foo(slice: &mut [int]) {} let mut vec = vec!(1, 2); foo(vec.as_mut_slice());
fn move_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
let v = vec!(~"a", ~"b"); for s in v.move_iter() { // s has type ~str, not &~str 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.
fn get<'a>(&'a self, index: uint) -> &'a T
Returns a reference to the value at index index
.
Failure
Fails if index
is out of bounds
Example
let vec = vec!(1, 2, 3); assert!(vec.get(1) == &2);
fn get_mut<'a>(&'a mut self, index: uint) -> &'a mut T
Returns a mutable reference to the value at index index
.
Failure
Fails if index
is out of bounds
Example
let mut vec = vec!(1, 2, 3); *vec.get_mut(1) = 4; assert_eq!(vec, vec!(1, 4, 3));
fn iter<'a>(&'a self) -> Items<'a, T>
Returns an iterator over references to the elements of the vector in order.
Example
let vec = vec!(1, 2, 3); for num in vec.iter() { println!("{}", *num); }
fn mut_iter<'a>(&'a mut self) -> MutItems<'a, T>
Returns an iterator over mutable references to the elements of the vector in order.
Example
let mut vec = vec!(1, 2, 3); for num in vec.mut_iter() { *num = 0; }
fn sort_by(&mut self, compare: |&T, &T| -> Ordering)
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!(1, 2, 3, 4, 5)); // reverse sorting v.sort_by(|a, b| b.cmp(a)); assert_eq!(v, vec!(5, 4, 3, 2, 1));
fn slice<'a>(&'a self, start: uint, end: uint) -> &'a [T]
Returns a 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 vec = vec!(1, 2, 3, 4); assert!(vec.slice(0, 2) == [1, 2]);
fn tail<'a>(&'a self) -> &'a [T]
Returns a slice containing all but the first element of the vector.
Failure
Fails when the vector is empty.
Example
let vec = vec!(1, 2, 3); assert!(vec.tail() == [2, 3]);
fn tailn<'a>(&'a self, n: uint) -> &'a [T]
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!(1, 2, 3, 4); assert!(vec.tailn(2) == [3, 4]);
fn last<'a>(&'a self) -> Option<&'a T>
Returns a reference to the last element of a vector, or None
if it is
empty.
Example
let vec = vec!(1, 2, 3); assert!(vec.last() == Some(&3));
fn mut_last<'a>(&'a mut self) -> Option<&'a mut T>
Returns a mutable reference to the last element of a vector, or None
if it is empty.
Example
let mut vec = vec!(1, 2, 3); *vec.mut_last().unwrap() = 4; assert_eq!(vec, vec!(1, 2, 4));
fn swap_remove(&mut self, index: uint) -> Option<T>
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", ~"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 unshift(&mut self, element: T)
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!(1, 2, 3); vec.unshift(4); assert_eq!(vec, vec!(4, 1, 2, 3));
fn shift(&mut self) -> Option<T>
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!(1, 2, 3); assert!(vec.shift() == Some(1)); assert_eq!(vec, vec!(2, 3));
fn insert(&mut self, index: uint, element: T)
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!(1, 2, 3); vec.insert(1, 4); assert_eq!(vec, vec!(1, 4, 2, 3));
fn remove(&mut self, index: uint) -> Option<T>
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!(1, 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 push_all_move(&mut self, other: Vec<T>)
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!(~1); vec.push_all_move(vec!(~2, ~3, ~4)); assert_eq!(vec, vec!(~1, ~2, ~3, ~4));
fn mut_slice<'a>(&'a mut self, start: uint, end: uint) -> &'a mut [T]
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!(1, 2, 3, 4); assert!(vec.mut_slice(0, 2) == [1, 2]);
fn mut_slice_from<'a>(&'a mut self, start: uint) -> &'a mut [T]
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!(1, 2, 3, 4); assert!(vec.mut_slice_from(2) == [3, 4]);
fn mut_slice_to<'a>(&'a mut self, end: uint) -> &'a mut [T]
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!(1, 2, 3, 4); assert!(vec.mut_slice_to(2) == [1, 2]);
fn mut_split_at<'a>(&'a mut self, mid: uint) -> (&'a mut [T], &'a mut [T])
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!(1, 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 []); }
fn reverse(&mut self)
Reverse the order of elements in a vector, in place.
Example
let mut v = vec!(1, 2, 3); v.reverse(); assert_eq!(v, vec!(3, 2, 1));
fn slice_from<'a>(&'a self, start: uint) -> &'a [T]
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!(1, 2, 3); assert!(vec.slice_from(1) == [2, 3]);
fn slice_to<'a>(&'a self, end: uint) -> &'a [T]
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!(1, 2, 3); assert!(vec.slice_to(2) == [1, 2]);
fn init<'a>(&'a self) -> &'a [T]
Returns a slice containing all but the last element of the vector.
Failure
Fails if the vector is empty
fn as_ptr(&self) -> *T
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.
fn as_mut_ptr(&mut self) -> *mut T
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.
impl<T: TotalOrd> Vec<T>
fn sort(&mut self)
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));
impl<T: Eq> Vec<T>
fn contains(&self, x: &T) -> bool
Return true if a vector contains an element with the given value
Example
let vec = vec!(1, 2, 3); assert!(vec.contains(&1));
fn dedup(&mut self)
Remove consecutive repeated elements in the vector.
If the vector is sorted, this removes all duplicates.
Example
let mut vec = vec!(1, 2, 2, 3, 2); vec.dedup(); assert_eq!(vec, vec!(1, 2, 3, 2));
Trait Implementations
impl<T: Clone> Clone for Vec<T>
fn clone(&self) -> Vec<T>
Returns a copy of the value. The contents of owned pointers are copied to maintain uniqueness, while the contents of managed pointers are not copied.
fn clone_from(&mut self, source: &Self)
Perform copy-assignment from source
.
a.clone_from(&b)
is equivalent to a = b.clone()
in functionality,
but can be overridden to reuse the resources of a
to avoid unnecessary
allocations.
impl<T> FromIterator<T> for Vec<T>
fn from_iter<I: Iterator<T>>(iterator: I) -> Vec<T>
Build a container with elements from an external iterator.
impl<T> Extendable<T> for Vec<T>
fn extend<I: Iterator<T>>(&mut self, iterator: I)
Extend a container with the elements yielded by an iterator
impl<T: Eq> Eq for Vec<T>
impl<T: Ord> Ord for Vec<T>
fn lt(&self, other: &Vec<T>) -> bool
fn le(&self, other: &Self) -> bool
fn gt(&self, other: &Self) -> bool
fn ge(&self, other: &Self) -> bool
impl<T: TotalEq> TotalEq for Vec<T>
impl<T: TotalOrd> TotalOrd for Vec<T>
impl<T> Container for Vec<T>
fn len(&self) -> uint
Return the number of elements in the container
fn is_empty(&self) -> bool
Return true if the container contains no elements
impl<T> Mutable for Vec<T>
fn clear(&mut self)
Clear the container, removing all values.
impl<T> Vector<T> for Vec<T>
fn as_slice<'a>(&'a self) -> &'a [T]
Work with self
as a slice.
Example
fn foo(slice: &[int]) {} let vec = vec!(1, 2); foo(vec.as_slice());
impl<T> Drop for Vec<T>
fn drop(&mut self)
The drop
method, called when the value goes out of scope.
impl<T> Default for Vec<T>
impl<T: Show> Show for Vec<T>
impl<'a, S: Str> StrVector for Vec<S>
fn concat(&self) -> ~str
Concatenate a vector of strings.
fn connect(&self, sep: &str) -> ~str
Concatenate a vector of strings, placing a given separator between each.
impl IntoStr for Vec<Ascii>
fn into_str(self) -> ~str
Consume and convert to a string.
impl<S: Writer, T: Hash<S>> Hash<S> for Vec<T>
fn hash(&self, state: &mut S)
Compute a hash of the value.