src/doc/book/vectors.md

   1 % Vectors
   2
   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>
  11 ```
  12
  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,
  15 this is just convention.)
  16
  17 There’s an alternate form of `vec!` for repeating an initial value:
  18
  19 ```rust
  20 let v = vec![0; 10]; // ten zeroes
  21 ```
  22
  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
  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
  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
  91 ## Iterating
  92
  93 Once you have a vector, you can iterate through its elements with `for`. There
  94 are three versions:
  95
  96 ```rust
  97 let mut v = vec![1, 2, 3, 4, 5];
  98
  99 for i in &v {
 100     println!("A reference to {}", i);
 101 }
 102
 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 }
 110 ```
 111
 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
 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