Move doc/ to src/doc/

We generate documentation into the doc/ directory, so we shouldn't be
intermingling source files with generated files

1 files changed, 3275 insertions, 0 deletions

diff --git a/src/doc/tutorial.md b/src/doc/tutorial.md
new file mode 100644
index 00000000000..5122ac35602
--- /dev/null
+++ b/src/doc/tutorial.md
@@ -0,0 +1,3275 @@
+% The Rust Language Tutorial
+
+# Introduction
+
+Rust is a programming language with a focus on type safety, memory
+safety, concurrency and performance. It is intended for writing
+large-scale, high-performance software that is free from several
+classes of common errors. Rust has a sophisticated memory model that
+encourages efficient data structures and safe concurrency patterns,
+forbidding invalid memory accesses that would otherwise cause
+segmentation faults. It is statically typed and compiled ahead of
+time.
+
+As a multi-paradigm language, Rust supports writing code in
+procedural, functional and object-oriented styles. Some of its
+pleasant high-level features include:
+
+* **Type inference.** Type annotations on local variable declarations
+  are optional.
+* **Safe task-based concurrency.** Rust's lightweight tasks do not share
+  memory, instead communicating through messages.
+* **Higher-order functions.** Efficient and flexible closures provide
+  iteration and other control structures
+* **Pattern matching and algebraic data types.** Pattern matching on
+  Rust's enumeration types (a more powerful version of C's enums,
+  similar to algebraic data types in functional languages) is a
+  compact and expressive way to encode program logic.
+* **Polymorphism.** Rust has type-parametric functions and
+  types, type classes and OO-style interfaces.
+
+## Scope
+
+This is an introductory tutorial for the Rust programming language. It
+covers the fundamentals of the language, including the syntax, the
+type system and memory model, generics, and modules. [Additional
+tutorials](#what-next) cover specific language features in greater
+depth.
+
+This tutorial assumes that the reader is already familiar with one or
+more languages in the C family. Understanding of pointers and general
+memory management techniques will help.
+
+## Conventions
+
+Throughout the tutorial, language keywords and identifiers defined in
+example code are displayed in `code font`.
+
+Code snippets are indented, and also shown in a monospaced font. Not
+all snippets constitute whole programs. For brevity, we'll often show
+fragments of programs that don't compile on their own. To try them
+out, you might have to wrap them in `fn main() { ... }`, and make sure
+they don't contain references to names that aren't actually defined.
+
+> ***Warning:*** Rust is a language under ongoing development. Notes
+> about potential changes to the language, implementation
+> deficiencies, and other caveats appear offset in blockquotes.
+
+# Getting started
+
+> **NOTE**: The tarball and installer links are for the most recent release,
+> not master.
+
+The Rust compiler currently must be built from a [tarball] or [git], unless
+you are on Windows, in which case using the [installer][win-exe] is
+recommended. There is a list of community-maintained nightly builds and
+packages [on the wiki][wiki-packages].
+
+Since the Rust compiler is written in Rust, it must be built by
+a precompiled "snapshot" version of itself (made in an earlier state
+of development). The source build automatically fetches these snapshots
+from the Internet on our supported platforms.
+
+Snapshot binaries are currently built and tested on several platforms:
+
+* Windows (7, 8, Server 2008 R2), x86 only
+* Linux (2.6.18 or later, various distributions), x86 and x86-64
+* OSX 10.7 (Lion) or greater, x86 and x86-64
+
+You may find that other platforms work, but these are our "tier 1"
+supported build environments that are most likely to work.
+
+> ***Note:*** Windows users should read the detailed
+> "[getting started][wiki-start]" notes on the wiki. Even when using
+> the binary installer, the Windows build requires a MinGW installation,
+> the precise details of which are not discussed here. Finally, `rustc` may
+> need to be [referred to as `rustc.exe`][bug-3319]. It's a bummer, we
+> know.
+
+[bug-3319]: https://github.com/mozilla/rust/issues/3319
+[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust
+[git]: https://github.com/mozilla/rust.git
+
+To build from source you will also need the following prerequisite
+packages:
+
+* g++ 4.4 or clang++ 3.x
+* python 2.6 or later (but not 3.x)
+* perl 5.0 or later
+* gnu make 3.81 or later
+* curl
+
+If you've fulfilled those prerequisites, something along these lines
+should work.
+
+~~~~ {.notrust}
+$ curl -O http://static.rust-lang.org/dist/rust-0.9.tar.gz
+$ tar -xzf rust-0.9.tar.gz
+$ cd rust-0.9
+$ ./configure
+$ make && make install
+~~~~
+
+You may need to use `sudo make install` if you do not normally have
+permission to modify the destination directory. The install locations
+can be adjusted by passing a `--prefix` argument to
+`configure`. Various other options are also supported: pass `--help`
+for more information on them.
+
+When complete, `make install` will place several programs into
+`/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
+API-documentation tool.
+
+[tarball]: http://static.rust-lang.org/dist/rust-0.9.tar.gz
+[win-exe]: http://static.rust-lang.org/dist/rust-0.9-install.exe
+
+## Compiling your first program
+
+Rust program files are, by convention, given the extension `.rs`. Say
+we have a file `hello.rs` containing this program:
+
+~~~~
+fn main() {
+    println!("hello?");
+}
+~~~~
+
+If the Rust compiler was installed successfully, running `rustc
+hello.rs` will produce an executable called `hello` (or `hello.exe` on
+Windows) which, upon running, will likely do exactly what you expect.
+
+The Rust compiler tries to provide useful information when it encounters an
+error. If you introduce an error into the program (for example, by changing
+`println!` to some nonexistent macro), and then compile it, you'll see
+an error message like this:
+
+~~~~ {.notrust}
+hello.rs:2:5: 2:24 error: macro undefined: 'print_with_unicorns'
+hello.rs:2     print_with_unicorns!("hello?");
+               ^~~~~~~~~~~~~~~~~~~
+~~~~
+
+In its simplest form, a Rust program is a `.rs` file with some types
+and functions defined in it. If it has a `main` function, it can be
+compiled to an executable. Rust does not allow code that's not a
+declaration to appear at the top level of the file: all statements must
+live inside a function.  Rust programs can also be compiled as
+libraries, and included in other programs, even ones not written in Rust.
+
+## Editing Rust code
+
+There are vim highlighting and indentation scripts in the Rust source
+distribution under `src/etc/vim/`. There is an emacs mode under
+`src/etc/emacs/` called `rust-mode`, but do read the instructions
+included in that directory. In particular, if you are running emacs
+24, then using emacs's internal package manager to install `rust-mode`
+is the easiest way to keep it up to date. There is also a package for
+Sublime Text 2, available both [standalone][sublime] and through
+[Sublime Package Control][sublime-pkg], and support for Kate
+under `src/etc/kate`.
+
+A community-maintained list of available Rust tooling is [on the
+wiki][wiki-packages].
+
+There is ctags support via `src/etc/ctags.rust`, but many other
+tools and editors are not yet supported. If you end up writing a Rust
+mode for your favorite editor, let us know so that we can link to it.
+
+[sublime]: http://github.com/dbp/sublime-rust
+[sublime-pkg]: http://wbond.net/sublime_packages/package_control
+
+# Syntax basics
+
+Assuming you've programmed in any C-family language (C++, Java,
+JavaScript, C#, or PHP), Rust will feel familiar. Code is arranged
+in blocks delineated by curly braces; there are control structures
+for branching and looping, like the familiar `if` and `while`; function
+calls are written `myfunc(arg1, arg2)`; operators are written the same
+and mostly have the same precedence as in C; comments are again like C;
+module names are separated with double-colon (`::`) as with C++.
+
+The main surface difference to be aware of is that the condition at
+the head of control structures like `if` and `while` does not require
+parentheses, while their bodies *must* be wrapped in
+braces. Single-statement, unbraced bodies are not allowed.
+
+~~~~
+# mod universe { pub fn recalibrate() -> bool { true } }
+fn main() {
+    /* A simple loop */
+    loop {
+        // A tricky calculation
+        if universe::recalibrate() {
+            return;
+        }
+    }
+}
+~~~~
+
+The `let` keyword introduces a local variable. Variables are immutable by
+default. To introduce a local variable that you can re-assign later, use `let
+mut` instead.
+
+~~~~
+let hi = "hi";
+let mut count = 0;
+
+while count < 10 {
+    println!("count is {}", count);
+    count += 1;
+}
+~~~~
+
+Although Rust can almost always infer the types of local variables, you can
+specify a variable's type by following it in the `let` with a colon, then the
+type name. Static items, on the other hand, always require a type annotation.
+
+
+~~~~
+static MONSTER_FACTOR: f64 = 57.8;
+let monster_size = MONSTER_FACTOR * 10.0;
+let monster_size: int = 50;
+~~~~
+
+Local variables may shadow earlier declarations, as in the previous example:
+`monster_size` was first declared as a `f64`, and then a second
+`monster_size` was declared as an `int`. If you were to actually compile this
+example, though, the compiler would determine that the first `monster_size` is
+unused and issue a warning (because this situation is likely to indicate a
+programmer error). For occasions where unused variables are intentional, their
+names may be prefixed with an underscore to silence the warning, like `let
+_monster_size = 50;`.
+
+Rust identifiers start with an alphabetic
+character or an underscore, and after that may contain any sequence of
+alphabetic characters, numbers, or underscores. The preferred style is to
+write function, variable, and module names with lowercase letters, using
+underscores where they help readability, while writing types in camel case.
+
+~~~
+let my_variable = 100;
+type MyType = int;     // primitive types are _not_ camel case
+~~~
+
+## Expressions and semicolons
+
+Though it isn't apparent in all code, there is a fundamental
+difference between Rust's syntax and predecessors like C.
+Many constructs that are statements in C are expressions
+in Rust, allowing code to be more concise. For example, you might
+write a piece of code like this:
+
+~~~~
+# let item = "salad";
+let price;
+if item == "salad" {
+    price = 3.50;
+} else if item == "muffin" {
+    price = 2.25;
+} else {
+    price = 2.00;
+}
+~~~~
+
+But, in Rust, you don't have to repeat the name `price`:
+
+~~~~
+# let item = "salad";
+let price =
+    if item == "salad" {
+        3.50
+    } else if item == "muffin" {
+        2.25
+    } else {
+        2.00
+    };
+~~~~
+
+Both pieces of code are exactly equivalent: they assign a value to
+`price` depending on the condition that holds. Note that there
+are no semicolons in the blocks of the second snippet. This is
+important: the lack of a semicolon after the last statement in a
+braced block gives the whole block the value of that last expression.
+
+Put another way, the semicolon in Rust *ignores the value of an expression*.
+Thus, if the branches of the `if` had looked like `{ 4; }`, the above example
+would simply assign `()` (nil or void) to `price`. But without the semicolon, each
+branch has a different value, and `price` gets the value of the branch that
+was taken.
+
+In short, everything that's not a declaration (declarations are `let` for
+variables; `fn` for functions; and any top-level named items such as
+[traits](#traits), [enum types](#enums), and static items) is an
+expression, including function bodies.
+
+~~~~
+fn is_four(x: int) -> bool {
+   // No need for a return statement. The result of the expression
+   // is used as the return value.
+   x == 4
+}
+~~~~
+
+## Primitive types and literals
+
+There are general signed and unsigned integer types, `int` and `uint`,
+as well as 8-, 16-, 32-, and 64-bit variants, `i8`, `u16`, etc.
+Integers can be written in decimal (`144`), hexadecimal (`0x90`), octal (`0o70`), or
+binary (`0b10010000`) base. Each integral type has a corresponding literal
+suffix that can be used to indicate the type of a literal: `i` for `int`,
+`u` for `uint`, `i8` for the `i8` type.
+
+In the absence of an integer literal suffix, Rust will infer the
+integer type based on type annotations and function signatures in the
+surrounding program. In the absence of any type information at all,
+Rust will assume that an unsuffixed integer literal has type
+`int`.
+
+~~~~
+let a = 1;       // `a` is an `int`
+let b = 10i;     // `b` is an `int`, due to the `i` suffix
+let c = 100u;    // `c` is a `uint`
+let d = 1000i32; // `d` is an `i32`
+~~~~
+
+There are two floating-point types: `f32`, and `f64`.
+Floating-point numbers are written `0.0`, `1e6`, or `2.1e-4`.
+Like integers, floating-point literals are inferred to the correct type.
+Suffixes `f32`, and `f64` can be used to create literals of a specific type.
+
+The keywords `true` and `false` produce literals of type `bool`.
+
+Characters, the `char` type, are four-byte Unicode codepoints,
+whose literals are written between single quotes, as in `'x'`.
+Just like C, Rust understands a number of character escapes, using the backslash
+character, such as `\n`, `\r`, and `\t`. String literals,
+written between double quotes, allow the same escape sequences, and do no
+other processing, unlike languages such as PHP or shell.
+
+On the other hand, raw string literals do not process any escape sequences.
+They are written as `r##"blah"##`, with a matching number of zero or more `#`
+before the opening and after the closing quote, and can contain any sequence of
+characters except their closing delimiter.  More on strings
+[later](#vectors-and-strings).
+
+The nil type, written `()`, has a single value, also written `()`.
+
+## Operators
+
+Rust's set of operators contains very few surprises. Arithmetic is done with
+`*`, `/`, `%`, `+`, and `-` (multiply, quotient, remainder, add, and subtract). `-` is
+also a unary prefix operator that negates numbers. As in C, the bitwise operators
+`>>`, `<<`, `&`, `|`, and `^` are also supported.
+
+Note that, if applied to an integer value, `!` flips all the bits (bitwise
+NOT, like `~` in C).
+
+The comparison operators are the traditional `==`, `!=`, `<`, `>`,
+`<=`, and `>=`. Short-circuiting (lazy) boolean operators are written
+`&&` (and) and `||` (or).
+
+For compile-time type casting, Rust uses the binary `as` operator.  It takes
+an expression on the left side and a type on the right side and will, if a
+meaningful conversion exists, convert the result of the expression to the
+given type. Generally, `as` is only used with the primitive numeric types or
+pointers, and is not overloadable.  [`transmute`][transmute] can be used for
+unsafe C-like casting of same-sized types.
+
+~~~~
+let x: f64 = 4.0;
+let y: uint = x as uint;
+assert!(y == 4u);
+~~~~
+
+[transmute]: http://static.rust-lang.org/doc/master/std/cast/fn.transmute.html
+
+## Syntax extensions
+
+*Syntax extensions* are special forms that are not built into the language,
+but are instead provided by the libraries. To make it clear to the reader when
+a name refers to a syntax extension, the names of all syntax extensions end
+with `!`. The standard library defines a few syntax extensions, the most
+useful of which is [`format!`][fmt], a `sprintf`-like text formatter that you
+will often see in examples, and its related family of macros: `print!`,
+`println!`, and `write!`.
+
+`format!` draws syntax from Python, but contains many of the same principles
+that [printf][pf] has. Unlike printf, `format!` will give you a compile-time
+error when the types of the directives don't match the types of the arguments.
+
+~~~~
+# let mystery_object = ();
+
+// `{}` will print the "default format" of a type
+println!("{} is {}", "the answer", 43);
+
+// `{:?}` will conveniently print any type
+println!("what is this thing: {:?}", mystery_object);
+~~~~
+
+[pf]: http://en.cppreference.com/w/cpp/io/c/fprintf
+[fmt]: http://static.rust-lang.org/doc/master/std/fmt/index.html
+
+You can define your own syntax extensions with the macro system. For details,
+see the [macro tutorial][macros]. Note that macro definition is currently
+considered an unstable feature.
+
+# Control structures
+
+## Conditionals
+
+We've seen `if` expressions a few times already. To recap, braces are
+compulsory, an `if` can have an optional `else` clause, and multiple
+`if`/`else` constructs can be chained together:
+
+~~~~
+if false {
+    println!("that's odd");
+} else if true {
+    println!("right");
+} else {
+    println!("neither true nor false");
+}
+~~~~
+
+The condition given to an `if` construct *must* be of type `bool` (no
+implicit conversion happens). If the arms are blocks that have a
+value, this value must be of the same type for every arm in which
+control reaches the end of the block:
+
+~~~~
+fn signum(x: int) -> int {
+    if x < 0 { -1 }
+    else if x > 0 { 1 }
+    else { 0 }
+}
+~~~~
+
+## Pattern matching
+
+Rust's `match` construct is a generalized, cleaned-up version of C's
+`switch` construct. You provide it with a value and a number of
+*arms*, each labelled with a pattern, and the code compares the value
+against each pattern in order until one matches. The matching pattern
+executes its corresponding arm.
+
+~~~~
+# let my_number = 1;
+match my_number {
+  0     => println!("zero"),
+  1 | 2 => println!("one or two"),
+  3..10 => println!("three to ten"),
+  _     => println!("something else")
+}
+~~~~
+
+Unlike in C, there is no "falling through" between arms: only one arm
+executes, and it doesn't have to explicitly `break` out of the
+construct when it is finished.
+
+A `match` arm consists of a *pattern*, then an arrow `=>`, followed by
+an *action* (expression). Literals are valid patterns and match only
+their own value. A single arm may match multiple different patterns by
+combining them with the pipe operator (`|`), so long as every pattern
+binds the same set of variables. Ranges of numeric literal patterns
+can be expressed with two dots, as in `M..N`. The underscore (`_`) is
+a wildcard pattern that matches any single value. (`..`) is a different
+wildcard that can match one or more fields in an `enum` variant.
+
+The patterns in a match arm are followed by a fat arrow, `=>`, then an
+expression to evaluate. Each case is separated by commas. It's often
+convenient to use a block expression for each case, in which case the
+commas are optional.
+
+~~~
+# let my_number = 1;
+match my_number {
+  0 => { println!("zero") }
+  _ => { println!("something else") }
+}
+~~~
+
+`match` constructs must be *exhaustive*: they must have an arm
+covering every possible case. For example, the typechecker would
+reject the previous example if the arm with the wildcard pattern was
+omitted.
+
+A powerful application of pattern matching is *destructuring*:
+matching in order to bind names to the contents of data
+types.
+
+> ***Note:*** The following code makes use of tuples (`(f64, f64)`) which
+> are explained in section 5.3. For now you can think of tuples as a list of
+> items.
+
+~~~~
+use std::f64;
+use std::num::atan;
+fn angle(vector: (f64, f64)) -> f64 {
+    let pi = f64::consts::PI;
+    match vector {
+      (0.0, y) if y < 0.0 => 1.5 * pi,
+      (0.0, y) => 0.5 * pi,
+      (x, y) => atan(y / x)
+    }
+}
+~~~~
+
+A variable name in a pattern matches any value, *and* binds that name
+to the value of the matched value inside of the arm's action. Thus, `(0.0,
+y)` matches any tuple whose first element is zero, and binds `y` to
+the second element. `(x, y)` matches any two-element tuple, and binds both
+elements to variables.
+A subpattern can also be bound to a variable, using `variable @ pattern`. For
+example:
+
+~~~~
+# let age = 23;
+match age {
+    a @ 0..20 => println!("{} years old", a),
+    _ => println!("older than 21")
+}
+~~~~
+
+Any `match` arm can have a guard clause (written `if EXPR`), called a
+*pattern guard*, which is an expression of type `bool` that
+determines, after the pattern is found to match, whether the arm is
+taken or not. The variables bound by the pattern are in scope in this
+guard expression. The first arm in the `angle` example shows an
+example of a pattern guard.
+
+You've already seen simple `let` bindings, but `let` is a little
+fancier than you've been led to believe. It, too, supports destructuring
+patterns. For example, you can write this to extract the fields from a
+tuple, introducing two variables at once: `a` and `b`.
+
+~~~~
+# fn get_tuple_of_two_ints() -> (int, int) { (1, 1) }
+let (a, b) = get_tuple_of_two_ints();
+~~~~
+
+Let bindings only work with _irrefutable_ patterns: that is, patterns
+that can never fail to match. This excludes `let` from matching
+literals and most `enum` variants.
+
+## Loops
+
+`while` denotes a loop that iterates as long as its given condition
+(which must have type `bool`) evaluates to `true`. Inside a loop, the
+keyword `break` aborts the loop, and `continue` aborts the current
+iteration and continues with the next.
+
+~~~~
+let mut cake_amount = 8;
+while cake_amount > 0 {
+    cake_amount -= 1;
+}
+~~~~
+
+`loop` denotes an infinite loop, and is the preferred way of writing `while true`:
+
+~~~~
+let mut x = 5u;
+loop {
+    x += x - 3;
+    if x % 5 == 0 { break; }
+    println!("{}", x);
+}
+~~~~
+
+This code prints out a weird sequence of numbers and stops as soon as
+it finds one that can be divided by five.
+
+# Data structures
+
+## Structs
+
+Rust struct types must be declared before they are used using the `struct`
+syntax: `struct Name { field1: T1, field2: T2 [, ...] }`, where `T1`, `T2`,
+... denote types. To construct a struct, use the same syntax, but leave off
+the `struct`: for example: `Point { x: 1.0, y: 2.0 }`.
+
+Structs are quite similar to C structs and are even laid out the same way in
+memory (so you can read from a Rust struct in C, and vice-versa). Use the dot
+operator to access struct fields, as in `mypoint.x`.
+
+~~~~
+struct Point {
+    x: f64,
+    y: f64
+}
+~~~~
+
+Structs have "inherited mutability", which means that any field of a struct
+may be mutable, if the struct is in a mutable slot.
+
+With a value (say, `mypoint`) of such a type in a mutable location, you can do
+`mypoint.y += 1.0`. But in an immutable location, such an assignment to a
+struct without inherited mutability would result in a type error.
+
+~~~~ {.ignore}
+# struct Point { x: f64, y: f64 }
+let mut mypoint = Point { x: 1.0, y: 1.0 };
+let origin = Point { x: 0.0, y: 0.0 };
+
+mypoint.y += 1.0; // `mypoint` is mutable, and its fields as well
+origin.y += 1.0; // ERROR: assigning to immutable field
+~~~~
+
+`match` patterns destructure structs. The basic syntax is
+`Name { fieldname: pattern, ... }`:
+
+~~~~
+# struct Point { x: f64, y: f64 }
+# let mypoint = Point { x: 0.0, y: 0.0 };
+match mypoint {
+    Point { x: 0.0, y: yy } => println!("{}", yy),
+    Point { x: xx,  y: yy } => println!("{} {}", xx, yy),
+}
+~~~~
+
+In general, the field names of a struct do not have to appear in the same
+order they appear in the type. When you are not interested in all
+the fields of a struct, a struct pattern may end with `, ..` (as in
+`Name { field1, .. }`) to indicate that you're ignoring all other fields.
+Additionally, struct fields have a shorthand matching form that simply
+reuses the field name as the binding name.
+
+~~~
+# struct Point { x: f64, y: f64 }
+# let mypoint = Point { x: 0.0, y: 0.0 };
+match mypoint {
+    Point { x, .. } => println!("{}", x),
+}
+~~~
+
+## Enums
+
+Enums are datatypes that have several alternate representations. For
+example, consider the following type:
+
+~~~~
+# struct Point { x: f64, y: f64 }
+enum Shape {
+    Circle(Point, f64),
+    Rectangle(Point, Point)
+}
+~~~~
+
+A value of this type is either a `Circle`, in which case it contains a
+`Point` struct and a f64, or a `Rectangle`, in which case it contains
+two `Point` structs. The run-time representation of such a value
+includes an identifier of the actual form that it holds, much like the
+"tagged union" pattern in C, but with better static guarantees.
+
+The above declaration will define a type `Shape` that can refer to
+such shapes, and two functions, `Circle` and `Rectangle`, which can be
+used to construct values of the type (taking arguments of the
+specified types). So `Circle(Point { x: 0.0, y: 0.0 }, 10.0)` is the way to
+create a new circle.
+
+Enum variants need not have parameters. This `enum` declaration,
+for example, is equivalent to a C enum:
+
+~~~~
+enum Direction {
+    North,
+    East,
+    South,
+    West
+}
+~~~~
+
+This declaration defines `North`, `East`, `South`, and `West` as constants,
+all of which have type `Direction`.
+
+When an enum is C-like (that is, when none of the variants have
+parameters), it is possible to explicitly set the discriminator values
+to a constant value:
+
+~~~~
+enum Color {
+  Red = 0xff0000,
+  Green = 0x00ff00,
+  Blue = 0x0000ff
+}
+~~~~
+
+If an explicit discriminator is not specified for a variant, the value
+defaults to the value of the previous variant plus one. If the first
+variant does not have a discriminator, it defaults to 0. For example,
+the value of `North` is 0, `East` is 1, `South` is 2, and `West` is 3.
+
+When an enum is C-like, you can apply the `as` cast operator to
+convert it to its discriminator value as an `int`.
+
+For enum types with multiple variants, destructuring is the only way to
+get at their contents. All variant constructors can be used as
+patterns, as in this definition of `area`:
+
+~~~~
+use std::f64;
+# struct Point {x: f64, y: f64}
+# enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
+fn area(sh: Shape) -> f64 {
+    match sh {
+        Circle(_, size) => f64::consts::PI * size * size,
+        Rectangle(Point { x, y }, Point { x: x2, y: y2 }) => (x2 - x) * (y2 - y)
+    }
+}
+~~~~
+
+You can write a lone `_` to ignore an individual field, and can
+ignore all fields of a variant like: `Circle(..)`. As in their
+introduction form, nullary enum patterns are written without
+parentheses.
+
+~~~~
+# struct Point { x: f64, y: f64 }
+# enum Direction { North, East, South, West }
+fn point_from_direction(dir: Direction) -> Point {
+    match dir {
+        North => Point { x:  0.0, y:  1.0 },
+        East  => Point { x:  1.0, y:  0.0 },
+        South => Point { x:  0.0, y: -1.0 },
+        West  => Point { x: -1.0, y:  0.0 }
+    }
+}
+~~~~
+
+Enum variants may also be structs. For example:
+
+~~~~
+use std::f64;
+# struct Point { x: f64, y: f64 }
+# fn square(x: f64) -> f64 { x * x }
+enum Shape {
+    Circle { center: Point, radius: f64 },
+    Rectangle { top_left: Point, bottom_right: Point }
+}
+fn area(sh: Shape) -> f64 {
+    match sh {
+        Circle { radius: radius, .. } => f64::consts::PI * square(radius),
+        Rectangle { top_left: top_left, bottom_right: bottom_right } => {
+            (bottom_right.x - top_left.x) * (top_left.y - bottom_right.y)
+        }
+    }
+}
+~~~~
+
+> ***Note:*** This feature of the compiler is currently gated behind the
+> `#[feature(struct_variant)]` directive. More about these directives can be
+> found in the manual.
+
+## Tuples
+
+Tuples in Rust behave exactly like structs, except that their fields do not
+have names. Thus, you cannot access their fields with dot notation.  Tuples
+can have any arity (number of elements) except for 0 (though you may consider
+unit, `()`, as the empty tuple if you like).
+
+~~~~
+let mytup: (int, int, f64) = (10, 20, 30.0);
+match mytup {
+  (a, b, c) => info!("{}", a + b + (c as int))
+}
+~~~~
+
+## Tuple structs
+
+Rust also has _tuple structs_, which behave like both structs and tuples,
+except that, unlike tuples, tuple structs have names (so `Foo(1, 2)` has a
+different type from `Bar(1, 2)`), and tuple structs' _fields_ do not have
+names.
+
+For example:
+
+~~~~
+struct MyTup(int, int, f64);
+let mytup: MyTup = MyTup(10, 20, 30.0);
+match mytup {
+  MyTup(a, b, c) => info!("{}", a + b + (c as int))
+}
+~~~~
+
+<a name="newtype"></a>
+
+There is a special case for tuple structs with a single field, which are
+sometimes called "newtypes" (after Haskell's "newtype" feature). These are
+used to define new types in such a way that the new name is not just a
+synonym for an existing type but is rather its own distinct type.
+
+~~~~
+struct GizmoId(int);
+~~~~
+
+Types like this can be useful to differentiate between data that have
+the same underlying type but must be used in different ways.
+
+~~~~
+struct Inches(int);
+struct Centimeters(int);
+~~~~
+
+The above definitions allow for a simple way for programs to avoid
+confusing numbers that correspond to different units. Their integer
+values can be extracted with pattern matching:
+
+~~~
+# struct Inches(int);
+
+let length_with_unit = Inches(10);
+let Inches(integer_length) = length_with_unit;
+println!("length is {} inches", integer_length);
+~~~
+
+# Functions
+
+We've already seen several function definitions. Like all other static
+declarations, such as `type`, functions can be declared both at the
+top level and inside other functions (or in modules, which we'll come
+back to [later](#crates-and-the-module-system)). The `fn` keyword introduces a
+function. A function has an argument list, which is a parenthesized
+list of `name: type` pairs separated by commas. An arrow `->`
+separates the argument list and the function's return type.
+
+~~~~
+fn line(a: int, b: int, x: int) -> int {
+    return a * x + b;
+}
+~~~~
+
+The `return` keyword immediately returns from the body of a function. It
+is optionally followed by an expression to return. A function can
+also return a value by having its top-level block produce an
+expression.
+
+~~~~
+fn line(a: int, b: int, x: int) -> int {
+    a * x + b
+}
+~~~~
+
+It's better Rust style to write a return value this way instead of
+writing an explicit `return`. The utility of `return` comes in when
+returning early from a function. Functions that do not return a value
+are said to return nil, `()`, and both the return type and the return
+value may be omitted from the definition. The following two functions
+are equivalent.
+
+~~~~
+fn do_nothing_the_hard_way() -> () { return (); }
+
+fn do_nothing_the_easy_way() { }
+~~~~
+
+Ending the function with a semicolon like so is equivalent to returning `()`.
+
+~~~~
+fn line(a: int, b: int, x: int) -> int { a * x + b  }
+fn oops(a: int, b: int, x: int) -> ()  { a * x + b; }
+
+assert!(8 == line(5, 3, 1));
+assert!(() == oops(5, 3, 1));
+~~~~
+
+As with `match` expressions and `let` bindings, function arguments support
+pattern destructuring. Like `let`, argument patterns must be irrefutable,
+as in this example that unpacks the first value from a tuple and returns it.
+
+~~~
+fn first((value, _): (int, f64)) -> int { value }
+~~~
+
+# Destructors
+
+A *destructor* is a function responsible for cleaning up the resources used by
+an object when it is no longer accessible. Destructors can be defined to handle
+the release of resources like files, sockets and heap memory.
+
+Objects are never accessible after their destructor has been called, so no
+dynamic failures are possible from accessing freed resources. When a task
+fails, destructors of all objects in the task are called.
+
+The `~` sigil represents a unique handle for a memory allocation on the heap:
+
+~~~~
+{
+    // an integer allocated on the heap
+    let y = ~10;
+}
+// the destructor frees the heap memory as soon as `y` goes out of scope
+~~~~
+
+Rust includes syntax for heap memory allocation in the language since it's
+commonly used, but the same semantics can be implemented by a type with a
+custom destructor.
+
+# Ownership
+
+Rust formalizes the concept of object ownership to delegate management of an
+object's lifetime to either a variable or a task-local garbage collector. An
+object's owner is responsible for managing the lifetime of the object by
+calling the destructor, and the owner determines whether the object is mutable.
+
+Ownership is recursive, so mutability is inherited recursively and a destructor
+destroys the contained tree of owned objects. Variables are top-level owners
+and destroy the contained object when they go out of scope.
+
+~~~~
+// the struct owns the objects contained in the `x` and `y` fields
+struct Foo { x: int, y: ~int }
+
+{
+    // `a` is the owner of the struct, and thus the owner of the struct's fields
+    let a = Foo { x: 5, y: ~10 };
+}
+// when `a` goes out of scope, the destructor for the `~int` in the struct's
+// field is called
+
+// `b` is mutable, and the mutability is inherited by the objects it owns
+let mut b = Foo { x: 5, y: ~10 };
+b.x = 10;
+~~~~
+
+If an object doesn't contain any non-Send types, it consists of a single
+ownership tree and is itself given the `Send` trait which allows it to be sent
+between tasks. Custom destructors can only be implemented directly on types
+that are `Send`, but non-`Send` types can still *contain* types with custom
+destructors. Example of types which are not `Send` are [`Gc<T>`][gc] and
+[`Rc<T>`][rc], the shared-ownership types.
+
+[gc]: http://static.rust-lang.org/doc/master/std/gc/struct.Gc.html
+[rc]: http://static.rust-lang.org/doc/master/std/rc/struct.Rc.html
+
+# Implementing a linked list
+
+An `enum` is a natural fit for describing a linked list, because it can express
+a `List` type as being *either* the end of the list (`Nil`) or another node
+(`Cons`). The full definition of the `Cons` variant will require some thought.
+
+~~~ {.ignore}
+enum List {
+    Cons(...), // an incomplete definition of the next element in a List
+    Nil        // the end of a List
+}
+~~~
+
+The obvious approach is to define `Cons` as containing an element in the list
+along with the next `List` node. However, this will generate a compiler error.
+
+~~~ {.ignore}
+// error: illegal recursive enum type; wrap the inner value in a box to make it representable
+enum List {
+    Cons(u32, List), // an element (`u32`) and the next node in the list
+    Nil
+}
+~~~
+
+This error message is related to Rust's precise control over memory layout, and
+solving it will require introducing the concept of *boxing*.
+
+## Boxes
+
+A value in Rust is stored directly inside the owner. If a `struct` contains
+four `u32` fields, it will be four times as large as a single `u32`.
+
+~~~
+use std::mem::size_of; // bring `size_of` into the current scope, for convenience
+
+struct Foo {
+    a: u32,
+    b: u32,
+    c: u32,
+    d: u32
+}
+
+assert_eq!(size_of::<Foo>(), size_of::<u32>() * 4);
+
+struct Bar {
+    a: Foo,
+    b: Foo,
+    c: Foo,
+    d: Foo
+}
+
+assert_eq!(size_of::<Bar>(), size_of::<u32>() * 16);
+~~~
+
+Our previous attempt at defining the `List` type included an `u32` and a `List`
+directly inside `Cons`, making it at least as big as the sum of both types. The
+type was invalid because the size was infinite!
+
+An *owned box* (`~`) uses a dynamic memory allocation to provide the invariant
+of always being the size of a pointer, regardless of the contained type. This
+can be leverage to create a valid `List` definition:
+
+~~~
+enum List {
+    Cons(u32, ~List),
+    Nil
+}
+~~~
+
+Defining a recursive data structure like this is the canonical example of an
+owned box. Much like an unboxed value, an owned box has a single owner and is
+therefore limited to expressing a tree-like data structure.
+
+Consider an instance of our `List` type:
+
+~~~
+# enum List {
+#     Cons(u32, ~List),
+#     Nil
+# }
+let list = Cons(1, ~Cons(2, ~Cons(3, ~Nil)));
+~~~
+
+It represents an owned tree of values, inheriting mutability down the tree and
+being destroyed along with the owner. Since the `list` variable above is
+immutable, the whole list is immutable. The memory allocation itself is the
+box, while the owner holds onto a pointer to it:
+
+              List box             List box           List box            List box
+            +--------------+    +--------------+    +--------------+    +--------------+
+    list -> | Cons | 1 | ~ | -> | Cons | 2 | ~ | -> | Cons | 3 | ~ | -> | Nil          |
+            +--------------+    +--------------+    +--------------+    +--------------+
+
+> Note: the above diagram shows the logical contents of the enum. The actual
+> memory layout of the enum may vary. For example, for the `List` enum shown
+> above, Rust guarantees that there will be no enum tag field in the actual
+> structure. See the language reference for more details.
+
+An owned box is a common example of a type with a destructor. The allocated
+memory is cleaned up when the box is destroyed.
+
+## Move semantics
+
+Rust uses a shallow copy for parameter passing, assignment and returning from
+functions. Passing around the `List` will copy only as deep as the pointer to
+the box rather than doing an implicit heap allocation.
+
+~~~
+# enum List {
+#     Cons(u32, ~List),
+#     Nil
+# }
+let xs = Cons(1, ~Cons(2, ~Cons(3, ~Nil)));
+let ys = xs; // copies `Cons(u32, pointer)` shallowly
+~~~
+
+Rust will consider a shallow copy of a type with a destructor like `List` to
+*move ownership* of the value. After a value has been moved, the source
+location cannot be used unless it is reinitialized.
+
+~~~
+# enum List {
+#     Cons(u32, ~List),
+#     Nil
+# }
+let mut xs = Nil;
+let ys = xs;
+
+// attempting to use `xs` will result in an error here
+
+xs = Nil;
+
+// `xs` can be used again
+~~~
+
+A destructor call will only occur for a variable that has not been moved from,
+as it is only called a single time.
+
+
+Avoiding a move can be done with the library-defined `clone` method:
+
+~~~~
+let x = ~5;
+let y = x.clone(); // `y` is a newly allocated box
+let z = x; // no new memory allocated, `x` can no longer be used
+~~~~
+
+The `clone` method is provided by the `Clone` trait, and can be derived for
+our `List` type. Traits will be explained in detail later.
+
+~~~{.ignore}
+#[deriving(Clone)]
+enum List {
+    Cons(u32, ~List),
+    Nil
+}
+
+let x = Cons(5, ~Nil);
+let y = x.clone();
+
+// `x` can still be used!
+
+let z = x;
+
+// and now, it can no longer be used since it has been moved
+~~~
+
+The mutability of a value may be changed by moving it to a new owner:
+
+~~~~
+let r = ~13;
+let mut s = r; // box becomes mutable
+*s += 1;
+let t = s; // box becomes immutable
+~~~~
+
+A simple way to define a function prepending to the `List` type is to take
+advantage of moves:
+
+~~~
+enum List {
+    Cons(u32, ~List),
+    Nil
+}
+
+fn prepend(xs: List, value: u32) -> List {
+    Cons(value, ~xs)
+}
+
+let mut xs = Nil;
+xs = prepend(xs, 1);
+xs = prepend(xs, 2);
+xs = prepend(xs, 3);
+~~~
+
+However, this is not a very flexible definition of `prepend` as it requires
+ownership of a list to be passed in rather than just mutating it in-place.
+
+## References
+
+The obvious signature for a `List` equality comparison is the following:
+
+~~~{.ignore}
+fn eq(xs: List, ys: List) -> bool { ... }
+~~~
+
+However, this will cause both lists to be moved into the function. Ownership
+isn't required to compare the lists, so the function should take *references*
+(&T) instead.
+
+~~~{.ignore}
+fn eq(xs: &List, ys: &List) -> bool { ... }
+~~~
+
+A reference is a *non-owning* view of a value. A reference can be obtained with the `&` (address-of)
+operator. It can be dereferenced by using the `*` operator. In a pattern, such as `match` expression
+branches, the `ref` keyword can be used to bind to a variable name by-reference rather than
+by-value. A recursive definition of equality using references is as follows:
+
+~~~
+# enum List {
+#     Cons(u32, ~List),
+#     Nil
+# }
+fn eq(xs: &List, ys: &List) -> bool {
+    // Match on the next node in both lists.
+    match (xs, ys) {
+        // If we have reached the end of both lists, they are equal.
+        (&Nil, &Nil) => true,
+        // If the current element in both lists is equal, keep going.
+        (&Cons(x, ~ref next_xs), &Cons(y, ~ref next_ys)) if x == y => eq(next_xs, next_ys),
+        // If the current elements are not equal, the lists are not equal.
+        _ => false
+    }
+}
+
+let xs = Cons(5, ~Cons(10, ~Nil));
+let ys = Cons(5, ~Cons(10, ~Nil));
+assert!(eq(&xs, &ys));
+~~~
+
+Note that Rust doesn't guarantee [tail-call](http://en.wikipedia.org/wiki/Tail_call) optimization,
+but LLVM is able to handle a simple case like this with optimizations enabled.
+
+## Lists of other types
+
+Our `List` type is currently always a list of 32-bit unsigned integers. By
+leveraging Rust's support for generics, it can be extended to work for any
+element type.
+
+The `u32` in the previous definition can be substituted with a type parameter:
+
+~~~
+enum List<T> {
+    Cons(T, ~List<T>),
+    Nil
+}
+~~~
+
+The old `List` of `u32` is now available as `List<u32>`. The `prepend`
+definition has to be updated too:
+
+~~~
+# enum List<T> {
+#     Cons(T, ~List<T>),
+#     Nil
+# }
+fn prepend<T>(xs: List<T>, value: T) -> List<T> {
+    Cons(value, ~xs)
+}
+~~~
+
+Generic functions and types like this are equivalent to defining specialized
+versions for each set of type parameters.
+
+Using the generic `List<T>` works much like before, thanks to type inference:
+
+~~~
+# enum List<T> {
+#     Cons(T, ~List<T>),
+#     Nil
+# }
+# fn prepend<T>(xs: List<T>, value: T) -> List<T> {
+#     Cons(value, ~xs)
+# }
+let mut xs = Nil; // Unknown type! This is a `List<T>`, but `T` can be anything.
+xs = prepend(xs, 10); // The compiler infers the type of `xs` as `List<int>` from this.
+xs = prepend(xs, 15);
+xs = prepend(xs, 20);
+~~~
+
+The code sample above demonstrates type inference making most type annotations optional. It is
+equivalent to the following type-annotated code:
+
+~~~
+# enum List<T> {
+#     Cons(T, ~List<T>),
+#     Nil
+# }
+# fn prepend<T>(xs: List<T>, value: T) -> List<T> {
+#     Cons(value, ~xs)
+# }
+let mut xs: List<int> = Nil::<int>;
+xs = prepend::<int>(xs, 10);
+xs = prepend::<int>(xs, 15);
+xs = prepend::<int>(xs, 20);
+~~~
+
+In declarations, the language uses `Type<T, U, V>` to describe a list of type
+parameters, but expressions use `identifier::<T, U, V>`, to disambiguate the
+`<` operator.
+
+## Defining list equality with generics
+
+Generic functions are type-checked from the definition, so any necessary properties of the type must
+be specified up-front. Our previous definition of list equality relied on the element type having
+the `==` operator available, and took advantage of the lack of a destructor on `u32` to copy it
+without a move of ownership.
+
+We can add a *trait bound* on the `Eq` trait to require that the type implement the `==` operator.
+Two more `ref` annotations need to be added to avoid attempting to move out the element types:
+
+~~~
+# enum List<T> {
+#     Cons(T, ~List<T>),
+#     Nil
+# }
+fn eq<T: Eq>(xs: &List<T>, ys: &List<T>) -> bool {
+    // Match on the next node in both lists.
+    match (xs, ys) {
+        // If we have reached the end of both lists, they are equal.
+        (&Nil, &Nil) => true,
+        // If the current element in both lists is equal, keep going.
+        (&Cons(ref x, ~ref next_xs), &Cons(ref y, ~ref next_ys)) if x == y => eq(next_xs, next_ys),
+        // If the current elements are not equal, the lists are not equal.
+        _ => false
+    }
+}
+
+let xs = Cons('c', ~Cons('a', ~Cons('t', ~Nil)));
+let ys = Cons('c', ~Cons('a', ~Cons('t', ~Nil)));
+assert!(eq(&xs, &ys));
+~~~
+
+This would be a good opportunity to implement the `Eq` trait for our list type, making the `==` and
+`!=` operators available. We'll need to provide an `impl` for the `Eq` trait and a definition of the
+`eq` method. In a method, the `self` parameter refers to an instance of the type we're implementing
+on.
+
+~~~
+# enum List<T> {
+#     Cons(T, ~List<T>),
+#     Nil
+# }
+impl<T: Eq> Eq for List<T> {
+    fn eq(&self, ys: &List<T>) -> bool {
+        // Match on the next node in both lists.
+        match (self, ys) {
+            // If we have reached the end of both lists, they are equal.
+            (&Nil, &Nil) => true,
+            // If the current element in both lists is equal, keep going.
+            (&Cons(ref x, ~ref next_xs), &Cons(ref y, ~ref next_ys)) if x == y => next_xs == next_ys,
+            // If the current elements are not equal, the lists are not equal.
+            _ => false
+        }
+    }
+}
+
+let xs = Cons(5, ~Cons(10, ~Nil));
+let ys = Cons(5, ~Cons(10, ~Nil));
+assert!(xs.eq(&ys));
+assert!(xs == ys);
+assert!(!xs.ne(&ys));
+assert!(!(xs != ys));
+~~~
+
+# More on boxes
+
+The most common use case for owned boxes is creating recursive data structures
+like a binary search tree. Rust's trait-based generics system (covered later in
+the tutorial) is usually used for static dispatch, but also provides dynamic
+dispatch via boxing. Values of different types may have different sizes, but a
+box is able to *erase* the difference via the layer of indirection they
+provide.
+
+In uncommon cases, the indirection can provide a performance gain or memory
+reduction by making values smaller. However, unboxed values should almost
+always be preferred when they are usable.
+
+Note that returning large unboxed values via boxes is unnecessary. A large
+value is returned via a hidden output parameter, and the decision on where to
+place the return value should be left to the caller:
+
+~~~~
+fn foo() -> (u64, u64, u64, u64, u64, u64) {
+    (5, 5, 5, 5, 5, 5)
+}
+
+let x = ~foo(); // allocates a `~` box, and writes the integers directly to it
+~~~~
+
+Beyond the properties granted by the size, an owned box behaves as a regular
+value by inheriting the mutability and lifetime of the owner:
+
+~~~~
+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
+~~~~
+
+# References
+
+In contrast with
+owned boxes, where the holder of an owned box is the owner of the pointed-to
+memory, references never imply ownership - they are "borrowed".
+A reference 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`:
+
+~~~
+struct Point {
+    x: f64,
+    y: f64
+}
+~~~~
+
+We can use this simple definition to allocate points in many different
+ways. For example, in this code, each of these three local variables
+contains a point, but allocated in a different location:
+
+~~~
+# struct Point { x: f64, y: f64 }
+let on_the_stack : Point  =  Point { x: 3.0, y: 4.0 };
+let managed_box  : @Point = @Point { x: 5.0, y: 1.0 };
+let owned_box    : ~Point = ~Point { x: 7.0, y: 9.0 };
+~~~
+
+Suppose we want to write a procedure that computes the distance
+between any two points, no matter where they are stored. For example,
+we might like to compute the distance between `on_the_stack` and
+`managed_box`, or between `managed_box` and `owned_box`. One option is
+to define a function that takes two arguments of type point—that is,
+it takes the points by value. But this will cause the points to be
+copied when we call the function. For points, this is probably not so
+bad, but often copies are expensive. So we’d like to define a function
+that takes the points by pointer. We can use references to do this:
+
+~~~
+# struct Point { x: f64, y: f64 }
+# fn sqrt(f: f64) -> f64 { 0.0 }
+fn compute_distance(p1: &Point, p2: &Point) -> f64 {
+    let x_d = p1.x - p2.x;
+    let y_d = p1.y - p2.y;
+    sqrt(x_d * x_d + y_d * y_d)
+}
+~~~
+
+Now we can call `compute_distance()` in various ways:
+
+~~~
+# struct Point{ x: f64, y: f64 };
+# let on_the_stack : Point  =  Point { x: 3.0, y: 4.0 };
+# let managed_box  : @Point = @Point { x: 5.0, y: 1.0 };
+# let owned_box    : ~Point = ~Point { x: 7.0, y: 9.0 };
+# fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }
+compute_distance(&on_the_stack, managed_box);
+compute_distance(managed_box, owned_box);
+~~~
+
+Here the `&` operator is used to take the address of the variable
+`on_the_stack`; this is because `on_the_stack` has the type `Point`
+(that is, a struct value) and we have to take its address to get a
+reference. We also call this _borrowing_ the local variable
+`on_the_stack`, because we are creating an alias: that is, another
+route to the same data.
+
+In the case of the boxes `managed_box` and `owned_box`, however, no
+explicit action is necessary. The compiler will automatically convert
+a box like `@point` or `~point` to a reference like
+`&point`. This is another form of borrowing; in this case, the
+contents of the managed/owned box are being lent out.
+
+Whenever a value is borrowed, there are some limitations on what you
+can do with the original. For example, if the contents of a variable
+have been lent out, you cannot send that variable to another task, nor
+will you be permitted to take actions that might cause the borrowed
+value to be freed or to change its type. This rule should make
+intuitive sense: you must wait for a borrowed value to be returned
+(that is, for the reference to go out of scope) before you can
+make full use of it again.
+
+For a more in-depth explanation of references and lifetimes, read the
+[references and lifetimes guide][lifetimes].
+
+## Freezing
+
+Lending an immutable pointer to an object freezes it and prevents mutation.
+`Freeze` objects have freezing enforced statically at compile-time. An example
+of a non-`Freeze` type is [`RefCell<T>`][refcell].
+
+~~~~
+let mut x = 5;
+{
+    let y = &x; // `x` is now frozen, it cannot be modified
+}
+// `x` is now unfrozen again
+# x = 3;
+~~~~
+
+[refcell]: http://static.rust-lang.org/doc/master/std/cell/struct.RefCell.html
+
+# Dereferencing pointers
+
+Rust uses the unary star operator (`*`) to access the contents of a
+box or pointer, similarly to C.
+
+~~~
+let managed = @10;
+let owned = ~20;
+let borrowed = &30;
+
+let sum = *managed + *owned + *borrowed;
+~~~
+
+Dereferenced mutable pointers may appear on the left hand side of
+assignments. Such an assignment modifies the value that the pointer
+points to.
+
+~~~
+let managed = @10;
+let mut owned = ~20;
+
+let mut value = 30;
+let borrowed = &mut value;
+
+*owned = *borrowed + 100;
+*borrowed = *managed + 1000;
+~~~
+
+Pointers have high operator precedence, but lower precedence than the
+dot operator used for field and method access. This precedence order
+can sometimes make code awkward and parenthesis-filled.
+
+~~~
+# struct Point { x: f64, y: f64 }
+# enum Shape { Rectangle(Point, Point) }
+# impl Shape { fn area(&self) -> int { 0 } }
+let start = @Point { x: 10.0, y: 20.0 };
+let end = ~Point { x: (*start).x + 100.0, y: (*start).y + 100.0 };
+let rect = &Rectangle(*start, *end);
+let area = (*rect).area();
+~~~
+
+To combat this ugliness the dot operator applies _automatic pointer
+dereferencing_ to the receiver (the value on the left-hand side of the
+dot), so in most cases, explicitly dereferencing the receiver is not necessary.
+
+~~~
+# struct Point { x: f64, y: f64 }
+# enum Shape { Rectangle(Point, Point) }
+# impl Shape { fn area(&self) -> int { 0 } }
+let start = @Point { x: 10.0, y: 20.0 };
+let end = ~Point { x: start.x + 100.0, y: start.y + 100.0 };
+let rect = &Rectangle(*start, *end);
+let area = rect.area();
+~~~
+
+You can write an expression that dereferences any number of pointers
+automatically. For example, if you feel inclined, you could write
+something silly like
+
+~~~
+# struct Point { x: f64, y: f64 }
+let point = &@~Point { x: 10.0, y: 20.0 };
+println!("{:f}", point.x);
+~~~
+
+The indexing operator (`[]`) also auto-dereferences.
+
+# Vectors and strings
+
+A vector is a contiguous block of memory containing zero or more values of the
+same type. Rust also supports vector reference types, called slices, which are
+a view into a block of memory represented as a pointer and a length.
+
+Strings are represented as vectors of `u8`, with the guarantee of containing a
+valid UTF-8 sequence.
+
+Fixed-size vectors are an unboxed block of memory, with the element length as
+part of the type. A fixed-size vector owns the elements it contains, so the
+elements are mutable if the vector is mutable. Fixed-size strings do not exist.
+
+~~~
+// A fixed-size vector
+let numbers = [1, 2, 3];
+let more_numbers = numbers;
+
+// The type of a fixed-size vector is written as `[Type, ..length]`
+let five_zeroes: [int, ..5] = [0, ..5];
+~~~
+
+A unique vector is dynamically sized, and has a destructor to clean up
+allocated memory on the heap. A unique vector owns the elements it contains, so
+the elements are mutable if the vector is mutable.
+
+~~~
+// A dynamically sized vector (unique vector)
+let mut numbers = ~[1, 2, 3];
+numbers.push(4);
+numbers.push(5);
+
+// The type of a unique vector is written as `~[int]`
+let more_numbers: ~[int] = numbers;
+
+// The original `numbers` value can no longer be used, due to move semantics.
+
+let mut string = ~"fo";
+string.push_char('o');
+~~~
+
+Slices are similar to fixed-size vectors, but the length is not part of the
+type. They simply point into a block of memory and do not have ownership over
+the elements.
+
+~~~
+// A slice
+let xs = &[1, 2, 3];
+
+// Slices have their type written as `&[int]`
+let ys: &[int] = xs;
+
+// Other vector types coerce to slices
+let three = [1, 2, 3];
+let zs: &[int] = three;
+
+// An unadorned string literal is an immutable string slice
+let string = "foobar";
+
+// A string slice type is written as `&str`
+let view: &str = string.slice(0, 3);
+~~~
+
+Mutable slices also exist, just as there are mutable references. However, there
+are no mutable string slices. Strings are a multi-byte encoding (UTF-8) of
+Unicode code points, so they cannot be freely mutated without the ability to
+alter the length.
+
+~~~
+let mut xs = [1, 2, 3];
+let view = xs.mut_slice(0, 2);
+view[0] = 5;
+
+// The type of a mutable slice is written as `&mut [T]`
+let ys: &mut [int] = &mut [1, 2, 3];
+~~~
+
+Square brackets denote indexing into a vector:
+
+~~~~
+# enum Crayon { Almond, AntiqueBrass, Apricot,
+#               Aquamarine, Asparagus, AtomicTangerine,
+#               BananaMania, Beaver, Bittersweet };
+# fn draw_scene(c: Crayon) { }
+let crayons: [Crayon, ..3] = [BananaMania, Beaver, Bittersweet];
+match crayons[0] {
+    Bittersweet => draw_scene(crayons[0]),
+    _ => ()
+}
+~~~~
+
+A vector can be destructured using pattern matching:
+
+~~~~
+let numbers: &[int] = &[1, 2, 3];
+let score = match numbers {
+    [] => 0,
+    [a] => a * 10,
+    [a, b] => a * 6 + b * 4,
+    [a, b, c, ..rest] => a * 5 + b * 3 + c * 2 + rest.len() as int
+};
+~~~~
+
+Both vectors and strings support a number of useful [methods](#methods),
+defined in [`std::vec`] and [`std::str`].
+
+[`std::vec`]: std/vec/index.html
+[`std::str`]: std/str/index.html
+
+# Ownership escape hatches
+
+Ownership can cleanly describe tree-like data structures, and references provide non-owning pointers. However, more flexibility is often desired and Rust provides ways to escape from strict
+single parent ownership.
+
+The standard library provides the `std::rc::Rc` pointer type to express *shared ownership* over a
+reference counted box. As soon as all of the `Rc` pointers go out of scope, the box and the
+contained value are destroyed.
+
+~~~
+use std::rc::Rc;
+
+// A fixed-size array allocated in a reference-counted box
+let x = Rc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+let y = x.clone(); // a new owner
+let z = x; // this moves `x` into `z`, rather than creating a new owner
+
+assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+// the variable is mutable, but not the contents of the box
+let mut a = Rc::new([10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
+a = z;
+~~~
+
+A garbage collected pointer is provided via `std::gc::Gc`, with a task-local garbage collector
+having ownership of the box. It allows the creation of cycles, and the individual `Gc` pointers do
+not have a destructor.
+
+~~~
+use std::gc::Gc;
+
+// A fixed-size array allocated in a garbage-collected box
+let x = Gc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+let y = x; // does not perform a move, unlike with `Rc`
+let z = x;
+
+assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+~~~
+
+With shared ownership, mutability cannot be inherited so the boxes are always immutable. However,
+it's possible to use *dynamic* mutability via types like `std::cell::Cell` where freezing is handled
+via dynamic checks and can fail at runtime.
+
+The `Rc` and `Gc` types are not sendable, so they cannot be used to share memory between tasks. Safe
+immutable and mutable shared memory is provided by the `extra::arc` module.
+
+# Closures
+
+Named functions, like those we've seen so far, may not refer to local
+variables declared outside the function: they do not close over their
+environment (sometimes referred to as "capturing" variables in their
+environment). For example, you couldn't write the following:
+
+~~~~ {.ignore}
+let foo = 10;
+
+fn bar() -> int {
+   return foo; // `bar` cannot refer to `foo`
+}
+~~~~
+
+Rust also supports _closures_, functions that can access variables in
+the enclosing scope.
+
+~~~~
+fn call_closure_with_ten(b: |int|) { b(10); }
+
+let captured_var = 20;
+let closure = |arg| println!("captured_var={}, arg={}", captured_var, arg);
+
+call_closure_with_ten(closure);
+~~~~
+
+Closures begin with the argument list between vertical bars and are followed by
+a single expression. Remember that a block, `{ <expr1>; <expr2>; ... }`, is
+considered a single expression: it evaluates to the result of the last
+expression it contains if that expression is not followed by a semicolon,
+otherwise the block evaluates to `()`.
+
+The types of the arguments are generally omitted, as is the return type,
+because the compiler can almost always infer them. In the rare case where the
+compiler needs assistance, though, the arguments and return types may be
+annotated.
+
+~~~~
+let square = |x: int| -> uint { (x * x) as uint };
+~~~~
+
+There are several forms of closure, each with its own role. The most
+common, called a _stack closure_, has type `||` and can directly
+access local variables in the enclosing scope.
+
+~~~~
+let mut max = 0;
+[1, 2, 3].map(|x| if *x > max { max = *x });
+~~~~
+
+Stack closures are very efficient because their environment is
+allocated on the call stack and refers by pointer to captured
+locals. To ensure that stack closures never outlive the local
+variables to which they refer, stack closures are not
+first-class. That is, they can only be used in argument position; they
+cannot be stored in data structures or returned from
+functions. Despite these limitations, stack closures are used
+pervasively in Rust code.
+
+## Owned closures
+
+Owned closures, written `proc`,
+hold on to things that can safely be sent between
+processes. They copy the values they close over, much like managed
+closures, but they also own them: that is, no other code can access
+them. Owned closures are used in concurrent code, particularly
+for spawning [tasks][tasks].
+
+## Closure compatibility
+
+Rust closures have a convenient subtyping property: you can pass any kind of
+closure (as long as the arguments and return types match) to functions
+that expect a `||`. Thus, when writing a higher-order function that
+only calls its function argument, and does nothing else with it, you
+should almost always declare the type of that argument as `||`. That way,
+callers may pass any kind of closure.
+
+~~~~
+fn call_twice(f: ||) { f(); f(); }
+let closure = || { "I'm a closure, and it doesn't matter what type I am"; };
+fn function() { "I'm a normal function"; }
+call_twice(closure);
+call_twice(function);
+~~~~
+
+> ***Note:*** Both the syntax and the semantics will be changing
+> in small ways. At the moment they can be unsound in some
+> scenarios, particularly with non-copyable types.
+
+## Do syntax
+
+The `do` expression makes it easier to call functions that take procedures
+as arguments.
+
+Consider this function that takes a procedure:
+
+~~~~
+fn call_it(op: proc(v: int)) {
+    op(10)
+}
+~~~~
+
+As a caller, if we use a closure to provide the final operator
+argument, we can write it in a way that has a pleasant, block-like
+structure.
+
+~~~~
+# fn call_it(op: proc(v: int)) { }
+call_it(proc(n) {
+    println!("{}", n);
+});
+~~~~
+
+A practical example of this pattern is found when using the `spawn` function,
+which starts a new task.
+
+~~~~
+use std::task::spawn;
+spawn(proc() {
+    debug!("I'm a new task")
+});
+~~~~
+
+If you want to see the output of `debug!` statements, you will need to turn on
+`debug!` logging.  To enable `debug!` logging, set the RUST_LOG environment
+variable to the name of your crate, which, for a file named `foo.rs`, will be
+`foo` (e.g., with bash, `export RUST_LOG=foo`).
+
+# Methods
+
+Methods are like functions except that they always begin with a special argument,
+called `self`,
+which has the type of the method's receiver. The
+`self` argument is like `this` in C++ and many other languages.
+Methods are called with dot notation, as in `my_vec.len()`.
+
+_Implementations_, written with the `impl` keyword, can define
+methods on most Rust types, including structs and enums.
+As an example, let's define a `draw` method on our `Shape` enum.
+
+~~~
+# fn draw_circle(p: Point, f: f64) { }
+# fn draw_rectangle(p: Point, p: Point) { }
+struct Point {
+    x: f64,
+    y: f64
+}
+
+enum Shape {
+    Circle(Point, f64),
+    Rectangle(Point, Point)
+}
+
+impl Shape {
+    fn draw(&self) {
+        match *self {
+            Circle(p, f) => draw_circle(p, f),
+            Rectangle(p1, p2) => draw_rectangle(p1, p2)
+        }
+    }
+}
+
+let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
+s.draw();
+~~~
+
+This defines an _implementation_ for `Shape` containing a single
+method, `draw`. In most respects the `draw` method is defined
+like any other function, except for the name `self`.
+
+The type of `self` is the type on which the method is implemented,
+or a pointer thereof. As an argument it is written either `self`,
+`&self`, `@self`, or `~self`.
+A caller must in turn have a compatible pointer type to call the method.
+
+~~~
+# fn draw_circle(p: Point, f: f64) { }
+# fn draw_rectangle(p: Point, p: Point) { }
+# struct Point { x: f64, y: f64 }
+# enum Shape {
+#     Circle(Point, f64),
+#     Rectangle(Point, Point)
+# }
+impl Shape {
+    fn draw_reference(&self) { ... }
+    fn draw_managed(@self) { ... }
+    fn draw_owned(~self) { ... }
+    fn draw_value(self) { ... }
+}
+
+let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
+
+(@s).draw_managed();
+(~s).draw_owned();
+(&s).draw_reference();
+s.draw_value();
+~~~
+
+Methods typically take a reference self type,
+so the compiler will go to great lengths to convert a callee
+to a reference.
+
+~~~
+# fn draw_circle(p: Point, f: f64) { }
+# fn draw_rectangle(p: Point, p: Point) { }
+# struct Point { x: f64, y: f64 }
+# enum Shape {
+#     Circle(Point, f64),
+#     Rectangle(Point, Point)
+# }
+# impl Shape {
+#    fn draw_reference(&self) { ... }
+#    fn draw_managed(@self) { ... }
+#    fn draw_owned(~self) { ... }
+#    fn draw_value(self) { ... }
+# }
+# let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
+// As with typical function arguments, managed and owned pointers
+// are automatically converted to references
+
+(@s).draw_reference();
+(~s).draw_reference();
+
+// Unlike typical function arguments, the self value will
+// automatically be referenced ...
+s.draw_reference();
+
+// ... and dereferenced
+(& &s).draw_reference();
+
+// ... and dereferenced and borrowed
+(&@~s).draw_reference();
+~~~
+
+Implementations may also define standalone (sometimes called "static")
+methods. The absence of a `self` parameter distinguishes such methods.
+These methods are the preferred way to define constructor functions.
+
+~~~~ {.ignore}
+impl Circle {
+    fn area(&self) -> f64 { ... }
+    fn new(area: f64) -> Circle { ... }
+}
+~~~~
+
+To call such a method, just prefix it with the type name and a double colon:
+
+~~~~
+use std::f64::consts::PI;
+struct Circle { radius: f64 }
+impl Circle {
+    fn new(area: f64) -> Circle { Circle { radius: (area / PI).sqrt() } }
+}
+let c = Circle::new(42.5);
+~~~~
+
+# Generics
+
+Throughout this tutorial, we've been defining functions that act only
+on specific data types. With type parameters we can also define
+functions whose arguments have generic types, and which can be invoked
+with a variety of types. Consider a generic `map` function, which
+takes a function `function` and a vector `vector` and returns a new
+vector consisting of the result of applying `function` to each element
+of `vector`:
+
+~~~~
+fn map<T, U>(vector: &[T], function: |v: &T| -> U) -> ~[U] {
+    let mut accumulator = ~[];
+    for element in vector.iter() {
+        accumulator.push(function(element));
+    }
+    return accumulator;
+}
+~~~~
+
+When defined with type parameters, as denoted by `<T, U>`, this
+function can be applied to any type of vector, as long as the type of
+`function`'s argument and the type of the vector's contents agree with
+each other.
+
+Inside a generic function, the names of the type parameters
+(capitalized by convention) stand for opaque types. All you can do
+with instances of these types is pass them around: you can't apply any
+operations to them or pattern-match on them. Note that instances of
+generic types are often passed by pointer. For example, the parameter
+`function()` is supplied with a pointer to a value of type `T` and not
+a value of type `T` itself. This ensures that the function works with
+the broadest set of types possible, since some types are expensive or
+illegal to copy and pass by value.
+
+Generic `type`, `struct`, and `enum` declarations follow the same pattern:
+
+~~~~
+use std::hashmap::HashMap;
+type Set<T> = HashMap<T, ()>;
+
+struct Stack<T> {
+    elements: ~[T]
+}
+
+enum Option<T> {
+    Some(T),
+    None
+}
+~~~~
+
+These declarations can be instantiated to valid types like `Set<int>`,
+`Stack<int>`, and `Option<int>`.
+
+The last type in that example, `Option`, appears frequently in Rust code.
+Because Rust does not have null pointers (except in unsafe code), we need
+another way to write a function whose result isn't defined on every possible
+combination of arguments of the appropriate types. The usual way is to write
+a function that returns `Option<T>` instead of `T`.
+
+~~~~
+# struct Point { x: f64, y: f64 }
+# enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
+fn radius(shape: Shape) -> Option<f64> {
+    match shape {
+        Circle(_, radius) => Some(radius),
+        Rectangle(..)      => None
+    }
+}
+~~~~
+
+The Rust compiler compiles generic functions very efficiently by
+*monomorphizing* them. *Monomorphization* is a fancy name for a simple
+idea: generate a separate copy of each generic function at each call site,
+a copy that is specialized to the argument
+types and can thus be optimized specifically for them. In this
+respect, Rust's generics have similar performance characteristics to
+C++ templates.
+
+## Traits
+
+Within a generic function -- that is, a function parameterized by a
+type parameter, say, `T` -- the operations we can do on arguments of
+type `T` are quite limited.  After all, since we don't know what type
+`T` will be instantiated with, we can't safely modify or query values
+of type `T`.  This is where _traits_ come into play. Traits are Rust's
+most powerful tool for writing polymorphic code. Java developers will
+see them as similar to Java interfaces, and Haskellers will notice
+their similarities to type classes. Rust's traits give us a way to
+express *bounded polymorphism*: by limiting the set of possible types
+that a type parameter could refer to, they expand the number of
+operations we can safely perform on arguments of that type.
+
+As motivation, let us consider copying of values in Rust.  The `clone`
+method is not defined for values of every type.  One reason is
+user-defined destructors: copying a value of a type that has a
+destructor could result in the destructor running multiple times.
+Therefore, values of types that have destructors cannot be copied
+unless we explicitly implement `clone` for them.
+
+This complicates handling of generic functions.
+If we have a function with a type parameter `T`,
+can we copy values of type `T` inside that function?
+In Rust, we can't,
+and if we try to run the following code the compiler will complain.
+
+~~~~ {.ignore}
+// This does not compile
+fn head_bad<T>(v: &[T]) -> T {
+    v[0] // error: copying a non-copyable value
+}
+~~~~
+
+However, we can tell the compiler
+that the `head` function is only for copyable types.
+In Rust, copyable types are those that _implement the `Clone` trait_.
+We can then explicitly create a second copy of the value we are returning
+by calling the `clone` method:
+
+~~~~
+// This does
+fn head<T: Clone>(v: &[T]) -> T {
+    v[0].clone()
+}
+~~~~
+
+The bounded type parameter `T: Clone` says that `head`
+can be called on an argument of type `&[T]` for any `T`,
+so long as there is an implementation of the
+`Clone` trait for `T`.
+When instantiating a generic function,
+we can only instantiate it with types
+that implement the correct trait,
+so we could not apply `head` to a vector whose elements are of some type
+that does not implement `Clone`.
+
+While most traits can be defined and implemented by user code,
+three traits are automatically derived and implemented
+for all applicable types by the compiler,
+and may not be overridden:
+
+* `Send` - Sendable types.
+Types are sendable
+unless they contain managed boxes, managed closures, or references.
+
+* `Freeze` - Constant (immutable) types.
+These are types that do not contain anything intrinsically mutable.
+Intrinsically mutable values include `Cell` in the standard library.
+
+* `'static` - Non-borrowed types.
+These are types that do not contain any data whose lifetime is bound to
+a particular stack frame. These are types that do not contain any
+references, or types where the only contained references
+have the `'static` lifetime.
+
+> ***Note:*** These two traits were referred to as 'kinds' in earlier
+> iterations of the language, and often still are.
+
+Additionally, the `Drop` trait is used to define destructors. This
+trait provides one method called `drop`, which is automatically
+called when a value of the type that implements this trait is
+destroyed, either because the value went out of scope or because the
+garbage collector reclaimed it.
+
+~~~
+struct TimeBomb {
+    explosivity: uint
+}
+
+impl Drop for TimeBomb {
+    fn drop(&mut self) {
+        for _ in range(0, self.explosivity) {
+            println!("blam!");
+        }
+    }
+}
+~~~
+
+It is illegal to call `drop` directly. Only code inserted by the compiler
+may call it.
+
+## Declaring and implementing traits
+
+At its simplest, a trait is a set of zero or more _method signatures_.
+For example, we could declare the trait
+`Printable` for things that can be printed to the console,
+with a single method signature:
+
+~~~~
+trait Printable {
+    fn print(&self);
+}
+~~~~
+
+We say that the `Printable` trait _provides_ a `print` method with the
+given signature.  This means that we can call `print` on an argument
+of any type that implements the `Printable` trait.
+
+Rust's built-in `Send` and `Freeze` types are examples of traits that
+don't provide any methods.
+
+Traits may be implemented for specific types with [impls]. An impl for
+a particular trait gives an implementation of the methods that
+trait provides.  For instance, the following impls of
+`Printable` for `int` and `~str` give implementations of the `print`
+method.
+
+[impls]: #methods
+
+~~~~
+# trait Printable { fn print(&self); }
+impl Printable for int {
+    fn print(&self) { println!("{:?}", *self) }
+}
+
+impl Printable for ~str {
+    fn print(&self) { println!("{}", *self) }
+}
+
+# 1.print();
+# (~"foo").print();
+~~~~
+
+Methods defined in an impl for a trait may be called just like
+any other method, using dot notation, as in `1.print()`.
+
+## Default method implementations in trait definitions
+
+Sometimes, a method that a trait provides will have the same
+implementation for most or all of the types that implement that trait.
+For instance, suppose that we wanted `bool`s and `f32`s to be
+printable, and that we wanted the implementation of `print` for those
+types to be exactly as it is for `int`, above:
+
+~~~~
+# trait Printable { fn print(&self); }
+impl Printable for f32 {
+    fn print(&self) { println!("{:?}", *self) }
+}
+
+impl Printable for bool {
+    fn print(&self) { println!("{:?}", *self) }
+}
+
+# true.print();
+# 3.14159.print();
+~~~~
+
+This works fine, but we've now repeated the same definition of `print`
+in three places.  Instead of doing that, we can simply include the
+definition of `print` right in the trait definition, instead of just
+giving its signature.  That is, we can write the following:
+
+~~~~
+trait Printable {
+	// Default method implementation
+    fn print(&self) { println!("{:?}", *self) }
+}
+
+impl Printable for int {}
+
+impl Printable for ~str {
+    fn print(&self) { println!("{}", *self) }
+}
+
+impl Printable for bool {}
+
+impl Printable for f32 {}
+
+# 1.print();
+# (~"foo").print();
+# true.print();
+# 3.14159.print();
+~~~~
+
+Here, the impls of `Printable` for `int`, `bool`, and `f32` don't
+need to provide an implementation of `print`, because in the absence
+of a specific implementation, Rust just uses the _default method_
+provided in the trait definition.  Depending on the trait, default
+methods can save a great deal of boilerplate code from having to be
+written in impls.  Of course, individual impls can still override the
+default method for `print`, as is being done above in the impl for
+`~str`.
+
+## Type-parameterized traits
+
+Traits may be parameterized by type variables.  For example, a trait
+for generalized sequence types might look like the following:
+
+~~~~
+trait Seq<T> {
+    fn length(&self) -> uint;
+}
+
+impl<T> Seq<T> for ~[T] {
+    fn length(&self) -> uint { self.len() }
+}
+~~~~
+
+The implementation has to explicitly declare the type parameter that
+it binds, `T`, before using it to specify its trait type. Rust
+requires this declaration because the `impl` could also, for example,
+specify an implementation of `Seq<int>`. The trait type (appearing
+between `impl` and `for`) *refers* to a type, rather than
+defining one.
+
+The type parameters bound by a trait are in scope in each of the
+method declarations. So, re-declaring the type parameter
+`T` as an explicit type parameter for `len`, in either the trait or
+the impl, would be a compile-time error.
+
+Within a trait definition, `Self` is a special type that you can think
+of as a type parameter. An implementation of the trait for any given
+type `T` replaces the `Self` type parameter with `T`. The following
+trait describes types that support an equality operation:
+
+~~~~
+// In a trait, `self` refers to the self argument.
+// `Self` refers to the type implementing the trait.
+trait Eq {
+    fn equals(&self, other: &Self) -> bool;
+}
+
+// In an impl, `self` refers just to the value of the receiver
+impl Eq for int {
+    fn equals(&self, other: &int) -> bool { *other == *self }
+}
+~~~~
+
+Notice that in the trait definition, `equals` takes a
+second parameter of type `Self`.
+In contrast, in the `impl`, `equals` takes a second parameter of
+type `int`, only using `self` as the name of the receiver.
+
+Just as in type implementations, traits can define standalone (static)
+methods.  These methods are called by prefixing the method name with the trait
+name and a double colon.  The compiler uses type inference to decide which
+implementation to use.
+
+~~~~
+use std::f64::consts::PI;
+trait Shape { fn new(area: f64) -> Self; }
+struct Circle { radius: f64 }
+struct Square { length: f64 }
+
+impl Shape for Circle {
+    fn new(area: f64) -> Circle { Circle { radius: (area / PI).sqrt() } }
+}
+impl Shape for Square {
+    fn new(area: f64) -> Square { Square { length: (area).sqrt() } }
+}
+
+let area = 42.5;
+let c: Circle = Shape::new(area);
+let s: Square = Shape::new(area);
+~~~~
+
+## Bounded type parameters and static method dispatch
+
+Traits give us a language for defining predicates on types, or
+abstract properties that types can have. We can use this language to
+define _bounds_ on type parameters, so that we can then operate on
+generic types.
+
+~~~~
+# trait Printable { fn print(&self); }
+fn print_all<T: Printable>(printable_things: ~[T]) {
+    for thing in printable_things.iter() {
+        thing.print();
+    }
+}
+~~~~
+
+Declaring `T` as conforming to the `Printable` trait (as we earlier
+did with `Clone`) makes it possible to call methods from that trait
+on values of type `T` inside the function. It will also cause a
+compile-time error when anyone tries to call `print_all` on an array
+whose element type does not have a `Printable` implementation.
+
+Type parameters can have multiple bounds by separating them with `+`,
+as in this version of `print_all` that copies elements.
+
+~~~
+# trait Printable { fn print(&self); }
+fn print_all<T: Printable + Clone>(printable_things: ~[T]) {
+    let mut i = 0;
+    while i < printable_things.len() {
+        let copy_of_thing = printable_things[i].clone();
+        copy_of_thing.print();
+        i += 1;
+    }
+}
+~~~
+
+Method calls to bounded type parameters are _statically dispatched_,
+imposing no more overhead than normal function invocation, so are
+the preferred way to use traits polymorphically.
+
+This usage of traits is similar to Haskell type classes.
+
+## Trait objects and dynamic method dispatch
+
+The above allows us to define functions that polymorphically act on
+values of a single unknown type that conforms to a given trait.
+However, consider this function:
+
+~~~~
+# type Circle = int; type Rectangle = int;
+# impl Drawable for int { fn draw(&self) {} }
+# fn new_circle() -> int { 1 }
+trait Drawable { fn draw(&self); }
+
+fn draw_all<T: Drawable>(shapes: ~[T]) {
+    for shape in shapes.iter() { shape.draw(); }
+}
+# let c: Circle = new_circle();
+# draw_all(~[c]);
+~~~~
+
+You can call that on an array of circles, or an array of rectangles
+(assuming those have suitable `Drawable` traits defined), but not on
+an array containing both circles and rectangles. When such behavior is
+needed, a trait name can alternately be used as a type, called
+an _object_.
+
+~~~~
+# trait Drawable { fn draw(&self); }
+fn draw_all(shapes: &[@Drawable]) {
+    for shape in shapes.iter() { shape.draw(); }
+}
+~~~~
+
+In this example, there is no type parameter. Instead, the `@Drawable`
+type denotes any managed box value that implements the `Drawable`
+trait. To construct such a value, you use the `as` operator to cast a
+value to an object:
+
+~~~~
+# type Circle = int; type Rectangle = bool;
+# trait Drawable { fn draw(&self); }
+# fn new_circle() -> Circle { 1 }
+# fn new_rectangle() -> Rectangle { true }
+# fn draw_all(shapes: &[@Drawable]) {}
+
+impl Drawable for Circle { fn draw(&self) { ... } }
+impl Drawable for Rectangle { fn draw(&self) { ... } }
+
+let c: @Circle = @new_circle();
+let r: @Rectangle = @new_rectangle();
+draw_all([c as @Drawable, r as @Drawable]);
+~~~~
+
+We omit the code for `new_circle` and `new_rectangle`; imagine that
+these just return `Circle`s and `Rectangle`s with a default size. Note
+that, like strings and vectors, objects have dynamic size and may
+only be referred to via one of the pointer types.
+Other pointer types work as well.
+Casts to traits may only be done with compatible pointers so,
+for example, an `@Circle` may not be cast to an `~Drawable`.
+
+~~~
+# type Circle = int; type Rectangle = int;
+# trait Drawable { fn draw(&self); }
+# impl Drawable for int { fn draw(&self) {} }
+# fn new_circle() -> int { 1 }
+# fn new_rectangle() -> int { 2 }
+// A managed object
+let boxy: @Drawable = @new_circle() as @Drawable;
+// An owned object
+let owny: ~Drawable = ~new_circle() as ~Drawable;
+// A borrowed object
+let stacky: &Drawable = &new_circle() as &Drawable;
+~~~
+
+Method calls to trait types are _dynamically dispatched_. Since the
+compiler doesn't know specifically which functions to call at compile
+time, it uses a lookup table (also known as a vtable or dictionary) to
+select the method to call at runtime.
+
+This usage of traits is similar to Java interfaces.
+
+By default, each of the three storage classes for traits enforce a
+particular set of built-in kinds that their contents must fulfill in
+order to be packaged up in a trait object of that storage class.
+
+* The contents of owned traits (`~Trait`) must fulfill the `Send` bound.
+* The contents of managed traits (`@Trait`) must fulfill the `'static` bound.
+* The contents of reference traits (`&Trait`) are not constrained by any bound.
+
+Consequently, the trait objects themselves automatically fulfill their
+respective kind bounds. However, this default behavior can be overridden by
+specifying a list of bounds on the trait type, for example, by writing `~Trait:`
+(which indicates that the contents of the owned trait need not fulfill any
+bounds), or by writing `~Trait:Send+Freeze`, which indicates that in addition
+to fulfilling `Send`, contents must also fulfill `Freeze`, and as a consequence,
+the trait itself fulfills `Freeze`.
+
+* `~Trait:Send` is equivalent to `~Trait`.
+* `@Trait:'static` is equivalent to `@Trait`.
+* `&Trait:` is equivalent to `&Trait`.
+
+Builtin kind bounds can also be specified on closure types in the same way (for
+example, by writing `fn:Freeze()`), and the default behaviours are the same as
+for traits of the same storage class.
+
+## Trait inheritance
+
+We can write a trait declaration that _inherits_ from other traits, called _supertraits_.
+Types that implement a trait must also implement its supertraits.
+For example,
+we can define a `Circle` trait that inherits from `Shape`.
+
+~~~~
+trait Shape { fn area(&self) -> f64; }
+trait Circle : Shape { fn radius(&self) -> f64; }
+~~~~
+
+Now, we can implement `Circle` on a type only if we also implement `Shape`.
+
+~~~~
+use std::f64::consts::PI;
+# trait Shape { fn area(&self) -> f64; }
+# trait Circle : Shape { fn radius(&self) -> f64; }
+# struct Point { x: f64, y: f64 }
+# fn square(x: f64) -> f64 { x * x }
+struct CircleStruct { center: Point, radius: f64 }
+impl Circle for CircleStruct {
+    fn radius(&self) -> f64 { (self.area() / PI).sqrt() }
+}
+impl Shape for CircleStruct {
+    fn area(&self) -> f64 { PI * square(self.radius) }
+}
+~~~~
+
+Notice that methods of `Circle` can call methods on `Shape`, as our
+`radius` implementation calls the `area` method.
+This is a silly way to compute the radius of a circle
+(since we could just return the `radius` field), but you get the idea.
+
+In type-parameterized functions,
+methods of the supertrait may be called on values of subtrait-bound type parameters.
+Refering to the previous example of `trait Circle : Shape`:
+
+~~~
+# trait Shape { fn area(&self) -> f64; }
+# trait Circle : Shape { fn radius(&self) -> f64; }
+fn radius_times_area<T: Circle>(c: T) -> f64 {
+    // `c` is both a Circle and a Shape
+    c.radius() * c.area()
+}
+~~~
+
+Likewise, supertrait methods may also be called on trait objects.
+
+~~~ {.ignore}
+use std::f64::consts::PI;
+# trait Shape { fn area(&self) -> f64; }
+# trait Circle : Shape { fn radius(&self) -> f64; }
+# struct Point { x: f64, y: f64 }
+# struct CircleStruct { center: Point, radius: f64 }
+# impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / PI).sqrt() } }
+# impl Shape for CircleStruct { fn area(&self) -> f64 { PI * square(self.radius) } }
+
+let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f};
+let mycircle: @Circle = concrete as @Circle;
+let nonsense = mycircle.radius() * mycircle.area();
+~~~
+
+> ***Note:*** Trait inheritance does not actually work with objects yet
+
+## Deriving implementations for traits
+
+A small number of traits in `std` and `extra` can have implementations
+that can be automatically derived. These instances are specified by
+placing the `deriving` attribute on a data type declaration. For
+example, the following will mean that `Circle` has an implementation
+for `Eq` and can be used with the equality operators, and that a value
+of type `ABC` can be randomly generated and converted to a string:
+
+~~~
+#[deriving(Eq)]
+struct Circle { radius: f64 }
+
+#[deriving(Rand, ToStr)]
+enum ABC { A, B, C }
+~~~
+
+The full list of derivable traits is `Eq`, `TotalEq`, `Ord`,
+`TotalOrd`, `Encodable` `Decodable`, `Clone`, `DeepClone`,
+`IterBytes`, `Rand`, `Default`, `Zero`, and `ToStr`.
+
+# Crates and the module system
+
+Rust's module system is very powerful, but because of that also somewhat complex.
+Nevertheless, this section will try to explain every important aspect of it.
+
+## Crates
+
+In order to speak about the module system, we first need to define the medium it exists in:
+
+Let's say you've written a program or a library, compiled it, and got the resulting binary.
+In Rust, the content of all source code that the compiler directly had to compile in order to end up with
+that binary is collectively called a 'crate'.
+
+For example, for a simple hello world program your crate only consists of this code:
+
+~~~~
+// `main.rs`
+fn main() {
+    println!("Hello world!");
+}
+~~~~
+
+A crate is also the unit of independent compilation in Rust: `rustc` always compiles a single crate at a time,
+from which it produces either a library or an executable.
+
+Note that merely using an already compiled library in your code does not make it part of your crate.
+
+## The module hierarchy
+
+For every crate, all the code in it is arranged in a hierarchy of modules starting with a single
+root module. That root module is called the 'crate root'.
+
+All modules in a crate below the crate root are declared with the `mod` keyword:
+
+~~~~
+// This is the crate root
+
+mod farm {
+    // This is the body of module 'farm' declared in the crate root.
+
+    fn chicken() { println!("cluck cluck"); }
+    fn cow() { println!("mooo"); }
+
+    mod barn {
+        // Body of module 'barn'
+
+        fn hay() { println!("..."); }
+    }
+}
+
+fn main() {
+    println!("Hello farm!");
+}
+~~~~
+
+As you can see, your module hierarchy is now three modules deep: There is the crate root, which contains your `main()`
+function, and the module `farm`. The module `farm` also contains two functions and a third module `barn`,
+which contains a function `hay`.
+
+(In case you already stumbled over `extern mod`: It isn't directly related to a bare `mod`, we'll get to it later. )
+
+## Paths and visibility
+
+We've now defined a nice module hierarchy. But how do we access the items in it from our `main` function?
+One way to do it is to simply fully qualifying it:
+
+~~~~ {.ignore}
+mod farm {
+    fn chicken() { println!("cluck cluck"); }
+    // ...
+}
+
+fn main() {
+    println!("Hello chicken!");
+
+    ::farm::chicken(); // Won't compile yet, see further down
+}
+~~~~
+
+The `::farm::chicken` construct is what we call a 'path'.
+
+Because it's starting with a `::`, it's also a 'global path', which qualifies
+an item by its full path in the module hierarchy relative to the crate root.
+
+If the path were to start with a regular identifier, like `farm::chicken`, it
+would be a 'local path' instead. We'll get to them later.
+
+Now, if you actually tried to compile this code example, you'll notice that you
+get a `function 'chicken' is private` error. That's because by default, items
+(`fn`, `struct`, `static`, `mod`, ...) are private.
+
+To make them visible outside their containing modules, you need to mark them
+_public_ with `pub`:
+
+~~~~
+mod farm {
+    pub fn chicken() { println!("cluck cluck"); }
+    pub fn cow() { println!("mooo"); }
+    // ...
+}
+
+fn main() {
+    println!("Hello chicken!");
+    ::farm::chicken(); // This compiles now
+}
+~~~~
+
+Visibility restrictions in Rust exist only at module boundaries. This
+is quite different from most object-oriented languages that also
+enforce restrictions on objects themselves. That's not to say that
+Rust doesn't support encapsulation: both struct fields and methods can
+be private. But this encapsulation is at the module level, not the
+struct level.
+
+For convenience, fields are _public_ by default, and can be made _private_ with
+the `priv` keyword:
+
+~~~
+mod farm {
+# pub type Chicken = int;
+# struct Human(int);
+# impl Human { pub fn rest(&self) { } }
+# pub fn make_me_a_farm() -> Farm { Farm { chickens: ~[], farmer: Human(0) } }
+    pub struct Farm {
+        priv chickens: ~[Chicken],
+        farmer: Human
+    }
+
+    impl Farm {
+        fn feed_chickens(&self) { ... }
+        pub fn add_chicken(&self, c: Chicken) { ... }
+    }
+
+    pub fn feed_animals(farm: &Farm) {
+        farm.feed_chickens();
+    }
+}
+
+fn main() {
+    let f = make_me_a_farm();
+    f.add_chicken(make_me_a_chicken());
+    farm::feed_animals(&f);
+    f.farmer.rest();
+
+    // This wouldn't compile because both are private:
+    // `f.feed_chickens();`
+    // `let chicken_counter = f.chickens.len();`
+}
+# fn make_me_a_farm() -> farm::Farm { farm::make_me_a_farm() }
+# fn make_me_a_chicken() -> farm::Chicken { 0 }
+~~~
+
+Exact details and specifications about visibility rules can be found in the Rust
+manual.
+
+## Files and modules
+
+One important aspect about Rusts module system is that source files are not important:
+You define a module hierarchy, populate it with all your definitions, define visibility,
+maybe put in a `fn main()`, and that's it: No need to think about source files.
+
+The only file that's relevant is the one that contains the body of your crate root,
+and it's only relevant because you have to pass that file to `rustc` to compile your crate.
+
+And in principle, that's all you need: You can write any Rust program as one giant source file that contains your
+crate root and everything below it in `mod ... { ... }` declarations.
+
+However, in practice you usually want to split you code up into multiple source files to make it more manageable.
+In order to do that, Rust allows you to move the body of any module into it's own source file, which works like this:
+
+If you declare a module without its body, like `mod foo;`, the compiler will look for the
+files `foo.rs` and `foo/mod.rs` inside some directory (usually the same as of the source file containing
+the `mod foo;`). If it finds either, it uses the content of that file as the body of the module.
+If it finds both, that's a compile error.
+
+So, if we want to move the content of `mod farm` into it's own file, it would look like this:
+
+~~~~ {.ignore}
+// `main.rs` - contains body of the crate root
+mod farm; // Compiler will look for `farm.rs` and `farm/mod.rs`
+
+fn main() {
+    println!("Hello farm!");
+    ::farm::cow();
+}
+~~~~
+
+~~~~
+// `farm.rs` - contains body of module 'farm' in the crate root
+pub fn chicken() { println!("cluck cluck"); }
+pub fn cow() { println!("mooo"); }
+
+pub mod barn {
+    pub fn hay() { println!("..."); }
+}
+# fn main() { }
+~~~~
+
+In short, `mod foo;` is just syntactic sugar for `mod foo { /* content of <...>/foo.rs or <...>/foo/mod.rs */ }`.
+
+This also means that having two or more identical `mod foo;` somewhere
+in your crate hierarchy is generally a bad idea,
+just like copy-and-paste-ing a module into two or more places is one.
+Both will result in duplicate and mutually incompatible definitions.
+
+The directory the compiler looks in for those two files is determined by starting with
+the same directory as the source file that contains the `mod foo;` declaration, and concatenating to that a
+path equivalent to the relative path of all nested `mod { ... }` declarations the `mod foo;`
+is contained in, if any.
+
+For example, given a file with this module body:
+
+~~~ {.ignore}
+// `src/main.rs`
+mod plants;
+mod animals {
+    mod fish;
+    mod mammals {
+        mod humans;
+    }
+}
+~~~
+
+The compiler would then try all these files:
+
+~~~ {.notrust}
+src/plants.rs
+src/plants/mod.rs
+
+src/animals/fish.rs
+src/animals/fish/mod.rs
+
+src/animals/mammals/humans.rs
+src/animals/mammals/humans/mod.rs
+~~~
+
+Keep in mind that identical module hierachies can still lead to different path lookups
+depending on how and where you've moved a module body to its own file.
+For example, if we move the `animals` module above into its own file...
+
+~~~ {.ignore}
+// `src/main.rs`
+mod plants;
+mod animals;
+~~~
+
+~~~ {.ignore}
+// `src/animals.rs` or `src/animals/mod.rs`
+mod fish;
+mod mammals {
+    mod humans;
+}
+~~~
+
+...then the source files of `mod animals`'s submodules can
+either be placed right next to that of its parents, or in a subdirectory if `animals` source file is:
+
+~~~ {.notrust}
+src/plants.rs
+src/plants/mod.rs
+
+src/animals.rs - if file sits next to that of parent module's:
+    src/fish.rs
+    src/fish/mod.rs
+
+    src/mammals/humans.rs
+    src/mammals/humans/mod.rs
+
+src/animals/mod.rs - if file is in it's own subdirectory:
+    src/animals/fish.rs
+    src/animals/fish/mod.rs
+
+    src/animals/mammals/humans.rs
+    src/animals/mammals/humans/mod.rs
+
+~~~
+
+These rules allow you to have both small modules that only need
+to consist of one source file each and can be conveniently placed right next to each other,
+and big complicated modules that group the source files of submodules in subdirectories.
+
+If you need to circumvent the defaults, you can also overwrite the path a `mod foo;` would take:
+
+~~~ {.ignore}
+#[path="../../area51/alien.rs"]
+mod classified;
+~~~
+
+## Importing names into the local scope
+
+Always referring to definitions in other modules with their global
+path gets old really fast, so Rust has a way to import
+them into the local scope of your module: `use`-statements.
+
+They work like this: At the beginning of any module body, `fn` body, or any other block
+you can write a list of `use`-statements, consisting of the keyword `use` and a __global path__ to an item
+without the `::` prefix. For example, this imports `cow` into the local scope:
+
+~~~
+use farm::cow;
+# mod farm { pub fn cow() { println!("I'm a hidden ninja cow!") } }
+# fn main() { cow() }
+~~~
+
+The path you give to `use` is per default global, meaning relative to the crate root,
+no matter how deep the module hierarchy is, or whether the module body it's written in
+is contained in its own file (remember: files are irrelevant).
+
+This is different to other languages, where you often only find a single import construct that combines the semantic
+of `mod foo;` and `use`-statements, and which tend to work relative to the source file or use an absolute file path
+- Rubys `require` or C/C++'s `#include` come to mind.
+
+However, it's also possible to import things relative to the module of the `use`-statement:
+Adding a `super::` in front of the path will start in the parent module,
+while adding a `self::` prefix will start in the current module:
+
+~~~
+# mod workaround {
+# pub fn some_parent_item(){ println!("...") }
+# mod foo {
+use super::some_parent_item;
+use self::some_child_module::some_item;
+# pub fn bar() { some_parent_item(); some_item() }
+# pub mod some_child_module { pub fn some_item() {} }
+# }
+# }
+~~~
+
+Again - relative to the module, not to the file.
+
+Imports are also shadowed by local definitions:
+For each name you mention in a module/block, `rust`
+will first look at all items that are defined locally,
+and only if that results in no match look at items you brought in
+scope with corresponding `use` statements.
+
+~~~ {.ignore}
+# // FIXME: Allow unused import in doc test
+use farm::cow;
+// ...
+# mod farm { pub fn cow() { println!("Hidden ninja cow is hidden.") } }
+fn cow() { println!("Mooo!") }
+
+fn main() {
+    cow() // resolves to the locally defined `cow()` function
+}
+~~~
+
+To make this behavior more obvious, the rule has been made that `use`-statement always need to be written
+before any declaration, like in the example above. This is a purely artificial rule introduced
+because people always assumed they shadowed each other based on order, despite the fact that all items in rust are
+mutually recursive, order independent definitions.
+
+One odd consequence of that rule is that `use` statements also go in front of any `mod` declaration,
+even if they refer to things inside them:
+
+~~~
+use farm::cow;
+mod farm {
+    pub fn cow() { println!("Moooooo?") }
+}
+
+fn main() { cow() }
+~~~
+
+This is what our `farm` example looks like with `use` statements:
+
+~~~~
+use farm::chicken;
+use farm::cow;
+use farm::barn;
+
+mod farm {
+    pub fn chicken() { println!("cluck cluck"); }
+    pub fn cow() { println!("mooo"); }
+
+    pub mod barn {
+        pub fn hay() { println!("..."); }
+    }
+}
+
+fn main() {
+    println!("Hello farm!");
+
+    // Can now refer to those names directly:
+    chicken();
+    cow();
+    barn::hay();
+}
+~~~~
+
+And here an example with multiple files:
+
+~~~{.ignore}
+// `a.rs` - crate root
+use b::foo;
+mod b;
+fn main() { foo(); }
+~~~
+
+~~~{.ignore}
+// `b.rs`
+use b::c::bar;
+pub mod c;
+pub fn foo() { bar(); }
+~~~
+
+~~~
+// `c.rs`
+pub fn bar() { println!("Baz!"); }
+# fn main() {}
+~~~
+
+There also exist two short forms for importing multiple names at once:
+
+1. Explicit mention multiple names as the last element of an `use` path:
+
+~~~
+use farm::{chicken, cow};
+# mod farm {
+#     pub fn cow() { println!("Did I already mention how hidden and ninja I am?") }
+#     pub fn chicken() { println!("I'm Bat-chicken, guardian of the hidden tutorial code.") }
+# }
+# fn main() { cow(); chicken() }
+~~~
+
+2. Import everything in a module with a wildcard:
+
+~~~
+use farm::*;
+# mod farm {
+#     pub fn cow() { println!("Bat-chicken? What a stupid name!") }
+#     pub fn chicken() { println!("Says the 'hidden ninja' cow.") }
+# }
+# fn main() { cow(); chicken() }
+~~~
+
+> ***Note:*** This feature of the compiler is currently gated behind the
+> `#[feature(globs)]` directive. More about these directives can be found in
+> the manual.
+
+However, that's not all. You can also rename an item while you're bringing it into scope:
+
+~~~
+use egg_layer = farm::chicken;
+# mod farm { pub fn chicken() { println!("Laying eggs is fun!")  } }
+// ...
+
+fn main() {
+    egg_layer();
+}
+~~~
+
+In general, `use` creates an local alias:
+An alternate path and a possibly different name to access the same item,
+without touching the original, and with both being interchangeable.
+
+## Reexporting names
+
+It is also possible to reexport items to be accessible under your module.
+
+For that, you write `pub use`:
+
+~~~
+mod farm {
+    pub use self::barn::hay;
+
+    pub fn chicken() { println!("cluck cluck"); }
+    pub fn cow() { println!("mooo"); }
+
+    mod barn {
+        pub fn hay() { println!("..."); }
+    }
+}
+
+fn main() {
+    farm::chicken();
+    farm::cow();
+    farm::hay();
+}
+~~~
+
+Just like in normal `use` statements, the exported names
+merely represent an alias to the same thing and can also be renamed.
+
+The above example also demonstrate what you can use `pub use` for:
+The nested `barn` module is private, but the `pub use` allows users
+of the module `farm` to access a function from `barn` without needing
+to know that `barn` exists.
+
+In other words, you can use them to decouple an public api from their internal implementation.
+
+## Using libraries
+
+So far we've only talked about how to define and structure your own crate.
+
+However, most code out there will want to use preexisting libraries,
+as there really is no reason to start from scratch each time you start a new project.
+
+In Rust terminology, we need a way to refer to other crates.
+
+For that, Rust offers you the `extern mod` declaration:
+
+~~~
+extern mod extra;
+// extra ships with Rust, you'll find more details further down.
+
+fn main() {
+    // The rational number '1/2':
+    let one_half = ::extra::rational::Ratio::new(1, 2);
+}
+~~~
+
+Despite its name, `extern mod` is a distinct construct from regular `mod` declarations:
+A statement of the form `extern mod foo;` will cause `rustc` to search for the crate `foo`,
+and if it finds a matching binary it lets you use it from inside your crate.
+
+The effect it has on your module hierarchy mirrors aspects of both `mod` and `use`:
+
+- Like `mod`, it causes `rustc` to actually emit code:
+  The linkage information the binary needs to use the library `foo`.
+
+- But like `use`, all `extern mod` statements that refer to the same library are interchangeable,
+  as each one really just presents an alias to an external module (the crate root of the library
+  you're linking against).
+
+Remember how `use`-statements have to go before local declarations because the latter shadows the former?
+Well, `extern mod` statements also have their own rules in that regard:
+Both `use` and local declarations can shadow them, so the rule is that `extern mod` has to go in front
+of both `use` and local declarations.
+
+Which can result in something like this:
+
+~~~
+extern mod extra;
+
+use farm::dog;
+use extra::rational::Ratio;
+
+mod farm {
+    pub fn dog() { println!("woof"); }
+}
+
+fn main() {
+    farm::dog();
+    let a_third = Ratio::new(1, 3);
+}
+~~~
+
+It's a bit weird, but it's the result of shadowing rules that have been set that way because
+they model most closely what people expect to shadow.
+
+## Package ids
+
+If you use `extern mod`, per default `rustc` will look for libraries in the library search path (which you can
+extend with the `-L` switch).
+
+## Crate metadata and settings
+
+For every crate you can define a number of metadata items, such as link name, version or author.
+You can also toggle settings that have crate-global consequences. Both mechanism
+work by providing attributes in the crate root.
+
+For example, Rust uniquely identifies crates by their link metadata, which includes
+the link name and the version. It also hashes the filename and the symbols in a binary
+based on the link metadata, allowing you to use two different versions of the same library in a crate
+without conflict.
+
+Therefore, if you plan to compile your crate as a library, you should annotate it with that information:
+
+~~~~
+// `lib.rs`
+
+# #[crate_type = "lib"];
+// Package ID
+#[crate_id = "farm#2.5"];
+
+// ...
+# fn farm() {}
+~~~~
+
+You can also specify package ID information in a `extern mod` statement.  For
+example, these `extern mod` statements would both accept and select the
+crate define above:
+
+~~~~ {.ignore}
+extern mod farm;
+extern mod farm = "farm#2.5";
+extern mod my_farm = "farm";
+~~~~
+
+Other crate settings and metadata include things like enabling/disabling certain errors or warnings,
+or setting the crate type (library or executable) explicitly:
+
+~~~~
+// `lib.rs`
+// ...
+
+// This crate is a library ("bin" is the default)
+#[crate_id = "farm#2.5"];
+#[crate_type = "lib"];
+
+// Turn on a warning
+#[warn(non_camel_case_types)]
+# fn farm() {}
+~~~~
+
+## A minimal example
+
+Now for something that you can actually compile yourself.
+
+We define two crates, and use one of them as a library in the other.
+
+~~~~
+// `world.rs`
+#[crate_id = "world#0.42"];
+# extern mod extra;
+pub fn explore() -> &'static str { "world" }
+# fn main() {}
+~~~~
+
+~~~~ {.ignore}
+// `main.rs`
+extern mod world;
+fn main() { println!("hello {}", world::explore()); }
+~~~~
+
+Now compile and run like this (adjust to your platform if necessary):
+
+~~~~ {.notrust}
+> rustc --lib world.rs  # compiles libworld-<HASH>-0.42.so
+> rustc main.rs -L .    # compiles main
+> ./main
+"hello world"
+~~~~
+
+Notice that the library produced contains the version in the file name
+as well as an inscrutable string of alphanumerics. As explained in the previous paragraph,
+these are both part of Rust's library versioning scheme. The alphanumerics are
+a hash representing the crates package ID.
+
+## The standard library and the prelude
+
+While reading the examples in this tutorial, you might have asked yourself where all
+those magical predefined items like `range` are coming from.
+
+The truth is, there's nothing magical about them: They are all defined normally
+in the `std` library, which is a crate that ships with Rust.
+
+The only magical thing that happens is that `rustc` automatically inserts this line into your crate root:
+
+~~~ {.ignore}
+extern mod std;
+~~~
+
+As well as this line into every module body:
+
+~~~ {.ignore}
+use std::prelude::*;
+~~~
+
+The role of the `prelude` module is to re-export common definitions from `std`.
+
+This allows you to use common types and functions like `Option<T>` or `range`
+without needing to import them. And if you need something from `std` that's not in the prelude,
+you just have to import it with an `use` statement.
+
+For example, it re-exports `range` which is defined in `std::iter::range`:
+
+~~~
+use iter_range = std::iter::range;
+
+fn main() {
+    // `range` is imported by default
+    for _ in range(0, 10) {}
+
+    // Doesn't hinder you from importing it under a different name yourself
+    for _ in iter_range(0, 10) {}
+
+    // Or from not using the automatic import.
+    for _ in ::std::iter::range(0, 10) {}
+}
+~~~
+
+Both auto-insertions can be disabled with an attribute if necessary:
+
+~~~
+// In the crate root:
+#[no_std];
+~~~
+
+~~~
+// In any module:
+#[no_implicit_prelude];
+~~~
+
+See the [API documentation][stddoc] for details.
+
+[stddoc]: std/index.html
+
+## The extra library
+
+Rust also ships with the [extra library], an accumulation of useful things,
+that are however not important enough to deserve a place in the standard
+library.  You can use them by linking to `extra` with an `extern mod extra;`.
+
+[extra library]: extra/index.html
+
+Right now `extra` contains those definitions directly, but in the future it will likely just
+re-export a bunch of 'officially blessed' crates that get managed with a
+package manager.
+
+# What next?
+
+Now that you know the essentials, check out any of the additional
+guides on individual topics.
+
+* [Pointers][pointers]
+* [Lifetimes][lifetimes]
+* [Tasks and communication][tasks]
+* [Macros][macros]
+* [The foreign function interface][ffi]
+* [Containers and iterators][container]
+* [Error-handling and Conditions][conditions]
+* [Documenting Rust code][rustdoc]
+* [Testing Rust code][testing]
+* [The Rust Runtime][runtime]
+
+There is further documentation on the [wiki], however those tend to be even more out of date as this document.
+
+[pointers]: guide-pointers.html
+[lifetimes]: guide-lifetimes.html
+[tasks]: guide-tasks.html
+[macros]: guide-macros.html
+[ffi]: guide-ffi.html
+[container]: guide-container.html
+[conditions]: guide-conditions.html
+[testing]: guide-testing.html
+[runtime]: guide-runtime.html
+[rustdoc]: rustdoc.html
+[wiki]: https://github.com/mozilla/rust/wiki/Docs
+
+[wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools