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 vector.

Examples

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

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

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]);

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)]);

Resizes the Vec in-place so that len is equal to new_len.

If new_len is greater than len, the Vec is extended by the difference, with each additional slot filled with value. If new_len is less than len, the Vec is simply truncated.

This method requires T to implement [Clone], in order to be able to clone the passed value. If you need more flexibility (or want to rely on [Default] instead of [Clone]), use [Vec::resize_with]. If you only need to resize to a smaller size, use [Vec::truncate].

Examples

let vec = ["hello"];
vec.resize(3, "world");
assert_eq!(vec, ["hello", "world", "world"]);

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

Resizing calls CLONE each new element, which means they are not structurally shared:

let inner = [1];
let vec = [2];
vec.resize(3, inner);

inner.push(3);
vec[1].push(4);

assert_eq!(vec, [2, [1, 4], [1]]);

Clone the specified value.

Examples

let a = 42;
let b = a;
let c = a.clone();

a += 1;

assert_eq!(a, 43);
assert_eq!(b, 42);
assert_eq!(c, 42);

Compare two values for equality.

Examples

assert_eq!(1.eq(2), false);
assert_eq!(2.eq(2), true);
assert_eq!(2.eq(1), false);

Compare two values for inequality.

Examples

assert_eq!(1.ne(2), true);
assert_eq!(2.ne(2), false);
assert_eq!(2.ne(1), true);

Compare two values.

Examples

use std::cmp::Ordering;

assert_eq!(1.partial_cmp(2), Some(Ordering::Less));
assert_eq!(2.partial_cmp(2), Some(Ordering::Equal));
assert_eq!(2.partial_cmp(1), Some(Ordering::Greater));

Tests less than (for self and other) and is used by the < operator.

Examples

assert_eq!(1.0 < 1.0, false);
assert_eq!(1.0 < 2.0, true);
assert_eq!(2.0 < 1.0, false);

Tests less than or equal to (for self and other) and is used by the <= operator.

Examples

assert_eq!(1.0 <= 1.0, true);
assert_eq!(1.0 <= 2.0, true);
assert_eq!(2.0 <= 1.0, false);

Tests greater than (for self and other) and is used by the > operator.

Examples

assert_eq!(1.0 > 1.0, false);
assert_eq!(1.0 > 2.0, false);
assert_eq!(2.0 > 1.0, true);

Tests greater than or equal to (for self and other) and is used by the >= operator.

Examples

assert_eq!(1.0 >= 1.0, true);
assert_eq!(1.0 >= 2.0, false);
assert_eq!(2.0 >= 1.0, true);

Compare two values.

Examples

use std::cmp::Ordering;

assert_eq!(1.cmp(2), Ordering::Less);
assert_eq!(2.cmp(2), Ordering::Equal);
assert_eq!(2.cmp(1), Ordering::Greater);

Return the minimum of two values.

Examples

assert_eq!(1.min(2), 1);
assert_eq!(2.min(2), 2);
assert_eq!(2.min(1), 1);

Return the maximum of two values.

Examples

assert_eq!(1.max(2), 2);
assert_eq!(2.max(2), 2);
assert_eq!(2.max(1), 2);

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]);

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]);

Inserts a value into the vector.

Examples

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

Write a debug representation to a string.

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

Examples

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

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]);

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]));

The protocol behind the < operator.

The protocol behind the <= operator.

The protocol behind the > operator.

The protocol behind the >= operator.

The implementation protocol for the PartialOrd::min method.

The implementation protocol for the PartialOrd::max method.