src/doc/book/second-edition/src/ch08-01-vectors.md

   1 ## Storing Lists of Values with Vectors
   2
   3 The first collection type we’ll look at is `Vec<T>`, also known as a *vector*.
   4 Vectors allow you to store more than one value in a single data structure that
   5 puts all the values next to each other in memory. Vectors can only store values
   6 of the same type. They are useful when you have a list of items, such as the
   7 lines of text in a file or the prices of items in a shopping cart.
   8
   9 ### Creating a New Vector
  10
  11 To create a new, empty vector, we can call the `Vec::new` function, as shown in
  12 Listing 8-1.
  13
  14 ```rust
  15 let v: Vec<i32> = Vec::new();
  16 ```
  17
  18 <span class="caption">Listing 8-1: Creating a new, empty vector to hold values
  19 of type `i32`</span>
  20
  21 Note that we added a type annotation here. Because we aren’t inserting any
  22 values into this vector, Rust doesn’t know what kind of elements we intend to
  23 store. This is an important point. Vectors are implemented using generics;
  24 we’ll cover how to use generics with your own types in Chapter 10. For now,
  25 know that the `Vec<T>` type provided by the standard library can hold any type,
  26 and when a specific vector holds a specific type, the type is specified within
  27 angle brackets. In Listing 8-1, we’ve told Rust that the `Vec<T>` in `v` will
  28 hold elements of the `i32` type.
  29
  30 In more realistic code, Rust can often infer the type of value you want to
  31 store once you insert values, so you rarely need to do this type annotation.
  32 It’s more common to create a `Vec<T>` that has initial values, and Rust
  33 provides the `vec!` macro for convenience. The macro will create a new vector
  34 that holds the values you give it. Listing 8-2 creates a new `Vec<i32>` that
  35 holds the values `1`, `2`, and `3`.
  36
  37 ```rust
  38 let v = vec![1, 2, 3];
  39 ```
  40
  41 <span class="caption">Listing 8-2: Creating a new vector containing
  42 values</span>
  43
  44 Because we’ve given initial `i32` values, Rust can infer that the type of `v`
  45 is `Vec<i32>`, and the type annotation isn’t necessary. Next, we’ll look at how
  46 to modify a vector.
  47
  48 ### Updating a Vector
  49
  50 To create a vector and then add elements to it, we can use the `push` method,
  51 as shown in Listing 8-3.
  52
  53 ```rust
  54 let mut v = Vec::new();
  55
  56 v.push(5);
  57 v.push(6);
  58 v.push(7);
  59 v.push(8);
  60 ```
  61
  62 <span class="caption">Listing 8-3: Using the `push` method to add values to a
  63 vector</span>
  64
  65 As with any variable, if we want to be able to change its value, we need to
  66 make it mutable using the `mut` keyword, as discussed in Chapter 3. The numbers
  67 we place inside are all of type `i32`, and Rust infers this from the data, so
  68 we don’t need the `Vec<i32>` annotation.
  69
  70 ### Dropping a Vector Drops Its Elements
  71
  72 Like any other `struct`, a vector is freed when it goes out of scope, as
  73 annotated in Listing 8-4.
  74
  75 ```rust
  76 {
  77     let v = vec![1, 2, 3, 4];
  78
  79     // do stuff with v
  80
  81 } // <- v goes out of scope and is freed here
  82 ```
  83
  84 <span class="caption">Listing 8-4: Showing where the vector and its elements
  85 are dropped</span>
  86
  87 When the vector gets dropped, all of its contents are also dropped, meaning
  88 those integers it holds will be cleaned up. This may seem like a
  89 straightforward point but can get a bit more complicated when you start to
  90 introduce references to the elements of the vector. Let’s tackle that next!
  91
  92 ### Reading Elements of Vectors
  93
  94 Now that you know how to create, update, and destroy vectors, knowing how to
  95 read their contents is a good next step. There are two ways to reference a
  96 value stored in a vector. In the examples, we’ve annotated the types of the
  97 values that are returned from these functions for extra clarity.
  98
  99 Listing 8-5 shows both methods of accessing a value in a vector, either with
 100 indexing syntax or the `get` method.
 101
 102 ```rust
 103 let v = vec![1, 2, 3, 4, 5];
 104
 105 let third: &i32 = &v[2];
 106 let third: Option<&i32> = v.get(2);
 107 ```
 108
 109 <span class="caption">Listing 8-5: Using indexing syntax or the `get` method to
 110 access an item in a vector</span>
 111
 112 Note two details here. First, we use the index value of `2` to get the third
 113 element: vectors are indexed by number, starting at zero. Second, the two ways
 114 to get the third element are by using `&` and `[]`, which gives us a reference,
 115 or by using the `get` method with the index passed as an argument, which gives
 116 us an `Option<&T>`.
 117
 118 Rust has two ways to reference an element so you can choose how the program
 119 behaves when you try to use an index value that the vector doesn’t have an
 120 element for. As an example, let’s see what a program will do if it has a vector
 121 that holds five elements and then tries to access an element at index 100, as
 122 shown in Listing 8-6.
 123
 124 ```rust,should_panic
 125 let v = vec![1, 2, 3, 4, 5];
 126
 127 let does_not_exist = &v[100];
 128 let does_not_exist = v.get(100);
 129 ```
 130
 131 <span class="caption">Listing 8-6: Attempting to access the element at index
 132 100 in a vector containing five elements</span>
 133
 134 When we run this code, the first `[]` method will cause the program to panic
 135 because it references a nonexistent element. This method is best used when you
 136 want your program to crash if there’s an attempt to access an element past the
 137 end of the vector.
 138
 139 When the `get` method is passed an index that is outside the vector, it returns
 140 `None` without panicking. You would use this method if accessing an element
 141 beyond the range of the vector happens occasionally under normal circumstances.
 142 Your code will then have logic to handle having either `Some(&element)` or
 143 `None`, as discussed in Chapter 6. For example, the index could be coming from
 144 a person entering a number. If they accidentally enter a number that’s too
 145 large and the program gets a `None` value, you could tell the user how many
 146 items are in the current vector and give them another chance to enter a valid
 147 value. That would be more user-friendly than crashing the program due to a typo!
 148
 149 When the program has a valid reference, the borrow checker enforces the
 150 ownership and borrowing rules (covered in Chapter 4) to ensure this reference
 151 and any other references to the contents of the vector remain valid. Recall the
 152 rule that states you can’t have mutable and immutable references in the same
 153 scope. That rule applies in Listing 8-7, where we hold an immutable reference to
 154 the first element in a vector and try to add an element to the end, which won’t
 155 work.
 156
 157 ```rust,ignore
 158 let mut v = vec![1, 2, 3, 4, 5];
 159
 160 let first = &v[0];
 161
 162 v.push(6);
 163 ```
 164
 165 <span class="caption">Listing 8-7: Attempting to add an element to a vector
 166 while holding a reference to an item</span>
 167
 168 Compiling this code will result in this error:
 169
 170 ```text
 171 error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 172  -->
 173   |
 174 4 |     let first = &v[0];
 175   |                  - immutable borrow occurs here
 176 5 |
 177 6 |     v.push(6);
 178   |     ^ mutable borrow occurs here
 179 7 |
 180 8 | }
 181   | - immutable borrow ends here
 182 ```
 183
 184 The code in Listing 8-7 might look like it should work: why should a reference
 185 to the first element care about what changes at the end of the vector? This
 186 error is due to the way vectors work: adding a new element onto the end of the
 187 vector might require allocating new memory and copying the old elements to the
 188 new space, if there isn’t enough room to put all the elements next to each
 189 other where the vector currently is. In that case, the reference to the first
 190 element would be pointing to deallocated memory. The borrowing rules prevent
 191 programs from ending up in that situation.
 192
 193 > Note: For more on the implementation details of the `Vec<T>` type, see “The
 194 > Rustonomicon” at https://doc.rust-lang.org/stable/nomicon/vec.html.
 195
 196 ### Iterating over the Values in a Vector
 197
 198 If we want to access each element in a vector in turn, we can iterate through
 199 all of the elements rather than use indexes to access one at a time. Listing
 200 8-8 shows how to use a `for` loop to get immutable references to each element
 201 in a vector of `i32` values and print them.
 202
 203 ```rust
 204 let v = vec![100, 32, 57];
 205 for i in &v {
 206     println!("{}", i);
 207 }
 208 ```
 209
 210 <span class="caption">Listing 8-8: Printing each element in a vector by
 211 iterating over the elements using a `for` loop</span>
 212
 213 We can also iterate over mutable references to each element in a mutable vector
 214 in order to make changes to all the elements. The `for` loop in Listing 8-9
 215 will add `50` to each element.
 216
 217 ```rust
 218 let mut v = vec![100, 32, 57];
 219 for i in &mut v {
 220     *i += 50;
 221 }
 222 ```
 223
 224 <span class="caption">Listing 8-9: Iterating over mutable references to
 225 elements in a vector</span>
 226
 227 To change the value that the mutable reference refers to, we have to use the
 228 dereference operator (`*`) to get to the value in `i` before we can use the
 229 `+=` operator .
 230
 231 ### Using an Enum to Store Multiple Types
 232
 233 At the beginning of this chapter, we said that vectors can only store values
 234 that are the same type. This can be inconvenient; there are definitely use
 235 cases for needing to store a list of items of different types. Fortunately, the
 236 variants of an enum are defined under the same enum type, so when we need to
 237 store elements of a different type in a vector, we can define and use an enum!
 238
 239 For example, say we want to get values from a row in a spreadsheet in which
 240 some of the columns in the row contain integers, some floating-point numbers,
 241 and some strings. We can define an enum whose variants will hold the different
 242 value types, and then all the enum variants will be considered the same type:
 243 that of the enum. Then we can create a vector that holds that enum and so,
 244 ultimately, holds different types. We’ve demonstrated this in Listing 8-10.
 245
 246 ```rust
 247 enum SpreadsheetCell {
 248     Int(i32),
 249     Float(f64),
 250     Text(String),
 251 }
 252
 253 let row = vec![
 254     SpreadsheetCell::Int(3),
 255     SpreadsheetCell::Text(String::from("blue")),
 256     SpreadsheetCell::Float(10.12),
 257 ];
 258 ```
 259
 260 <span class="caption">Listing 8-10: Defining an `enum` to store values of
 261 different types in one vector</span>
 262
 263 Rust needs to know what types will be in the vector at compile time so it knows
 264 exactly how much memory on the heap will be needed to store each element. A
 265 secondary advantage is that we can be explicit about what types are allowed in
 266 this vector. If Rust allowed a vector to hold any type, there would be a chance
 267 that one or more of the types would cause errors with the operations performed
 268 on the elements of the vector. Using an enum plus a `match` expression means
 269 that Rust will ensure at compile time that every possible case is handled, as
 270 discussed in Chapter 6.
 271
 272 When you’re writing a program, if you don’t know the exhaustive set of types
 273 the program will get at runtime to store in a vector, the enum technique won’t
 274 work. Instead, you can use a trait object, which we’ll cover in Chapter 17.
 275
 276 Now that we’ve discussed some of the most common ways to use vectors, be sure
 277 to review the API documentation for all the many useful methods defined on
 278 `Vec<T>` by the standard library. For example, in addition to `push`, a `pop`
 279 method removes and returns the last element. Let’s move on to the next
 280 collection type: `String`!