Constructs a new, empty dynamic Vec.

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

Examples

let vec = Vec::new();

Constructs a new, empty dynamic Vec with at least the specified capacity.

The vector will be able to hold at least capacity elements without reallocating. This method is allowed to allocate for more elements than capacity. If capacity is 0, the vector will not allocate.

It is important to note that although the returned vector has the minimum capacity specified, the vector will have a zero length. For an explanation of the difference between length and capacity, see Capacity and reallocation.

If it is important to know the exact allocated capacity of a Vec, always use the capacity method after construction.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Examples

let vec = Vec::with_capacity(10);

// The vector contains no items, even though it has capacity for more
assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 10);

// These are all done without reallocating...
for i in 0..10 {
   vec.push(i);
}

assert_eq!(vec.len(), 10);
assert!(vec.capacity() >= 10);

// ...but this may make the vector reallocate
vec.push(11);
assert_eq!(vec.len(), 11);
assert!(vec.capacity() >= 11);

Returns the number of elements in the vector, also referred to as its 'length'.

Examples

let a = [1, 2, 3];
assert_eq!(a.len(), 3);

Returns true if the vector contains no elements.

Examples

let v = Vec::new();
assert!(v.is_empty());

v.push(1);
assert!(!v.is_empty());

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

Examples

let vec = Vec::with_capacity(10);
vec.push(42);
assert!(vec.capacity() >= 10);

Returns a reference to an element or subslice depending on the type of index.

• If given a position, returns a reference to the element at that position or None if out of bounds.
• If given a range, returns the subslice corresponding to that range, or None if out of bounds.

Examples

let v = [1, 4, 3];
assert_eq!(Some(4), v.get(1));
assert_eq!(Some([1, 4]), v.get(0..2));
assert_eq!(Some([1, 4, 3]), v.get(0..=2));
assert_eq!(Some([1, 4, 3]), v.get(0..));
assert_eq!(Some([1, 4, 3]), v.get(..));
assert_eq!(Some([4, 3]), v.get(1..));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));

Clears the vector, removing all values.

Note that this method has no effect on the allocated capacity of the vector.

Examples

let v = [1, 2, 3];

v.clear();

assert!(v.is_empty());

Extend these bytes with another collection.

Examples

let vec = [1, 2, 3, 4];
vec.extend([5, 6, 7, 8]);
assert_eq!(vec, [1, 2, 3, 4, 5, 6, 7, 8]);

Iterate over the collection.

Examples

let vec = [1, 2, 3, 4];
let it = vec.iter();

assert_eq!(Some(1), it.next());
assert_eq!(Some(4), it.next_back());

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

If you'd like to pop the first element, consider using VecDeque::pop_front instead.

Examples

let vec = [1, 2, 3];
assert_eq!(vec.pop(), Some(3));
assert_eq!(vec, [1, 2]);

Appends an element to the back of a collection.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Examples

let vec = [1, 2];
vec.push(3);
assert_eq!(vec, [1, 2, 3]);

Removes and returns the element at position index within the vector, shifting all elements after it to the left.

Note: Because this shifts over the remaining elements, it has a worst-case performance of O(n). If you don't need the order of elements to be preserved, use swap_remove instead. If you'd like to remove elements from the beginning of the Vec, consider using VecDeque::pop_front instead.

Panics

Panics if index is out of bounds.

let v = [1, 2, 3];
v.remove(3);

Examples

let v = [1, 2, 3];
assert_eq!(v.remove(1), 2);
assert_eq!(v, [1, 3]);

Inserts an element at position index within the vector, shifting all elements after it to the right.

Panics

Panics if index > len.

Examples

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

Clone the vector.

Examples

let a = [1, 2, 3];
let b = a.clone();

b.push(4);

assert_eq!(a, [1, 2, 3]);
assert_eq!(b, [1, 2, 3, 4]);

Sort a vector by the specified comparator function.

Examples

use std::ops::cmp;

let values = [1, 2, 3];
values.sort_by(|a, b| cmp(b, a))

Sort the vector.

This require all elements to be of the same type, and implement total ordering per the [CMP] protocol.

Panics

If any elements present are not comparable, this method will panic.

This will panic because a tuple and a string are not comparable:

let values = [(3, 1), "hello"];
values.sort();

This too will panic because floating point values which do not have a total ordering:

let values = [1.0, 2.0, f64::NAN];
values.sort();

Examples

let values = [3, 2, 1];
values.sort();
assert_eq!(values, [1, 2, 3]);

let values = [(3, 1), (2, 1), (1, 1)];
values.sort();
assert_eq!(values, [(1, 1), (2, 1), (3, 1)]);

Construct an iterator over the tuple.

Examples

let vec = [1, 2, 3];
let out = [];

for v in vec {
   out.push(v);
}

assert_eq!(out, [1, 2, 3]);

Inserts a value into the vector.

Examples

let vec = [1, 2, 3];
vec[0] = "a";
assert_eq!(vec, ["a", 2, 3]);

Returns a reference to an element or subslice depending on the type of index.

• If given a position, returns a reference to the element at that position or None if out of bounds.
• If given a range, returns the subslice corresponding to that range, or None if out of bounds.

Panics

Panics if the specified index is out of range.

let v = [10, 40, 30];
assert_eq!(None, v[1..4]);

let v = [10, 40, 30];
assert_eq!(None, v[3]);

Examples

let v = [10, 40, 30];
assert_eq!(40, v[1]);
assert_eq!([10, 40], v[0..2]);

Write a debug representation to a string.

This calls the [STRING_DEBUG] protocol over all elements of the collection.

Examples

let vec = [1, 2, 3];
assert_eq!(format!("{:?}", vec), "[1, 2, 3]");

Perform a partial equality check with this vector.

This can take any argument which can be converted into an iterator using [INTO_ITER].

Examples

let vec = [1, 2, 3];

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

Perform a total equality check with this vector.

Examples

use std::ops::eq;

let vec = [1, 2, 3];

assert!(eq(vec, [1, 2, 3]));
assert!(!eq(vec, [2, 3, 4]));

Perform a partial comparison check with this vector.

Examples

let vec = [1, 2, 3];

assert!(vec > [0, 2, 3]);
assert!(vec < [2, 2, 3]);

Perform a total comparison check with this vector.

Examples

use std::cmp::Ordering;
use std::ops::cmp;

let vec = [1, 2, 3];

assert_eq!(cmp(vec, [0, 2, 3]), Ordering::Greater);
assert_eq!(cmp(vec, [2, 2, 3]), Ordering::Less);

Calculate the hash of a vector.

Examples

use std::ops::hash;

assert_eq!(hash([0, 2, 3]), hash([0, 2, 3]));