Struct alloc::vec::Vec1.0.0[−][src]

pub struct Vec<T, A: Allocator = Global> { /* fields omitted */ }

Expand description

连续的可增长数组类型，写为 Vec<T>，发音为 ‘vector’。

Examples

let mut vec = Vec::new();
vec.push(1);
vec.push(2);

assert_eq!(vec.len(), 2);
assert_eq!(vec[0], 1);

assert_eq!(vec.pop(), Some(2));
assert_eq!(vec.len(), 1);

vec[0] = 7;
assert_eq!(vec[0], 7);

vec.extend([1, 2, 3].iter().copied());

for x in &vec {
    println!("{}", x);
}
assert_eq!(vec, [7, 1, 2, 3]);

Run

提供 vec! 宏可以使初始化更加方便:

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

Run

它还可以使用给定值初始化 Vec<T> 的每个元素。这可能比在单独的步骤中执行分配和初始化更为有效，尤其是在初始化零的 vector 时:

let vec = vec![0; 5];
assert_eq!(vec, [0, 0, 0, 0, 0]);

// 以下是等效的，但可能会更慢:
let mut vec = Vec::with_capacity(5);
vec.resize(5, 0);
assert_eq!(vec, [0, 0, 0, 0, 0]);

Run

有关更多信息，请参见容量和重新分配。

使用 Vec<T> 作为有效的栈:

let mut stack = Vec::new();

stack.push(1);
stack.push(2);
stack.push(3);

while let Some(top) = stack.pop() {
    // 打印 3、2、1
    println!("{}", top);
}

Run

Indexing

Vec 类型实现了 Index trait，因此允许按索引访问值。一个例子将更加明确:

let v = vec![0, 2, 4, 6];
println!("{}", v[1]); // 它将显示 '2'

Run

但是要小心: 如果您尝试访问 Vec 中没有的索引，则您的软件将为 panic! 您不可以做这个:

let v = vec![0, 2, 4, 6];
println!("{}", v[6]); // 它会 panic!

Run

如果要检查索引是否在 Vec 中，请使用 get 和 get_mut。

Slicing

Vec 可以是可变的。另一方面，切片是只读对象。要获得 slice，请使用 &。Example:

fn read_slice(slice: &[usize]) {
    // ...
}

let v = vec![0, 1];
read_slice(&v);

// ... 就这样!
// 您也可以这样:
let u: &[usize] = &v;
// 或像这样:
let u: &[_] = &v;

Run

在 Rust 中，当您只想提供读取访问权限时，将切片作为参数而不是 vectors 传递是更常见的。String 和 &str 也是如此。

容量和重新分配

vector 的容量是为将添加到 vector 上的任何 future 元素分配的空间量。请勿将其与 vector 的长度混淆，后者指定 vector 中的实际元素数量。如果 vector 的长度超过其容量，则其容量将自动增加，但必须重新分配其元素。

例如，容量为 10 且长度为 0 的 vector 将是一个空的 vector，具有 10 个以上元素的空间。将 10 个或更少的元素压入 vector 不会改变其容量或引起重新分配。但是，如果 vector 的长度增加到 11，则必须重新分配，这可能会很慢。因此，建议尽可能使用 Vec::with_capacity 来指定 vector 希望达到的大小。

Guarantees

由于其不可思议的基本特性，Vec 为其设计提供了很多保证。这样可以确保它在一般情况下的开销尽可能小，并且可以通过不安全的代码以原始方式正确地进行操作。请注意，这些保证是针对不合格的 Vec<T>。如果添加了其他类型参数 (例如，以支持自定义分配器)，则覆盖其默认值可能会更改行为。

从根本上讲，Vec 始终是 (指针，容量，长度) 三元组。不多不少。这些字段的顺序是完全不确定的，您应该使用适当的方法来修改它们。指针永远不会为空，因此此类型是经过空指针优化的。

