Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
int
Rust
提交
7ffbd8ba
R
Rust
项目概览
int
/
Rust
大约 1 年 前同步成功
通知
1
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
R
Rust
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
7ffbd8ba
编写于
12月 17, 2014
作者:
A
Alex Crichton
浏览文件
操作
浏览文件
下载
差异文件
rollup merge of #19943: steveklabnik/doc_std_vec
Random improvements to the `std::vec` docs.
上级
cbc3cf7a
18c420ed
变更
1
隐藏空白更改
内联
并排
Showing
1 changed file
with
105 addition
and
74 deletion
+105
-74
src/libcollections/vec.rs
src/libcollections/vec.rs
+105
-74
未找到文件。
src/libcollections/vec.rs
浏览文件 @
7ffbd8ba
...
...
@@ -11,6 +11,38 @@
//! A growable list type, written `Vec<T>` but pronounced 'vector.'
//!
//! Vectors have `O(1)` indexing, push (to the end) and pop (from the end).
//!
//! # Examples
//!
//! Explicitly creating a `Vec<T>` with `new()`:
//!
//! ```
//! let xs: Vec<i32> = Vec::new();
//! ```
//!
//! Using the `vec!` macro:
//!
//! ```
//! let ys: Vec<i32> = vec![];
//!
//! let zs = vec![1i32, 2, 3, 4, 5];
//! ```
//!
//! Push:
//!
//! ```
//! let mut xs = vec![1i32, 2];
//!
//! xs.push(3);
//! ```
//!
//! And pop:
//!
//! ```
//! let mut xs = vec![1i32, 2];
//!
//! let two = xs.pop();
//! ```
use
core
::
prelude
::
*
;
...
...
@@ -32,7 +64,7 @@
use
slice
::
CloneSliceExt
;
/// A
n owned, growable vector.
/// A
growable list type, written `Vec<T>` but pronounced 'vector.'
///
/// # Examples
///
...
...
@@ -66,7 +98,7 @@
/// assert_eq!(vec, vec![1, 2, 3, 4]);
/// ```
///
/// Use a `Vec` as an efficient stack:
/// Use a `Vec
<T>
` as an efficient stack:
///
/// ```
/// let mut stack = Vec::new();
...
...
@@ -87,20 +119,17 @@
///
/// # 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.
/// 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.
/// 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.
#[unsafe_no_drop_flag]
#[stable]
pub
struct
Vec
<
T
>
{
...
...
@@ -131,7 +160,7 @@ fn into_cow(self) -> CowVec<'a, T> {
}
impl
<
T
>
Vec
<
T
>
{
/// Constructs a new, empty `Vec`.
/// Constructs a new, empty `Vec
<T>
`.
///
/// The vector will not allocate until elements are pushed onto it.
///
...
...
@@ -150,16 +179,15 @@ pub fn new() -> Vec<T> {
Vec
{
ptr
:
EMPTY
as
*
mut
T
,
len
:
0
,
cap
:
0
}
}
/// Constructs a new, empty `Vec` with the specified capacity.
/// Constructs a new, empty `Vec
<T>
` 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.
/// 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`.
/// 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<T>` docs above, 'Capacity and reallocation'.) To create a
/// vector of a given length, use `Vec::from_elem` or `Vec::from_fn`.
///
/// # Examples
///
...
...
@@ -193,10 +221,10 @@ pub fn with_capacity(capacity: uint) -> Vec<T> {
}
}
/// Creates and initializes a `Vec`.
/// Creates and initializes a `Vec
<T>
`.
///
/// Creates a `Vec
` of size `length` and initializes the elements to the
///
value returned by
the closure `op`.
/// Creates a `Vec
<T>` of size `length` and initializes the elements to the value returned by
/// the closure `op`.
///
/// # Examples
///
...
...
@@ -261,10 +289,9 @@ pub unsafe fn from_raw_parts(ptr: *mut T, length: uint,
/// Creates a vector by copying the elements from a raw pointer.
///
/// This function will copy `elts` contiguous elements starting at `ptr`
/// into a new allocation owned by the returned `Vec`. The elements of the
/// buffer are copied into the vector without cloning, as if `ptr::read()`
/// were called on them.
/// This function will copy `elts` contiguous elements starting at `ptr` into a new allocation
/// owned by the returned `Vec<T>`. The elements of the buffer are copied into the vector
/// without cloning, as if `ptr::read()` were called on them.
#[inline]
#[unstable
=
"just renamed from raw::from_buf"
]
pub
unsafe
fn
from_raw_buf
(
ptr
:
*
const
T
,
elts
:
uint
)
->
Vec
<
T
>
{
...
...
@@ -274,11 +301,10 @@ pub unsafe fn from_raw_buf(ptr: *const T, elts: uint) -> Vec<T> {
dst
}
/// Consumes the `Vec`, partitioning it based on a predicate.
/// Consumes the `Vec
<T>
`, partitioning it based on a predicate.
///
/// 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.
/// Partitions the `Vec<T>` into two `Vec<T>`s `(A,B)`, where all elements of `A` satisfy `f`
/// and all elements of `B` do not. The order of elements is preserved.
///
/// # Examples
///
...
...
@@ -307,9 +333,9 @@ pub fn partition<F>(self, mut f: F) -> (Vec<T>, Vec<T>) where F: FnMut(&T) -> bo
}
impl
<
T
:
Clone
>
Vec
<
T
>
{
/// Constructs a `Vec` with copies of a value.
/// Constructs a `Vec
<T>
` with copies of a value.
///
/// Creates a `Vec` with `length` copies of `value`.
/// Creates a `Vec
<T>
` with `length` copies of `value`.
///
/// # Examples
///
...
...
@@ -332,10 +358,10 @@ pub fn from_elem(length: uint, value: T) -> Vec<T> {
}
}
/// Appends all elements in a slice to the `Vec`.
/// Appends all elements in a slice to the `Vec
<T>
`.
///
/// Iterates over the slice `other`, clones each element, and then appends
/// it to this `Vec`. The `other` vector is traversed in-order.
/// it to this `Vec
<T>
`. The `other` vector is traversed in-order.
///
/// # Examples
///
...
...
@@ -364,9 +390,9 @@ pub fn push_all(&mut self, other: &[T]) {
}
}
/// Grows the `Vec` in-place.
/// Grows the `Vec
<T>
` in-place.
///
/// Adds `n` copies of `value` to the `Vec`.
/// Adds `n` copies of `value` to the `Vec
<T>
`.
///
/// # Examples
///
...
...
@@ -388,7 +414,7 @@ pub fn grow(&mut self, n: uint, value: T) {
/// Partitions a vector based on a predicate.
///
/// Clones the elements of the vector, partitioning them into two `Vec`s
/// Clones the elements of the vector, partitioning them into two `Vec
<T>
`s
/// `(a, b)`, where all elements of `a` satisfy `f` and all elements of `b`
/// do not. The order of elements is preserved.
///
...
...
@@ -647,8 +673,7 @@ unsafe fn dealloc<T>(ptr: *mut T, len: uint) {
}
impl
<
T
>
Vec
<
T
>
{
/// Returns the number of elements the vector can hold without
/// reallocating.
/// Returns the number of elements the vector can hold without reallocating.
///
/// # Examples
///
...
...
@@ -669,7 +694,7 @@ pub fn reserve_additional(&mut self, extra: 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.
/// `Vec
<T>
`. The collection may reserve more space to avoid frequent reallocations.
///
/// # Panics
///
...
...
@@ -703,7 +728,7 @@ pub fn reserve(&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.
/// given `Vec
<T>
`. 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
...
...
@@ -730,16 +755,19 @@ pub fn reserve_exact(&mut self, additional: uint) {
}
}
/// 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.
/// 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.
///
/// # Examples
///
/// ```
/// 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);
/// ```
...
...
@@ -828,14 +856,14 @@ pub fn as_mut_slice<'a>(&'a mut self) -> &'a mut [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.
/// 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.
///
/// # Examples
///
/// ```
/// let v = vec!["a".to_string(), "b".to_string()];
///
/// for s in v.into_iter() {
/// // s has type String, not &String
/// println!("{}", s);
...
...
@@ -860,9 +888,8 @@ pub fn into_iter(self) -> MoveItems<T> {
/// 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.
/// 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.
///
/// # Examples
///
...
...
@@ -878,8 +905,10 @@ pub unsafe fn set_len(&mut self, len: uint) {
self
.len
=
len
;
}
/// 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).
/// 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.
///
...
...
@@ -908,13 +937,12 @@ pub fn swap_remove(&mut self, index: uint) -> Option<T> {
self
.pop
()
}
/// Inserts an element at position `index` within the vector, shifting all
///
elements after
position `i` one position to the right.
/// 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).
/// Panics if `index` is not between `0` and the vector's length (both bounds inclusive).
///
/// # Examples
///
...
...
@@ -947,9 +975,9 @@ pub fn insert(&mut self, index: uint, element: 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.
/// 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.
///
/// # Examples
///
...
...
@@ -988,8 +1016,8 @@ pub fn remove(&mut self, index: uint) -> Option<T> {
/// 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.
/// 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.
///
/// # Examples
///
...
...
@@ -1078,8 +1106,7 @@ pub fn push(&mut self, value: T) {
}
}
/// Removes the last element from a vector and returns it, or `None` if
/// it is empty.
/// Removes the last element from a vector and returns it, or `None` if it is empty.
///
/// # Examples
///
...
...
@@ -1107,7 +1134,9 @@ pub fn pop(&mut self) -> Option<T> {
///
/// ```
/// let mut v = vec![1i, 2, 3];
///
/// v.clear();
///
/// assert!(v.is_empty());
/// ```
#[inline]
...
...
@@ -1116,7 +1145,7 @@ pub fn clear(&mut self) {
self
.truncate
(
0
)
}
/// Return
the number of elements in the vector
/// Return
s the number of elements in the vector.
///
/// # Examples
///
...
...
@@ -1128,13 +1157,14 @@ pub fn clear(&mut self) {
#[stable]
pub
fn
len
(
&
self
)
->
uint
{
self
.len
}
/// Returns
true if the vector contains no elements
/// Returns
`true` if the vector contains no elements.
///
/// # Examples
///
/// ```
/// let mut v = Vec::new();
/// assert!(v.is_empty());
///
/// v.push(1i);
/// assert!(!v.is_empty());
/// ```
...
...
@@ -1169,7 +1199,9 @@ impl<T: PartialEq> Vec<T> {
///
/// ```
/// let mut vec = vec![1i, 2, 2, 3, 2];
///
/// vec.dedup();
///
/// assert_eq!(vec, vec![1i, 2, 3, 2]);
/// ```
#[unstable
=
"this function may be renamed"
]
...
...
@@ -1442,10 +1474,9 @@ fn drop(&mut self) {
/// Converts an iterator of pairs into a pair of vectors.
///
/// Returns a tuple containing two vectors where the i-th element of the first
/// vector contains the first element of the i-th tuple of the input iterator,
/// and the i-th element of the second vector contains the second element
/// of the i-th tuple of the input iterator.
/// Returns a tuple containing two vectors where the i-th element of the first vector contains the
/// first element of the i-th tuple of the input iterator, and the i-th element of the second
/// vector contains the second element of the i-th tuple of the input iterator.
#[unstable
=
"this functionality may become more generic over time"
]
pub
fn
unzip
<
T
,
U
,
V
:
Iterator
<
(
T
,
U
)
>>
(
mut
iter
:
V
)
->
(
Vec
<
T
>
,
Vec
<
U
>
)
{
let
(
lo
,
_
)
=
iter
.size_hint
();
...
...
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录