16
16
//!
17
17
//! # Examples
18
18
//!
19
- //! You can explicitly create a `Vec<T>` with `new()`:
19
+ //! You can explicitly create a [ `Vec<T>`] with [ `new()`] :
20
20
//!
21
21
//! ```
22
22
//! let v: Vec<i32> = Vec::new();
23
23
//! ```
24
24
//!
25
- //! ...or by using the `vec!` macro:
25
+ //! ...or by using the [ `vec!`] macro:
26
26
//!
27
27
//! ```
28
28
//! let v: Vec<i32> = vec![];
32
32
//! let v = vec![0; 10]; // ten zeroes
33
33
//! ```
34
34
//!
35
- //! You can `push` values onto the end of a vector (which will grow the vector
35
+ //! You can [ `push`] values onto the end of a vector (which will grow the vector
36
36
//! as needed):
37
37
//!
38
38
//! ```
49
49
//! let two = v.pop();
50
50
//! ```
51
51
//!
52
- //! Vectors also support indexing (through the `Index` and `IndexMut` traits):
52
+ //! Vectors also support indexing (through the [ `Index`] and [ `IndexMut`] traits):
53
53
//!
54
54
//! ```
55
55
//! let mut v = vec![1, 2, 3];
56
56
//! let three = v[2];
57
57
//! v[1] = v[1] + 5;
58
58
//! ```
59
+ //!
60
+ //! [`Vec<T>`]: ../../std/vec/struct.Vec.html
61
+ //! [`new()`]: ../../std/vec/struct.Vec.html#method.new
62
+ //! [`push`]: ../../std/vec/struct.Vec.html#method.push
63
+ //! [`Index`]: ../../std/ops/trait.Index.html
64
+ //! [`IndexMut`]: ../../std/ops/trait.IndexMut.html
65
+ //! [`vec!`]: ../../std/macro.vec.html
59
66
60
67
#![ stable( feature = "rust1" , since = "1.0.0" ) ]
61
68
@@ -79,7 +86,7 @@ use core::slice;
79
86
use super :: SpecExtend ;
80
87
use super :: range:: RangeArgument ;
81
88
82
- /// A contiguous growable array type, written `Vec<T>` but pronounced 'vector.'
89
+ /// A contiguous growable array type, written `Vec<T>` but pronounced 'vector'.
83
90
///
84
91
/// # Examples
85
92
///
@@ -105,7 +112,7 @@ use super::range::RangeArgument;
105
112
/// assert_eq!(vec, [7, 1, 2, 3]);
106
113
/// ```
107
114
///
108
- /// The `vec!` macro is provided to make initialization more convenient:
115
+ /// The [ `vec!`] macro is provided to make initialization more convenient:
109
116
///
110
117
/// ```
111
118
/// let mut vec = vec![1, 2, 3];
@@ -137,15 +144,15 @@ use super::range::RangeArgument;
137
144
///
138
145
/// # Indexing
139
146
///
140
- /// The Vec type allows to access values by index, because it implements the
141
- /// `Index` trait. An example will be more explicit:
147
+ /// The ` Vec` type allows to access values by index, because it implements the
148
+ /// [ `Index`] trait. An example will be more explicit:
142
149
///
143
150
/// ```
144
151
/// let v = vec!(0, 2, 4, 6);
145
152
/// println!("{}", v[1]); // it will display '2'
146
153
/// ```
147
154
///
148
- /// However be careful: if you try to access an index which isn't in the Vec,
155
+ /// However be careful: if you try to access an index which isn't in the ` Vec` ,
149
156
/// your software will panic! You cannot do this:
150
157
///
151
158
/// ```ignore
@@ -158,7 +165,7 @@ use super::range::RangeArgument;
158
165
///
159
166
/// # Slicing
160
167
///
161
- /// A Vec can be mutable. Slices, on the other hand, are read-only objects.
168
+ /// A ` Vec` can be mutable. Slices, on the other hand, are read-only objects.
162
169
/// To get a slice, use "&". Example:
163
170
///
164
171
/// ```
@@ -175,8 +182,8 @@ use super::range::RangeArgument;
175
182
/// ```
176
183
///
177
184
/// In Rust, it's more common to pass slices as arguments rather than vectors
178
- /// when you just want to provide a read access. The same goes for String and
179
- /// &str.
185
+ /// when you just want to provide a read access. The same goes for [` String`] and
186
+ /// [` &str`] .
180
187
///
181
188
/// # Capacity and reallocation
182
189
///
@@ -191,7 +198,7 @@ use super::range::RangeArgument;
191
198
/// with space for 10 more elements. Pushing 10 or fewer elements onto the
192
199
/// vector will not change its capacity or cause reallocation to occur. However,
193
200
/// if the vector's length is increased to 11, it will have to reallocate, which
194
- /// can be slow. For this reason, it is recommended to use `Vec::with_capacity`
201
+ /// can be slow. For this reason, it is recommended to use [ `Vec::with_capacity`]
195
202
/// whenever possible to specify how big the vector is expected to get.
196
203
///
197
204
/// # Guarantees
@@ -209,65 +216,83 @@ use super::range::RangeArgument;
209
216
/// The pointer will never be null, so this type is null-pointer-optimized.
210
217
///
211
218
/// However, the pointer may not actually point to allocated memory. In particular,
212
- /// if you construct a Vec with capacity 0 via `Vec::new()`, `vec![]`,
213
- /// `Vec::with_capacity(0)`, or by calling `shrink_to_fit()` on an empty Vec, it
214
- /// will not allocate memory. Similarly, if you store zero-sized types inside
215
- /// a Vec, it will not allocate space for them. *Note that in this case the
216
- /// Vec may not report a `capacity()` of 0*. Vec will allocate if and only
217
- /// if `mem::size_of::<T>() * capacity() > 0`. In general, Vec's allocation
219
+ /// if you construct a Vec with capacity 0 via [ `Vec::new()`], [ `vec![]`][`vec!`] ,
220
+ /// [ `Vec::with_capacity(0)`][`Vec::with_capacity`] , or by calling [ `shrink_to_fit()`]
221
+ /// on an empty Vec, it will not allocate memory. Similarly, if you store zero-sized
222
+ /// types inside a ` Vec` , it will not allocate space for them. *Note that in this case
223
+ /// the ` Vec` may not report a [ `capacity()`] of 0*. Vec will allocate if and only
224
+ /// if [ `mem::size_of::<T>()`]` * capacity() > 0`. In general, ` Vec` 's allocation
218
225
/// details are subtle enough that it is strongly recommended that you only
219
226
/// free memory allocated by a Vec by creating a new Vec and dropping it.
220
227
///
221
- /// If a Vec *has* allocated memory, then the memory it points to is on the heap
228
+ /// If a ` Vec` *has* allocated memory, then the memory it points to is on the heap
222
229
/// (as defined by the allocator Rust is configured to use by default), and its
223
- /// pointer points to `len()` initialized elements in order (what you would see
224
- /// if you coerced it to a slice), followed by `capacity() - len ()` logically
225
- /// uninitialized elements.
230
+ /// pointer points to [ `len()`] initialized elements in order (what you would see
231
+ /// if you coerced it to a slice), followed by `[ capacity()][`capacity ()`] -
232
+ /// [len()][`len()`]` logically uninitialized elements.
226
233
///
227
- /// Vec will never perform a "small optimization" where elements are actually
234
+ /// ` Vec` will never perform a "small optimization" where elements are actually
228
235
/// stored on the stack for two reasons:
229
236
///
230
237
/// * It would make it more difficult for unsafe code to correctly manipulate
231
- /// a Vec. The contents of a Vec wouldn't have a stable address if it were
232
- /// only moved, and it would be more difficult to determine if a Vec had
238
+ /// a ` Vec` . The contents of a ` Vec` wouldn't have a stable address if it were
239
+ /// only moved, and it would be more difficult to determine if a ` Vec` had
233
240
/// actually allocated memory.
234
241
///
235
242
/// * It would penalize the general case, incurring an additional branch
236
243
/// on every access.
237
244
///
238
- /// Vec will never automatically shrink itself, even if completely empty. This
239
- /// ensures no unnecessary allocations or deallocations occur. Emptying a Vec
240
- /// and then filling it back up to the same `len()` should incur no calls to
241
- /// the allocator. If you wish to free up unused memory, use `shrink_to_fit`.
245
+ /// `Vec` will never automatically shrink itself, even if completely empty. This
246
+ /// ensures no unnecessary allocations or deallocations occur. Emptying a `Vec`
247
+ /// and then filling it back up to the same [`len()`] should incur no calls to
248
+ /// the allocator. If you wish to free up unused memory, use
249
+ /// [`shrink_to_fit`][`shrink_to_fit()`].
242
250
///
243
- /// `push` and `insert` will never (re)allocate if the reported capacity is
244
- /// sufficient. `push` and `insert` *will* (re)allocate if `len() == capacity()`.
245
- /// That is, the reported capacity is completely accurate, and can be relied on.
246
- /// It can even be used to manually free the memory allocated by a Vec if
247
- /// desired. Bulk insertion methods *may* reallocate, even when not necessary.
251
+ /// [`push`] and [`insert`] will never (re)allocate if the reported capacity is
252
+ /// sufficient. [`push`] and [`insert`] *will* (re)allocate if `[len()][`len()`]
253
+ /// == [capacity()][`capacity()`]`. That is, the reported capacity is completely
254
+ /// accurate, and can be relied on. It can even be used to manually free the memory
255
+ /// allocated by a `Vec` if desired. Bulk insertion methods *may* reallocate, even
256
+ /// when not necessary.
248
257
///
249
- /// Vec does not guarantee any particular growth strategy when reallocating
250
- /// when full, nor when `reserve` is called. The current strategy is basic
258
+ /// ` Vec` does not guarantee any particular growth strategy when reallocating
259
+ /// when full, nor when [ `reserve`] is called. The current strategy is basic
251
260
/// and it may prove desirable to use a non-constant growth factor. Whatever
252
- /// strategy is used will of course guarantee `O(1)` amortized `push`.
261
+ /// strategy is used will of course guarantee `O(1)` amortized [ `push`] .
253
262
///
254
- /// `vec![x; n]`, `vec![a, b, c, d]`, and `Vec::with_capacity(n)`, will all
255
- /// produce a Vec with exactly the requested capacity. If `len() == capacity()`,
256
- /// (as is the case for the `vec!` macro), then a `Vec<T>` can be converted
257
- /// to and from a `Box<[T]>` without reallocating or moving the elements.
263
+ /// `vec![x; n]`, `vec![a, b, c, d]`, and
264
+ /// [`Vec::with_capacity(n)`][`Vec::with_capacity`], will all
265
+ /// produce a `Vec` with exactly the requested capacity. If `[len()][`len()`] ==
266
+ /// [capacity()][`capacity()`]`, (as is the case for the [`vec!`] macro), then a
267
+ /// `Vec<T>` can be converted to and from a [`Box<[T]>`] without reallocating or
268
+ /// moving the elements.
258
269
///
259
- /// Vec will not specifically overwrite any data that is removed from it,
270
+ /// ` Vec` will not specifically overwrite any data that is removed from it,
260
271
/// but also won't specifically preserve it. Its uninitialized memory is
261
272
/// scratch space that it may use however it wants. It will generally just do
262
273
/// whatever is most efficient or otherwise easy to implement. Do not rely on
263
- /// removed data to be erased for security purposes. Even if you drop a Vec, its
264
- /// buffer may simply be reused by another Vec. Even if you zero a Vec's memory
274
+ /// removed data to be erased for security purposes. Even if you drop a ` Vec` , its
275
+ /// buffer may simply be reused by another ` Vec` . Even if you zero a ` Vec` 's memory
265
276
/// first, that may not actually happen because the optimizer does not consider
266
277
/// this a side-effect that must be preserved.
267
278
///
268
- /// Vec does not currently guarantee the order in which elements are dropped
279
+ /// ` Vec` does not currently guarantee the order in which elements are dropped
269
280
/// (the order has changed in the past, and may change again).
270
281
///
282
+ /// [`vec!`]: ../../std/macro.vec.html
283
+ /// [`Index`]: ../../std/ops/trait.Index.html
284
+ /// [`String`]: ../../std/string/struct.String.html
285
+ /// [`&str`]: ../../std/primitive.str.html
286
+ /// [`Vec::with_capacity`]: ../../std/vec/struct.Vec.html#method.with_capacity
287
+ /// [`Vec::new()`]: ../../std/vec/struct.Vec.html#method.new
288
+ /// [`shrink_to_fit()`]: ../../std/vec/struct.Vec.html#method.shrink_to_fit
289
+ /// [`capacity()`]: ../../std/vec/struct.Vec.html#method.capacity
290
+ /// [`mem::size_of::<T>()`]: ../../std/mem/fn.size_of.html
291
+ /// [`len()`]: ../../std/vec/struct.Vec.html#method.len
292
+ /// [`push`]: ../../std/vec/struct.Vec.html#method.push
293
+ /// [`insert`]: ../../std/vec/struct.Vec.html#method.insert
294
+ /// [`reserve`]: ../../std/vec/struct.Vec.html#method.reserve
295
+ /// [`Box<[T]>`]: ../../std/boxed/struct.Box.html
271
296
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
272
297
pub struct Vec < T > {
273
298
buf : RawVec < T > ,
@@ -340,7 +365,7 @@ impl<T> Vec<T> {
340
365
/// This is highly unsafe, due to the number of invariants that aren't
341
366
/// checked:
342
367
///
343
- /// * `ptr` needs to have been previously allocated via `String`/`Vec<T>`
368
+ /// * `ptr` needs to have been previously allocated via [ `String`] /`Vec<T>`
344
369
/// (at least, it's highly likely to be incorrect if it wasn't).
345
370
/// * `length` needs to be less than or equal to `capacity`.
346
371
/// * `capacity` needs to be the capacity that the pointer was allocated with.
@@ -354,6 +379,8 @@ impl<T> Vec<T> {
354
379
/// that nothing else uses the pointer after calling this
355
380
/// function.
356
381
///
382
+ /// [`String`]: ../../std/string/struct.String.html
383
+ ///
357
384
/// # Examples
358
385
///
359
386
/// ```
@@ -470,11 +497,15 @@ impl<T> Vec<T> {
470
497
self . buf . shrink_to_fit ( self . len ) ;
471
498
}
472
499
473
- /// Converts the vector into Box<[T]>.
500
+ /// Converts the vector into [` Box<[T]>`] .
474
501
///
475
502
/// Note that this will drop any excess capacity. Calling this and
476
- /// converting back to a vector with `into_vec()` is equivalent to calling
477
- /// `shrink_to_fit()`.
503
+ /// converting back to a vector with [`into_vec()`] is equivalent to calling
504
+ /// [`shrink_to_fit()`].
505
+ ///
506
+ /// [`Box<[T]>`]: ../../std/boxed/struct.Box.html
507
+ /// [`into_vec()`]: ../../std/primitive.slice.html#method.into_vec
508
+ /// [`shrink_to_fit()`]: #method.shrink_to_fit
478
509
///
479
510
/// # Examples
480
511
///
@@ -673,7 +704,7 @@ impl<T> Vec<T> {
673
704
///
674
705
/// # Panics
675
706
///
676
- /// Panics if `index` is greater than the vector's length .
707
+ /// Panics if `index` is out of bounds .
677
708
///
678
709
/// # Examples
679
710
///
@@ -933,9 +964,11 @@ impl<T> Vec<T> {
933
964
}
934
965
}
935
966
936
- /// Removes the last element from a vector and returns it, or `None` if it
967
+ /// Removes the last element from a vector and returns it, or [ `None`] if it
937
968
/// is empty.
938
969
///
970
+ /// [`None`]: ../../std/option/enum.Option.html#variant.None
971
+ ///
939
972
/// # Examples
940
973
///
941
974
/// ```
0 commit comments