src/doc/trpl/arrays-vectors-and-slices.md

   1 % Arrays, Vectors, and Slices
   2
   3 Like many programming languages, Rust has list types to represent a sequence of
   4 things. The most basic is the *array*, a fixed-size list of elements of the
   5 same type. By default, arrays are immutable.
   6
   7 ```{rust}
   8 let a = [1, 2, 3]; // a: [i32; 3]
   9 let mut m = [1, 2, 3]; // mut m: [i32; 3]
  10 ```
  11
  12 There's a shorthand for initializing each element of an array to the same
  13 value. In this example, each element of `a` will be initialized to `0`:
  14
  15 ```{rust}
  16 let a = [0; 20]; // a: [i32; 20]
  17 ```
  18
  19 Arrays have type `[T; N]`. We'll talk about this `T` notation later, when we
  20 cover generics.
  21
  22 You can get the number of elements in an array `a` with `a.len()`, and use
  23 `a.iter()` to iterate over them with a for loop. This code will print each
  24 number in order:
  25
  26 ```{rust}
  27 let a = [1, 2, 3];
  28
  29 println!("a has {} elements", a.len());
  30 for e in a.iter() {
  31     println!("{}", e);
  32 }
  33 ```
  34
  35 You can access a particular element of an array with *subscript notation*:
  36
  37 ```{rust}
  38 let names = ["Graydon", "Brian", "Niko"]; // names: [&str; 3]
  39
  40 println!("The second name is: {}", names[1]);
  41 ```
  42
  43 Subscripts start at zero, like in most programming languages, so the first name
  44 is `names[0]` and the second name is `names[1]`. The above example prints
  45 `The second name is: Brian`. If you try to use a subscript that is not in the
  46 array, you will get an error: array access is bounds-checked at run-time. Such
  47 errant access is the source of many bugs in other systems programming
  48 languages.
  49
  50 A *vector* is a dynamic or "growable" array, implemented as the standard
  51 library type [`Vec<T>`](../std/vec/) (we'll talk about what the `<T>` means
  52 later). Vectors are to arrays what `String` is to `&str`. You can create them
  53 with the `vec!` macro:
  54
  55 ```{rust}
  56 let v = vec![1, 2, 3]; // v: Vec<i32>
  57 ```
  58
  59 (Notice that unlike the `println!` macro we've used in the past, we use square
  60 brackets `[]` with `vec!`. Rust allows you to use either in either situation,
  61 this is just convention.)
  62
  63 You can get the length of, iterate over, and subscript vectors just like
  64 arrays. In addition, (mutable) vectors can grow automatically:
  65
  66 ```{rust}
  67 let mut nums = vec![1, 2, 3]; // mut nums: Vec<i32>
  68
  69 nums.push(4);
  70
  71 println!("The length of nums is now {}", nums.len()); // Prints 4
  72 ```
  73
  74 Vectors have many more useful methods.
  75
  76 A *slice* is a reference to (or "view" into) an array. They are useful for
  77 allowing safe, efficient access to a portion of an array without copying. For
  78 example, you might want to reference just one line of a file read into memory.
  79 By nature, a slice is not created directly, but from an existing variable.
  80 Slices have a length, can be mutable or not, and in many ways behave like
  81 arrays:
  82
  83 ```{rust}
  84 let a = [0, 1, 2, 3, 4];
  85 let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3
  86
  87 for e in middle.iter() {
  88     println!("{}", e); // Prints 1, 2, 3
  89 }
  90 ```
  91
  92 You can also take a slice of a vector, `String`, or `&str`, because they are
  93 backed by arrays. Slices have type `&[T]`, which we'll talk about when we cover
  94 generics.
  95
  96 We have now learned all of the most basic Rust concepts. We're ready to start
  97 building ourselves a guessing game, we just need to know one last thing: how to
  98 get input from the keyboard. You can't have a guessing game without the ability
  99 to guess!