auto merge of #5624 : thestinger/rust/tutorial, r=pcwalton

This commit is contained in:
bors 2013-03-29 13:30:46 -07:00
commit a17a9d41f6

View File

@ -1002,11 +1002,46 @@ refer to that through a pointer.
## Owned boxes
An owned box (`~`) is a uniquely owned allocation on the heap. An owned box
inherits the mutability and lifetime of the owner as it would if there was no
box. The purpose of an owned box is to add a layer of indirection in order to
create recursive data structures or cheaply pass around an object larger than a
pointer.
An owned box (`~`) is a uniquely owned allocation on the heap. It inherits the
mutability and lifetime of the owner as it would if there was no box.
~~~~
let x = 5; // immutable
let mut y = 5; // mutable
y += 2;
let x = ~5; // immutable
let mut y = ~5; // mutable
*y += 2; // the * operator is needed to access the contained value
~~~~
The purpose of an owned box is to add a layer of indirection in order to create
recursive data structures or cheaply pass around an object larger than a
pointer. Since an owned box has a unique owner, it can be used to represent any
tree data structure.
The following struct won't compile, because the lack of indirection would mean
it has an infinite size:
~~~~ {.xfail-test}
struct Foo {
child: Option<Foo>
}
~~~~
> ***Note:*** The `Option` type is an enum that represents an *optional* value.
> It's comparable to a nullable pointer in many other languages, but stores the
> contained value unboxed.
Adding indirection with an owned pointer allocates the child outside of the
struct on the heap, which makes it a finite size and won't result in a
compile-time error:
~~~~
struct Foo {
child: Option<~Foo>
}
~~~~
## Managed boxes
@ -1018,6 +1053,20 @@ mutability. They do own the contained object, and mutability is defined by the
type of the shared box (`@` or `@mut`). An object containing a managed box is
not `Owned`, and can't be sent between tasks.
~~~~
let a = @5; // immutable
let mut b = @5; // mutable variable, immutable box
b = @10;
let c = @mut 5; // immutable variable, mutable box
*c = 10;
let mut d = @mut 5; // mutable variable, mutable box
*d += 5;
d = @mut 15;
~~~~
# Move semantics
Rust uses a shallow copy for parameter passing, assignment and returning values
@ -1035,10 +1084,10 @@ let z = x; // no new memory allocated, x can no longer be used
# Borrowed pointers
Rust's borrowed pointers are a general purpose reference type. In contrast with
owned pointers, where the holder of an owned pointer is the owner of the
pointed-to memory, borrowed pointers never imply ownership. A pointer can be
borrowed to any object, and the compiler verifies that it cannot outlive the
lifetime of the object.
owned boxes, where the holder of an owned box is the owner of the pointed-to
memory, borrowed pointers never imply ownership. A pointer can be borrowed to
any object, and the compiler verifies that it cannot outlive the lifetime of
the object.
As an example, consider a simple struct type, `Point`:
@ -1124,10 +1173,7 @@ For a more in-depth explanation of borrowed pointers, read the
## Freezing
Borrowing an immutable pointer to an object freezes it and prevents mutation.
`Owned` objects have freezing enforced statically at compile-time. Mutable
managed boxes handle freezing dynamically when any of their contents are
borrowed, and the task will fail if an attempt to modify them is made while
they are frozen.
`Owned` objects have freezing enforced statically at compile-time.
~~~~
let mut x = 5;
@ -1137,6 +1183,20 @@ let mut x = 5;
// x is now unfrozen again
~~~~
Mutable managed boxes handle freezing dynamically when any of their contents
are borrowed, and the task will fail if an attempt to modify them is made while
they are frozen:
~~~~
let x = @mut 5;
let y = x;
{
let y = &*y; // the managed box is now frozen
// modifying it through x or y will cause a task failure
}
// the box is now unfrozen again
~~~~
# Dereferencing pointers
Rust uses the unary star operator (`*`) to access the contents of a