1 % The Rust Language Tutorial
3 <div style="border: 2px solid red; padding:5px;">
4 The tutorial is undergoing a complete re-write as <a href="guide.html">the Guide</a>.
5 Until it's ready, this tutorial is the right place to come to start learning
6 Rust. Please submit improvements as pull requests, but understand that
7 eventually it will be going away.
12 Rust is a programming language with a focus on type safety, memory
13 safety, concurrency and performance. It is intended for writing
14 large-scale, high-performance software that is free from several
15 classes of common errors. Rust has a sophisticated memory model that
16 encourages efficient data structures and safe concurrency patterns,
17 forbidding invalid memory accesses that would otherwise cause
18 segmentation faults. It is statically typed and compiled ahead of
21 As a multi-paradigm language, Rust supports writing code in
22 procedural, functional and object-oriented styles. Some of its
23 pleasant high-level features include:
25 * **Type inference.** Type annotations on local variable declarations
27 * **Safe task-based concurrency.** Rust's lightweight tasks do not share
28 memory, instead communicating through messages.
29 * **Higher-order functions.** Efficient and flexible closures provide
30 iteration and other control structures
31 * **Pattern matching and algebraic data types.** Pattern matching on
32 Rust's enumeration types (a more powerful version of C's enums,
33 similar to algebraic data types in functional languages) is a
34 compact and expressive way to encode program logic.
35 * **Polymorphism.** Rust has type-parametric functions and
36 types, type classes and OO-style interfaces.
40 This is an introductory tutorial for the Rust programming language. It
41 covers the fundamentals of the language, including the syntax, the
42 type system and memory model, generics, and modules. [Additional
43 tutorials](#what-next?) cover specific language features in greater
46 This tutorial assumes that the reader is already familiar with one or
47 more languages in the C family. Understanding of pointers and general
48 memory management techniques will help.
52 Throughout the tutorial, language keywords and identifiers defined in
53 example code are displayed in `code font`.
55 Code snippets are indented, and also shown in a monospaced font. Not
56 all snippets constitute whole programs. For brevity, we'll often show
57 fragments of programs that don't compile on their own. To try them
58 out, you might have to wrap them in `fn main() { ... }`, and make sure
59 they don't contain references to names that aren't actually defined.
61 > *Warning:* Rust is a language under ongoing development. Notes
62 > about potential changes to the language, implementation
63 > deficiencies, and other caveats appear offset in blockquotes.
67 There are two ways to install the Rust compiler: by building from source or
68 by downloading prebuilt binaries or installers for your platform. The
69 [install page][rust-install] contains links to download binaries for both
70 the nightly build and the most current Rust major release. For Windows and
71 OS X, the install page provides links to native installers.
73 > *Note:* Windows users should read the detailed
74 > [Getting started][wiki-start] notes on the wiki. Even when using
75 > the binary installer, the Windows build requires a MinGW installation,
76 > the precise details of which are not discussed here.
78 For Linux and OS X, the install page provides links to binary tarballs.
79 To install the Rust compiler from a binary tarball, download
80 the binary package, extract it, and execute the `install.sh` script in
81 the root directory of the package.
83 To build the Rust compiler from source, you will need to obtain the source through
84 [Git][git] or by downloading the source package from the [install page][rust-install].
86 Since the Rust compiler is written in Rust, it must be built by
87 a precompiled "snapshot" version of itself (made in an earlier state
88 of development). The source build automatically fetches these snapshots
89 from the Internet on our supported platforms.
91 Snapshot binaries are currently built and tested on several platforms:
93 * Windows (7, 8, Server 2008 R2), x86 only
94 * Linux (2.6.18 or later, various distributions), x86 and x86-64
95 * OSX 10.7 (Lion) or greater, x86 and x86-64
97 You may find that other platforms work, but these are our "tier 1"
98 supported build environments that are most likely to work.
100 [wiki-start]: https://github.com/rust-lang/rust/wiki/Note-getting-started-developing-Rust
101 [git]: https://github.com/rust-lang/rust.git
102 [rust-install]: http://www.rust-lang.org/install.html
104 To build from source you will also need the following prerequisite
107 * g++ 4.7 or clang++ 3.x
108 * python 2.6 or later (but not 3.x)
110 * gnu make 3.81 or later
113 If you've fulfilled those prerequisites, something along these lines
117 $ curl -O https://static.rust-lang.org/dist/rust-nightly.tar.gz
118 $ tar -xzf rust-nightly.tar.gz
121 $ make && make install
124 You may need to use `sudo make install` if you do not normally have
125 permission to modify the destination directory. The install locations
126 can be adjusted by passing a `--prefix` argument to
127 `configure`. Various other options are also supported: pass `--help`
128 for more information on them.
130 When complete, `make install` will place several programs into
131 `/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
132 API-documentation tool.
134 [tarball]: https://static.rust-lang.org/dist/rust-nightly.tar.gz
135 [win-exe]: https://static.rust-lang.org/dist/rust-nightly-install.exe
137 ## Compiling your first program
139 Rust program files are, by convention, given the extension `.rs`. Say
140 we have a file `hello.rs` containing this program:
147 > *Note:* An identifier followed by an exclamation point, like
148 > `println!`, is a macro invocation. Macros are explained
149 > [later](#syntax-extensions); for now just remember to include the
152 If the Rust compiler was installed successfully, running `rustc
153 hello.rs` will produce an executable called `hello` (or `hello.exe` on
154 Windows) which, upon running, will likely do exactly what you expect.
156 The Rust compiler tries to provide useful information when it encounters an
157 error. If you introduce an error into the program (for example, by changing
158 `println!` to some nonexistent macro), and then compile it, you'll see
159 an error message like this:
162 hello.rs:2:5: 2:24 error: macro undefined: 'print_with_unicorns'
163 hello.rs:2 print_with_unicorns!("hello?");
167 In its simplest form, a Rust program is a `.rs` file with some types
168 and functions defined in it. If it has a `main` function, it can be
169 compiled to an executable. Rust does not allow code that's not a
170 declaration to appear at the top level of the file: all statements must
171 live inside a function. Rust programs can also be compiled as
172 libraries, and included in other programs, even ones not written in Rust.
176 There are vim highlighting and indentation scripts in the Rust source
177 distribution under `src/etc/vim/`. There is an emacs mode under
178 `src/etc/emacs/` called `rust-mode`, but do read the instructions
179 included in that directory. In particular, if you are running emacs
180 24, then using emacs's internal package manager to install `rust-mode`
181 is the easiest way to keep it up to date. There is also a package for
182 Sublime Text 2, available both [standalone][sublime] and through
183 [Sublime Package Control][sublime-pkg], and support for Kate
184 under `src/etc/kate`.
186 A community-maintained list of available Rust tooling is [on the
187 wiki][wiki-packages].
189 There is ctags support via `src/etc/ctags.rust`, but many other
190 tools and editors are not yet supported. If you end up writing a Rust
191 mode for your favorite editor, let us know so that we can link to it.
193 [sublime]: http://github.com/jhasse/sublime-rust
194 [sublime-pkg]: http://wbond.net/sublime_packages/package_control
198 Assuming you've programmed in any C-family language (C++, Java,
199 JavaScript, C#, or PHP), Rust will feel familiar. Code is arranged
200 in blocks delineated by curly braces; there are control structures
201 for branching and looping, like the familiar `if` and `while`; function
202 calls are written `myfunc(arg1, arg2)`; operators are written the same
203 and mostly have the same precedence as in C; comments are again like C;
204 module names are separated with double-colon (`::`) as with C++.
206 The main surface difference to be aware of is that the condition at
207 the head of control structures like `if` and `while` does not require
208 parentheses, while their bodies *must* be wrapped in
209 braces. Single-statement, unbraced bodies are not allowed.
212 # mod universe { pub fn recalibrate() -> bool { true } }
216 // A tricky calculation
217 if universe::recalibrate() {
224 The `let` keyword introduces a local variable. Variables are immutable by
225 default. To introduce a local variable that you can re-assign later, use `let
233 println!("count is {}", count);
238 Although Rust can almost always infer the types of local variables, you can
239 specify a variable's type by following it in the `let` with a colon, then the
240 type name. Static items, on the other hand, always require a type annotation.
244 static MONSTER_FACTOR: f64 = 57.8;
245 let monster_size = MONSTER_FACTOR * 10.0;
246 let monster_size: int = 50;
249 Local variables may shadow earlier declarations, as in the previous example:
250 `monster_size` was first declared as a `f64`, and then a second
251 `monster_size` was declared as an `int`. If you were to actually compile this
252 example, though, the compiler would determine that the first `monster_size` is
253 unused and issue a warning (because this situation is likely to indicate a
254 programmer error). For occasions where unused variables are intentional, their
255 names may be prefixed with an underscore to silence the warning, like `let
256 _monster_size = 50;`.
258 Rust identifiers start with an alphabetic
259 character or an underscore, and after that may contain any sequence of
260 alphabetic characters, numbers, or underscores. The preferred style is to
261 write function, variable, and module names with lowercase letters, using
262 underscores where they help readability, while writing types in camel case.
265 let my_variable = 100i;
266 type MyType = int; // primitive types are _not_ camel case
269 ## Expressions and semicolons
271 Though it isn't apparent in all code, there is a fundamental
272 difference between Rust's syntax and predecessors like C.
273 Many constructs that are statements in C are expressions
274 in Rust, allowing code to be more concise. For example, you might
275 write a piece of code like this:
278 # let item = "salad";
282 } else if item == "muffin" {
289 But, in Rust, you don't have to repeat the name `price`:
292 # let item = "salad";
296 } else if item == "muffin" {
303 Both pieces of code are exactly equivalent: they assign a value to
304 `price` depending on the condition that holds. Note that there
305 are no semicolons in the blocks of the second snippet. This is
306 important: the lack of a semicolon after the last statement in a
307 braced block gives the whole block the value of that last expression.
309 Put another way, the semicolon in Rust *ignores the value of an expression*.
310 Thus, if the branches of the `if` had looked like `{ 4; }`, the above example
311 would simply assign `()` (unit or void) to `price`. But without the semicolon, each
312 branch has a different value, and `price` gets the value of the branch that
315 In short, everything that's not a declaration (declarations are `let` for
316 variables; `fn` for functions; and any top-level named items such as
317 [traits](#traits), [enum types](#enums), and static items) is an
318 expression, including function bodies.
321 fn is_four(x: int) -> bool {
322 // No need for a return statement. The result of the expression
323 // is used as the return value.
328 ## Primitive types and literals
330 There are general signed and unsigned integer types, `int` and `uint`,
331 as well as 8-, 16-, 32-, and 64-bit variants, `i8`, `u16`, etc.
332 Integers can be written in decimal (`144`), hexadecimal (`0x90`), octal (`0o70`), or
333 binary (`0b10010000`) base. Each integral type has a corresponding literal
334 suffix that can be used to indicate the type of a literal: `i` for `int`,
335 `u` for `uint`, `i8` for the `i8` type.
337 In the absence of an integer literal suffix, Rust will infer the
338 integer type based on type annotations and function signatures in the
339 surrounding program. In the absence of any type information at all,
340 Rust will report an error and request that the type be specified explicitly.
343 let a: int = 1; // `a` is an `int`
344 let b = 10i; // `b` is an `int`, due to the `i` suffix
345 let c = 100u; // `c` is a `uint`
346 let d = 1000i32; // `d` is an `i32`
349 There are two floating-point types: `f32`, and `f64`.
350 Floating-point numbers are written `0.0`, `1e6`, or `2.1e-4`.
351 Like integers, floating-point literals are inferred to the correct type.
352 Suffixes `f32`, and `f64` can be used to create literals of a specific type.
354 The keywords `true` and `false` produce literals of type `bool`.
356 Characters, the `char` type, are four-byte Unicode codepoints,
357 whose literals are written between single quotes, as in `'x'`.
358 Just like C, Rust understands a number of character escapes, using the backslash
359 character, such as `\n`, `\r`, and `\t`. String literals,
360 written between double quotes, allow the same escape sequences, and do no
361 other processing, unlike languages such as PHP or shell.
363 On the other hand, raw string literals do not process any escape sequences.
364 They are written as `r##"blah"##`, with a matching number of zero or more `#`
365 before the opening and after the closing quote, and can contain any sequence of
366 characters except their closing delimiter. More on strings
367 [later](#vectors-and-strings).
369 The unit type, written `()`, has a single value, also written `()`.
373 Rust's set of operators contains very few surprises. Arithmetic is done with
374 `*`, `/`, `%`, `+`, and `-` (multiply, quotient, remainder, add, and subtract). `-` is
375 also a unary prefix operator that negates numbers. As in C, the bitwise operators
376 `>>`, `<<`, `&`, `|`, and `^` are also supported.
378 Note that, if applied to an integer value, `!` flips all the bits (bitwise
381 The comparison operators are the traditional `==`, `!=`, `<`, `>`,
382 `<=`, and `>=`. Short-circuiting (lazy) boolean operators are written
383 `&&` (and) and `||` (or).
385 For compile-time type casting, Rust uses the binary `as` operator. It takes
386 an expression on the left side and a type on the right side and will, if a
387 meaningful conversion exists, convert the result of the expression to the
388 given type. Generally, `as` is only used with the primitive numeric types or
389 pointers, and is not overloadable. [`transmute`][transmute] can be used for
390 unsafe C-like casting of same-sized types.
394 let y: uint = x as uint;
398 [transmute]: http://doc.rust-lang.org/std/mem/fn.transmute.html
402 *Syntax extensions* are special forms that are not built into the language,
403 but are instead provided by the libraries. To make it clear to the reader when
404 a name refers to a syntax extension, the names of all syntax extensions end
405 with `!`. The standard library defines a few syntax extensions, the most
406 useful of which is [`format!`][fmt], a `sprintf`-like text formatter that you
407 will often see in examples, and its related family of macros: `print!`,
408 `println!`, and `write!`.
410 `format!` draws syntax from Python, but contains many of the same principles
411 that [printf][pf] has. Unlike printf, `format!` will give you a compile-time
412 error when the types of the directives don't match the types of the arguments.
415 // `{}` will print the "default format" of a type
416 println!("{} is {}", "the answer", 43i);
423 # let mystery_object = ();
424 // `{:?}` will conveniently print any type,
425 // but requires the `debug` crate to be linked in
426 println!("what is this thing: {:?}", mystery_object);
430 [pf]: http://en.cppreference.com/w/cpp/io/c/fprintf
431 [fmt]: http://doc.rust-lang.org/std/fmt/
433 You can define your own syntax extensions with the macro system. For details,
434 see the [macro tutorial][macros]. Note that macro definition is currently
435 considered an unstable feature.
441 We've seen `if` expressions a few times already. To recap, braces are
442 compulsory, an `if` can have an optional `else` clause, and multiple
443 `if`/`else` constructs can be chained together:
447 println!("that's odd");
451 println!("neither true nor false");
455 The condition given to an `if` construct *must* be of type `bool` (no
456 implicit conversion happens). If the arms are blocks that have a
457 value, this value must be of the same type for every arm in which
458 control reaches the end of the block:
461 fn signum(x: int) -> int {
470 Rust's `match` construct is a generalized, cleaned-up version of C's
471 `switch` construct. You provide it with a value and a number of
472 *arms*, each labeled with a pattern, and the code compares the value
473 against each pattern in order until one matches. The matching pattern
474 executes its corresponding arm.
479 0 => println!("zero"),
480 1 | 2 => println!("one or two"),
481 3..10 => println!("three to ten"),
482 _ => println!("something else")
486 Unlike in C, there is no "falling through" between arms: only one arm
487 executes, and it doesn't have to explicitly `break` out of the
488 construct when it is finished.
490 A `match` arm consists of a *pattern*, then a fat arrow `=>`, followed
491 by an *action* (expression). Each case is separated by commas. It is
492 often convenient to use a block expression for each case, in which case
493 the commas are optional as shown below. Literals are valid patterns and
494 match only their own value. A single arm may match multiple different
495 patterns by combining them with the pipe operator (`|`), so long as
496 every pattern binds the same set of variables (see "destructuring"
497 below). Ranges of numeric literal patterns can be expressed with two
498 dots, as in `M..N`. The underscore (`_`) is a wildcard pattern that
499 matches any single value. (`..`) is a different wildcard that can match
500 one or more fields in an `enum` variant.
503 # let my_number = 1i;
505 0 => { println!("zero") }
506 _ => { println!("something else") }
510 `match` constructs must be *exhaustive*: they must have an arm
511 covering every possible case. For example, the typechecker would
512 reject the previous example if the arm with the wildcard pattern was
515 A powerful application of pattern matching is *destructuring*:
516 matching in order to bind names to the contents of data types.
518 > *Note:* The following code makes use of tuples (`(f64, f64)`) which
519 > are explained in section 5.3. For now you can think of tuples as a list of
524 fn angle(vector: (f64, f64)) -> f64 {
525 let pi = f64::consts::PI;
527 (0.0, y) if y < 0.0 => 1.5 * pi,
528 (0.0, _) => 0.5 * pi,
529 (x, y) => (y / x).atan()
534 A variable name in a pattern matches any value, *and* binds that name
535 to the value of the matched value inside of the arm's action. Thus, `(0.0,
536 y)` matches any tuple whose first element is zero, and binds `y` to
537 the second element. `(x, y)` matches any two-element tuple, and binds both
538 elements to variables. `(0.0,_)` matches any tuple whose first element is zero
539 and does not bind anything to the second element.
541 A subpattern can also be bound to a variable, using `variable @ pattern`. For
547 a @ 0..20 => println!("{} years old", a),
548 _ => println!("older than 21")
552 Any `match` arm can have a guard clause (written `if EXPR`), called a
553 *pattern guard*, which is an expression of type `bool` that
554 determines, after the pattern is found to match, whether the arm is
555 taken or not. The variables bound by the pattern are in scope in this
556 guard expression. The first arm in the `angle` example shows an
557 example of a pattern guard.
559 You've already seen simple `let` bindings, but `let` is a little
560 fancier than you've been led to believe. It, too, supports destructuring
561 patterns. For example, you can write this to extract the fields from a
562 tuple, introducing two variables at once: `a` and `b`.
565 # fn get_tuple_of_two_ints() -> (int, int) { (1, 1) }
566 let (a, b) = get_tuple_of_two_ints();
569 Let bindings only work with _irrefutable_ patterns: that is, patterns that can
570 never fail to match. This excludes `let` from matching literals and most `enum`
571 variants as binding patterns, since most such patterns are not irrefutable. For
572 example, this will not compile:
580 `while` denotes a loop that iterates as long as its given condition
581 (which must have type `bool`) evaluates to `true`. Inside a loop, the
582 keyword `break` aborts the loop, and `continue` aborts the current
583 iteration and continues with the next.
586 let mut cake_amount = 8i;
587 while cake_amount > 0 {
592 `loop` denotes an infinite loop, and is the preferred way of writing `while true`:
598 if x % 5 == 0 { break; }
603 This code prints out a weird sequence of numbers and stops as soon as
604 it finds one that can be divided by five.
606 There is also a for-loop that can be used to iterate over a range of numbers:
609 for n in range(0u, 5) {
614 The snippet above prints integer numbers under 5 starting at 0.
616 More generally, a for loop works with anything implementing the `Iterator` trait.
617 Data structures can provide one or more methods that return iterators over
618 their contents. For example, strings support iteration over their contents in
628 The snippet above prints the characters in "Hello" vertically, adding a new
629 line after each character.
636 Rust struct types must be declared before they are used using the `struct`
637 syntax: `struct Name { field1: T1, field2: T2 [, ...] }`, where `T1`, `T2`,
638 ... denote types. To construct a struct, use the same syntax, but leave off
639 the `struct`: for example: `Point { x: 1.0, y: 2.0 }`.
641 Structs are quite similar to C structs and are even laid out the same way in
642 memory (so you can read from a Rust struct in C, and vice-versa). Use the dot
643 operator to access struct fields, as in `mypoint.x`.
652 Structs have "inherited mutability", which means that any field of a struct
653 may be mutable, if the struct is in a mutable slot.
655 With a value (say, `mypoint`) of such a type in a mutable location, you can do
656 `mypoint.y += 1.0`. But in an immutable location, such an assignment to a
657 struct without inherited mutability would result in a type error.
660 # struct Point { x: f64, y: f64 }
661 let mut mypoint = Point { x: 1.0, y: 1.0 };
662 let origin = Point { x: 0.0, y: 0.0 };
664 mypoint.y += 1.0; // `mypoint` is mutable, and its fields as well
665 origin.y += 1.0; // ERROR: assigning to immutable field
668 `match` patterns destructure structs. The basic syntax is
669 `Name { fieldname: pattern, ... }`:
672 # struct Point { x: f64, y: f64 }
673 # let mypoint = Point { x: 0.0, y: 0.0 };
675 Point { x: 0.0, y: yy } => println!("{}", yy),
676 Point { x: xx, y: yy } => println!("{} {}", xx, yy)
680 In general, the field names of a struct do not have to appear in the same
681 order they appear in the type. When you are not interested in all
682 the fields of a struct, a struct pattern may end with `, ..` (as in
683 `Name { field1, .. }`) to indicate that you're ignoring all other fields.
684 Additionally, struct fields have a shorthand matching form that simply
685 reuses the field name as the binding name.
688 # struct Point { x: f64, y: f64 }
689 # let mypoint = Point { x: 0.0, y: 0.0 };
691 Point { x, .. } => println!("{}", x)
697 Enums are datatypes with several alternate representations. A simple `enum`
698 defines one or more constants, all of which have the same type:
709 Each variant of this enum has a unique and constant integral discriminator
710 value. If no explicit discriminator is specified for a variant, the value
711 defaults to the value of the previous variant plus one. If the first variant
712 does not have a discriminator, it defaults to 0. For example, the value of
713 `North` is 0, `East` is 1, `South` is 2, and `West` is 3.
715 When an enum has simple integer discriminators, you can apply the `as` cast
716 operator to convert a variant to its discriminator value as an `int`:
719 # enum Direction { North, East, South, West }
720 println!( "North => {}", North as int );
723 It is possible to set the discriminator values to chosen constant values:
733 Variants do not have to be simple values; they may be more complex:
736 # struct Point { x: f64, y: f64 }
739 Rectangle(Point, Point)
743 A value of this type is either a `Circle`, in which case it contains a
744 `Point` struct and a f64, or a `Rectangle`, in which case it contains
745 two `Point` structs. The run-time representation of such a value
746 includes an identifier of the actual form that it holds, much like the
747 "tagged union" pattern in C, but with better static guarantees.
749 This declaration defines a type `Shape` that can refer to such shapes, and two
750 functions, `Circle` and `Rectangle`, which can be used to construct values of
753 To create a new `Circle`, write:
756 # struct Point { x: f64, y: f64 }
757 # enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
758 let circle = Circle(Point { x: 0.0, y: 0.0 }, 10.0);
761 All of these variant constructors may be used as patterns. The only way to
762 access the contents of an enum instance is the destructuring of a match. For
768 # struct Point {x: f64, y: f64}
769 # enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
770 fn area(sh: Shape) -> f64 {
772 Circle(_, size) => f64::consts::PI * size * size,
773 Rectangle(Point { x, y }, Point { x: x2, y: y2 }) => (x2 - x) * (y2 - y)
777 let rect = Rectangle(Point { x: 0.0, y: 0.0 }, Point { x: 2.0, y: 2.0 });
778 println!("area: {}", area(rect));
781 Use a lone `_` to ignore an individual field. Ignore all fields of a variant
782 like: `Circle(..)`. Nullary enum patterns are written without parentheses:
785 # struct Point { x: f64, y: f64 }
786 # enum Direction { North, East, South, West }
787 fn point_from_direction(dir: Direction) -> Point {
789 North => Point { x: 0.0, y: 1.0 },
790 East => Point { x: 1.0, y: 0.0 },
791 South => Point { x: 0.0, y: -1.0 },
792 West => Point { x: -1.0, y: 0.0 }
797 Enum variants may also be structs. For example:
800 #![feature(struct_variant)]
803 # struct Point { x: f64, y: f64 }
804 # fn square(x: f64) -> f64 { x * x }
806 Circle { center: Point, radius: f64 },
807 Rectangle { top_left: Point, bottom_right: Point }
809 fn area(sh: Shape) -> f64 {
811 Circle { radius: radius, .. } => f64::consts::PI * square(radius),
812 Rectangle { top_left: top_left, bottom_right: bottom_right } => {
813 (bottom_right.x - top_left.x) * (top_left.y - bottom_right.y)
819 let rect = Rectangle {
820 top_left: Point { x: 0.0, y: 0.0 },
821 bottom_right: Point { x: 2.0, y: -2.0 }
823 println!("area: {}", area(rect));
827 > *Note:* This feature of the compiler is currently gated behind the
828 > `#[feature(struct_variant)]` directive. More about these directives can be
829 > found in the manual.
833 Tuples in Rust behave exactly like structs, except that their fields do not
834 have names. Thus, you cannot access their fields with dot notation. Tuples
835 can have any arity (number of elements) except for 0 (though you may consider
836 unit, `()`, as the empty tuple if you like).
839 let mytup: (int, int, f64) = (10, 20, 30.0);
841 (a, b, c) => println!("{}", a + b + (c as int))
847 Rust also has _tuple structs_, which behave like both structs and tuples,
848 except that, unlike tuples, tuple structs have names (so `Foo(1, 2)` has a
849 different type from `Bar(1, 2)`), and tuple structs' _fields_ do not have
855 struct MyTup(int, int, f64);
856 let mytup: MyTup = MyTup(10, 20, 30.0);
858 MyTup(a, b, c) => println!("{}", a + b + (c as int))
862 <a name="newtype"></a>
864 There is a special case for tuple structs with a single field, which are
865 sometimes called "newtypes" (after Haskell's "newtype" feature). These are
866 used to define new types in such a way that the new name is not just a
867 synonym for an existing type but is rather its own distinct type.
873 Types like this can be useful to differentiate between data that have
874 the same underlying type but must be used in different ways.
878 struct Centimeters(int);
881 The above definitions allow for a simple way for programs to avoid
882 confusing numbers that correspond to different units. Their integer
883 values can be extracted with pattern matching:
886 # struct Inches(int);
887 let length_with_unit = Inches(10);
888 let Inches(integer_length) = length_with_unit;
889 println!("length is {} inches", integer_length);
894 We've already seen several function definitions. Like all other static
895 declarations, such as `type`, functions can be declared both at the
896 top level and inside other functions (or in modules, which we'll come
897 back to [later](#crates-and-the-module-system)). The `fn` keyword introduces a
898 function. A function has an argument list, which is a parenthesized
899 list of `name: type` pairs separated by commas. An arrow `->`
900 separates the argument list and the function's return type.
903 fn line(a: int, b: int, x: int) -> int {
908 The `return` keyword immediately returns from the body of a function. It
909 is optionally followed by an expression to return. A function can
910 also return a value by having its top-level block produce an
914 fn line(a: int, b: int, x: int) -> int {
919 It's better Rust style to write a return value this way instead of
920 writing an explicit `return`. The utility of `return` comes in when
921 returning early from a function. Functions that do not return a value
922 are said to return unit, `()`, and both the return type and the return
923 value may be omitted from the definition. The following two functions
927 fn do_nothing_the_hard_way() -> () { return (); }
929 fn do_nothing_the_easy_way() { }
932 Ending the function with a semicolon like so is equivalent to returning `()`.
935 fn line(a: int, b: int, x: int) -> int { a * x + b }
936 fn oops(a: int, b: int, x: int) -> () { a * x + b; }
938 assert!(8 == line(5, 3, 1));
939 assert!(() == oops(5, 3, 1));
942 As with `match` expressions and `let` bindings, function arguments support
943 pattern destructuring. Like `let`, argument patterns must be irrefutable,
944 as in this example that unpacks the first value from a tuple and returns it.
947 fn first((value, _): (int, f64)) -> int { value }
952 A *destructor* is a function responsible for cleaning up the resources used by
953 an object when it is no longer accessible. Destructors can be defined to handle
954 the release of resources like files, sockets and heap memory.
956 Objects are never accessible after their destructor has been called, so no
957 dynamic failures are possible from accessing freed resources. When a task
958 fails, destructors of all objects in the task are called.
960 The `box` operator performs memory allocation on the heap:
964 // an integer allocated on the heap
967 // the destructor frees the heap memory as soon as `y` goes out of scope
970 Rust includes syntax for heap memory allocation in the language since it's
971 commonly used, but the same semantics can be implemented by a type with a
976 Rust formalizes the concept of object ownership to delegate management of an
977 object's lifetime to either a variable or a task-local garbage collector. An
978 object's owner is responsible for managing the lifetime of the object by
979 calling the destructor, and the owner determines whether the object is mutable.
981 Ownership is recursive, so mutability is inherited recursively and a destructor
982 destroys the contained tree of owned objects. Variables are top-level owners
983 and destroy the contained object when they go out of scope.
986 // the struct owns the objects contained in the `x` and `y` fields
987 struct Foo { x: int, y: Box<int> }
990 // `a` is the owner of the struct, and thus the owner of the struct's fields
991 let a = Foo { x: 5, y: box 10 };
993 // when `a` goes out of scope, the destructor for the `Box<int>` in the struct's
996 // `b` is mutable, and the mutability is inherited by the objects it owns
997 let mut b = Foo { x: 5, y: box 10 };
1001 If an object doesn't contain any non-`Send` types, it consists of a single
1002 ownership tree and is itself given the `Send` trait which allows it to be sent
1003 between tasks. Custom destructors can only be implemented directly on types
1004 that are `Send`, but non-`Send` types can still *contain* types with custom
1005 destructors. Example of types which are not `Send` are [`Gc<T>`][gc] and
1006 [`Rc<T>`][rc], the shared-ownership types.
1008 > *Note:* See a [later chapter](#ownership-escape-hatches) for a discussion about
1009 > [`Gc<T>`][gc] and [`Rc<T>`][rc], and the [chapter about traits](#traits) for
1010 > a discussion about `Send`.
1012 [gc]: http://doc.rust-lang.org/std/gc/struct.Gc.html
1013 [rc]: http://doc.rust-lang.org/std/rc/struct.Rc.html
1015 # Implementing a linked list
1017 An `enum` is a natural fit for describing a linked list, because it can express
1018 a `List` type as being *either* the end of the list (`Nil`) or another node
1019 (`Cons`). The full definition of the `Cons` variant will require some thought.
1023 Cons(...), // an incomplete definition of the next element in a List
1024 Nil // the end of a List
1028 The obvious approach is to define `Cons` as containing an element in the list
1029 along with the next `List` node. However, this will generate a compiler error.
1032 // error: illegal recursive enum type; wrap the inner value in a box to make it
1035 Cons(u32, List), // an element (`u32`) and the next node in the list
1040 This error message is related to Rust's precise control over memory layout, and
1041 solving it will require introducing the concept of *boxing*.
1045 A value in Rust is stored directly inside the owner. If a `struct` contains
1046 four `u32` fields, it will be four times as large as a single `u32`.
1049 use std::mem::size_of; // bring `size_of` into the current scope, for convenience
1058 assert_eq!(size_of::<Foo>(), size_of::<u32>() * 4);
1067 assert_eq!(size_of::<Bar>(), size_of::<u32>() * 16);
1070 Our previous attempt at defining the `List` type included an `u32` and a `List`
1071 directly inside `Cons`, making it at least as big as the sum of both types. The
1072 type was invalid because the size was infinite!
1074 An *owned box* (`Box`, located in the `std::owned` module) uses a dynamic memory
1075 allocation to provide the invariant of always being the size of a pointer,
1076 regardless of the contained type. This can be leveraged to create a valid `List`
1082 Cons(u32, Box<List>),
1087 Defining a recursive data structure like this is the canonical example of an
1088 owned box. Much like an unboxed value, an owned box has a single owner and is
1089 therefore limited to expressing a tree-like data structure.
1091 Consider an instance of our `List` type:
1095 # Cons(u32, Box<List>),
1098 let list = Cons(1, box Cons(2, box Cons(3, box Nil)));
1101 It represents an owned tree of values, inheriting mutability down the tree and
1102 being destroyed along with the owner. Since the `list` variable above is
1103 immutable, the whole list is immutable. The memory allocation itself is the
1104 box, while the owner holds onto a pointer to it:
1107 List box List box List box List box
1108 +--------------+ +--------------+ +--------------+ +----------+
1109 list -> | Cons | 1 | | -> | Cons | 2 | | -> | Cons | 3 | | -> | Nil |
1110 +--------------+ +--------------+ +--------------+ +----------+
1113 > *Note:* the above diagram shows the logical contents of the enum. The actual
1114 > memory layout of the enum may vary. For example, for the `List` enum shown
1115 > above, Rust guarantees that there will be no enum tag field in the actual
1116 > structure. See the language reference for more details.
1118 An owned box is a common example of a type with a destructor. The allocated
1119 memory is cleaned up when the box is destroyed.
1123 Rust uses a shallow copy for parameter passing, assignment and returning from
1124 functions. Passing around the `List` will copy only as deep as the pointer to
1125 the box rather than doing an implicit heap allocation.
1129 # Cons(u32, Box<List>),
1132 let xs = Cons(1, box Cons(2, box Cons(3, box Nil)));
1133 let ys = xs; // copies `Cons(u32, pointer)` shallowly
1136 > *Note:* Names like `xs` and `ys` are a naming
1137 > convention for collection-like data structures
1138 > (like our `List`). These collections are given
1139 > names appended with 's' to signify plurality,
1140 > i.e. that the data structure stores multiple
1141 > elements. For example, `xs` in this case can
1142 > be read as "a list of ex-es", where "x" here
1143 > are elements of type `u32`.
1146 Rust will consider a shallow copy of a type with a destructor like `List` to
1147 *move ownership* of the value. After a value has been moved, the source
1148 location cannot be used unless it is reinitialized.
1152 # Cons(u32, Box<List>),
1158 // attempting to use `xs` will result in an error here
1162 // `xs` can be used again
1165 A destructor call will only occur for a variable that has not been moved from,
1166 as it is only called a single time.
1169 Avoiding a move can be done with the library-defined `clone` method:
1173 let y = x.clone(); // `y` is a newly allocated box
1174 let z = x; // no new memory allocated, `x` can no longer be used
1177 The `clone` method is provided by the `Clone` trait, and can be derived for
1178 our `List` type. Traits will be explained in detail [later](#traits).
1183 Cons(u32, Box<List>),
1187 let x = Cons(5, box Nil);
1190 // `x` can still be used!
1194 // and now, it can no longer be used since it has been moved
1197 The mutability of a value may be changed by moving it to a new owner:
1201 let mut s = r; // box becomes mutable
1203 let t = s; // box becomes immutable
1206 A simple way to define a function prepending to the `List` type is to take
1211 Cons(u32, Box<List>),
1215 fn prepend(xs: List, value: u32) -> List {
1220 xs = prepend(xs, 1);
1221 xs = prepend(xs, 2);
1222 xs = prepend(xs, 3);
1225 However, this is not a very flexible definition of `prepend` as it requires
1226 ownership of a list to be passed in rather than just mutating it in-place.
1230 The obvious signature for a `List` equality comparison is the following:
1233 fn eq(xs: List, ys: List) -> bool { /* ... */ }
1236 However, this will cause both lists to be moved into the function. Ownership
1237 isn't required to compare the lists, so the function should take *references*
1241 fn eq(xs: &List, ys: &List) -> bool { /* ... */ }
1244 A reference is a *non-owning* view of a value. A reference can be obtained with the `&` (address-of)
1245 operator. It can be dereferenced by using the `*` operator. In a pattern, such as `match` expression
1246 branches, the `ref` keyword can be used to bind to a variable name by-reference rather than
1247 by-value. A recursive definition of equality using references is as follows:
1251 # Cons(u32, Box<List>),
1254 fn eq(xs: &List, ys: &List) -> bool {
1255 // Match on the next node in both lists.
1257 // If we have reached the end of both lists, they are equal.
1258 (&Nil, &Nil) => true,
1259 // If the current elements of both lists are equal, keep going.
1260 (&Cons(x, box ref next_xs), &Cons(y, box ref next_ys))
1261 if x == y => eq(next_xs, next_ys),
1262 // If the current elements are not equal, the lists are not equal.
1267 let xs = Cons(5, box Cons(10, box Nil));
1268 let ys = Cons(5, box Cons(10, box Nil));
1269 assert!(eq(&xs, &ys));
1272 > *Note:* Rust doesn't guarantee [tail-call](http://en.wikipedia.org/wiki/Tail_call) optimization,
1273 > but LLVM is able to handle a simple case like this with optimizations enabled.
1275 ## Lists of other types
1277 Our `List` type is currently always a list of 32-bit unsigned integers. By
1278 leveraging Rust's support for generics, it can be extended to work for any
1281 The `u32` in the previous definition can be substituted with a type parameter:
1283 > *Note:* The following code introduces generics, which are explained in a
1284 > [dedicated section](#generics).
1288 Cons(T, Box<List<T>>),
1293 The old `List` of `u32` is now available as `List<u32>`. The `prepend`
1294 definition has to be updated too:
1298 # Cons(T, Box<List<T>>),
1301 fn prepend<T>(xs: List<T>, value: T) -> List<T> {
1306 Generic functions and types like this are equivalent to defining specialized
1307 versions for each set of type parameters.
1309 Using the generic `List<T>` works much like before, thanks to type inference:
1313 # Cons(T, Box<List<T>>),
1316 # fn prepend<T>(xs: List<T>, value: T) -> List<T> {
1317 # Cons(value, box xs)
1319 let mut xs = Nil; // Unknown type! This is a `List<T>`, but `T` can be anything.
1320 xs = prepend(xs, 10i); // Here the compiler infers `xs`'s type as `List<int>`.
1321 xs = prepend(xs, 15i);
1322 xs = prepend(xs, 20i);
1325 The code sample above demonstrates type inference making most type annotations optional. It is
1326 equivalent to the following type-annotated code:
1330 # Cons(T, Box<List<T>>),
1333 # fn prepend<T>(xs: List<T>, value: T) -> List<T> {
1334 # Cons(value, box xs)
1336 let mut xs: List<int> = Nil::<int>;
1337 xs = prepend::<int>(xs, 10);
1338 xs = prepend::<int>(xs, 15);
1339 xs = prepend::<int>(xs, 20);
1342 In declarations, the language uses `Type<T, U, V>` to describe a list of type
1343 parameters, but expressions use `identifier::<T, U, V>`, to disambiguate the
1346 ## Defining list equality with generics
1348 Generic functions are type-checked from the definition, so any necessary properties of the type must
1349 be specified up-front. Our previous definition of list equality relied on the element type having
1350 the `==` operator available, and took advantage of the lack of a destructor on `u32` to copy it
1351 without a move of ownership.
1353 We can add a *trait bound* on the `PartialEq` trait to require that the type implement the `==` operator.
1354 Two more `ref` annotations need to be added to avoid attempting to move out the element types:
1358 # Cons(T, Box<List<T>>),
1361 fn eq<T: PartialEq>(xs: &List<T>, ys: &List<T>) -> bool {
1362 // Match on the next node in both lists.
1364 // If we have reached the end of both lists, they are equal.
1365 (&Nil, &Nil) => true,
1366 // If the current elements of both lists are equal, keep going.
1367 (&Cons(ref x, box ref next_xs), &Cons(ref y, box ref next_ys))
1368 if x == y => eq(next_xs, next_ys),
1369 // If the current elements are not equal, the lists are not equal.
1374 let xs = Cons('c', box Cons('a', box Cons('t', box Nil)));
1375 let ys = Cons('c', box Cons('a', box Cons('t', box Nil)));
1376 assert!(eq(&xs, &ys));
1379 This would be a good opportunity to implement the `PartialEq` trait for our list type, making the `==` and
1380 `!=` operators available. We'll need to provide an `impl` for the `PartialEq` trait and a definition of the
1381 `eq` method. In a method, the `self` parameter refers to an instance of the type we're implementing
1386 # Cons(T, Box<List<T>>),
1389 impl<T: PartialEq> PartialEq for List<T> {
1390 fn eq(&self, ys: &List<T>) -> bool {
1391 // Match on the next node in both lists.
1393 // If we have reached the end of both lists, they are equal.
1394 (&Nil, &Nil) => true,
1395 // If the current elements of both lists are equal, keep going.
1396 (&Cons(ref x, box ref next_xs), &Cons(ref y, box ref next_ys))
1397 if x == y => next_xs == next_ys,
1398 // If the current elements are not equal, the lists are not equal.
1404 let xs = Cons(5i, box Cons(10i, box Nil));
1405 let ys = Cons(5i, box Cons(10i, box Nil));
1406 // The methods below are part of the PartialEq trait,
1407 // which we implemented on our linked list.
1408 assert!(xs.eq(&ys));
1409 assert!(!xs.ne(&ys));
1411 // The PartialEq trait also allows us to use the shorthand infix operators.
1412 assert!(xs == ys); // `xs == ys` is short for `xs.eq(&ys)`
1413 assert!(!(xs != ys)); // `xs != ys` is short for `xs.ne(&ys)`
1418 The most common use case for owned boxes is creating recursive data structures
1419 like a binary search tree. Rust's trait-based generics system (covered later in
1420 the tutorial) is usually used for static dispatch, but also provides dynamic
1421 dispatch via boxing. Values of different types may have different sizes, but a
1422 box is able to *erase* the difference via the layer of indirection they
1425 In uncommon cases, the indirection can provide a performance gain or memory
1426 reduction by making values smaller. However, unboxed values should almost
1427 always be preferred when they are usable.
1429 Note that returning large unboxed values via boxes is unnecessary. A large
1430 value is returned via a hidden output parameter, and the decision on where to
1431 place the return value should be left to the caller:
1434 fn foo() -> (u64, u64, u64, u64, u64, u64) {
1438 let x = box foo(); // allocates a box, and writes the integers directly to it
1441 Beyond the properties granted by the size, an owned box behaves as a regular
1442 value by inheriting the mutability and lifetime of the owner:
1445 let x = 5i; // immutable
1446 let mut y = 5i; // mutable
1449 let x = box 5i; // immutable
1450 let mut y = box 5i; // mutable
1451 *y += 2; // the `*` operator is needed to access the contained value
1457 owned boxes, where the holder of an owned box is the owner of the pointed-to
1458 memory, references never imply ownership - they are "borrowed".
1459 You can borrow a reference to
1460 any object, and the compiler verifies that it cannot outlive the lifetime of
1463 As an example, consider a simple struct type, `Point`:
1472 We can use this simple definition to allocate points in many different
1473 ways. For example, in this code, each of these local variables
1474 contains a point, but allocated in a different location:
1477 # struct Point { x: f64, y: f64 }
1478 let on_the_stack : Point = Point { x: 3.0, y: 4.0 };
1479 let on_the_heap : Box<Point> = box Point { x: 7.0, y: 9.0 };
1482 Suppose we want to write a procedure that computes the distance
1483 between any two points, no matter where they are stored. One option is
1484 to define a function that takes two arguments of type point—that is,
1485 it takes the points by value. But this will cause the points to be
1486 copied when we call the function. For points, this is probably not so
1487 bad, but often copies are expensive. So we’d like to define a function
1488 that takes the points by pointer. We can use references to do this:
1491 # struct Point { x: f64, y: f64 }
1492 fn compute_distance(p1: &Point, p2: &Point) -> f64 {
1493 let x_d = p1.x - p2.x;
1494 let y_d = p1.y - p2.y;
1495 (x_d * x_d + y_d * y_d).sqrt()
1499 Now we can call `compute_distance()` in various ways:
1502 # struct Point{ x: f64, y: f64 };
1503 # let on_the_stack : Point = Point { x: 3.0, y: 4.0 };
1504 # let on_the_heap : Box<Point> = box Point { x: 7.0, y: 9.0 };
1505 # fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }
1506 compute_distance(&on_the_stack, &*on_the_heap);
1509 Here the `&` operator is used to take the address of the variable
1510 `on_the_stack`; this is because `on_the_stack` has the type `Point`
1511 (that is, a struct value) and we have to take its address to get a
1512 reference. We also call this _borrowing_ the local variable
1513 `on_the_stack`, because we are creating an alias: that is, another
1514 route to the same data.
1516 Likewise, in the case of `on_the_heap`,
1517 the `&` operator is used in conjunction with the `*` operator
1518 to take a reference to the contents of the box.
1520 Whenever a value is borrowed, there are some limitations on what you
1521 can do with the original. For example, if the contents of a variable
1522 have been lent out, you cannot send that variable to another task, nor
1523 will you be permitted to take actions that might cause the borrowed
1524 value to be freed or to change its type. This rule should make
1525 intuitive sense: you must wait for a borrowed value to be returned
1526 (that is, for the reference to go out of scope) before you can
1527 make full use of it again.
1529 For a more in-depth explanation of references and lifetimes, read the
1530 [references and lifetimes guide][lifetimes].
1534 Lending an &-pointer to an object freezes the pointed-to object and prevents
1535 mutation—even if the object was declared as `mut`. `Freeze` objects have
1536 freezing enforced statically at compile-time. An example of a non-`Freeze` type
1537 is [`RefCell<T>`][refcell].
1542 let y = &x; // `x` is now frozen. It cannot be modified or re-assigned.
1544 // `x` is now unfrozen again
1548 [refcell]: http://doc.rust-lang.org/std/cell/struct.RefCell.html
1550 # Dereferencing pointers
1552 Rust uses the unary star operator (`*`) to access the contents of a
1553 box or pointer, similarly to C.
1556 let owned = box 10i;
1557 let borrowed = &20i;
1559 let sum = *owned + *borrowed;
1562 Dereferenced mutable pointers may appear on the left hand side of
1563 assignments. Such an assignment modifies the value that the pointer
1567 let mut owned = box 10i;
1569 let mut value = 20i;
1570 let borrowed = &mut value;
1572 *owned = *borrowed + 100;
1573 *borrowed = *owned + 1000;
1576 Pointers have high operator precedence, but lower precedence than the
1577 dot operator used for field and method access. This precedence order
1578 can sometimes make code awkward and parenthesis-filled.
1581 # struct Point { x: f64, y: f64 }
1582 # enum Shape { Rectangle(Point, Point) }
1583 # impl Shape { fn area(&self) -> int { 0 } }
1584 let start = box Point { x: 10.0, y: 20.0 };
1585 let end = box Point { x: (*start).x + 100.0, y: (*start).y + 100.0 };
1586 let rect = &Rectangle(*start, *end);
1587 let area = (*rect).area();
1590 To combat this ugliness the dot operator applies _automatic pointer
1591 dereferencing_ to the receiver (the value on the left-hand side of the
1592 dot), so in most cases, explicitly dereferencing the receiver is not necessary.
1595 # struct Point { x: f64, y: f64 }
1596 # enum Shape { Rectangle(Point, Point) }
1597 # impl Shape { fn area(&self) -> int { 0 } }
1598 let start = box Point { x: 10.0, y: 20.0 };
1599 let end = box Point { x: start.x + 100.0, y: start.y + 100.0 };
1600 let rect = &Rectangle(*start, *end);
1601 let area = rect.area();
1604 You can write an expression that dereferences any number of pointers
1605 automatically. For example, if you feel inclined, you could write
1606 something silly like
1609 # struct Point { x: f64, y: f64 }
1610 let point = &box Point { x: 10.0, y: 20.0 };
1611 println!("{:f}", point.x);
1614 The indexing operator (`[]`) also auto-dereferences.
1616 # Vectors and strings
1618 A vector is a contiguous block of memory containing zero or more values of the
1619 same type. Rust also supports vector reference types, called slices, which are
1620 a view into a block of memory represented as a pointer and a length.
1622 Strings are represented as vectors of `u8`, with the guarantee of containing a
1623 valid UTF-8 sequence.
1625 Fixed-size vectors are an unboxed block of memory, with the element length as
1626 part of the type. A fixed-size vector owns the elements it contains, so the
1627 elements are mutable if the vector is mutable. Fixed-size strings do not exist.
1630 // A fixed-size vector
1631 let numbers = [1i, 2, 3];
1632 let more_numbers = numbers;
1634 // The type of a fixed-size vector is written as `[Type, ..length]`
1635 let five_zeroes: [int, ..5] = [0, ..5];
1638 A unique vector is dynamically sized, and has a destructor to clean up
1639 allocated memory on the heap. A unique vector owns the elements it contains, so
1640 the elements are mutable if the vector is mutable.
1643 use std::string::String;
1645 // A dynamically sized vector (unique vector)
1646 let mut numbers = vec![1i, 2, 3];
1650 // The type of a unique vector is written as `Vec<int>`
1651 let more_numbers: Vec<int> = numbers.move_iter().map(|i| i+1).collect();
1653 // The original `numbers` value can no longer be used, due to move semantics.
1655 let mut string = String::from_str("fo");
1656 string.push_char('o');
1659 Slices are similar to fixed-size vectors, but the length is not part of the
1660 type. They simply point into a block of memory and do not have ownership over
1665 let xs = &[1, 2, 3];
1667 // Slices have their type written as `&[int]`
1668 let ys: &[int] = xs;
1670 // Other vector types coerce to slices
1671 let three = [1, 2, 3];
1672 let zs: &[int] = three;
1674 // An unadorned string literal is an immutable string slice
1675 let string = "foobar";
1677 // A string slice type is written as `&str`
1678 let view: &str = string.slice(0, 3);
1681 Square brackets denote indexing into a slice or fixed-size vector:
1684 let crayons: [&str, ..3] = ["BananaMania", "Beaver", "Bittersweet"];
1685 println!("Crayon 2 is '{}'", crayons[2]);
1688 Mutable slices also exist, just as there are mutable references. However, there
1689 are no mutable string slices. Strings are a multi-byte encoding (UTF-8) of
1690 Unicode code points, so they cannot be freely mutated without the ability to
1694 let mut xs = [1i, 2i, 3i];
1695 let view = xs.mut_slice(0, 2);
1698 // The type of a mutable slice is written as `&mut [T]`
1699 let ys: &mut [int] = &mut [1i, 2i, 3i];
1702 A slice or fixed-size vector can be destructured using pattern matching:
1705 let numbers: &[int] = &[1, 2, 3];
1706 let score = match numbers {
1709 [a, b] => a * 6 + b * 4,
1710 [a, b, c, ..rest] => a * 5 + b * 3 + c * 2 + rest.len() as int
1714 Both vectors and strings support a number of useful [methods](#methods),
1715 defined in [`std::vec`], [`std::slice`], and [`std::str`].
1717 [`std::vec`]: std/vec/index.html
1718 [`std::slice`]: std/slice/index.html
1719 [`std::str`]: std/str/index.html
1721 # Ownership escape hatches
1723 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
1724 single parent ownership.
1726 The standard library provides the `std::rc::Rc` pointer type to express *shared ownership* over a
1727 reference counted box. As soon as all of the `Rc` pointers go out of scope, the box and the
1728 contained value are destroyed.
1733 // A fixed-size array allocated in a reference-counted box
1734 let x = Rc::new([1i, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
1735 let y = x.clone(); // a new owner
1736 let z = x; // this moves `x` into `z`, rather than creating a new owner
1738 assert!(*z == [1i, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
1740 // the variable is mutable, but not the contents of the box
1741 let mut a = Rc::new([10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
1745 A garbage collected pointer is provided via `std::gc::Gc`, with a task-local garbage collector
1746 having ownership of the box. It allows the creation of cycles, and the individual `Gc` pointers do
1747 not have a destructor.
1752 // A fixed-size array allocated in a garbage-collected box
1753 let x = box(GC) [1i, 2, 3, 4, 5, 6, 7, 8, 9, 10];
1754 let y = x; // does not perform a move, unlike with `Rc`
1757 assert!(*z == [1i, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
1760 With shared ownership, mutability cannot be inherited so the boxes are always immutable. However,
1761 it's possible to use *dynamic* mutability via types like `std::cell::Cell` where freezing is handled
1762 via dynamic checks and can fail at runtime.
1764 The `Rc` and `Gc` types are not sendable, so they cannot be used to share memory between tasks. Safe
1765 immutable and mutable shared memory is provided by the `sync::arc` module.
1767 > *Note:* See a [later chapter](#traits) for a discussion about `Send` and sendable types.
1771 Named functions, like those we've seen so far, may not refer to local
1772 variables declared outside the function: they do not close over their
1773 environment (sometimes referred to as "capturing" variables in their
1774 environment). For example, you couldn't write the following:
1779 // `fun` cannot refer to `x`
1780 fn fun() -> () { println!("{}", x); }
1783 A _closure_ does support accessing the enclosing scope; below we will create
1784 2 _closures_ (nameless functions). Compare how `||` replaces `()` and how
1785 they try to access `x`:
1790 // `fun` is an invalid definition
1791 fn fun () -> () { println!("{}", x) } // cannot capture from enclosing scope
1792 let closure = || -> () { println!("{}", x) }; // can capture from enclosing scope
1794 // `fun_arg` is an invalid definition
1795 fn fun_arg (arg: int) -> () { println!("{}", arg + x) } // cannot capture
1796 let closure_arg = |arg: int| -> () { println!("{}", arg + x) }; // can capture
1798 // Requires a type because the implementation needs to know which `+` to use.
1799 // In the future, the implementation may not need the help.
1801 fun(); // Still won't work
1802 closure(); // Prints: 3
1804 fun_arg(7); // Still won't work
1805 closure_arg(7); // Prints: 10
1808 Closures begin with the argument list between vertical bars and are followed by
1809 a single expression. Remember that a block, `{ <expr1>; <expr2>; ... }`, is
1810 considered a single expression: it evaluates to the result of the last
1811 expression it contains if that expression is not followed by a semicolon,
1812 otherwise the block evaluates to `()`, the unit value.
1814 In general, return types and all argument types must be specified
1815 explicitly for function definitions. (As previously mentioned in the
1816 [Functions section](#functions), omitting the return type from a
1817 function declaration is synonymous with an explicit declaration of
1818 return type unit, `()`.)
1821 fn fun (x: int) { println!("{}", x) } // this is same as saying `-> ()`
1822 fn square(x: int) -> uint { (x * x) as uint } // other return types are explicit
1824 // Error: mismatched types: expected `()` but found `uint`
1825 fn badfun(x: int) { (x * x) as uint }
1828 On the other hand, the compiler can usually infer both the argument
1829 and return types for a closure expression; therefore they are often
1830 omitted, since both a human reader and the compiler can deduce the
1831 types from the immediate context. This is in contrast to function
1832 declarations, which require types to be specified and are not subject
1833 to type inference. Compare:
1836 // `fun` as a function declaration cannot infer the type of `x`, so it must be provided
1837 fn fun (x: int) { println!("{}", x) }
1838 let closure = |x | { println!("{}", x) }; // infers `x: int`, return type `()`
1840 // For closures, omitting a return type is *not* synonymous with `-> ()`
1841 let add_3 = |y | { 3i + y }; // infers `y: int`, return type `int`.
1843 fun(10); // Prints 10
1844 closure(20); // Prints 20
1845 closure(add_3(30)); // Prints 33
1847 fun("String"); // Error: mismatched types
1849 // Error: mismatched types
1850 // inference already assigned `closure` the type `|int| -> ()`
1854 In cases where the compiler needs assistance, the arguments and return
1855 types may be annotated on closures, using the same notation as shown
1856 earlier. In the example below, since different types provide an
1857 implementation for the operator `*`, the argument type for the `x`
1858 parameter must be explicitly provided.
1861 // Error: the type of `x` must be known to be used with `x * x`
1862 let square = |x | -> uint { (x * x) as uint };
1865 In the corrected version, the argument type is explicitly annotated,
1866 while the return type can still be inferred.
1869 let square_explicit = |x: int| -> uint { (x * x) as uint };
1870 let square_infer = |x: int| { (x * x) as uint };
1872 println!("{}", square_explicit(20)); // 400
1873 println!("{}", square_infer(-20)); // 400
1876 There are several forms of closure, each with its own role. The most
1877 common, called a _stack closure_, has type `||` and can directly
1878 access local variables in the enclosing scope.
1882 let f = |x: int| if x > max { max = x };
1883 for x in [1, 2, 3].iter() {
1888 Stack closures are very efficient because their environment is
1889 allocated on the call stack and refers by pointer to captured
1890 locals. To ensure that stack closures never outlive the local
1891 variables to which they refer, stack closures are not
1892 first-class. That is, they can only be used in argument position; they
1893 cannot be stored in data structures or returned from
1894 functions. Despite these limitations, stack closures are used
1895 pervasively in Rust code.
1899 Owned closures, written `proc`,
1900 hold on to things that can safely be sent between
1901 processes. They copy the values they close over,
1902 but they also own them: that is, no other code can access
1903 them. Owned closures are used in concurrent code, particularly
1904 for spawning [tasks][tasks].
1906 Closures can be used to spawn tasks.
1907 A practical example of this pattern is found when using the `spawn` function,
1908 which starts a new task.
1911 use std::task::spawn;
1913 // proc is the closure which will be spawned.
1915 println!("I'm a new task")
1919 ## Closure compatibility
1921 Rust closures have a convenient subtyping property: you can pass any kind of
1922 closure (as long as the arguments and return types match) to functions
1923 that expect a `||`. Thus, when writing a higher-order function that
1924 only calls its function argument, and does nothing else with it, you
1925 should almost always declare the type of that argument as `||`. That way,
1926 callers may pass any kind of closure.
1929 fn call_twice(f: ||) { f(); f(); }
1930 let closure = || { "I'm a closure, and it doesn't matter what type I am"; };
1931 fn function() { "I'm a normal function"; }
1932 call_twice(closure);
1933 call_twice(function);
1936 > *Note:* Both the syntax and the semantics will be changing
1937 > in small ways. At the moment they can be unsound in some
1938 > scenarios, particularly with non-copyable types.
1942 Methods are like functions except that they always begin with a special argument,
1944 which has the type of the method's receiver. The
1945 `self` argument is like `this` in C++ and many other languages.
1946 Methods are called with dot notation, as in `my_vec.len()`.
1948 _Implementations_, written with the `impl` keyword, can define
1949 methods on most Rust types, including structs and enums.
1950 As an example, let's define a `draw` method on our `Shape` enum.
1953 # fn draw_circle(p: Point, f: f64) { }
1954 # fn draw_rectangle(p: Point, p: Point) { }
1962 Rectangle(Point, Point)
1968 Circle(p, f) => draw_circle(p, f),
1969 Rectangle(p1, p2) => draw_rectangle(p1, p2)
1974 let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
1978 This defines an _implementation_ for `Shape` containing a single
1979 method, `draw`. In most respects the `draw` method is defined
1980 like any other function, except for the name `self`.
1982 The type of `self` is the type on which the method is implemented,
1983 or a pointer thereof. As an argument it is written either `self`,
1984 `&self`, or `self: TYPE`.
1985 A caller must in turn have a compatible pointer type to call the method.
1988 # fn draw_circle(p: Point, f: f64) { }
1989 # fn draw_rectangle(p: Point, p: Point) { }
1990 # struct Point { x: f64, y: f64 }
1992 # Circle(Point, f64),
1993 # Rectangle(Point, Point)
1996 fn draw_reference(&self) { /* ... */ }
1997 fn draw_owned(self: Box<Shape>) { /* ... */ }
1998 fn draw_value(self) { /* ... */ }
2001 let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
2003 (&s).draw_reference();
2004 (box s).draw_owned();
2008 Methods typically take a reference self type,
2009 so the compiler will go to great lengths to convert a callee
2013 # fn draw_circle(p: Point, f: f64) { }
2014 # fn draw_rectangle(p: Point, p: Point) { }
2015 # struct Point { x: f64, y: f64 }
2017 # Circle(Point, f64),
2018 # Rectangle(Point, Point)
2021 # fn draw_reference(&self) { /* ... */ }
2022 # fn draw_owned(self: Box<Shape>) { /* ... */ }
2023 # fn draw_value(self) { /* ... */ }
2025 # let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
2026 // As with typical function arguments, owned pointers
2027 // are automatically converted to references
2029 (box s).draw_reference();
2031 // Unlike typical function arguments, the self value will
2032 // automatically be referenced ...
2035 // ... and dereferenced
2036 (& &s).draw_reference();
2038 // ... and dereferenced and borrowed
2039 (&box s).draw_reference();
2042 Implementations may also define standalone (sometimes called "static")
2043 methods. The absence of a `self` parameter distinguishes such methods.
2044 These methods are the preferred way to define constructor functions.
2048 fn area(&self) -> f64 { /* ... */ }
2049 fn new(area: f64) -> Circle { /* ... */ }
2053 To call such a method, just prefix it with the type name and a double colon:
2056 use std::f64::consts::PI;
2057 struct Circle { radius: f64 }
2059 fn new(area: f64) -> Circle { Circle { radius: (area / PI).sqrt() } }
2061 let c = Circle::new(42.5);
2066 Throughout this tutorial, we've been defining functions that act only
2067 on specific data types. With type parameters we can also define
2068 functions whose arguments have generic types, and which can be invoked
2069 with a variety of types. Consider a generic `map` function, which
2070 takes a function `function` and a vector `vector` and returns a new
2071 vector consisting of the result of applying `function` to each element
2075 fn map<T, U>(vector: &[T], function: |v: &T| -> U) -> Vec<U> {
2076 let mut accumulator = Vec::new();
2077 for element in vector.iter() {
2078 accumulator.push(function(element));
2084 When defined with type parameters, as denoted by `<T, U>`, this
2085 function can be applied to any type of vector, as long as the type of
2086 `function`'s argument and the type of the vector's contents agree with
2089 Inside a generic function, the names of the type parameters
2090 (capitalized by convention) stand for opaque types. All you can do
2091 with instances of these types is pass them around: you can't apply any
2092 operations to them or pattern-match on them. Note that instances of
2093 generic types are often passed by pointer. For example, the parameter
2094 `function()` is supplied with a pointer to a value of type `T` and not
2095 a value of type `T` itself. This ensures that the function works with
2096 the broadest set of types possible, since some types are expensive or
2097 illegal to copy and pass by value.
2099 Generic `type`, `struct`, and `enum` declarations follow the same pattern:
2102 type Set<T> = std::collections::HashMap<T, ()>;
2115 These declarations can be instantiated to valid types like `Set<int>`,
2116 `Stack<int>`, and `Option<int>`.
2118 The last type in that example, `Option`, appears frequently in Rust code.
2119 Because Rust does not have null pointers (except in unsafe code), we need
2120 another way to write a function whose result isn't defined on every possible
2121 combination of arguments of the appropriate types. The usual way is to write
2122 a function that returns `Option<T>` instead of `T`.
2125 # struct Point { x: f64, y: f64 }
2126 # enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
2127 fn radius(shape: Shape) -> Option<f64> {
2129 Circle(_, radius) => Some(radius),
2130 Rectangle(..) => None
2135 The Rust compiler compiles generic functions very efficiently by
2136 *monomorphizing* them. *Monomorphization* is a fancy name for a simple
2137 idea: generate a separate copy of each generic function at each call site,
2138 a copy that is specialized to the argument
2139 types and can thus be optimized specifically for them. In this
2140 respect, Rust's generics have similar performance characteristics to
2145 Within a generic function—that is, a function parameterized by a
2146 type parameter, say, `T`—the operations we can do on arguments of
2147 type `T` are quite limited. After all, since we don't know what type
2148 `T` will be instantiated with, we can't safely modify or query values
2149 of type `T`. This is where _traits_ come into play. Traits are Rust's
2150 most powerful tool for writing polymorphic code. Java developers will
2151 see them as similar to Java interfaces, and Haskellers will notice
2152 their similarities to type classes. Rust's traits give us a way to
2153 express *bounded polymorphism*: by limiting the set of possible types
2154 that a type parameter could refer to, they expand the number of
2155 operations we can safely perform on arguments of that type.
2157 As motivation, let us consider copying of values in Rust. The `clone`
2158 method is not defined for values of every type. One reason is
2159 user-defined destructors: copying a value of a type that has a
2160 destructor could result in the destructor running multiple times.
2161 Therefore, values of types that have destructors cannot be copied
2162 unless we explicitly implement `clone` for them.
2164 This complicates handling of generic functions.
2165 If we have a function with a type parameter `T`,
2166 can we copy values of type `T` inside that function?
2168 and if we try to run the following code the compiler will complain.
2171 // This does not compile
2172 fn head_bad<T>(v: &[T]) -> T {
2173 v[0] // error: copying a non-copyable value
2177 However, we can tell the compiler
2178 that the `head` function is only for copyable types.
2179 In Rust, copyable types are those that _implement the `Clone` trait_.
2180 We can then explicitly create a second copy of the value we are returning
2181 by calling the `clone` method:
2185 fn head<T: Clone>(v: &[T]) -> T {
2190 The bounded type parameter `T: Clone` says that `head`
2191 can be called on an argument of type `&[T]` for any `T`,
2192 so long as there is an implementation of the
2193 `Clone` trait for `T`.
2194 When instantiating a generic function,
2195 we can only instantiate it with types
2196 that implement the correct trait,
2197 so we could not apply `head` to a vector whose elements are of some type
2198 that does not implement `Clone`.
2200 While most traits can be defined and implemented by user code,
2201 three traits are automatically derived and implemented
2202 for all applicable types by the compiler,
2203 and may not be overridden:
2205 * `Send` - Sendable types.
2207 unless they contain references.
2209 * `Sync` - Types that are *threadsafe*.
2210 These are types that are safe to be used across several threads with access to
2211 a `&T` pointer. `Mutex<T>` is an example of a *sharable* type with internal mutable data.
2213 * `'static` - Non-borrowed types.
2214 These are types that do not contain any data whose lifetime is bound to
2215 a particular stack frame. These are types that do not contain any
2216 references, or types where the only contained references
2217 have the `'static` lifetime. (For more on named lifetimes and their uses,
2218 see the [references and lifetimes guide][lifetimes].)
2220 > *Note:* These built-in traits were referred to as 'kinds' in earlier
2221 > iterations of the language, and often still are.
2223 Additionally, the `Drop` trait is used to define destructors. This
2224 trait provides one method called `drop`, which is automatically
2225 called when a value of the type that implements this trait is
2226 destroyed, either because the value went out of scope or because the
2227 garbage collector reclaimed it.
2234 impl Drop for TimeBomb {
2235 fn drop(&mut self) {
2236 for _ in range(0, self.explosivity) {
2243 It is illegal to call `drop` directly. Only code inserted by the compiler
2246 ## Declaring and implementing traits
2248 At its simplest, a trait is a set of zero or more _method signatures_.
2249 For example, we could declare the trait
2250 `Printable` for things that can be printed to the console,
2251 with a single method signature:
2259 We say that the `Printable` trait _provides_ a `print` method with the
2260 given signature. This means that we can call `print` on an argument
2261 of any type that implements the `Printable` trait.
2263 Rust's built-in `Send` and `Sync` types are examples of traits that
2264 don't provide any methods.
2266 Traits may be implemented for specific types with [impls]. An impl for
2267 a particular trait gives an implementation of the methods that
2268 trait provides. For instance, the following impls of
2269 `Printable` for `int` and `String` give implementations of the `print`
2275 # trait Printable { fn print(&self); }
2276 impl Printable for int {
2277 fn print(&self) { println!("{}", *self) }
2280 impl Printable for String {
2281 fn print(&self) { println!("{}", *self) }
2285 # ("foo".to_string()).print();
2288 Methods defined in an impl for a trait may be called just like
2289 any other method, using dot notation, as in `1.print()`.
2291 ## Default method implementations in trait definitions
2293 Sometimes, a method that a trait provides will have the same
2294 implementation for most or all of the types that implement that trait.
2295 For instance, suppose that we wanted `bool`s and `f32`s to be
2296 printable, and that we wanted the implementation of `print` for those
2297 types to be exactly as it is for `int`, above:
2300 # trait Printable { fn print(&self); }
2301 impl Printable for f32 {
2302 fn print(&self) { println!("{}", *self) }
2305 impl Printable for bool {
2306 fn print(&self) { println!("{}", *self) }
2313 This works fine, but we've now repeated the same definition of `print`
2314 in three places. Instead of doing that, we can simply include the
2315 definition of `print` right in the trait definition, instead of just
2316 giving its signature. That is, we can write the following:
2323 // Default method implementation
2324 fn print(&self) { println!("{:?}", *self) }
2327 impl Printable for int {}
2329 impl Printable for String {
2330 fn print(&self) { println!("{}", *self) }
2333 impl Printable for bool {}
2335 impl Printable for f32 {}
2338 # ("foo".to_string()).print();
2344 Here, the impls of `Printable` for `int`, `bool`, and `f32` don't
2345 need to provide an implementation of `print`, because in the absence
2346 of a specific implementation, Rust just uses the _default method_
2347 provided in the trait definition. Depending on the trait, default
2348 methods can save a great deal of boilerplate code from having to be
2349 written in impls. Of course, individual impls can still override the
2350 default method for `print`, as is being done above in the impl for
2353 ## Type-parameterized traits
2355 Traits may be parameterized by type variables. For example, a trait
2356 for generalized sequence types might look like the following:
2360 fn length(&self) -> uint;
2363 impl<T> Seq<T> for Vec<T> {
2364 fn length(&self) -> uint { self.len() }
2368 The implementation has to explicitly declare the type parameter that
2369 it binds, `T`, before using it to specify its trait type. Rust
2370 requires this declaration because the `impl` could also, for example,
2371 specify an implementation of `Seq<int>`. The trait type (appearing
2372 between `impl` and `for`) *refers* to a type, rather than
2375 The type parameters bound by a trait are in scope in each of the
2376 method declarations. So, re-declaring the type parameter
2377 `T` as an explicit type parameter for `length`, in either the trait or
2378 the impl, would be a compile-time error.
2380 Within a trait definition, `Self` is a special type that you can think
2381 of as a type parameter. An implementation of the trait for any given
2382 type `T` replaces the `Self` type parameter with `T`. The following
2383 trait describes types that support an equality operation:
2386 // In a trait, `self` refers to the self argument.
2387 // `Self` refers to the type implementing the trait.
2389 fn equals(&self, other: &Self) -> bool;
2392 // In an impl, `self` refers just to the value of the receiver
2393 impl PartialEq for int {
2394 fn equals(&self, other: &int) -> bool { *other == *self }
2398 Notice that in the trait definition, `equals` takes a
2399 second parameter of type `Self`.
2400 In contrast, in the `impl`, `equals` takes a second parameter of
2401 type `int`, only using `self` as the name of the receiver.
2403 Just as in type implementations, traits can define standalone (static)
2404 methods. These methods are called by prefixing the method name with the trait
2405 name and a double colon. The compiler uses type inference to decide which
2406 implementation to use.
2409 use std::f64::consts::PI;
2410 trait Shape { fn new(area: f64) -> Self; }
2411 struct Circle { radius: f64 }
2412 struct Square { length: f64 }
2414 impl Shape for Circle {
2415 fn new(area: f64) -> Circle { Circle { radius: (area / PI).sqrt() } }
2417 impl Shape for Square {
2418 fn new(area: f64) -> Square { Square { length: area.sqrt() } }
2422 let c: Circle = Shape::new(area);
2423 let s: Square = Shape::new(area);
2426 ## Bounded type parameters and static method dispatch
2428 Traits give us a language for defining predicates on types, or
2429 abstract properties that types can have. We can use this language to
2430 define _bounds_ on type parameters, so that we can then operate on
2434 # trait Printable { fn print(&self); }
2435 fn print_all<T: Printable>(printable_things: Vec<T>) {
2436 for thing in printable_things.iter() {
2442 Declaring `T` as conforming to the `Printable` trait (as we earlier
2443 did with `Clone`) makes it possible to call methods from that trait
2444 on values of type `T` inside the function. It will also cause a
2445 compile-time error when anyone tries to call `print_all` on a vector
2446 whose element type does not have a `Printable` implementation.
2448 Type parameters can have multiple bounds by separating them with `+`,
2449 as in this version of `print_all` that copies elements.
2452 # trait Printable { fn print(&self); }
2453 fn print_all<T: Printable + Clone>(printable_things: Vec<T>) {
2455 while i < printable_things.len() {
2456 let copy_of_thing = printable_things[i].clone();
2457 copy_of_thing.print();
2463 Method calls to bounded type parameters are _statically dispatched_,
2464 imposing no more overhead than normal function invocation, so are
2465 the preferred way to use traits polymorphically.
2467 This usage of traits is similar to Haskell type classes.
2469 ## Trait objects and dynamic method dispatch
2471 The above allows us to define functions that polymorphically act on
2472 values of a single unknown type that conforms to a given trait.
2473 However, consider this function:
2476 # type Circle = int; type Rectangle = int;
2477 # impl Drawable for int { fn draw(&self) {} }
2478 # fn new_circle() -> int { 1 }
2479 trait Drawable { fn draw(&self); }
2481 fn draw_all<T: Drawable>(shapes: Vec<T>) {
2482 for shape in shapes.iter() { shape.draw(); }
2484 # let c: Circle = new_circle();
2485 # draw_all(vec![c]);
2488 You can call that on a vector of circles, or a vector of rectangles
2489 (assuming those have suitable `Drawable` traits defined), but not on
2490 a vector containing both circles and rectangles. When such behavior is
2491 needed, a trait name can alternately be used as a type, called
2495 # trait Drawable { fn draw(&self); }
2496 fn draw_all(shapes: &[Box<Drawable>]) {
2497 for shape in shapes.iter() { shape.draw(); }
2501 In this example, there is no type parameter. Instead, the `Box<Drawable>`
2502 type denotes any owned box value that implements the `Drawable` trait.
2503 To construct such a value, you use the `as` operator to cast a value
2507 # type Circle = int; type Rectangle = bool;
2508 # trait Drawable { fn draw(&self); }
2509 # fn new_circle() -> Circle { 1 }
2510 # fn new_rectangle() -> Rectangle { true }
2511 # fn draw_all(shapes: &[Box<Drawable>]) {}
2513 impl Drawable for Circle { fn draw(&self) { /* ... */ } }
2514 impl Drawable for Rectangle { fn draw(&self) { /* ... */ } }
2516 let c: Box<Circle> = box new_circle();
2517 let r: Box<Rectangle> = box new_rectangle();
2518 draw_all([c as Box<Drawable>, r as Box<Drawable>]);
2521 We omit the code for `new_circle` and `new_rectangle`; imagine that
2522 these just return `Circle`s and `Rectangle`s with a default size. Note
2523 that, like strings and vectors, objects have dynamic size and may
2524 only be referred to via one of the pointer types.
2525 Other pointer types work as well.
2526 Casts to traits may only be done with compatible pointers so,
2527 for example, an `&Circle` may not be cast to a `Box<Drawable>`.
2530 # type Circle = int; type Rectangle = int;
2531 # trait Drawable { fn draw(&self); }
2532 # impl Drawable for int { fn draw(&self) {} }
2533 # fn new_circle() -> int { 1 }
2534 # fn new_rectangle() -> int { 2 }
2536 let owny: Box<Drawable> = box new_circle() as Box<Drawable>;
2537 // A borrowed object
2538 let stacky: &Drawable = &new_circle() as &Drawable;
2541 Method calls to trait types are _dynamically dispatched_. Since the
2542 compiler doesn't know specifically which functions to call at compile
2543 time, it uses a lookup table (also known as a vtable or dictionary) to
2544 select the method to call at runtime.
2546 This usage of traits is similar to Java interfaces.
2548 There are some built-in bounds, such as `Send` and `Sync`, which are properties
2549 of the components of types. By design, trait objects don't know the exact type
2550 of their contents and so the compiler cannot reason about those properties.
2552 You can instruct the compiler, however, that the contents of a trait object must
2553 ascribe to a particular bound with a trailing colon (`:`). These are examples of
2560 fn sendable_foo(f: Box<Foo + Send>) { /* ... */ }
2561 fn sync_bar<T: Sync>(b: &Bar<T> + Sync) { /* ... */ }
2564 When no colon is specified (such as the type `Box<Foo>`), it is inferred that the
2565 value ascribes to no bounds. They must be added manually if any bounds are
2566 necessary for usage.
2568 Builtin kind bounds can also be specified on closure types in the same way (for
2569 example, by writing `fn:Send()`), and the default behaviours are the same as
2570 for traits of the same storage class.
2572 ## Trait inheritance
2574 We can write a trait declaration that _inherits_ from other traits, called _supertraits_.
2575 Types that implement a trait must also implement its supertraits.
2577 we can define a `Circle` trait that inherits from `Shape`.
2580 trait Shape { fn area(&self) -> f64; }
2581 trait Circle : Shape { fn radius(&self) -> f64; }
2584 Now, we can implement `Circle` on a type only if we also implement `Shape`.
2587 use std::f64::consts::PI;
2588 # trait Shape { fn area(&self) -> f64; }
2589 # trait Circle : Shape { fn radius(&self) -> f64; }
2590 # struct Point { x: f64, y: f64 }
2591 # fn square(x: f64) -> f64 { x * x }
2592 struct CircleStruct { center: Point, radius: f64 }
2593 impl Circle for CircleStruct {
2594 fn radius(&self) -> f64 { (self.area() / PI).sqrt() }
2596 impl Shape for CircleStruct {
2597 fn area(&self) -> f64 { PI * square(self.radius) }
2601 Notice that methods of `Circle` can call methods on `Shape`, as our
2602 `radius` implementation calls the `area` method.
2603 This is a silly way to compute the radius of a circle
2604 (since we could just return the `radius` field), but you get the idea.
2606 In type-parameterized functions,
2607 methods of the supertrait may be called on values of subtrait-bound type parameters.
2608 Referring to the previous example of `trait Circle : Shape`:
2611 # trait Shape { fn area(&self) -> f64; }
2612 # trait Circle : Shape { fn radius(&self) -> f64; }
2613 fn radius_times_area<T: Circle>(c: T) -> f64 {
2614 // `c` is both a Circle and a Shape
2615 c.radius() * c.area()
2619 Likewise, supertrait methods may also be called on trait objects.
2622 use std::f64::consts::PI;
2623 # trait Shape { fn area(&self) -> f64; }
2624 # trait Circle : Shape { fn radius(&self) -> f64; }
2625 # struct Point { x: f64, y: f64 }
2626 # struct CircleStruct { center: Point, radius: f64 }
2627 # impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / PI).sqrt() } }
2628 # impl Shape for CircleStruct { fn area(&self) -> f64 { PI * square(self.radius) } }
2629 # fn square(x: f64) -> f64 { x * x }
2631 let concrete = box CircleStruct{center:Point{x:3.0,y:4.0},radius:5.0};
2632 let mycircle: Box<Circle> = concrete as Box<Circle>;
2633 let nonsense = mycircle.radius() * mycircle.area();
2636 > *Note:* Trait inheritance does not actually work with objects yet
2638 ## Deriving implementations for traits
2640 A small number of traits in can have implementations
2641 that can be automatically derived. These instances are specified by
2642 placing the `deriving` attribute on a data type declaration. For
2643 example, the following will mean that `Circle` has an implementation
2644 for `PartialEq` and can be used with the equality operators, and that a value
2645 of type `ABC` can be randomly generated and converted to a string:
2649 use std::rand::{task_rng, Rng};
2651 #[deriving(PartialEq)]
2652 struct Circle { radius: f64 }
2654 #[deriving(Rand, Show)]
2655 enum ABC { A, B, C }
2658 // Use the Show trait to print "A, B, C."
2659 println!("{}, {}, {}", A, B, C);
2661 let mut rng = task_rng();
2663 // Use the Rand trait to generate a random variants.
2664 for _ in range(0i, 10) {
2665 println!("{}", rng.gen::<ABC>());
2670 The full list of derivable traits is `PartialEq`, `Eq`, `PartialOrd`,
2671 `Ord`, `Encodable`, `Decodable`, `Clone`,
2672 `Hash`, `Rand`, `Default`, `Zero`, `FromPrimitive` and `Show`.
2674 # Crates and the module system
2676 Rust's module system is very powerful, but because of that also somewhat complex.
2677 Nevertheless, this section will try to explain every important aspect of it.
2681 In order to speak about the module system, we first need to define the medium it exists in:
2683 Let's say you've written a program or a library, compiled it, and got the resulting binary.
2684 In Rust, the content of all source code that the compiler directly had to compile in order to end up with
2685 that binary is collectively called a 'crate'.
2687 For example, for a simple hello world program your crate only consists of this code:
2692 println!("Hello world!");
2696 A crate is also the unit of independent compilation in Rust: `rustc` always compiles a single crate at a time,
2697 from which it produces either a library or an executable.
2699 Note that merely using an already compiled library in your code does not make it part of your crate.
2701 ## The module hierarchy
2703 For every crate, all the code in it is arranged in a hierarchy of modules starting with a single
2704 root module. That root module is called the 'crate root'.
2706 All modules in a crate below the crate root are declared with the `mod` keyword:
2709 // This is the crate root
2712 // This is the body of module 'farm' declared in the crate root.
2714 fn chicken() { println!("cluck cluck"); }
2715 fn cow() { println!("mooo"); }
2718 // Body of module 'barn'
2720 fn hay() { println!("..."); }
2725 println!("Hello farm!");
2729 As you can see, your module hierarchy is now three modules deep: There is the crate root, which contains your `main()`
2730 function, and the module `farm`. The module `farm` also contains two functions and a third module `barn`,
2731 which contains a function `hay`.
2733 ## Paths and visibility
2735 We've now defined a nice module hierarchy. But how do we access the items in it from our `main` function?
2736 One way to do it is to simply fully qualifying it:
2740 fn chicken() { println!("cluck cluck"); }
2745 println!("Hello chicken!");
2747 ::farm::chicken(); // Won't compile yet, see further down
2751 The `::farm::chicken` construct is what we call a 'path'.
2753 Because it's starting with a `::`, it's also a 'global path', which qualifies
2754 an item by its full path in the module hierarchy relative to the crate root.
2756 If the path were to start with a regular identifier, like `farm::chicken`, it
2757 would be a 'local path' instead. We'll get to them later.
2759 Now, if you actually tried to compile this code example, you'll notice that you
2760 get a `function 'chicken' is private` error. That's because by default, items
2761 (`fn`, `struct`, `static`, `mod`, ...) are private.
2763 To make them visible outside their containing modules, you need to mark them
2764 _public_ with `pub`:
2768 pub fn chicken() { println!("cluck cluck"); }
2769 pub fn cow() { println!("mooo"); }
2774 println!("Hello chicken!");
2775 ::farm::chicken(); // This compiles now
2779 Visibility restrictions in Rust exist only at module boundaries. This
2780 is quite different from most object-oriented languages that also
2781 enforce restrictions on objects themselves. That's not to say that
2782 Rust doesn't support encapsulation: both struct fields and methods can
2783 be private. But this encapsulation is at the module level, not the
2786 Fields are _private_ by default, and can be made _public_ with
2791 # pub type Chicken = int;
2792 # struct Human(int);
2793 # impl Human { pub fn rest(&self) { } }
2794 # pub fn make_me_a_farm() -> Farm { Farm { chickens: vec![], farmer: Human(0) } }
2796 chickens: Vec<Chicken>,
2801 fn feed_chickens(&self) { /* ... */ }
2802 pub fn add_chicken(&self, c: Chicken) { /* ... */ }
2805 pub fn feed_animals(farm: &Farm) {
2806 farm.feed_chickens();
2811 let f = make_me_a_farm();
2812 f.add_chicken(make_me_a_chicken());
2813 farm::feed_animals(&f);
2816 // This wouldn't compile because both are private:
2817 // `f.feed_chickens();`
2818 // `let chicken_counter = f.chickens.len();`
2820 # fn make_me_a_farm() -> farm::Farm { farm::make_me_a_farm() }
2821 # fn make_me_a_chicken() -> farm::Chicken { 0 }
2824 Exact details and specifications about visibility rules can be found in the Rust
2827 ## Files and modules
2829 One important aspect of Rust's module system is that source files and modules are not the same thing. You define a module hierarchy, populate it with all your definitions, define visibility, maybe put in a `fn main()`, and that's it.
2831 The only file that's relevant when compiling is the one that contains the body
2832 of your crate root, and it's only relevant because you have to pass that file
2833 to `rustc` to compile your crate.
2835 In principle, that's all you need: You can write any Rust program as one giant source file that contains your
2836 crate root and everything else in `mod ... { ... }` declarations.
2838 However, in practice you usually want to split up your code into multiple
2839 source files to make it more manageable. Rust allows you to move the body of
2840 any module into its own source file. If you declare a module without its body,
2841 like `mod foo;`, the compiler will look for the files `foo.rs` and `foo/mod.rs`
2842 inside some directory (usually the same as of the source file containing the
2843 `mod foo;` declaration). If it finds either, it uses the content of that file
2844 as the body of the module. If it finds both, that's a compile error.
2846 To move the content of `mod farm` into its own file, you can write:
2849 // `main.rs` - contains body of the crate root
2850 mod farm; // Compiler will look for `farm.rs` and `farm/mod.rs`
2853 println!("Hello farm!");
2859 // `farm.rs` - contains body of module 'farm' in the crate root
2860 pub fn chicken() { println!("cluck cluck"); }
2861 pub fn cow() { println!("mooo"); }
2864 pub fn hay() { println!("..."); }
2869 In short, `mod foo;` is just syntactic sugar for `mod foo { /* content of <...>/foo.rs or <...>/foo/mod.rs */ }`.
2871 This also means that having two or more identical `mod foo;` declarations
2872 somewhere in your crate hierarchy is generally a bad idea,
2873 just like copy-and-paste-ing a module into multiple places is a bad idea.
2874 Both will result in duplicate and mutually incompatible definitions.
2876 When `rustc` resolves these module declarations, it starts by looking in the
2877 parent directory of the file containing the `mod foo` declaration. For example,
2878 given a file with the module body:
2891 The compiler will look for these files, in this order:
2898 src/animals/fish/mod.rs
2900 src/animals/mammals/humans.rs
2901 src/animals/mammals/humans/mod.rs
2904 Keep in mind that identical module hierarchies can still lead to different path
2905 lookups depending on how and where you've moved a module body to its own file.
2906 For example, if you move the `animals` module into its own file:
2915 // `src/animals.rs` or `src/animals/mod.rs`
2922 ...then the source files of `mod animals`'s submodules can either be in the same directory as the animals source file or in a subdirectory of its directory. If the animals file is `src/animals.rs`, `rustc` will look for:
2929 src/mammals/humans.rs
2930 src/mammals/humans/mod.rs
2933 If the animals file is `src/animals/mod.rs`, `rustc` will look for:
2938 src/animals/fish/mod.rs
2940 src/animals/mammals/humans.rs
2941 src/animals/mammals/humans/mod.rs
2945 These rules allow you to write small modules consisting of single source files which can live in the same directory as well as large modules which group submodule source files in subdirectories.
2947 If you need to override where `rustc` will look for the file containing a
2948 module's source code, use the `path` compiler directive. For example, to load a
2949 `classified` module from a different file:
2952 #[path="../../area51/alien.rs"]
2956 ## Importing names into the local scope
2958 Always referring to definitions in other modules with their global
2959 path gets old really fast, so Rust has a way to import
2960 them into the local scope of your module: `use`-statements.
2962 They work like this: At the beginning of any module body, `fn` body, or any other block
2963 you can write a list of `use`-statements, consisting of the keyword `use` and a __global path__ to an item
2964 without the `::` prefix. For example, this imports `cow` into the local scope:
2968 # mod farm { pub fn cow() { println!("I'm a hidden ninja cow!") } }
2969 # fn main() { cow() }
2972 The path you give to `use` is per default global, meaning relative to the crate root,
2973 no matter how deep the module hierarchy is, or whether the module body it's written in
2974 is contained in its own file. (Remember: files are irrelevant.)
2976 This is different from other languages, where you often only find a single import construct that combines the semantic
2977 of `mod foo;` and `use`-statements, and which tend to work relative to the source file or use an absolute file path
2978 - Ruby's `require` or C/C++'s `#include` come to mind.
2980 However, it's also possible to import things relative to the module of the `use`-statement:
2981 Adding a `super::` in front of the path will start in the parent module,
2982 while adding a `self::` prefix will start in the current module:
2986 # pub fn some_parent_item(){ println!("...") }
2988 use super::some_parent_item;
2989 use self::some_child_module::some_item;
2990 # pub fn bar() { some_parent_item(); some_item() }
2991 # pub mod some_child_module { pub fn some_item() {} }
2996 Again - relative to the module, not to the file.
2998 Imports are also shadowed by local definitions:
2999 For each name you mention in a module/block, `rust`
3000 will first look at all items that are defined locally,
3001 and only if that results in no match look at items you brought in
3002 scope with corresponding `use` statements.
3005 # // FIXME: Allow unused import in doc test
3008 # mod farm { pub fn cow() { println!("Hidden ninja cow is hidden.") } }
3009 fn cow() { println!("Mooo!") }
3012 cow() // resolves to the locally defined `cow()` function
3016 To make this behavior more obvious, the rule has been made that `use`-statement always need to be written
3017 before any declaration, like in the example above. This is a purely artificial rule introduced
3018 because people always assumed they shadowed each other based on order, despite the fact that all items in rust are
3019 mutually recursive, order independent definitions.
3021 One odd consequence of that rule is that `use` statements also go in front of any `mod` declaration,
3022 even if they refer to things inside them:
3027 pub fn cow() { println!("Moooooo?") }
3033 This is what our `farm` example looks like with `use` statements:
3041 pub fn chicken() { println!("cluck cluck"); }
3042 pub fn cow() { println!("mooo"); }
3045 pub fn hay() { println!("..."); }
3050 println!("Hello farm!");
3052 // Can now refer to those names directly:
3059 And here an example with multiple files:
3062 // `a.rs` - crate root
3075 pub fn foo() { println!("Foo!"); }
3080 pub fn bar() { println!("Bar!"); }
3083 There also exist two short forms for importing multiple names at once:
3085 1. Explicit mention multiple names as the last element of an `use` path:
3088 use farm::{chicken, cow};
3090 # pub fn cow() { println!("Did I already mention how hidden and ninja I am?") }
3091 # pub fn chicken() { println!("I'm Bat-chicken, guardian of the hidden tutorial code.") }
3093 # fn main() { cow(); chicken() }
3096 2. Import everything in a module with a wildcard:
3099 # #![feature(globs)]
3102 # pub fn cow() { println!("Bat-chicken? What a stupid name!") }
3103 # pub fn chicken() { println!("Says the 'hidden ninja' cow.") }
3105 # fn main() { cow(); chicken() }
3108 > *Note:* This feature of the compiler is currently gated behind the
3109 > `#![feature(globs)]` directive. More about these directives can be found in
3112 However, that's not all. You can also rename an item while you're bringing it into scope:
3115 use farm::chicken as egg_layer;
3116 # mod farm { pub fn chicken() { println!("Laying eggs is fun!") } }
3124 In general, `use` creates a local alias:
3125 An alternate path and a possibly different name to access the same item,
3126 without touching the original, and with both being interchangeable.
3128 ## Reexporting names
3130 It is also possible to reexport items to be accessible under your module.
3132 For that, you write `pub use`:
3136 pub use self::barn::hay;
3138 pub fn chicken() { println!("cluck cluck"); }
3139 pub fn cow() { println!("mooo"); }
3142 pub fn hay() { println!("..."); }
3153 Just like in normal `use` statements, the exported names
3154 merely represent an alias to the same thing and can also be renamed.
3156 The above example also demonstrate what you can use `pub use` for:
3157 The nested `barn` module is private, but the `pub use` allows users
3158 of the module `farm` to access a function from `barn` without needing
3159 to know that `barn` exists.
3161 In other words, you can use it to decouple a public api from its internal implementation.
3165 So far we've only talked about how to define and structure your own crate.
3167 However, most code out there will want to use preexisting libraries,
3168 as there really is no reason to start from scratch each time you start a new project.
3170 In Rust terminology, we need a way to refer to other crates.
3172 For that, Rust offers you the `extern crate` declaration:
3175 // `num` ships with Rust.
3179 // The rational number '1/2':
3180 let one_half = ::num::rational::Ratio::new(1i, 2);
3184 A statement of the form `extern crate foo;` will cause `rustc` to search for the crate `foo`,
3185 and if it finds a matching binary it lets you use it from inside your crate.
3187 The effect it has on your module hierarchy mirrors aspects of both `mod` and `use`:
3189 - Like `mod`, it causes `rustc` to actually emit code:
3190 The linkage information the binary needs to use the library `foo`.
3192 - But like `use`, all `extern crate` statements that refer to the same library are interchangeable,
3193 as each one really just presents an alias to an external module (the crate root of the library
3194 you're linking against).
3196 Remember how `use`-statements have to go before local declarations because the latter shadows the former?
3197 Well, `extern crate` statements also have their own rules in that regard:
3198 Both `use` and local declarations can shadow them, so the rule is that `extern crate` has to go in front
3199 of both `use` and local declarations.
3201 Which can result in something like this:
3207 use num::rational::Ratio;
3210 pub fn dog() { println!("woof"); }
3215 let a_third = Ratio::new(1i, 3);
3219 It's a bit weird, but it's the result of shadowing rules that have been set that way because
3220 they model most closely what people expect to shadow.
3222 ## Crate metadata and settings
3224 For every crate you can define a number of metadata items, such as link name, version or author.
3225 You can also toggle settings that have crate-global consequences. Both mechanism
3226 work by providing attributes in the crate root.
3228 For example, Rust uniquely identifies crates by their link metadata, which includes
3229 the link name and the version. It also hashes the filename and the symbols in a binary
3230 based on the link metadata, allowing you to use two different versions of the same library in a crate
3233 Therefore, if you plan to compile your crate as a library, you should annotate it with that information:
3236 # #![allow(unused_attribute)]
3239 # #![crate_type = "lib"]
3240 #![crate_id = "farm#2.5"]
3246 You can also specify crate id information in a `extern crate` statement. For
3247 example, these `extern crate` statements would both accept and select the
3252 extern crate farm = "farm#2.5";
3253 extern crate my_farm = "farm";
3256 Other crate settings and metadata include things like enabling/disabling certain errors or warnings,
3257 or setting the crate type (library or executable) explicitly:
3260 # #![allow(unused_attribute)]
3264 // This crate is a library ("bin" is the default)
3265 #![crate_id = "farm#2.5"]
3266 #![crate_type = "lib"]
3268 // Turn on a warning
3269 #[warn(non_camel_case_types)]
3273 ## A minimal example
3275 Now for something that you can actually compile yourself.
3277 We define two crates, and use one of them as a library in the other.
3280 # #![allow(unused_attribute)]
3282 #![crate_id = "world#0.42"]
3284 # mod secret_module_to_make_this_test_run {
3285 pub fn explore() -> &'static str { "world" }
3292 fn main() { println!("hello {}", world::explore()); }
3295 Now compile and run like this (adjust to your platform if necessary):
3298 $ rustc --crate-type=lib world.rs # compiles libworld-<HASH>-0.42.rlib
3299 $ rustc main.rs -L . # compiles main
3304 Notice that the library produced contains the version in the file name
3305 as well as an inscrutable string of alphanumerics. As explained in the previous paragraph,
3306 these are both part of Rust's library versioning scheme. The alphanumerics are
3307 a hash representing the crate's id.
3309 ## The standard library and the prelude
3311 While reading the examples in this tutorial, you might have asked yourself where all
3312 those magical predefined items like `range` are coming from.
3314 The truth is, there's nothing magical about them: They are all defined normally
3315 in the `std` library, which is a crate that ships with Rust.
3317 The only magical thing that happens is that `rustc` automatically inserts this line into your crate root:
3323 As well as this line into every module body:
3326 use std::prelude::*;
3329 The role of the `prelude` module is to re-export common definitions from `std`.
3331 This allows you to use common types and functions like `Option<T>` or `range`
3332 without needing to import them. And if you need something from `std` that's not in the prelude,
3333 you just have to import it with an `use` statement.
3335 For example, it re-exports `range` which is defined in `std::iter::range`:
3338 use std::iter::range as iter_range;
3341 // `range` is imported by default
3342 for _ in range(0u, 10) {}
3344 // Doesn't hinder you from importing it under a different name yourself
3345 for _ in iter_range(0u, 10) {}
3347 // Or from not using the automatic import.
3348 for _ in ::std::iter::range(0u, 10) {}
3352 Both auto-insertions can be disabled with an attribute if necessary:
3355 # #![allow(unused_attribute)]
3356 // In the crate root:
3361 # #![allow(unused_attribute)]
3363 #![no_implicit_prelude]
3366 See the [API documentation][stddoc] for details.
3368 [stddoc]: std/index.html
3372 Now that you know the essentials, check out any of the additional
3373 guides on individual topics.
3375 * [Pointers][pointers]
3376 * [Lifetimes][lifetimes]
3377 * [Tasks and communication][tasks]
3379 * [The foreign function interface][ffi]
3380 * [Containers and iterators][container]
3381 * [Documenting Rust code][rustdoc]
3382 * [Testing Rust code][testing]
3383 * [The Rust Runtime][runtime]
3385 There is further documentation on the [wiki], however those tend to be even more out of date than this document.
3387 [pointers]: guide-pointers.html
3388 [lifetimes]: guide-lifetimes.html
3389 [tasks]: guide-tasks.html
3390 [macros]: guide-macros.html
3391 [ffi]: guide-ffi.html
3392 [container]: guide-container.html
3393 [testing]: guide-testing.html
3394 [runtime]: guide-runtime.html
3395 [rustdoc]: rustdoc.html
3396 [wiki]: https://github.com/rust-lang/rust/wiki/Docs
3398 [wiki-packages]: https://github.com/rust-lang/rust/wiki/Doc-packages,-editors,-and-other-tools