mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

rollup merge of #19943: steveklabnik/doc_std_vec

Browse Source 
Random improvements to the `std::vec` docs.
This commit is contained in:
Alex Crichton 2014-12-17 08:35:52 -08:00
commit 7ffbd8bad5
1 changed files with 105 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
src/libcollections/vec.rs
View File

@ -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 core::uint;
use slice::CloneSliceExt;
/// An owned, growable vector.
/// A growable list type, written `Vec<T>` but pronounced 'vector.'
///
/// # Examples
///
@ -66,7 +98,7 @@ use slice::CloneSliceExt;
/// 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 @@ use slice::CloneSliceExt;
///
/// # 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 @@ impl<'a, T> IntoCow<'a, Vec<T>, [T]> for &'a [T] where T: Clone {
}
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 @@ impl<T> 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 @@ impl<T> 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 @@ impl<T> Vec<T> {
/// 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 @@ impl<T> 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 @@ impl<T> Vec<T> {
}
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 @@ impl<T: Clone> 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 @@ impl<T: Clone> Vec<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 @@ impl<T: Clone> Vec<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 @@ impl<T> Vec<T> {
}
/// 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 @@ impl<T> Vec<T> {
}
/// 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 @@ impl<T> Vec<T> {
}
}
/// 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 @@ impl<T> Vec<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 @@ impl<T> Vec<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 @@ impl<T> Vec<T> {
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 @@ impl<T> Vec<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 @@ impl<T> Vec<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 @@ impl<T> Vec<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 @@ impl<T> Vec<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 @@ impl<T> Vec<T> {
///
/// ```
/// let mut v = vec![1i, 2, 3];
///
/// v.clear();
///
/// assert!(v.is_empty());
/// ```
#[inline]
@ -1116,7 +1145,7 @@ impl<T> Vec<T> {
self.truncate(0)
}
/// Return the number of elements in the vector
/// Returns the number of elements in the vector.
///
/// # Examples
///
@ -1128,13 +1157,14 @@ impl<T> Vec<T> {
#[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 @@ impl<T> Drop for MoveItems<T> {
/// 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();