diff --git a/doc/tutorial.md b/doc/tutorial.md index 42b0d5a585aee..5a47cefb33d2c 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -1067,6 +1067,28 @@ let mut d = @mut 5; // mutable variable, mutable box d = @mut 15; ~~~~ +A mutable variable and an immutable variable can refer to the same box, given +that their types are compatible. Mutability of a box is a property of its type, +however, so for example a mutable handle to an immutable box cannot be +assigned a reference to a mutable box. + +~~~~ +let a = @1; // immutable box +let b = @mut 2; // mutable box + +let mut c : @int; // declare a variable with type managed immutable int +let mut d : @mut int; // and one of type managed mutable int + +c = a; // box type is the same, okay +d = b; // box type is the same, okay +~~~~ + +~~~~ {.xfail-test} +// but b cannot be assigned to c, or a to d +c = b; // error +~~~~ + + # Move semantics Rust uses a shallow copy for parameter passing, assignment and returning values @@ -1081,6 +1103,16 @@ let y = x.clone(); // y is a newly allocated box let z = x; // no new memory allocated, x can no longer be used ~~~~ +Since in owned boxes mutability is a property of the owner, not the +box, mutable boxes may become immutable when they are moved, and vice-versa. + +~~~~ +let r = ~13; +let mut s = r; // box becomes mutable +*s += 1; +let t = s; // box becomes immutable +~~~~ + # Borrowed pointers Rust's borrowed pointers are a general purpose reference type. In contrast with @@ -1191,7 +1223,7 @@ they are frozen: let x = @mut 5; let y = x; { - let y = &*y; // the managed box is now frozen + let z = &*y; // the managed box is now frozen // modifying it through x or y will cause a task failure } // the box is now unfrozen again