3 A ‘vector’ is a dynamic or ‘growable’ array, implemented as the standard
4 library type [`Vec<T>`][vec]. The `T` means that we can have vectors
5 of any type (see the chapter on [generics][generic] for more).
6 Vectors always allocate their data on the heap.
7 You can create them with the `vec!` macro:
10 let v = vec![1, 2, 3, 4, 5]; // v: Vec<i32>
13 (Notice that unlike the `println!` macro we’ve used in the past, we use square
14 brackets `[]` with `vec!` macro. Rust allows you to use either in either
15 situation, this is just convention.)
17 There’s an alternate form of `vec!` for repeating an initial value:
20 let v = vec![0; 10]; // ten zeroes
23 Vectors store their contents as contiguous arrays of `T` on the heap. This means
24 that they must be able to know the size of `T` at compile time (that is, how
25 many bytes are needed to store a `T`?). The size of some things can't be known
26 at compile time. For these you'll have to store a pointer to that thing:
27 thankfully, the [`Box`][box] type works perfectly for this.
31 To get the value at a particular index in the vector, we use `[]`s:
34 let v = vec![1, 2, 3, 4, 5];
36 println!("The third element of v is {}", v[2]);
39 The indices count from `0`, so the third element is `v[2]`.
41 It’s also important to note that you must index with the `usize` type:
44 let v = vec![1, 2, 3, 4, 5];
56 Indexing with a non-`usize` type gives an error that looks like this:
59 error: the trait `core::ops::Index<i32>` is not implemented for the type
60 `collections::vec::Vec<_>` [E0277]
63 note: the type `collections::vec::Vec<_>` cannot be indexed by `i32`
64 error: aborting due to previous error
67 There’s a lot of punctuation in that message, but the core of it makes sense:
68 you cannot index with an `i32`.
70 ## Out-of-bounds Access
72 If you try to access an index that doesn’t exist:
75 let v = vec![1, 2, 3];
76 println!("Item 7 is {}", v[7]);
79 then the current thread will [panic] with a message like this:
82 thread '<main>' panicked at 'index out of bounds: the len is 3 but the index is 7'
85 If you want to handle out-of-bounds errors without panicking, you can use
86 methods like [`get`][get] or [`get_mut`][get_mut] that return `None` when
87 given an invalid index:
90 let v = vec![1, 2, 3];
92 Some(x) => println!("Item 7 is {}", x),
93 None => println!("Sorry, this vector is too short.")
99 Once you have a vector, you can iterate through its elements with `for`. There
103 let mut v = vec![1, 2, 3, 4, 5];
106 println!("A reference to {}", i);
110 println!("A mutable reference to {}", i);
114 println!("Take ownership of the vector and its element {}", i);
118 Note: You cannot use the vector again once you have iterated by taking ownership of the vector.
119 You can iterate the vector multiple times by taking a reference to the vector whilst iterating.
120 For example, the following code does not compile.
123 let mut v = vec![1, 2, 3, 4, 5];
126 println!("Take ownership of the vector and its element {}", i);
130 println!("Take ownership of the vector and its element {}", i);
134 Whereas the following works perfectly,
137 let mut v = vec![1, 2, 3, 4, 5];
140 println!("This is a reference to {}", i);
144 println!("This is a reference to {}", i);
148 Vectors have many more useful methods, which you can read about in [their
149 API documentation][vec].
151 [vec]: ../std/vec/index.html
152 [box]: ../std/boxed/index.html
153 [generic]: generics.html
154 [panic]: concurrency.html#panics
155 [get]: http://doc.rust-lang.org/std/vec/struct.Vec.html#method.get
156 [get_mut]: http://doc.rust-lang.org/std/vec/struct.Vec.html#method.get_mut