但是，指针实际上可能并不指向分配的内存。特别是，如果您通过 Vec::new，vec![]，Vec::with_capacity(0) 或通过在空 Vec 上调用 shrink_to_fit 来构造容量为 0 的 Vec，则它将不会分配内存。同样，如果将零大小的类型存储在 Vec 内，则不会为它们分配空间。 Note 在这种情况下，Vec 可能不会报告 capacity 为 0。 Vec 将仅在 mem::size_of::<T>() * capacity() > 0 时分配。通常，Vec 的分配细节非常微妙 - 如果您打算使用 Vec 分配内存并将其用于其他用途 (传递给不安全的代码或构建自己的内存支持的集合)，请确保通过使用 from_raw_parts 恢复 Vec 然后丢弃它来释放该内存。

如果 Vec 具有已分配的内存，则它指向的内存在堆上 (由分配器 Rust 定义为默认使用)，并且其指针按顺序指向 len 初始化的连续元素 (您将执行的操作) 看看是否将其强制为切片)，然后是 capacity-len 逻辑上未初始化的连续元素。

包含元素 'a' 和 'b' 且容量为 4 的 vector 可以如下所示。顶部是 Vec 结构体，它包含一个指向堆中分配头，长度和容量的指针。底部是堆上的分配，即连续的内存块。

            ptr      len  capacity
       +--------+--------+--------+
       | 0x0123 |      2 |      4 |
       +--------+--------+--------+
            |
            v
Heap   +--------+--------+--------+--------+
       |    'a' |    'b' | uninit | uninit |
       +--------+--------+--------+--------+

uninit 代表未初始化的内存，请参见 MaybeUninit。
Note: ABI 不稳定，并且 Vec 不保证其内存布局 (包括字段顺序)。

Vec 永远不会执行小优化，因为实际上有两个原因会在其中将元素实际存储在栈中:

对于不安全的代码，正确地操纵 Vec 会更加困难。如果仅移动 Vec 的内容，它的地址就不会稳定，因此，确定 Vec 是否实际分配了内存将更加困难。
这将惩罚一般情况，每次访问都会产生一个额外的分支。

Vec 即使完全为空，也永远不会自动收缩。这样可以确保不会发生不必要的分配或释放。清空 Vec，然后将其填充回相同的 len，将不会引起对分配器的调用。如果您希望释放未使用的内存，请使用 shrink_to_fit 或 shrink_to。

push 如果报告的容量足够，则 insert 将永远不会 (重新) 分配。如果 len==capacity，push 和 insert 将 * (重新) 分配。也就是说，报告的容量是完全准确的，并且可以依赖。如果需要，它甚至可以用来手动释放 Vec 分配的内存。批量插入方法可能重新分配，即使在没有必要时也是如此。

Vec 在完全分配或调用 reserve 时重新分配时，不能保证任何特定的增长策略。当前的策略是基本的，使用非恒定增长因子可能是合乎需要的。无论使用哪种策略，当然都可以保证 O(1) 摊销 push。

vec![x; n], vec![a, b, c, d] 和 Vec::with_capacity(n) 都将产生具有所需容量的 Vec。如果 len==capacity (如 vec! 宏的情况)，那么 Vec<T> 可以与 Box<[T]> 相互转换，而无需重新分配或移动元素。

Vec 不会专门覆盖从其中删除的任何数据，但也不会专门保留它。它的未初始化内存是它可以使用的临时空间。通常，它只会执行最有效或最容易实现的任何事情。为了安全起见，请勿依赖删除的数据进行擦除。即使您丢弃了 Vec，它的缓冲区也可能被另一个 Vec 简单地重用。即使您先将 Vec 的内存清零，这可能不会实际发生，因为优化器不认为这是一个必须保留的副作用。但是，有一种情况我们不会中断: 使用 unsafe 代码写入多余的容量，然后增加长度以匹配，始终是有效的。

当前，Vec 不保证删除元素的顺序。顺序过去已更改，并且可能会再次更改。

Struct alloc::vec::Vec1.0.0[−][src]

Implementations

impl<T> Vec<T>

pub const fn new() -> Self

