Skip to content

Book: replace deprecated int and i type annotations with explicit i32 #21279

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.

Sign up for GitHub

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

Closed
wants to merge 2 commits into from
Closed

Book: replace deprecated int and i type annotations with explicit i32 #21279

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7bd4ba7
replace deprecated `i` type suffix with `i32`
hinsley Jan 17, 2015
a13fc2a
replace deprecated `int` type with `i32`
hinsley Jan 17, 2015
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
96 changes: 48 additions & 48 deletions src/doc/trpl/pointers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ question](http://stackoverflow.com/questions/79923/what-and-where-are-the-stack-
as the rest of this guide assumes you know the difference.) Like this:

```{rust}
let x = 5i;
let y = 8i;
let x = 5i32;
let y = 8i32;
```
| location | value |
|----------|-------|
Expand All @@ -46,8 +46,8 @@ Let's introduce a pointer. In some languages, there is just one type of
*reference*, which is the simplest kind of pointer.

```{rust}
let x = 5i;
let y = 8i;
let x = 5i32;
let y = 8i32;
let z = &y;
```
|location | value |
Expand All @@ -58,25 +58,25 @@ let z = &y;

See the difference? Rather than contain a value, the value of a pointer is a
location in memory. In this case, the location of `y`. `x` and `y` have the
type `int`, but `z` has the type `&int`. We can print this location using the
type `i32`, but `z` has the type `&i32`. We can print this location using the
`{:p}` format string:

```{rust}
let x = 5i;
let y = 8i;
let x = 5i32;
let y = 8i32;
let z = &y;

println!("{:p}", z);
```

This would print `0xd3e028`, with our fictional memory addresses.

Because `int` and `&int` are different types, we can't, for example, add them
Because `i32` and `&i32` are different types, we can't, for example, add them
together:

```{rust,ignore}
let x = 5i;
let y = 8i;
let x = 5i32;
let y = 8i32;
let z = &y;

println!("{}", x + z);
Expand All @@ -95,8 +95,8 @@ pointer means accessing the value at the location stored in the pointer. This
will work:

```{rust}
let x = 5i;
let y = 8i;
let x = 5i32;
let y = 8i32;
let z = &y;

println!("{}", x + *z);
Expand Down Expand Up @@ -252,7 +252,7 @@ The most basic type of pointer that Rust has is called a *reference*. Rust
references look like this:

```{rust}
let x = 5i;
let x = 5i32;
let y = &x;

println!("{}", *y);
Expand All @@ -269,18 +269,18 @@ referent, because `println!` will automatically dereference it for us.
Here's a function that takes a reference:

```{rust}
fn succ(x: &int) -> int { *x + 1 }
fn succ(x: &i32) -> i32 { *x + 1 }
```

You can also use `&` as an operator to create a reference, so we can
call this function in two different ways:

```{rust}
fn succ(x: &int) -> int { *x + 1 }
fn succ(x: &i32) -> i32 { *x + 1 }

