]>
Commit | Line | Data |
---|---|---|
9346a6ac AL |
1 | % Vectors |
2 | ||
bd371182 AL |
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: | |
8 | ||
9 | ```rust | |
10 | let v = vec![1, 2, 3, 4, 5]; // v: Vec<i32> | |
9346a6ac AL |
11 | ``` |
12 | ||
bd371182 AL |
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 situation, | |
9346a6ac AL |
15 | this is just convention.) |
16 | ||
bd371182 | 17 | There’s an alternate form of `vec!` for repeating an initial value: |
9346a6ac | 18 | |
62682a34 | 19 | ```rust |
9346a6ac AL |
20 | let v = vec![0; 10]; // ten zeroes |
21 | ``` | |
22 | ||
bd371182 AL |
23 | ## Accessing elements |
24 | ||
25 | To get the value at a particular index in the vector, we use `[]`s: | |
26 | ||
27 | ```rust | |
28 | let v = vec![1, 2, 3, 4, 5]; | |
29 | ||
30 | println!("The third element of v is {}", v[2]); | |
31 | ``` | |
32 | ||
33 | The indices count from `0`, so the third element is `v[2]`. | |
34 | ||
b039eaaf SL |
35 | It’s also important to note that you must index with the `usize` type: |
36 | ||
37 | ```ignore | |
38 | let v = vec![1, 2, 3, 4, 5]; | |
39 | ||
40 | let i: usize = 0; | |
41 | let j: i32 = 0; | |
42 | ||
43 | // works | |
44 | v[i]; | |
45 | ||
46 | // doesn’t | |
47 | v[j]; | |
48 | ``` | |
49 | ||
50 | Indexing with a non-`usize` type gives an error that looks like this: | |
51 | ||
52 | ```text | |
53 | error: the trait `core::ops::Index<i32>` is not implemented for the type | |
54 | `collections::vec::Vec<_>` [E0277] | |
55 | v[j]; | |
56 | ^~~~ | |
57 | note: the type `collections::vec::Vec<_>` cannot be indexed by `i32` | |
58 | error: aborting due to previous error | |
59 | ``` | |
60 | ||
61 | There’s a lot of punctuation in that message, but the core of it makes sense: | |
62 | you cannot index with an `i32`. | |
63 | ||
9cc50fc6 SL |
64 | ## Out-of-bounds Access |
65 | ||
66 | If you try to access an index that doesn’t exist: | |
67 | ||
68 | ```ignore | |
69 | let v = vec![1, 2, 3]; | |
70 | println!("Item 7 is {}", v[7]); | |
71 | ``` | |
72 | ||
73 | then the current thread will [panic] with a message like this: | |
74 | ||
75 | ```text | |
76 | thread '<main>' panicked at 'index out of bounds: the len is 3 but the index is 7' | |
77 | ``` | |
78 | ||
79 | If you want to handle out-of-bounds errors without panicking, you can use | |
80 | methods like [`get`][get] or [`get_mut`][get_mut] that return `None` when | |
81 | given an invalid index: | |
82 | ||
83 | ```rust | |
84 | let v = vec![1, 2, 3]; | |
85 | match v.get(7) { | |
86 | Some(x) => println!("Item 7 is {}", x), | |
87 | None => println!("Sorry, this vector is too short.") | |
88 | } | |
89 | ``` | |
90 | ||
bd371182 AL |
91 | ## Iterating |
92 | ||
93 | Once you have a vector, you can iterate through its elements with `for`. There | |
94 | are three versions: | |
9346a6ac | 95 | |
bd371182 AL |
96 | ```rust |
97 | let mut v = vec![1, 2, 3, 4, 5]; | |
9346a6ac | 98 | |
bd371182 AL |
99 | for i in &v { |
100 | println!("A reference to {}", i); | |
101 | } | |
9346a6ac | 102 | |
bd371182 AL |
103 | for i in &mut v { |
104 | println!("A mutable reference to {}", i); | |
105 | } | |
106 | ||
107 | for i in v { | |
108 | println!("Take ownership of the vector and its element {}", i); | |
109 | } | |
9346a6ac AL |
110 | ``` |
111 | ||
bd371182 AL |
112 | Vectors have many more useful methods, which you can read about in [their |
113 | API documentation][vec]. | |
114 | ||
115 | [vec]: ../std/vec/index.html | |
116 | [generic]: generics.html | |
9cc50fc6 SL |
117 | [panic]: concurrency.html#panics |
118 | [get]: http://doc.rust-lang.org/std/vec/struct.Vec.html#method.get | |
119 | [get_mut]: http://doc.rust-lang.org/std/vec/struct.Vec.html#method.get_mut |