@@ -51,10 +51,27 @@ pub static PTR_MARKER: u8 = 0;
5151/// The `vec!` macro is provided to make initialization more convenient:
5252///
5353/// ```rust
54- /// let mut vec = vec!( 1i, 2i, 3i) ;
54+ /// let mut vec = vec![ 1i, 2i, 3i] ;
5555/// vec.push(4);
56- /// assert_eq!(vec, vec!( 1, 2, 3, 4) );
56+ /// assert_eq!(vec, vec![ 1, 2, 3, 4] );
5757/// ```
58+ ///
59+ /// # Capacity and reallocation
60+ ///
61+ /// The capacity of a vector is the amount of space allocated for any future
62+ /// elements that will be added onto the vector. This is not to be confused
63+ /// with the *length* of a vector, which specifies the number of actual
64+ /// elements within the vector. If a vector's length exceeds its capacity,
65+ /// its capacity will automatically be increased, but its elements will
66+ /// have to be reallocated.
67+ ///
68+ /// For example, a vector with capacity 10 and length 0 would be an empty
69+ /// vector with space for 10 more elements. Pushing 10 or fewer elements onto
70+ /// the vector will not change its capacity or cause reallocation to occur.
71+ /// However, if the vector's length is increased to 11, it will have to
72+ /// reallocate, which can be slow. For this reason, it is recommended
73+ /// to use `Vec::with_capacity` whenever possible to specify how big the vector
74+ /// is expected to get.
5875#[ unsafe_no_drop_flag]
5976pub struct Vec < T > {
6077 len : uint ,
@@ -87,11 +104,28 @@ impl<T> Vec<T> {
87104/// The vector will be able to hold exactly `capacity` elements without
88105/// reallocating. If `capacity` is 0, the vector will not allocate.
89106///
107+ /// It is important to note that this function does not specify the
108+ /// *length* of the returned vector, but only the *capacity*. (For an
109+ /// explanation of the difference between length and capacity, see
110+ /// the main `Vec` docs above, 'Capacity and reallocation'.) To create
111+ /// a vector of a given length, use `Vec::from_elem` or `Vec::from_fn`.
112+ ///
90113/// # Example
91114///
92115/// ```rust
93116/// # use std::vec::Vec;
94- /// let vec: Vec<int> = Vec::with_capacity(10);
117+ /// let mut vec: Vec<int> = Vec::with_capacity(10);
118+ ///
119+ /// // The vector contains no items, even though it has capacity for more
120+ /// assert_eq!(vec.len(), 0);
121+ ///
122+ /// // These are all done without reallocating...
123+ /// for i in range(0u, 10) {
124+ /// vec.push(i);
125+ /// }
126+ ///
127+ /// // ...but this may make the vector reallocate
128+ /// vec.push(11);
95129/// ```
96130#[ inline]
97131 pub fn with_capacity ( capacity : uint ) -> Vec < T > {
0 commit comments