Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add comments with type annotations. #19743

Merged
merged 1 commit into from
Dec 17, 2014
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 46 additions & 26 deletions src/doc/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,19 @@ let x: int = 5;
If I asked you to read this out loud to the rest of the class, you'd say "`x`
is a binding with the type `int` and the value `five`."

In future examples, we may annotate the type in a comment. The examples will
look like this:

```{rust}
fn main() {
let x = 5i; // x: int
}
```

Note the similarities between this annotation and the syntax you use with `let`.
Including these kinds of comments is not idiomatic Rust, but we'll occasionally
include them to help you understand what the types that Rust infers are.

By default, bindings are **immutable**. This code will not compile:

```{ignore}
Expand All @@ -435,7 +448,7 @@ error: re-assignment of immutable variable `x`
If you want a binding to be mutable, you can use `mut`:

```{rust}
let mut x = 5i;
let mut x = 5i; // mut x: int
x = 10i;
```

Expand Down Expand Up @@ -583,15 +596,15 @@ let y = if x == 5i {
10i
} else {
15i
};
}; // y: int
```

Which we can (and probably should) write like this:

```{rust}
let x = 5i;

let y = if x == 5i { 10i } else { 15i };
let y = if x == 5i { 10i } else { 15i }; // y: int
```

This reveals two interesting things about Rust: it is an expression-based
Expand Down Expand Up @@ -927,8 +940,8 @@ destructuring. You can assign one tuple into another, if they have the same
arity and contained types.

```rust
let mut x = (1i, 2i);
let y = (2i, 3i);
let mut x = (1i, 2i); // x: (int, int)
let y = (2i, 3i); // y: (int, int)

x = y;
```
Expand Down Expand Up @@ -980,7 +993,7 @@ struct Point {
}

fn main() {
let origin = Point { x: 0i, y: 0i };
let origin = Point { x: 0i, y: 0i }; // origin: Point

println!("The origin is at ({}, {})", origin.x, origin.y);
}
Expand Down Expand Up @@ -1100,7 +1113,7 @@ fn main() {
let x = 5i;
let y = 10i;

let ordering = cmp(x, y);
let ordering = cmp(x, y); // ordering: Ordering

if ordering == Less {
println!("less");
Expand Down Expand Up @@ -1387,7 +1400,7 @@ Instead, it looks like this:

```{rust}
for x in range(0i, 10i) {
println!("{}", x);
println!("{}", x); // x: int
}
```

Expand Down Expand Up @@ -1422,8 +1435,8 @@ The other kind of looping construct in Rust is the `while` loop. It looks like
this:

```{rust}
let mut x = 5u;
let mut done = false;
let mut x = 5u; // mut x: uint
let mut done = false; // mut done: bool

while !done {
x += x - 3;
Expand Down Expand Up @@ -1519,7 +1532,7 @@ The first kind is a `&str`. This is pronounced a 'string slice.' String literals
are of the type `&str`:

```{rust}
let string = "Hello there.";
let string = "Hello there."; // string: &str
```

This string is statically allocated, meaning that it's saved inside our
Expand All @@ -1531,7 +1544,7 @@ A `String`, on the other hand, is an in-memory string. This string is
growable, and is also guaranteed to be UTF-8.

```{rust}
let mut s = "Hello".to_string();
let mut s = "Hello".to_string(); // mut s: String
println!("{}", s);

s.push_str(", world.");
Expand Down Expand Up @@ -1587,16 +1600,19 @@ things. The most basic is the **array**, a fixed-size list of elements of the
same type. By default, arrays are immutable.

```{rust}
let a = [1i, 2i, 3i];
let mut m = [1i, 2i, 3i];
let a = [1i, 2i, 3i]; // a: [int, ..3]
let mut m = [1i, 2i, 3i]; // mut m: [int, ..3]
```

You can create an array with a given number of elements, all initialized to the
same value, with `[val, ..N]` syntax. The compiler ensures that arrays are
always initialized.

There's a shorthand for initializing each element of an array to the same
value. In this example, each element of `a` will be initialized to `0i`:

```{rust}
let a = [0i, ..20]; // Shorthand for array of 20 elements all initialized to 0
let a = [0i, ..20]; // a: [int, ..20]
```

Arrays have type `[T,..N]`. We'll talk about this `T` notation later, when we
Expand All @@ -1607,7 +1623,7 @@ You can get the number of elements in an array `a` with `a.len()`, and use
number in order:

```{rust}
let a = [1i, 2, 3]; // Only the first item needs a type suffix
let a = [1i, 2, 3]; // Only the first item needs a type suffix

println!("a has {} elements", a.len());
for e in a.iter() {
Expand All @@ -1618,7 +1634,7 @@ for e in a.iter() {
You can access a particular element of an array with **subscript notation**:

```{rust}
let names = ["Graydon", "Brian", "Niko"];
let names = ["Graydon", "Brian", "Niko"]; // names: [&str, 3]

println!("The second name is: {}", names[1]);
```
Expand All @@ -1636,7 +1652,7 @@ later). Vectors are to arrays what `String` is to `&str`. You can create them
with the `vec!` macro:

```{rust}
let v = vec![1i, 2, 3];
let v = vec![1i, 2, 3]; // v: Vec<int>
```

(Notice that unlike the `println!` macro we've used in the past, we use square
Expand All @@ -1647,8 +1663,10 @@ You can get the length of, iterate over, and subscript vectors just like
arrays. In addition, (mutable) vectors can grow automatically:

```{rust}
let mut nums = vec![1i, 2, 3];
let mut nums = vec![1i, 2, 3]; // mut nums: Vec<int>

nums.push(4);

println!("The length of nums is now {}", nums.len()); // Prints 4
```

Expand Down Expand Up @@ -1822,10 +1840,12 @@ use std::io;
fn main() {
println!("Type something!");

let input = io::stdin()
.read_line()
.ok()
.expect("Failed to read line");
// here, we'll show the types at each step

let input = io::stdin() // std::io::stdio::StdinReader
.read_line() // IoResult<String>
.ok() // Option<String>
.expect("Failed to read line"); // String

println!("{}", input);
}
Expand Down Expand Up @@ -1968,7 +1988,7 @@ use std::rand;
fn main() {
println!("Guess the number!");

let secret_number = (rand::random() % 100i) + 1i;
let secret_number = (rand::random() % 100i) + 1i; // secret_number: int

println!("The secret number is: {}", secret_number);

Expand Down Expand Up @@ -2261,8 +2281,8 @@ In this case, we say `x` is a `uint` explicitly, so Rust is able to properly
tell `random()` what to generate. In a similar fashion, both of these work:

```{rust,ignore}
let input_num = from_str::<uint>("5");
let input_num: Option<uint> = from_str("5");
let input_num = from_str::<uint>("5"); // input_num: Option<uint>
let input_num: Option<uint> = from_str("5"); // input_num: Option<uint>
```

Anyway, with us now converting our input to a number, our code looks like this:
Expand Down