fn main() {

let x = 5i;
let x = 5i32;
let y = &x;

println!("{}", succ(y));
Expand All @@ -294,13 +294,13 @@ Of course, if this were real code, we wouldn't bother with the reference, and
just write:

```{rust}
fn succ(x: int) -> int { x + 1 }
fn succ(x: i32) -> i32 { x + 1 }
```

References are immutable by default:

```{rust,ignore}
let x = 5i;
let x = 5i32;
let y = &x;

*y = 5; // error: cannot assign to immutable dereference of `&`-pointer `*y`
Expand All @@ -310,29 +310,29 @@ They can be made mutable with `mut`, but only if its referent is also mutable.
This works:

```{rust}
let mut x = 5i;
let mut x = 5i32;
let y = &mut x;
```

This does not:

```{rust,ignore}
let x = 5i;
let x = 5i32;
let y = &mut x; // error: cannot borrow immutable local variable `x` as mutable
```

Immutable pointers are allowed to alias:

```{rust}
let x = 5i;
let x = 5i32;
let y = &x;
let z = &x;
```

Mutable ones, however, are not:

```{rust,ignore}
let mut x = 5i;
let mut x = 5i32;
let y = &mut x;
let z = &mut x; // error: cannot borrow `x` as mutable more than once at a time
```
Expand All @@ -359,7 +359,7 @@ duration a *lifetime*. Let's try a more complex example:

```{rust}
fn main() {
let x = &mut 5i;
let x = &mut 5i32;

if *x < 10 {
let y = &x;
Expand All @@ -380,7 +380,7 @@ mutated, and therefore, lets us pass. This wouldn't work:

```{rust,ignore}
fn main() {
let x = &mut 5i;
let x = &mut 5i32;

if *x < 10 {
let y = &x;
Expand Down Expand Up @@ -425,31 +425,31 @@ References just borrow ownership, which is more polite if you don't need the
ownership. In other words, prefer:

```{rust}
fn succ(x: &int) -> int { *x + 1 }
fn succ(x: &i32) -> i32 { *x + 1 }
```

to

```{rust}
fn succ(x: Box<int>) -> int { *x + 1 }
fn succ(x: Box<i32>) -> i32 { *x + 1 }
```

As a corollary to that rule, references allow you to accept a wide variety of
other pointers, and so are useful so that you don't have to write a number
of variants per pointer. In other words, prefer:

```{rust}
fn succ(x: &int) -> int { *x + 1 }
fn succ(x: &i32) -> i32 { *x + 1 }
```

to

```{rust}
use std::rc::Rc;

fn box_succ(x: Box<int>) -> int { *x + 1 }
fn box_succ(x: Box<i32>) -> i32 { *x + 1 }

fn rc_succ(x: Rc<int>) -> int { *x + 1 }
fn rc_succ(x: Rc<i32>) -> i32 { *x + 1 }
```

Note that the caller of your function will have to modify their calls slightly:
Expand All @@ -459,9 +459,9 @@ use std::rc::Rc;

fn succ(x: &int) -> int { *x + 1 }

let ref_x = &5i;
let box_x = Box::new(5i);
let rc_x = Rc::new(5i);
let ref_x = &5i32;
let box_x = Box::new(5i32);
let rc_x = Rc::new(5i32);

succ(ref_x);
succ(&*box_x);
Expand All @@ -477,15 +477,15 @@ those contents.
heap allocation in Rust. Creating a box looks like this:

```{rust}
let x = Box::new(5i);
let x = Box::new(5i32);
```

Boxes are heap allocated and they are deallocated automatically by Rust when
they go out of scope:

```{rust}
{
let x = Box::new(5i);
let x = Box::new(5i32);

// stuff happens

Expand All @@ -505,7 +505,7 @@ boxes, though. As a rough approximation, you can treat this Rust code:

```{rust}
{
let x = Box::new(5i);
let x = Box::new(5i32);

// stuff happens
}
Expand Down Expand Up @@ -544,12 +544,12 @@ for more detail on how lifetimes work.
Using boxes and references together is very common. For example:

```{rust}
fn add_one(x: &int) -> int {
fn add_one(x: &i32) -> i32 {
*x + 1
}

fn main() {
let x = Box::new(5i);
let x = Box::new(5i32);

println!("{}", add_one(&*x));
}
Expand All @@ -561,12 +561,12 @@ function, and since it's only reading the value, allows it.
We can borrow `x` multiple times, as long as it's not simultaneous:

```{rust}
fn add_one(x: &int) -> int {
fn add_one(x: &i32) -> i32 {
*x + 1
}

fn main() {
let x = Box::new(5i);
let x = Box::new(5i32);

println!("{}", add_one(&*x));
println!("{}", add_one(&*x));
Expand All @@ -577,12 +577,12 @@ fn main() {
Or as long as it's not a mutable borrow. This will error:

```{rust,ignore}
fn add_one(x: &mut int) -> int {
fn add_one(x: &mut i32) -> i32 {
*x + 1
}

fn main() {
let x = Box::new(5i);
let x = Box::new(5i32);

println!("{}", add_one(&*x)); // error: cannot borrow immutable dereference
// of `&`-pointer as mutable
Expand Down Expand Up @@ -610,7 +610,7 @@ enum List<T> {
}

fn main() {
let list: List<int> = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Cons(3, Box::new(List::Nil))))));
let list: List<i32> = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Cons(3, Box::new(List::Nil))))));
println!("{:?}", list);
}
```
Expand Down Expand Up @@ -659,10 +659,10 @@ so as to avoid copying a large data structure. For example:

```{rust}
struct BigStruct {
one: int,
two: int,
one: i32,
two: i32,
// etc
one_hundred: int,
one_hundred: i32,
}

fn foo(x: Box<BigStruct>) -> Box<BigStruct> {
Expand All @@ -687,10 +687,10 @@ This is an antipattern in Rust. Instead, write this:

```{rust}
struct BigStruct {
one: int,
two: int,
one: i32,
two: i32,
// etc
one_hundred: int,
one_hundred: i32,
}

fn foo(x: Box<BigStruct>) -> BigStruct {
Expand Down