pub fn with_capacity(capacity: usize) -> Self

pub unsafe fn from_raw_parts( ptr: *mut T, length: usize, capacity: usize) -> Self

impl<T, A: Allocator> Vec<T, A>

pub const fn new_in(alloc: A) -> Self

pub fn with_capacity_in(capacity: usize, alloc: A) -> Self

pub unsafe fn from_raw_parts_in( ptr: *mut T, length: usize, capacity: usize, alloc: A) -> Self

pub fn into_raw_parts(self) -> (*mut T, usize, usize)

pub fn into_raw_parts_with_alloc(self) -> (*mut T, usize, usize, A)

pub fn capacity(&self) -> usize

pub fn reserve(&mut self, additional: usize)

pub fn reserve_exact(&mut self, additional: usize)

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

pub fn try_reserve_exact( &mut self, additional: usize) -> Result<(), TryReserveError>

pub fn shrink_to_fit(&mut self)

pub fn shrink_to(&mut self, min_capacity: usize)

pub fn into_boxed_slice(self) -> Box<[T], A>ⓘNotable traits for Box<I, A>impl<I: Iterator + ?Sized, A: Allocator> Iterator for Box<I, A> type Item = I::Item;impl<F: ?Sized + Future + Unpin, A: Allocator> Future for Box<F, A> where A: 'static, type Output = F::Output;

pub fn truncate(&mut self, len: usize)

pub fn as_slice(&self) -> &[T]

pub fn as_mut_slice(&mut self) -> &mut [T]

pub fn as_ptr(&self) -> *const T

pub fn as_mut_ptr(&mut self) -> *mut T

pub fn allocator(&self) -> &A

pub unsafe fn set_len(&mut self, new_len: usize)

pub fn swap_remove(&mut self, index: usize) -> T

pub fn insert(&mut self, index: usize, element: T)

pub fn remove(&mut self, index: usize) -> T

pub fn retain<F>(&mut self, f: F) where F: FnMut(&T) -> bool,

pub fn dedup_by_key<F, K>(&mut self, key: F) where F: FnMut(&mut T) -> K, K: PartialEq,

pub fn dedup_by<F>(&mut self, same_bucket: F) where F: FnMut(&mut T, &mut T) -> bool,

pub fn push(&mut self, value: T)

pub fn pop(&mut self) -> Option<T>

pub fn append(&mut self, other: &mut Self)

pub fn drain<R>(&mut self, range: R) -> Drain<'_, T, A>ⓘNotable traits for Drain<'_, T, A>impl<T, A: Allocator> Iterator for Drain<'_, T, A> type Item = T; where R: RangeBounds<usize>,

pub fn clear(&mut self)

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

#[must_use = "use `.truncate()` if you don't need the other half"]pub fn split_off(&mut self, at: usize) -> Self where A: Clone,

pub fn resize_with<F>(&mut self, new_len: usize, f: F) where F: FnMut() -> T,

pub fn leak<'a>(self) -> &'a mut [T] where A: 'a,

pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>]

pub fn split_at_spare_mut(&mut self) -> (&mut [T], &mut [MaybeUninit<T>])

impl<T: Clone, A: Allocator> Vec<T, A>

pub fn resize(&mut self, new_len: usize, value: T)

pub fn extend_from_slice(&mut self, other: &[T])

pub fn extend_from_within<R>(&mut self, src: R) where R: RangeBounds<usize>,

impl<T: PartialEq, A: Allocator> Vec<T, A>

pub fn dedup(&mut self)

impl<T, A: Allocator> Vec<T, A>

pub fn splice<R, I>( &mut self, range: R, replace_with: I) -> Splice<'_, I::IntoIter, A>ⓘNotable traits for Splice<'_, I, A>impl<I: Iterator, A: Allocator> Iterator for Splice<'_, I, A> type Item = I::Item; where R: RangeBounds<usize>, I: IntoIterator<Item = T>,

