Skip to content

R
Rust

int / Rust
大约 1 年 前同步成功

通知 1
Star 0
Fork 0
R
Rust

体验新版 GitCode，发现更多精彩内容 >>

提交 7ffbd8ba 编写于 作者: A Alex Crichton
浏览文件
操作

rollup merge of #19943: steveklabnik/doc_std_vec 

Random improvements to the `std::vec` docs.
上级 cbc3cf7a 18c420ed
隐藏空白更改
内联 并排
Showing with 105 addition and 74 deletion
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;
/// An 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
/// Returns 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.
先完成此消息的编辑！
想要评论请 注册 或