From 18c420ed6250f605d3a67739d5513ffe4f2914d6 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 16 Dec 2014 20:12:30 -0500 Subject: [PATCH] Improve docs for std::vec --- src/libcollections/vec.rs | 179 ++++++++++++++++++++++---------------- 1 file changed, 105 insertions(+), 74 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 932366d77ad30..866147b140985 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -11,6 +11,38 @@ //! A growable list type, written `Vec` but pronounced 'vector.' //! //! Vectors have `O(1)` indexing, push (to the end) and pop (from the end). +//! +//! # Examples +//! +//! Explicitly creating a `Vec` with `new()`: +//! +//! ``` +//! let xs: Vec = Vec::new(); +//! ``` +//! +//! Using the `vec!` macro: +//! +//! ``` +//! let ys: Vec = 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::*; @@ -31,7 +63,7 @@ use core::uint; use slice::CloneSliceExt; -/// An owned, growable vector. +/// A growable list type, written `Vec` but pronounced 'vector.' /// /// # Examples /// @@ -65,7 +97,7 @@ use slice::CloneSliceExt; /// assert_eq!(vec, vec![1, 2, 3, 4]); /// ``` /// -/// Use a `Vec` as an efficient stack: +/// Use a `Vec` as an efficient stack: /// /// ``` /// let mut stack = Vec::new(); @@ -86,20 +118,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 { @@ -130,7 +159,7 @@ impl<'a, T> IntoCow<'a, Vec, [T]> for &'a [T] where T: Clone { } impl Vec { - /// Constructs a new, empty `Vec`. + /// Constructs a new, empty `Vec`. /// /// The vector will not allocate until elements are pushed onto it. /// @@ -149,16 +178,15 @@ impl Vec { Vec { ptr: EMPTY as *mut T, len: 0, cap: 0 } } - /// Constructs a new, empty `Vec` with the specified capacity. + /// Constructs a new, empty `Vec` 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` docs above, 'Capacity and reallocation'.) To create a + /// vector of a given length, use `Vec::from_elem` or `Vec::from_fn`. /// /// # Examples /// @@ -192,10 +220,10 @@ impl Vec { } } - /// Creates and initializes a `Vec`. + /// Creates and initializes a `Vec`. /// - /// Creates a `Vec` of size `length` and initializes the elements to the - /// value returned by the closure `op`. + /// Creates a `Vec` of size `length` and initializes the elements to the value returned by + /// the closure `op`. /// /// # Examples /// @@ -260,10 +288,9 @@ impl Vec { /// 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`. 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 { @@ -273,11 +300,10 @@ impl Vec { dst } - /// Consumes the `Vec`, partitioning it based on a predicate. + /// Consumes the `Vec`, 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` 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. /// /// # Examples /// @@ -306,9 +332,9 @@ impl Vec { } impl Vec { - /// Constructs a `Vec` with copies of a value. + /// Constructs a `Vec` with copies of a value. /// - /// Creates a `Vec` with `length` copies of `value`. + /// Creates a `Vec` with `length` copies of `value`. /// /// # Examples /// @@ -331,10 +357,10 @@ impl Vec { } } - /// Appends all elements in a slice to the `Vec`. + /// Appends all elements in a slice to the `Vec`. /// /// 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`. The `other` vector is traversed in-order. /// /// # Examples /// @@ -363,9 +389,9 @@ impl Vec { } } - /// Grows the `Vec` in-place. + /// Grows the `Vec` in-place. /// - /// Adds `n` copies of `value` to the `Vec`. + /// Adds `n` copies of `value` to the `Vec`. /// /// # Examples /// @@ -387,7 +413,7 @@ impl Vec { /// 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`s /// `(a, b)`, where all elements of `a` satisfy `f` and all elements of `b` /// do not. The order of elements is preserved. /// @@ -639,8 +665,7 @@ unsafe fn dealloc(ptr: *mut T, len: uint) { } impl Vec { - /// Returns the number of elements the vector can hold without - /// reallocating. + /// Returns the number of elements the vector can hold without reallocating. /// /// # Examples /// @@ -661,7 +686,7 @@ impl Vec { } /// 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`. The collection may reserve more space to avoid frequent reallocations. /// /// # Panics /// @@ -695,7 +720,7 @@ impl Vec { } /// 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`. 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 @@ -722,16 +747,19 @@ impl Vec { } } - /// 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 = Vec::with_capacity(10); + /// /// vec.push_all(&[1, 2, 3]); /// assert_eq!(vec.capacity(), 10); + /// /// vec.shrink_to_fit(); /// assert!(vec.capacity() >= 3); /// ``` @@ -820,14 +848,14 @@ impl Vec { } } - /// 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); @@ -852,9 +880,8 @@ impl Vec { /// 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 /// @@ -870,8 +897,10 @@ impl Vec { 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. /// @@ -900,13 +929,12 @@ impl Vec { 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 /// @@ -939,9 +967,9 @@ impl Vec { } } - /// 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 /// @@ -980,8 +1008,8 @@ impl Vec { /// 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 /// @@ -1070,8 +1098,7 @@ impl Vec { } } - /// 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 /// @@ -1099,7 +1126,9 @@ impl Vec { /// /// ``` /// let mut v = vec![1i, 2, 3]; + /// /// v.clear(); + /// /// assert!(v.is_empty()); /// ``` #[inline] @@ -1108,7 +1137,7 @@ impl Vec { self.truncate(0) } - /// Return the number of elements in the vector + /// Returns the number of elements in the vector. /// /// # Examples /// @@ -1120,13 +1149,14 @@ impl Vec { #[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()); /// ``` @@ -1161,7 +1191,9 @@ impl Vec { /// /// ``` /// 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"] @@ -1433,10 +1465,9 @@ impl Drop for MoveItems { /// 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>(mut iter: V) -> (Vec, Vec) { let (lo, _) = iter.size_hint();