pub fn drain_filter<F>(&mut self, filter: F) -> DrainFilter<'_, T, F, A>ⓘNotable traits for DrainFilter<'_, T, F, A>impl<T, F, A: Allocator> Iterator for DrainFilter<'_, T, F, A> where F: FnMut(&mut T) -> bool, type Item = T; where F: FnMut(&mut T) -> bool,

Trait Implementations

impl<T, A: Allocator> AsMut<[T]> for Vec<T, A>

fn as_mut(&mut self) -> &mut [T]

impl<T, A: Allocator> AsMut<Vec<T, A>> for Vec<T, A>

fn as_mut(&mut self) -> &mut Vec<T, A>

impl<T, A: Allocator> AsRef<[T]> for Vec<T, A>

fn as_ref(&self) -> &[T]

impl<T, A: Allocator> AsRef<Vec<T, A>> for Vec<T, A>

fn as_ref(&self) -> &Vec<T, A>

impl<T> Borrow<[T]> for Vec<T>

fn borrow(&self) -> &[T]

impl<T> BorrowMut<[T]> for Vec<T>

fn borrow_mut(&mut self) -> &mut [T]

impl<T: Clone, A: Allocator + Clone> Clone for Vec<T, A>

fn clone(&self) -> Self

fn clone_from(&mut self, other: &Self)

impl<T: Debug, A: Allocator> Debug for Vec<T, A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl<T> Default for Vec<T>

fn default() -> Vec<T>

impl<T, A: Allocator> Deref for Vec<T, A>

type Target = [T]

pub unsafe fn from_raw_parts(
ptr: *mut T,
length: usize,
capacity: usize
) -> Self

pub unsafe fn from_raw_parts_in(
ptr: *mut T,
length: usize,
capacity: usize,
alloc: A
) -> Self

pub fn try_reserve_exact(
&mut self,
additional: usize
) -> Result<(), TryReserveError>

pub fn into_boxed_slice(self) -> Box<[T], A>ⓘ
Notable traits for Box<I, A>
`impl<I: Iterator + ?Sized, A: Allocator> Iterator for Box<I, A> type Item = I::Item;impl<F: ?Sized + Future + Unpin, A: Allocator> Future for Box<F, A> where A: 'static, type Output = F::Output;`

pub fn retain<F>(&mut self, f: F) where
F: FnMut(&T) -> bool,

pub fn dedup_by_key<F, K>(&mut self, key: F) where
F: FnMut(&mut T) -> K,
K: PartialEq,

pub fn dedup_by<F>(&mut self, same_bucket: F) where
F: FnMut(&mut T, &mut T) -> bool,

pub fn drain<R>(&mut self, range: R) -> Drain<'_, T, A>ⓘ
Notable traits for Drain<'_, T, A>
`impl<T, A: Allocator> Iterator for Drain<'_, T, A> type Item = T;`
where
R: RangeBounds<usize>,

#[must_use = "use `.truncate()` if you don't need the other half"]
pub fn split_off(&mut self, at: usize) -> Self where
A: Clone,

pub fn resize_with<F>(&mut self, new_len: usize, f: F) where
F: FnMut() -> T,

pub fn leak<'a>(self) -> &'a mut [T] where
A: 'a,

pub fn extend_from_within<R>(&mut self, src: R) where
R: RangeBounds<usize>,

pub fn splice<R, I>(
&mut self,
range: R,
replace_with: I
) -> Splice<'_, I::IntoIter, A>ⓘ
Notable traits for Splice<'_, I, A>
`impl<I: Iterator, A: Allocator> Iterator for Splice<'_, I, A> type Item = I::Item;`
where
R: RangeBounds<usize>,
I: IntoIterator<Item = T>,

pub fn drain_filter<F>(&mut self, filter: F) -> DrainFilter<'_, T, F, A>ⓘ
Notable traits for DrainFilter<'_, T, F, A>
`impl<T, F, A: Allocator> Iterator for DrainFilter<'_, T, F, A> where F: FnMut(&mut T) -> bool, type Item = T;`
where
F: FnMut(&mut T) -> bool,