1 % The Rust Language Tutorial
5 Rust is a programming language with a focus on type safety, memory
6 safety, concurrency and performance. It is intended for writing
7 large-scale, high-performance software that is free from several
8 classes of common errors. Rust has a sophisticated memory model that
9 encourages efficient data structures and safe concurrency patterns,
10 forbidding invalid memory accesses that would otherwise cause
11 segmentation faults. It is statically typed and compiled ahead of
14 As a multi-paradigm language, Rust supports writing code in
15 procedural, functional and object-oriented styles. Some of its
16 pleasant high-level features include:
18 * **Type inference.** Type annotations on local variable declarations
20 * **Safe task-based concurrency.** Rust's lightweight tasks do not share
21 memory, instead communicating through messages.
22 * **Higher-order functions.** Efficient and flexible closures provide
23 iteration and other control structures
24 * **Pattern matching and algebraic data types.** Pattern matching on
25 Rust's enumeration types (a more powerful version of C's enums,
26 similar to algebraic data types in functional languages) is a
27 compact and expressive way to encode program logic.
28 * **Polymorphism.** Rust has type-parametric functions and
29 types, type classes and OO-style interfaces.
33 This is an introductory tutorial for the Rust programming language. It
34 covers the fundamentals of the language, including the syntax, the
35 type system and memory model, generics, and modules. [Additional
36 tutorials](#what-next) cover specific language features in greater
39 This tutorial assumes that the reader is already familiar with one or
40 more languages in the C family. Understanding of pointers and general
41 memory management techniques will help.
45 Throughout the tutorial, language keywords and identifiers defined in
46 example code are displayed in `code font`.
48 Code snippets are indented, and also shown in a monospaced font. Not
49 all snippets constitute whole programs. For brevity, we'll often show
50 fragments of programs that don't compile on their own. To try them
51 out, you might have to wrap them in `fn main() { ... }`, and make sure
52 they don't contain references to names that aren't actually defined.
54 > ***Warning:*** Rust is a language under ongoing development. Notes
55 > about potential changes to the language, implementation
56 > deficiencies, and other caveats appear offset in blockquotes.
60 > **NOTE**: The tarball and installer links are for the most recent release,
63 The Rust compiler currently must be built from a [tarball] or [git], unless
64 you are on Windows, in which case using the [installer][win-exe] is
65 recommended. There is a list of community-maintained nightly builds and
66 packages [on the wiki][wiki-packages].
68 Since the Rust compiler is written in Rust, it must be built by
69 a precompiled "snapshot" version of itself (made in an earlier state
70 of development). The source build automatically fetches these snapshots
71 from the Internet on our supported platforms.
73 Snapshot binaries are currently built and tested on several platforms:
75 * Windows (7, 8, Server 2008 R2), x86 only
76 * Linux (2.6.18 or later, various distributions), x86 and x86-64
77 * OSX 10.7 (Lion) or greater, x86 and x86-64
79 You may find that other platforms work, but these are our "tier 1"
80 supported build environments that are most likely to work.
82 > ***Note:*** Windows users should read the detailed
83 > "[getting started][wiki-start]" notes on the wiki. Even when using
84 > the binary installer, the Windows build requires a MinGW installation,
85 > the precise details of which are not discussed here. Finally, `rustc` may
86 > need to be [referred to as `rustc.exe`][bug-3319]. It's a bummer, we
89 [bug-3319]: https://github.com/mozilla/rust/issues/3319
90 [wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust
91 [git]: https://github.com/mozilla/rust.git
93 To build from source you will also need the following prerequisite
96 * g++ 4.4 or clang++ 3.x
97 * python 2.6 or later (but not 3.x)
99 * gnu make 3.81 or later
102 If you've fulfilled those prerequisites, something along these lines
106 $ curl -O http://static.rust-lang.org/dist/rust-0.9.tar.gz
107 $ tar -xzf rust-0.9.tar.gz
110 $ make && make install
113 You may need to use `sudo make install` if you do not normally have
114 permission to modify the destination directory. The install locations
115 can be adjusted by passing a `--prefix` argument to
116 `configure`. Various other options are also supported: pass `--help`
117 for more information on them.
119 When complete, `make install` will place several programs into
120 `/usr/local/bin`: `rustc`, the Rust compiler; `rustdoc`, the
121 API-documentation tool; and `rustpkg`, the Rust package manager.
123 [tarball]: http://static.rust-lang.org/dist/rust-0.9.tar.gz
124 [win-exe]: http://static.rust-lang.org/dist/rust-0.9-install.exe
126 ## Compiling your first program
128 Rust program files are, by convention, given the extension `.rs`. Say
129 we have a file `hello.rs` containing this program:
137 If the Rust compiler was installed successfully, running `rustc
138 hello.rs` will produce an executable called `hello` (or `hello.exe` on
139 Windows) which, upon running, will likely do exactly what you expect.
141 The Rust compiler tries to provide useful information when it encounters an
142 error. If you introduce an error into the program (for example, by changing
143 `println!` to some nonexistent macro), and then compile it, you'll see
144 an error message like this:
147 hello.rs:2:5: 2:24 error: macro undefined: 'print_with_unicorns'
148 hello.rs:2 print_with_unicorns!("hello?");
152 In its simplest form, a Rust program is a `.rs` file with some types
153 and functions defined in it. If it has a `main` function, it can be
154 compiled to an executable. Rust does not allow code that's not a
155 declaration to appear at the top level of the file: all statements must
156 live inside a function. Rust programs can also be compiled as
157 libraries, and included in other programs, even ones not written in Rust.
161 There are vim highlighting and indentation scripts in the Rust source
162 distribution under `src/etc/vim/`. There is an emacs mode under
163 `src/etc/emacs/` called `rust-mode`, but do read the instructions
164 included in that directory. In particular, if you are running emacs
165 24, then using emacs's internal package manager to install `rust-mode`
166 is the easiest way to keep it up to date. There is also a package for
167 Sublime Text 2, available both [standalone][sublime] and through
168 [Sublime Package Control][sublime-pkg], and support for Kate
169 under `src/etc/kate`.
171 A community-maintained list of available Rust tooling is [on the
172 wiki][wiki-packages].
174 There is ctags support via `src/etc/ctags.rust`, but many other
175 tools and editors are not yet supported. If you end up writing a Rust
176 mode for your favorite editor, let us know so that we can link to it.
178 [sublime]: http://github.com/dbp/sublime-rust
179 [sublime-pkg]: http://wbond.net/sublime_packages/package_control
183 Assuming you've programmed in any C-family language (C++, Java,
184 JavaScript, C#, or PHP), Rust will feel familiar. Code is arranged
185 in blocks delineated by curly braces; there are control structures
186 for branching and looping, like the familiar `if` and `while`; function
187 calls are written `myfunc(arg1, arg2)`; operators are written the same
188 and mostly have the same precedence as in C; comments are again like C;
189 module names are separated with double-colon (`::`) as with C++.
191 The main surface difference to be aware of is that the condition at
192 the head of control structures like `if` and `while` does not require
193 parentheses, while their bodies *must* be wrapped in
194 braces. Single-statement, unbraced bodies are not allowed.
197 # mod universe { pub fn recalibrate() -> bool { true } }
201 // A tricky calculation
202 if universe::recalibrate() {
209 The `let` keyword introduces a local variable. Variables are immutable by
210 default. To introduce a local variable that you can re-assign later, use `let
218 println!("count is {}", count);
223 Although Rust can almost always infer the types of local variables, you can
224 specify a variable's type by following it in the `let` with a colon, then the
225 type name. Static items, on the other hand, always require a type annotation.
229 static MONSTER_FACTOR: f64 = 57.8;
230 let monster_size = MONSTER_FACTOR * 10.0;
231 let monster_size: int = 50;
234 Local variables may shadow earlier declarations, as in the previous example:
235 `monster_size` was first declared as a `f64`, and then a second
236 `monster_size` was declared as an `int`. If you were to actually compile this
237 example, though, the compiler would determine that the first `monster_size` is
238 unused and issue a warning (because this situation is likely to indicate a
239 programmer error). For occasions where unused variables are intentional, their
240 names may be prefixed with an underscore to silence the warning, like `let
241 _monster_size = 50;`.
243 Rust identifiers start with an alphabetic
244 character or an underscore, and after that may contain any sequence of
245 alphabetic characters, numbers, or underscores. The preferred style is to
246 write function, variable, and module names with lowercase letters, using
247 underscores where they help readability, while writing types in camel case.
250 let my_variable = 100;
251 type MyType = int; // primitive types are _not_ camel case
254 ## Expressions and semicolons
256 Though it isn't apparent in all code, there is a fundamental
257 difference between Rust's syntax and predecessors like C.
258 Many constructs that are statements in C are expressions
259 in Rust, allowing code to be more concise. For example, you might
260 write a piece of code like this:
263 # let item = "salad";
267 } else if item == "muffin" {
274 But, in Rust, you don't have to repeat the name `price`:
277 # let item = "salad";
281 } else if item == "muffin" {
288 Both pieces of code are exactly equivalent: they assign a value to
289 `price` depending on the condition that holds. Note that there
290 are no semicolons in the blocks of the second snippet. This is
291 important: the lack of a semicolon after the last statement in a
292 braced block gives the whole block the value of that last expression.
294 Put another way, the semicolon in Rust *ignores the value of an expression*.
295 Thus, if the branches of the `if` had looked like `{ 4; }`, the above example
296 would simply assign `()` (nil or void) to `price`. But without the semicolon, each
297 branch has a different value, and `price` gets the value of the branch that
300 In short, everything that's not a declaration (declarations are `let` for
301 variables; `fn` for functions; and any top-level named items such as
302 [traits](#traits), [enum types](#enums), and static items) is an
303 expression, including function bodies.
306 fn is_four(x: int) -> bool {
307 // No need for a return statement. The result of the expression
308 // is used as the return value.
313 ## Primitive types and literals
315 There are general signed and unsigned integer types, `int` and `uint`,
316 as well as 8-, 16-, 32-, and 64-bit variants, `i8`, `u16`, etc.
317 Integers can be written in decimal (`144`), hexadecimal (`0x90`), octal (`0o70`), or
318 binary (`0b10010000`) base. Each integral type has a corresponding literal
319 suffix that can be used to indicate the type of a literal: `i` for `int`,
320 `u` for `uint`, `i8` for the `i8` type.
322 In the absence of an integer literal suffix, Rust will infer the
323 integer type based on type annotations and function signatures in the
324 surrounding program. In the absence of any type information at all,
325 Rust will assume that an unsuffixed integer literal has type
329 let a = 1; // a is an int
330 let b = 10i; // b is an int, due to the 'i' suffix
331 let c = 100u; // c is a uint
332 let d = 1000i32; // d is an i32
335 There are two floating-point types: `f32`, and `f64`.
336 Floating-point numbers are written `0.0`, `1e6`, or `2.1e-4`.
337 Like integers, floating-point literals are inferred to the correct type.
338 Suffixes `f32`, and `f64` can be used to create literals of a specific type.
340 The keywords `true` and `false` produce literals of type `bool`.
342 Characters, the `char` type, are four-byte Unicode codepoints,
343 whose literals are written between single quotes, as in `'x'`.
344 Just like C, Rust understands a number of character escapes, using the backslash
345 character, such as `\n`, `\r`, and `\t`. String literals,
346 written between double quotes, allow the same escape sequences, and do no
347 other processing, unlike languages such as PHP or shell.
349 On the other hand, raw string literals do not process any escape sequences.
350 They are written as `r##"blah"##`, with a matching number of zero or more `#`
351 before the opening and after the closing quote, and can contain any sequence of
352 characters except their closing delimiter. More on strings
353 [later](#vectors-and-strings).
355 The nil type, written `()`, has a single value, also written `()`.
359 Rust's set of operators contains very few surprises. Arithmetic is done with
360 `*`, `/`, `%`, `+`, and `-` (multiply, quotient, remainder, add, and subtract). `-` is
361 also a unary prefix operator that negates numbers. As in C, the bitwise operators
362 `>>`, `<<`, `&`, `|`, and `^` are also supported.
364 Note that, if applied to an integer value, `!` flips all the bits (bitwise
367 The comparison operators are the traditional `==`, `!=`, `<`, `>`,
368 `<=`, and `>=`. Short-circuiting (lazy) boolean operators are written
369 `&&` (and) and `||` (or).
371 For compile-time type casting, Rust uses the binary `as` operator. It takes
372 an expression on the left side and a type on the right side and will, if a
373 meaningful conversion exists, convert the result of the expression to the
374 given type. Generally, `as` is only used with the primitive numeric types or
375 pointers, and is not overloadable. [`transmute`][transmute] can be used for
376 unsafe C-like casting of same-sized types.
380 let y: uint = x as uint;
384 [transmute]: http://static.rust-lang.org/doc/master/std/cast/fn.transmute.html
388 *Syntax extensions* are special forms that are not built into the language,
389 but are instead provided by the libraries. To make it clear to the reader when
390 a name refers to a syntax extension, the names of all syntax extensions end
391 with `!`. The standard library defines a few syntax extensions, the most
392 useful of which is [`format!`][fmt], a `sprintf`-like text formatter that you
393 will often see in examples, and its related family of macros: `print!`,
394 `println!`, and `write!`.
396 `format!` draws syntax from Python, but contains many of the same principles
397 that [printf][pf] has. Unlike printf, `format!` will give you a compile-time
398 error when the types of the directives don't match the types of the arguments.
401 # let mystery_object = ();
403 // {} will print the "default format" of a type
404 println!("{} is {}", "the answer", 43);
406 // {:?} will conveniently print any type
407 println!("what is this thing: {:?}", mystery_object);
410 [pf]: http://en.cppreference.com/w/cpp/io/c/fprintf
411 [fmt]: http://static.rust-lang.org/doc/master/std/fmt/index.html
413 You can define your own syntax extensions with the macro system. For details,
414 see the [macro tutorial][macros]. Note that macro definition is currently
415 considered an unstable feature.
421 We've seen `if` expressions a few times already. To recap, braces are
422 compulsory, an `if` can have an optional `else` clause, and multiple
423 `if`/`else` constructs can be chained together:
427 println!("that's odd");
431 println!("neither true nor false");
435 The condition given to an `if` construct *must* be of type `bool` (no
436 implicit conversion happens). If the arms are blocks that have a
437 value, this value must be of the same type for every arm in which
438 control reaches the end of the block:
441 fn signum(x: int) -> int {
450 Rust's `match` construct is a generalized, cleaned-up version of C's
451 `switch` construct. You provide it with a value and a number of
452 *arms*, each labelled with a pattern, and the code compares the value
453 against each pattern in order until one matches. The matching pattern
454 executes its corresponding arm.
459 0 => println!("zero"),
460 1 | 2 => println!("one or two"),
461 3..10 => println!("three to ten"),
462 _ => println!("something else")
466 Unlike in C, there is no "falling through" between arms: only one arm
467 executes, and it doesn't have to explicitly `break` out of the
468 construct when it is finished.
470 A `match` arm consists of a *pattern*, then an arrow `=>`, followed by
471 an *action* (expression). Literals are valid patterns and match only
472 their own value. A single arm may match multiple different patterns by
473 combining them with the pipe operator (`|`), so long as every pattern
474 binds the same set of variables. Ranges of numeric literal patterns
475 can be expressed with two dots, as in `M..N`. The underscore (`_`) is
476 a wildcard pattern that matches any single value. (`..`) is a different
477 wildcard that can match one or more fields in an `enum` variant.
479 The patterns in a match arm are followed by a fat arrow, `=>`, then an
480 expression to evaluate. Each case is separated by commas. It's often
481 convenient to use a block expression for each case, in which case the
487 0 => { println!("zero") }
488 _ => { println!("something else") }
492 `match` constructs must be *exhaustive*: they must have an arm
493 covering every possible case. For example, the typechecker would
494 reject the previous example if the arm with the wildcard pattern was
497 A powerful application of pattern matching is *destructuring*:
498 matching in order to bind names to the contents of data
501 > ***Note:*** The following code makes use of tuples (`(f64, f64)`) which
502 > are explained in section 5.3. For now you can think of tuples as a list of
508 fn angle(vector: (f64, f64)) -> f64 {
509 let pi = f64::consts::PI;
511 (0.0, y) if y < 0.0 => 1.5 * pi,
512 (0.0, y) => 0.5 * pi,
513 (x, y) => atan(y / x)
518 A variable name in a pattern matches any value, *and* binds that name
519 to the value of the matched value inside of the arm's action. Thus, `(0.0,
520 y)` matches any tuple whose first element is zero, and binds `y` to
521 the second element. `(x, y)` matches any two-element tuple, and binds both
522 elements to variables.
523 A subpattern can also be bound to a variable, using `variable @ pattern`. For
529 a @ 0..20 => println!("{} years old", a),
530 _ => println!("older than 21")
534 Any `match` arm can have a guard clause (written `if EXPR`), called a
535 *pattern guard*, which is an expression of type `bool` that
536 determines, after the pattern is found to match, whether the arm is
537 taken or not. The variables bound by the pattern are in scope in this
538 guard expression. The first arm in the `angle` example shows an
539 example of a pattern guard.
541 You've already seen simple `let` bindings, but `let` is a little
542 fancier than you've been led to believe. It, too, supports destructuring
543 patterns. For example, you can write this to extract the fields from a
544 tuple, introducing two variables at once: `a` and `b`.
547 # fn get_tuple_of_two_ints() -> (int, int) { (1, 1) }
548 let (a, b) = get_tuple_of_two_ints();
551 Let bindings only work with _irrefutable_ patterns: that is, patterns
552 that can never fail to match. This excludes `let` from matching
553 literals and most `enum` variants.
557 `while` denotes a loop that iterates as long as its given condition
558 (which must have type `bool`) evaluates to `true`. Inside a loop, the
559 keyword `break` aborts the loop, and `continue` aborts the current
560 iteration and continues with the next.
563 let mut cake_amount = 8;
564 while cake_amount > 0 {
569 `loop` denotes an infinite loop, and is the preferred way of writing `while true`:
575 if x % 5 == 0 { break; }
580 This code prints out a weird sequence of numbers and stops as soon as
581 it finds one that can be divided by five.
587 Rust struct types must be declared before they are used using the `struct`
588 syntax: `struct Name { field1: T1, field2: T2 [, ...] }`, where `T1`, `T2`,
589 ... denote types. To construct a struct, use the same syntax, but leave off
590 the `struct`: for example: `Point { x: 1.0, y: 2.0 }`.
592 Structs are quite similar to C structs and are even laid out the same way in
593 memory (so you can read from a Rust struct in C, and vice-versa). Use the dot
594 operator to access struct fields, as in `mypoint.x`.
603 Structs have "inherited mutability", which means that any field of a struct
604 may be mutable, if the struct is in a mutable slot.
606 With a value (say, `mypoint`) of such a type in a mutable location, you can do
607 `mypoint.y += 1.0`. But in an immutable location, such an assignment to a
608 struct without inherited mutability would result in a type error.
611 # struct Point { x: f64, y: f64 }
612 let mut mypoint = Point { x: 1.0, y: 1.0 };
613 let origin = Point { x: 0.0, y: 0.0 };
615 mypoint.y += 1.0; // mypoint is mutable, and its fields as well
616 origin.y += 1.0; // ERROR: assigning to immutable field
619 `match` patterns destructure structs. The basic syntax is
620 `Name { fieldname: pattern, ... }`:
623 # struct Point { x: f64, y: f64 }
624 # let mypoint = Point { x: 0.0, y: 0.0 };
626 Point { x: 0.0, y: yy } => println!("{}", yy),
627 Point { x: xx, y: yy } => println!("{} {}", xx, yy),
631 In general, the field names of a struct do not have to appear in the same
632 order they appear in the type. When you are not interested in all
633 the fields of a struct, a struct pattern may end with `, ..` (as in
634 `Name { field1, .. }`) to indicate that you're ignoring all other fields.
635 Additionally, struct fields have a shorthand matching form that simply
636 reuses the field name as the binding name.
639 # struct Point { x: f64, y: f64 }
640 # let mypoint = Point { x: 0.0, y: 0.0 };
642 Point { x, .. } => println!("{}", x),
648 Enums are datatypes that have several alternate representations. For
649 example, consider the following type:
652 # struct Point { x: f64, y: f64 }
655 Rectangle(Point, Point)
659 A value of this type is either a `Circle`, in which case it contains a
660 `Point` struct and a f64, or a `Rectangle`, in which case it contains
661 two `Point` structs. The run-time representation of such a value
662 includes an identifier of the actual form that it holds, much like the
663 "tagged union" pattern in C, but with better static guarantees.
665 The above declaration will define a type `Shape` that can refer to
666 such shapes, and two functions, `Circle` and `Rectangle`, which can be
667 used to construct values of the type (taking arguments of the
668 specified types). So `Circle(Point { x: 0.0, y: 0.0 }, 10.0)` is the way to
671 Enum variants need not have parameters. This `enum` declaration,
672 for example, is equivalent to a C enum:
683 This declaration defines `North`, `East`, `South`, and `West` as constants,
684 all of which have type `Direction`.
686 When an enum is C-like (that is, when none of the variants have
687 parameters), it is possible to explicitly set the discriminator values
698 If an explicit discriminator is not specified for a variant, the value
699 defaults to the value of the previous variant plus one. If the first
700 variant does not have a discriminator, it defaults to 0. For example,
701 the value of `North` is 0, `East` is 1, `South` is 2, and `West` is 3.
703 When an enum is C-like, you can apply the `as` cast operator to
704 convert it to its discriminator value as an `int`.
706 For enum types with multiple variants, destructuring is the only way to
707 get at their contents. All variant constructors can be used as
708 patterns, as in this definition of `area`:
712 # struct Point {x: f64, y: f64}
713 # enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
714 fn area(sh: Shape) -> f64 {
716 Circle(_, size) => f64::consts::PI * size * size,
717 Rectangle(Point { x, y }, Point { x: x2, y: y2 }) => (x2 - x) * (y2 - y)
722 You can write a lone `_` to ignore an individual field, and can
723 ignore all fields of a variant like: `Circle(..)`. As in their
724 introduction form, nullary enum patterns are written without
728 # struct Point { x: f64, y: f64 }
729 # enum Direction { North, East, South, West }
730 fn point_from_direction(dir: Direction) -> Point {
732 North => Point { x: 0.0, y: 1.0 },
733 East => Point { x: 1.0, y: 0.0 },
734 South => Point { x: 0.0, y: -1.0 },
735 West => Point { x: -1.0, y: 0.0 }
740 Enum variants may also be structs. For example:
744 # struct Point { x: f64, y: f64 }
745 # fn square(x: f64) -> f64 { x * x }
747 Circle { center: Point, radius: f64 },
748 Rectangle { top_left: Point, bottom_right: Point }
750 fn area(sh: Shape) -> f64 {
752 Circle { radius: radius, .. } => f64::consts::PI * square(radius),
753 Rectangle { top_left: top_left, bottom_right: bottom_right } => {
754 (bottom_right.x - top_left.x) * (top_left.y - bottom_right.y)
760 > ***Note:*** This feature of the compiler is currently gated behind the
761 > `#[feature(struct_variant)]` directive. More about these directives can be
762 > found in the manual.
766 Tuples in Rust behave exactly like structs, except that their fields do not
767 have names. Thus, you cannot access their fields with dot notation. Tuples
768 can have any arity (number of elements) except for 0 (though you may consider
769 unit, `()`, as the empty tuple if you like).
772 let mytup: (int, int, f64) = (10, 20, 30.0);
774 (a, b, c) => info!("{}", a + b + (c as int))
780 Rust also has _tuple structs_, which behave like both structs and tuples,
781 except that, unlike tuples, tuple structs have names (so `Foo(1, 2)` has a
782 different type from `Bar(1, 2)`), and tuple structs' _fields_ do not have
788 struct MyTup(int, int, f64);
789 let mytup: MyTup = MyTup(10, 20, 30.0);
791 MyTup(a, b, c) => info!("{}", a + b + (c as int))
795 <a name="newtype"></a>
797 There is a special case for tuple structs with a single field, which are
798 sometimes called "newtypes" (after Haskell's "newtype" feature). These are
799 used to define new types in such a way that the new name is not just a
800 synonym for an existing type but is rather its own distinct type.
806 Types like this can be useful to differentiate between data that have
807 the same underlying type but must be used in different ways.
811 struct Centimeters(int);
814 The above definitions allow for a simple way for programs to avoid
815 confusing numbers that correspond to different units. Their integer
816 values can be extracted with pattern matching:
819 # struct Inches(int);
821 let length_with_unit = Inches(10);
822 let Inches(integer_length) = length_with_unit;
823 println!("length is {} inches", integer_length);
828 We've already seen several function definitions. Like all other static
829 declarations, such as `type`, functions can be declared both at the
830 top level and inside other functions (or in modules, which we'll come
831 back to [later](#crates-and-the-module-system)). The `fn` keyword introduces a
832 function. A function has an argument list, which is a parenthesized
833 list of `name: type` pairs separated by commas. An arrow `->`
834 separates the argument list and the function's return type.
837 fn line(a: int, b: int, x: int) -> int {
842 The `return` keyword immediately returns from the body of a function. It
843 is optionally followed by an expression to return. A function can
844 also return a value by having its top-level block produce an
848 fn line(a: int, b: int, x: int) -> int {
853 It's better Rust style to write a return value this way instead of
854 writing an explicit `return`. The utility of `return` comes in when
855 returning early from a function. Functions that do not return a value
856 are said to return nil, `()`, and both the return type and the return
857 value may be omitted from the definition. The following two functions
861 fn do_nothing_the_hard_way() -> () { return (); }
863 fn do_nothing_the_easy_way() { }
866 Ending the function with a semicolon like so is equivalent to returning `()`.
869 fn line(a: int, b: int, x: int) -> int { a * x + b }
870 fn oops(a: int, b: int, x: int) -> () { a * x + b; }
872 assert!(8 == line(5, 3, 1));
873 assert!(() == oops(5, 3, 1));
876 As with `match` expressions and `let` bindings, function arguments support
877 pattern destructuring. Like `let`, argument patterns must be irrefutable,
878 as in this example that unpacks the first value from a tuple and returns it.
881 fn first((value, _): (int, f64)) -> int { value }
886 A *destructor* is a function responsible for cleaning up the resources used by
887 an object when it is no longer accessible. Destructors can be defined to handle
888 the release of resources like files, sockets and heap memory.
890 Objects are never accessible after their destructor has been called, so no
891 dynamic failures are possible from accessing freed resources. When a task
892 fails, destructors of all objects in the task are called.
894 The `~` sigil represents a unique handle for a memory allocation on the heap:
898 // an integer allocated on the heap
901 // the destructor frees the heap memory as soon as `y` goes out of scope
904 Rust includes syntax for heap memory allocation in the language since it's
905 commonly used, but the same semantics can be implemented by a type with a
910 Rust formalizes the concept of object ownership to delegate management of an
911 object's lifetime to either a variable or a task-local garbage collector. An
912 object's owner is responsible for managing the lifetime of the object by
913 calling the destructor, and the owner determines whether the object is mutable.
915 Ownership is recursive, so mutability is inherited recursively and a destructor
916 destroys the contained tree of owned objects. Variables are top-level owners
917 and destroy the contained object when they go out of scope.
920 // the struct owns the objects contained in the `x` and `y` fields
921 struct Foo { x: int, y: ~int }
924 // `a` is the owner of the struct, and thus the owner of the struct's fields
925 let a = Foo { x: 5, y: ~10 };
927 // when `a` goes out of scope, the destructor for the `~int` in the struct's
930 // `b` is mutable, and the mutability is inherited by the objects it owns
931 let mut b = Foo { x: 5, y: ~10 };
935 If an object doesn't contain any non-Send types, it consists of a single
936 ownership tree and is itself given the `Send` trait which allows it to be sent
937 between tasks. Custom destructors can only be implemented directly on types
938 that are `Send`, but non-`Send` types can still *contain* types with custom
939 destructors. Example of types which are not `Send` are [`Gc<T>`][gc] and
940 [`Rc<T>`][rc], the shared-ownership types.
942 [gc]: http://static.rust-lang.org/doc/master/std/gc/struct.Gc.html
943 [rc]: http://static.rust-lang.org/doc/master/std/rc/struct.Rc.html
945 # Implementing a linked list
947 An `enum` is a natural fit for describing a linked list, because it can express
948 a `List` type as being *either* the end of the list (`Nil`) or another node
949 (`Cons`). The full definition of the `Cons` variant will require some thought.
953 Cons(...), // an incomplete definition of the next element in a List
954 Nil // the end of a List
958 The obvious approach is to define `Cons` as containing an element in the list
959 along with the next `List` node. However, this will generate a compiler error.
962 // error: illegal recursive enum type; wrap the inner value in a box to make it representable
964 Cons(u32, List), // an element (`u32`) and the next node in the list
969 This error message is related to Rust's precise control over memory layout, and
970 solving it will require introducing the concept of *boxing*.
974 A value in Rust is stored directly inside the owner. If a `struct` contains
975 four `u32` fields, it will be four times as large as a single `u32`.
978 use std::mem::size_of; // bring `size_of` into the current scope, for convenience
987 assert_eq!(size_of::<Foo>(), size_of::<u32>() * 4);
996 assert_eq!(size_of::<Bar>(), size_of::<u32>() * 16);
999 Our previous attempt at defining the `List` type included an `u32` and a `List`
1000 directly inside `Cons`, making it at least as big as the sum of both types. The
1001 type was invalid because the size was infinite!
1003 An *owned box* (`~`) uses a dynamic memory allocation to provide the invariant
1004 of always being the size of a pointer, regardless of the contained type. This
1005 can be leverage to create a valid `List` definition:
1014 Defining a recursive data structure like this is the canonical example of an
1015 owned box. Much like an unboxed value, an owned box has a single owner and is
1016 therefore limited to expressing a tree-like data structure.
1018 Consider an instance of our `List` type:
1025 let list = Cons(1, ~Cons(2, ~Cons(3, ~Nil)));
1028 It represents an owned tree of values, inheriting mutability down the tree and
1029 being destroyed along with the owner. Since the `list` variable above is
1030 immutable, the whole list is immutable. The memory allocation itself is the
1031 box, while the owner holds onto a pointer to it:
1033 List box List box List box List box
1034 +--------------+ +--------------+ +--------------+ +--------------+
1035 list -> | Cons | 1 | ~ | -> | Cons | 2 | ~ | -> | Cons | 3 | ~ | -> | Nil |
1036 +--------------+ +--------------+ +--------------+ +--------------+
1038 > Note: the above diagram shows the logical contents of the enum. The actual
1039 > memory layout of the enum may vary. For example, for the `List` enum shown
1040 > above, Rust guarantees that there will be no enum tag field in the actual
1041 > structure. See the language reference for more details.
1043 An owned box is a common example of a type with a destructor. The allocated
1044 memory is cleaned up when the box is destroyed.
1048 Rust uses a shallow copy for parameter passing, assignment and returning from
1049 functions. Passing around the `List` will copy only as deep as the pointer to
1050 the box rather than doing an implicit heap allocation.
1057 let xs = Cons(1, ~Cons(2, ~Cons(3, ~Nil)));
1058 let ys = xs; // copies `Cons(u32, pointer)` shallowly
1061 Rust will consider a shallow copy of a type with a destructor like `List` to
1062 *move ownership* of the value. After a value has been moved, the source
1063 location cannot be used unless it is reinitialized.
1073 // attempting to use `xs` will result in an error here
1077 // `xs` can be used again
1080 A destructor call will only occur for a variable that has not been moved from,
1081 as it is only called a single time.
1084 Avoiding a move can be done with the library-defined `clone` method:
1088 let y = x.clone(); // y is a newly allocated box
1089 let z = x; // no new memory allocated, x can no longer be used
1092 The `clone` method is provided by the `Clone` trait, and can be derived for
1093 our `List` type. Traits will be explained in detail later.
1102 let x = Cons(5, ~Nil);
1105 // `x` can still be used!
1109 // and now, it can no longer be used since it has been moved
1112 The mutability of a value may be changed by moving it to a new owner:
1116 let mut s = r; // box becomes mutable
1118 let t = s; // box becomes immutable
1121 A simple way to define a function prepending to the `List` type is to take
1130 fn prepend(xs: List, value: u32) -> List {
1135 xs = prepend(xs, 1);
1136 xs = prepend(xs, 2);
1137 xs = prepend(xs, 3);
1140 However, this is not a very flexible definition of `prepend` as it requires
1141 ownership of a list to be passed in rather than just mutating it in-place.
1145 The obvious signature for a `List` equality comparison is the following:
1148 fn eq(xs: List, ys: List) -> bool { ... }
1151 However, this will cause both lists to be moved into the function. Ownership
1152 isn't required to compare the lists, so the function should take *references*
1156 fn eq(xs: &List, ys: &List) -> bool { ... }
1159 A reference is a *non-owning* view of a value. A reference can be obtained with the `&` (address-of)
1160 operator. It can be dereferenced by using the `*` operator. In a pattern, such as `match` expression
1161 branches, the `ref` keyword can be used to bind to a variable name by-reference rather than
1162 by-value. A recursive definition of equality using references is as follows:
1169 fn eq(xs: &List, ys: &List) -> bool {
1170 // Match on the next node in both lists.
1172 // If we have reached the end of both lists, they are equal.
1173 (&Nil, &Nil) => true,
1174 // If the current element in both lists is equal, keep going.
1175 (&Cons(x, ~ref next_xs), &Cons(y, ~ref next_ys)) if x == y => eq(next_xs, next_ys),
1176 // If the current elements are not equal, the lists are not equal.
1181 let xs = Cons(5, ~Cons(10, ~Nil));
1182 let ys = Cons(5, ~Cons(10, ~Nil));
1183 assert!(eq(&xs, &ys));
1186 Note that Rust doesn't guarantee [tail-call](http://en.wikipedia.org/wiki/Tail_call) optimization,
1187 but LLVM is able to handle a simple case like this with optimizations enabled.
1189 ## Lists of other types
1191 Our `List` type is currently always a list of 32-bit unsigned integers. By
1192 leveraging Rust's support for generics, it can be extended to work for any
1195 The `u32` in the previous definition can be substituted with a type parameter:
1204 The old `List` of `u32` is now available as `List<u32>`. The `prepend`
1205 definition has to be updated too:
1209 # Cons(T, ~List<T>),
1212 fn prepend<T>(xs: List<T>, value: T) -> List<T> {
1217 Generic functions and types like this are equivalent to defining specialized
1218 versions for each set of type parameters.
1220 Using the generic `List<T>` works much like before, thanks to type inference:
1224 # Cons(T, ~List<T>),
1227 # fn prepend<T>(xs: List<T>, value: T) -> List<T> {
1230 let mut xs = Nil; // Unknown type! This is a `List<T>`, but `T` can be anything.
1231 xs = prepend(xs, 10); // The compiler infers the type of `xs` as `List<int>` from this.
1232 xs = prepend(xs, 15);
1233 xs = prepend(xs, 20);
1236 The code sample above demonstrates type inference making most type annotations optional. It is
1237 equivalent to the following type-annotated code:
1241 # Cons(T, ~List<T>),
1244 # fn prepend<T>(xs: List<T>, value: T) -> List<T> {
1247 let mut xs: List<int> = Nil::<int>;
1248 xs = prepend::<int>(xs, 10);
1249 xs = prepend::<int>(xs, 15);
1250 xs = prepend::<int>(xs, 20);
1253 In declarations, the language uses `Type<T, U, V>` to describe a list of type
1254 parameters, but expressions use `identifier::<T, U, V>`, to disambiguate the
1257 ## Defining list equality with generics
1259 Generic functions are type-checked from the definition, so any necessary properties of the type must
1260 be specified up-front. Our previous definition of list equality relied on the element type having
1261 the `==` operator available, and took advantage of the lack of a destructor on `u32` to copy it
1262 without a move of ownership.
1264 We can add a *trait bound* on the `Eq` trait to require that the type implement the `==` operator.
1265 Two more `ref` annotations need to be added to avoid attempting to move out the element types:
1269 # Cons(T, ~List<T>),
1272 fn eq<T: Eq>(xs: &List<T>, ys: &List<T>) -> bool {
1273 // Match on the next node in both lists.
1275 // If we have reached the end of both lists, they are equal.
1276 (&Nil, &Nil) => true,
1277 // If the current element in both lists is equal, keep going.
1278 (&Cons(ref x, ~ref next_xs), &Cons(ref y, ~ref next_ys)) if x == y => eq(next_xs, next_ys),
1279 // If the current elements are not equal, the lists are not equal.
1284 let xs = Cons('c', ~Cons('a', ~Cons('t', ~Nil)));
1285 let ys = Cons('c', ~Cons('a', ~Cons('t', ~Nil)));
1286 assert!(eq(&xs, &ys));
1289 This would be a good opportunity to implement the `Eq` trait for our list type, making the `==` and
1290 `!=` operators available. We'll need to provide an `impl` for the `Eq` trait and a definition of the
1291 `eq` method. In a method, the `self` parameter refers to an instance of the type we're implementing
1296 # Cons(T, ~List<T>),
1299 impl<T: Eq> Eq for List<T> {
1300 fn eq(&self, ys: &List<T>) -> bool {
1301 // Match on the next node in both lists.
1303 // If we have reached the end of both lists, they are equal.
1304 (&Nil, &Nil) => true,
1305 // If the current element in both lists is equal, keep going.
1306 (&Cons(ref x, ~ref next_xs), &Cons(ref y, ~ref next_ys)) if x == y => next_xs == next_ys,
1307 // If the current elements are not equal, the lists are not equal.
1313 let xs = Cons(5, ~Cons(10, ~Nil));
1314 let ys = Cons(5, ~Cons(10, ~Nil));
1315 assert!(xs.eq(&ys));
1317 assert!(!xs.ne(&ys));
1318 assert!(!(xs != ys));
1323 The most common use case for owned boxes is creating recursive data structures
1324 like a binary search tree. Rust's trait-based generics system (covered later in
1325 the tutorial) is usually used for static dispatch, but also provides dynamic
1326 dispatch via boxing. Values of different types may have different sizes, but a
1327 box is able to *erase* the difference via the layer of indirection they
1330 In uncommon cases, the indirection can provide a performance gain or memory
1331 reduction by making values smaller. However, unboxed values should almost
1332 always be preferred when they are usable.
1334 Note that returning large unboxed values via boxes is unnecessary. A large
1335 value is returned via a hidden output parameter, and the decision on where to
1336 place the return value should be left to the caller:
1339 fn foo() -> (u64, u64, u64, u64, u64, u64) {
1343 let x = ~foo(); // allocates a ~ box, and writes the integers directly to it
1346 Beyond the properties granted by the size, an owned box behaves as a regular
1347 value by inheriting the mutability and lifetime of the owner:
1350 let x = 5; // immutable
1351 let mut y = 5; // mutable
1354 let x = ~5; // immutable
1355 let mut y = ~5; // mutable
1356 *y += 2; // the * operator is needed to access the contained value
1362 owned boxes, where the holder of an owned box is the owner of the pointed-to
1363 memory, references never imply ownership - they are "borrowed".
1364 A reference can be borrowed to
1365 any object, and the compiler verifies that it cannot outlive the lifetime of
1368 As an example, consider a simple struct type, `Point`:
1377 We can use this simple definition to allocate points in many different
1378 ways. For example, in this code, each of these three local variables
1379 contains a point, but allocated in a different location:
1382 # struct Point { x: f64, y: f64 }
1383 let on_the_stack : Point = Point { x: 3.0, y: 4.0 };
1384 let managed_box : @Point = @Point { x: 5.0, y: 1.0 };
1385 let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };
1388 Suppose we want to write a procedure that computes the distance
1389 between any two points, no matter where they are stored. For example,
1390 we might like to compute the distance between `on_the_stack` and
1391 `managed_box`, or between `managed_box` and `owned_box`. One option is
1392 to define a function that takes two arguments of type point—that is,
1393 it takes the points by value. But this will cause the points to be
1394 copied when we call the function. For points, this is probably not so
1395 bad, but often copies are expensive. So we’d like to define a function
1396 that takes the points by pointer. We can use references to do this:
1399 # struct Point { x: f64, y: f64 }
1400 # fn sqrt(f: f64) -> f64 { 0.0 }
1401 fn compute_distance(p1: &Point, p2: &Point) -> f64 {
1402 let x_d = p1.x - p2.x;
1403 let y_d = p1.y - p2.y;
1404 sqrt(x_d * x_d + y_d * y_d)
1408 Now we can call `compute_distance()` in various ways:
1411 # struct Point{ x: f64, y: f64 };
1412 # let on_the_stack : Point = Point { x: 3.0, y: 4.0 };
1413 # let managed_box : @Point = @Point { x: 5.0, y: 1.0 };
1414 # let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };
1415 # fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }
1416 compute_distance(&on_the_stack, managed_box);
1417 compute_distance(managed_box, owned_box);
1420 Here the `&` operator is used to take the address of the variable
1421 `on_the_stack`; this is because `on_the_stack` has the type `Point`
1422 (that is, a struct value) and we have to take its address to get a
1423 reference. We also call this _borrowing_ the local variable
1424 `on_the_stack`, because we are creating an alias: that is, another
1425 route to the same data.
1427 In the case of the boxes `managed_box` and `owned_box`, however, no
1428 explicit action is necessary. The compiler will automatically convert
1429 a box like `@point` or `~point` to a reference like
1430 `&point`. This is another form of borrowing; in this case, the
1431 contents of the managed/owned box are being lent out.
1433 Whenever a value is borrowed, there are some limitations on what you
1434 can do with the original. For example, if the contents of a variable
1435 have been lent out, you cannot send that variable to another task, nor
1436 will you be permitted to take actions that might cause the borrowed
1437 value to be freed or to change its type. This rule should make
1438 intuitive sense: you must wait for a borrowed value to be returned
1439 (that is, for the reference to go out of scope) before you can
1440 make full use of it again.
1442 For a more in-depth explanation of references and lifetimes, read the
1443 [references and lifetimes guide][lifetimes].
1447 Lending an immutable pointer to an object freezes it and prevents mutation.
1448 `Freeze` objects have freezing enforced statically at compile-time. An example
1449 of a non-`Freeze` type is [`RefCell<T>`][refcell].
1454 let y = &x; // x is now frozen, it cannot be modified
1456 // x is now unfrozen again
1460 [refcell]: http://static.rust-lang.org/doc/master/std/cell/struct.RefCell.html
1462 # Dereferencing pointers
1464 Rust uses the unary star operator (`*`) to access the contents of a
1465 box or pointer, similarly to C.
1472 let sum = *managed + *owned + *borrowed;
1475 Dereferenced mutable pointers may appear on the left hand side of
1476 assignments. Such an assignment modifies the value that the pointer
1481 let mut owned = ~20;
1484 let borrowed = &mut value;
1486 *owned = *borrowed + 100;
1487 *borrowed = *managed + 1000;
1490 Pointers have high operator precedence, but lower precedence than the
1491 dot operator used for field and method access. This precedence order
1492 can sometimes make code awkward and parenthesis-filled.
1495 # struct Point { x: f64, y: f64 }
1496 # enum Shape { Rectangle(Point, Point) }
1497 # impl Shape { fn area(&self) -> int { 0 } }
1498 let start = @Point { x: 10.0, y: 20.0 };
1499 let end = ~Point { x: (*start).x + 100.0, y: (*start).y + 100.0 };
1500 let rect = &Rectangle(*start, *end);
1501 let area = (*rect).area();
1504 To combat this ugliness the dot operator applies _automatic pointer
1505 dereferencing_ to the receiver (the value on the left-hand side of the
1506 dot), so in most cases, explicitly dereferencing the receiver is not necessary.
1509 # struct Point { x: f64, y: f64 }
1510 # enum Shape { Rectangle(Point, Point) }
1511 # impl Shape { fn area(&self) -> int { 0 } }
1512 let start = @Point { x: 10.0, y: 20.0 };
1513 let end = ~Point { x: start.x + 100.0, y: start.y + 100.0 };
1514 let rect = &Rectangle(*start, *end);
1515 let area = rect.area();
1518 You can write an expression that dereferences any number of pointers
1519 automatically. For example, if you feel inclined, you could write
1520 something silly like
1523 # struct Point { x: f64, y: f64 }
1524 let point = &@~Point { x: 10.0, y: 20.0 };
1525 println!("{:f}", point.x);
1528 The indexing operator (`[]`) also auto-dereferences.
1530 # Vectors and strings
1532 A vector is a contiguous block of memory containing zero or more values of the
1533 same type. Rust also supports vector reference types, called slices, which are
1534 a view into a block of memory represented as a pointer and a length.
1536 Strings are represented as vectors of `u8`, with the guarantee of containing a
1537 valid UTF-8 sequence.
1539 Fixed-size vectors are an unboxed block of memory, with the element length as
1540 part of the type. A fixed-size vector owns the elements it contains, so the
1541 elements are mutable if the vector is mutable. Fixed-size strings do not exist.
1544 // A fixed-size vector
1545 let numbers = [1, 2, 3];
1546 let more_numbers = numbers;
1548 // The type of a fixed-size vector is written as `[Type, ..length]`
1549 let five_zeroes: [int, ..5] = [0, ..5];
1552 A unique vector is dynamically sized, and has a destructor to clean up
1553 allocated memory on the heap. A unique vector owns the elements it contains, so
1554 the elements are mutable if the vector is mutable.
1557 // A dynamically sized vector (unique vector)
1558 let mut numbers = ~[1, 2, 3];
1562 // The type of a unique vector is written as ~[int]
1563 let more_numbers: ~[int] = numbers;
1565 // The original `numbers` value can no longer be used, due to move semantics.
1567 let mut string = ~"fo";
1568 string.push_char('o');
1571 Slices are similar to fixed-size vectors, but the length is not part of the
1572 type. They simply point into a block of memory and do not have ownership over
1577 let xs = &[1, 2, 3];
1579 // Slices have their type written as &[int]
1580 let ys: &[int] = xs;
1582 // Other vector types coerce to slices
1583 let three = [1, 2, 3];
1584 let zs: &[int] = three;
1586 // An unadorned string literal is an immutable string slice
1587 let string = "foobar";
1589 // A string slice type is written as &str
1590 let view: &str = string.slice(0, 3);
1593 Mutable slices also exist, just as there are mutable references. However, there
1594 are no mutable string slices. Strings are a multi-byte encoding (UTF-8) of
1595 Unicode code points, so they cannot be freely mutated without the ability to
1599 let mut xs = [1, 2, 3];
1600 let view = xs.mut_slice(0, 2);
1603 // The type of a mutable slice is written as &mut [T]
1604 let ys: &mut [int] = &mut [1, 2, 3];
1607 Square brackets denote indexing into a vector:
1610 # enum Crayon { Almond, AntiqueBrass, Apricot,
1611 # Aquamarine, Asparagus, AtomicTangerine,
1612 # BananaMania, Beaver, Bittersweet };
1613 # fn draw_scene(c: Crayon) { }
1614 let crayons: [Crayon, ..3] = [BananaMania, Beaver, Bittersweet];
1616 Bittersweet => draw_scene(crayons[0]),
1621 A vector can be destructured using pattern matching:
1624 let numbers: &[int] = &[1, 2, 3];
1625 let score = match numbers {
1628 [a, b] => a * 6 + b * 4,
1629 [a, b, c, ..rest] => a * 5 + b * 3 + c * 2 + rest.len() as int
1633 Both vectors and strings support a number of useful [methods](#methods),
1634 defined in [`std::vec`] and [`std::str`].
1636 [`std::vec`]: std/vec/index.html
1637 [`std::str`]: std/str/index.html
1639 # Ownership escape hatches
1641 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
1642 single parent ownership.
1644 The standard library provides the `std::rc::Rc` pointer type to express *shared ownership* over a
1645 reference counted box. As soon as all of the `Rc` pointers go out of scope, the box and the
1646 contained value are destroyed.
1651 // A fixed-size array allocated in a reference-counted box
1652 let x = Rc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
1653 let y = x.clone(); // a new owner
1654 let z = x; // this moves `x` into `z`, rather than creating a new owner
1656 assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
1658 // the variable is mutable, but not the contents of the box
1659 let mut a = Rc::new([10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
1663 A garbage collected pointer is provided via `std::gc::Gc`, with a task-local garbage collector
1664 having ownership of the box. It allows the creation of cycles, and the individual `Gc` pointers do
1665 not have a destructor.
1670 // A fixed-size array allocated in a garbage-collected box
1671 let x = Gc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
1672 let y = x; // does not perform a move, unlike with `Rc`
1675 assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
1678 With shared ownership, mutability cannot be inherited so the boxes are always immutable. However,
1679 it's possible to use *dynamic* mutability via types like `std::cell::Cell` where freezing is handled
1680 via dynamic checks and can fail at runtime.
1682 The `Rc` and `Gc` types are not sendable, so they cannot be used to share memory between tasks. Safe
1683 immutable and mutable shared memory is provided by the `extra::arc` module.
1687 Named functions, like those we've seen so far, may not refer to local
1688 variables declared outside the function: they do not close over their
1689 environment (sometimes referred to as "capturing" variables in their
1690 environment). For example, you couldn't write the following:
1696 return foo; // `bar` cannot refer to `foo`
1700 Rust also supports _closures_, functions that can access variables in
1701 the enclosing scope.
1704 fn call_closure_with_ten(b: |int|) { b(10); }
1706 let captured_var = 20;
1707 let closure = |arg| println!("captured_var={}, arg={}", captured_var, arg);
1709 call_closure_with_ten(closure);
1712 Closures begin with the argument list between vertical bars and are followed by
1713 a single expression. Remember that a block, `{ <expr1>; <expr2>; ... }`, is
1714 considered a single expression: it evaluates to the result of the last
1715 expression it contains if that expression is not followed by a semicolon,
1716 otherwise the block evaluates to `()`.
1718 The types of the arguments are generally omitted, as is the return type,
1719 because the compiler can almost always infer them. In the rare case where the
1720 compiler needs assistance, though, the arguments and return types may be
1724 let square = |x: int| -> uint { (x * x) as uint };
1727 There are several forms of closure, each with its own role. The most
1728 common, called a _stack closure_, has type `||` and can directly
1729 access local variables in the enclosing scope.
1733 [1, 2, 3].map(|x| if *x > max { max = *x });
1736 Stack closures are very efficient because their environment is
1737 allocated on the call stack and refers by pointer to captured
1738 locals. To ensure that stack closures never outlive the local
1739 variables to which they refer, stack closures are not
1740 first-class. That is, they can only be used in argument position; they
1741 cannot be stored in data structures or returned from
1742 functions. Despite these limitations, stack closures are used
1743 pervasively in Rust code.
1747 Owned closures, written `proc`,
1748 hold on to things that can safely be sent between
1749 processes. They copy the values they close over, much like managed
1750 closures, but they also own them: that is, no other code can access
1751 them. Owned closures are used in concurrent code, particularly
1752 for spawning [tasks][tasks].
1754 ## Closure compatibility
1756 Rust closures have a convenient subtyping property: you can pass any kind of
1757 closure (as long as the arguments and return types match) to functions
1758 that expect a `||`. Thus, when writing a higher-order function that
1759 only calls its function argument, and does nothing else with it, you
1760 should almost always declare the type of that argument as `||`. That way,
1761 callers may pass any kind of closure.
1764 fn call_twice(f: ||) { f(); f(); }
1765 let closure = || { "I'm a closure, and it doesn't matter what type I am"; };
1766 fn function() { "I'm a normal function"; }
1767 call_twice(closure);
1768 call_twice(function);
1771 > ***Note:*** Both the syntax and the semantics will be changing
1772 > in small ways. At the moment they can be unsound in some
1773 > scenarios, particularly with non-copyable types.
1777 The `do` expression makes it easier to call functions that take procedures
1780 Consider this function that takes a procedure:
1783 fn call_it(op: proc(v: int)) {
1788 As a caller, if we use a closure to provide the final operator
1789 argument, we can write it in a way that has a pleasant, block-like
1793 # fn call_it(op: proc(v: int)) { }
1799 A practical example of this pattern is found when using the `spawn` function,
1800 which starts a new task.
1803 use std::task::spawn;
1805 debug!("I'm a new task")
1809 If you want to see the output of `debug!` statements, you will need to turn on
1810 `debug!` logging. To enable `debug!` logging, set the RUST_LOG environment
1811 variable to the name of your crate, which, for a file named `foo.rs`, will be
1812 `foo` (e.g., with bash, `export RUST_LOG=foo`).
1816 Methods are like functions except that they always begin with a special argument,
1818 which has the type of the method's receiver. The
1819 `self` argument is like `this` in C++ and many other languages.
1820 Methods are called with dot notation, as in `my_vec.len()`.
1822 _Implementations_, written with the `impl` keyword, can define
1823 methods on most Rust types, including structs and enums.
1824 As an example, let's define a `draw` method on our `Shape` enum.
1827 # fn draw_circle(p: Point, f: f64) { }
1828 # fn draw_rectangle(p: Point, p: Point) { }
1836 Rectangle(Point, Point)
1842 Circle(p, f) => draw_circle(p, f),
1843 Rectangle(p1, p2) => draw_rectangle(p1, p2)
1848 let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
1852 This defines an _implementation_ for `Shape` containing a single
1853 method, `draw`. In most respects the `draw` method is defined
1854 like any other function, except for the name `self`.
1856 The type of `self` is the type on which the method is implemented,
1857 or a pointer thereof. As an argument it is written either `self`,
1858 `&self`, `@self`, or `~self`.
1859 A caller must in turn have a compatible pointer type to call the method.
1862 # fn draw_circle(p: Point, f: f64) { }
1863 # fn draw_rectangle(p: Point, p: Point) { }
1864 # struct Point { x: f64, y: f64 }
1866 # Circle(Point, f64),
1867 # Rectangle(Point, Point)
1870 fn draw_reference(&self) { ... }
1871 fn draw_managed(@self) { ... }
1872 fn draw_owned(~self) { ... }
1873 fn draw_value(self) { ... }
1876 let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
1878 (@s).draw_managed();
1880 (&s).draw_reference();
1884 Methods typically take a reference self type,
1885 so the compiler will go to great lengths to convert a callee
1889 # fn draw_circle(p: Point, f: f64) { }
1890 # fn draw_rectangle(p: Point, p: Point) { }
1891 # struct Point { x: f64, y: f64 }
1893 # Circle(Point, f64),
1894 # Rectangle(Point, Point)
1897 # fn draw_reference(&self) { ... }
1898 # fn draw_managed(@self) { ... }
1899 # fn draw_owned(~self) { ... }
1900 # fn draw_value(self) { ... }
1902 # let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
1903 // As with typical function arguments, managed and owned pointers
1904 // are automatically converted to references
1906 (@s).draw_reference();
1907 (~s).draw_reference();
1909 // Unlike typical function arguments, the self value will
1910 // automatically be referenced ...
1913 // ... and dereferenced
1914 (& &s).draw_reference();
1916 // ... and dereferenced and borrowed
1917 (&@~s).draw_reference();
1920 Implementations may also define standalone (sometimes called "static")
1921 methods. The absence of a `self` parameter distinguishes such methods.
1922 These methods are the preferred way to define constructor functions.
1926 fn area(&self) -> f64 { ... }
1927 fn new(area: f64) -> Circle { ... }
1931 To call such a method, just prefix it with the type name and a double colon:
1934 use std::f64::consts::PI;
1935 struct Circle { radius: f64 }
1937 fn new(area: f64) -> Circle { Circle { radius: (area / PI).sqrt() } }
1939 let c = Circle::new(42.5);
1944 Throughout this tutorial, we've been defining functions that act only
1945 on specific data types. With type parameters we can also define
1946 functions whose arguments have generic types, and which can be invoked
1947 with a variety of types. Consider a generic `map` function, which
1948 takes a function `function` and a vector `vector` and returns a new
1949 vector consisting of the result of applying `function` to each element
1953 fn map<T, U>(vector: &[T], function: |v: &T| -> U) -> ~[U] {
1954 let mut accumulator = ~[];
1955 for element in vector.iter() {
1956 accumulator.push(function(element));
1962 When defined with type parameters, as denoted by `<T, U>`, this
1963 function can be applied to any type of vector, as long as the type of
1964 `function`'s argument and the type of the vector's contents agree with
1967 Inside a generic function, the names of the type parameters
1968 (capitalized by convention) stand for opaque types. All you can do
1969 with instances of these types is pass them around: you can't apply any
1970 operations to them or pattern-match on them. Note that instances of
1971 generic types are often passed by pointer. For example, the parameter
1972 `function()` is supplied with a pointer to a value of type `T` and not
1973 a value of type `T` itself. This ensures that the function works with
1974 the broadest set of types possible, since some types are expensive or
1975 illegal to copy and pass by value.
1977 Generic `type`, `struct`, and `enum` declarations follow the same pattern:
1980 use std::hashmap::HashMap;
1981 type Set<T> = HashMap<T, ()>;
1993 These declarations can be instantiated to valid types like `Set<int>`,
1994 `Stack<int>`, and `Option<int>`.
1996 The last type in that example, `Option`, appears frequently in Rust code.
1997 Because Rust does not have null pointers (except in unsafe code), we need
1998 another way to write a function whose result isn't defined on every possible
1999 combination of arguments of the appropriate types. The usual way is to write
2000 a function that returns `Option<T>` instead of `T`.
2003 # struct Point { x: f64, y: f64 }
2004 # enum Shape { Circle(Point, f64), Rectangle(Point, Point) }
2005 fn radius(shape: Shape) -> Option<f64> {
2007 Circle(_, radius) => Some(radius),
2008 Rectangle(..) => None
2013 The Rust compiler compiles generic functions very efficiently by
2014 *monomorphizing* them. *Monomorphization* is a fancy name for a simple
2015 idea: generate a separate copy of each generic function at each call site,
2016 a copy that is specialized to the argument
2017 types and can thus be optimized specifically for them. In this
2018 respect, Rust's generics have similar performance characteristics to
2023 Within a generic function -- that is, a function parameterized by a
2024 type parameter, say, `T` -- the operations we can do on arguments of
2025 type `T` are quite limited. After all, since we don't know what type
2026 `T` will be instantiated with, we can't safely modify or query values
2027 of type `T`. This is where _traits_ come into play. Traits are Rust's
2028 most powerful tool for writing polymorphic code. Java developers will
2029 see them as similar to Java interfaces, and Haskellers will notice
2030 their similarities to type classes. Rust's traits give us a way to
2031 express *bounded polymorphism*: by limiting the set of possible types
2032 that a type parameter could refer to, they expand the number of
2033 operations we can safely perform on arguments of that type.
2035 As motivation, let us consider copying of values in Rust. The `clone`
2036 method is not defined for values of every type. One reason is
2037 user-defined destructors: copying a value of a type that has a
2038 destructor could result in the destructor running multiple times.
2039 Therefore, values of types that have destructors cannot be copied
2040 unless we explicitly implement `clone` for them.
2042 This complicates handling of generic functions.
2043 If we have a function with a type parameter `T`,
2044 can we copy values of type `T` inside that function?
2046 and if we try to run the following code the compiler will complain.
2049 // This does not compile
2050 fn head_bad<T>(v: &[T]) -> T {
2051 v[0] // error: copying a non-copyable value
2055 However, we can tell the compiler
2056 that the `head` function is only for copyable types.
2057 In Rust, copyable types are those that _implement the `Clone` trait_.
2058 We can then explicitly create a second copy of the value we are returning
2059 by calling the `clone` method:
2063 fn head<T: Clone>(v: &[T]) -> T {
2068 The bounded type parameter `T: Clone` says that `head`
2069 can be called on an argument of type `&[T]` for any `T`,
2070 so long as there is an implementation of the
2071 `Clone` trait for `T`.
2072 When instantiating a generic function,
2073 we can only instantiate it with types
2074 that implement the correct trait,
2075 so we could not apply `head` to a vector whose elements are of some type
2076 that does not implement `Clone`.
2078 While most traits can be defined and implemented by user code,
2079 three traits are automatically derived and implemented
2080 for all applicable types by the compiler,
2081 and may not be overridden:
2083 * `Send` - Sendable types.
2085 unless they contain managed boxes, managed closures, or references.
2087 * `Freeze` - Constant (immutable) types.
2088 These are types that do not contain anything intrinsically mutable.
2089 Intrinsically mutable values include `Cell` in the standard library.
2091 * `'static` - Non-borrowed types.
2092 These are types that do not contain any data whose lifetime is bound to
2093 a particular stack frame. These are types that do not contain any
2094 references, or types where the only contained references
2095 have the `'static` lifetime.
2097 > ***Note:*** These two traits were referred to as 'kinds' in earlier
2098 > iterations of the language, and often still are.
2100 Additionally, the `Drop` trait is used to define destructors. This
2101 trait provides one method called `drop`, which is automatically
2102 called when a value of the type that implements this trait is
2103 destroyed, either because the value went out of scope or because the
2104 garbage collector reclaimed it.
2111 impl Drop for TimeBomb {
2112 fn drop(&mut self) {
2113 for _ in range(0, self.explosivity) {
2120 It is illegal to call `drop` directly. Only code inserted by the compiler
2123 ## Declaring and implementing traits
2125 At its simplest, a trait is a set of zero or more _method signatures_.
2126 For example, we could declare the trait
2127 `Printable` for things that can be printed to the console,
2128 with a single method signature:
2136 We say that the `Printable` trait _provides_ a `print` method with the
2137 given signature. This means that we can call `print` on an argument
2138 of any type that implements the `Printable` trait.
2140 Rust's built-in `Send` and `Freeze` types are examples of traits that
2141 don't provide any methods.
2143 Traits may be implemented for specific types with [impls]. An impl for
2144 a particular trait gives an implementation of the methods that
2145 trait provides. For instance, the following impls of
2146 `Printable` for `int` and `~str` give implementations of the `print`
2152 # trait Printable { fn print(&self); }
2153 impl Printable for int {
2154 fn print(&self) { println!("{:?}", *self) }
2157 impl Printable for ~str {
2158 fn print(&self) { println!("{}", *self) }
2165 Methods defined in an impl for a trait may be called just like
2166 any other method, using dot notation, as in `1.print()`.
2168 ## Default method implementations in trait definitions
2170 Sometimes, a method that a trait provides will have the same
2171 implementation for most or all of the types that implement that trait.
2172 For instance, suppose that we wanted `bool`s and `f32`s to be
2173 printable, and that we wanted the implementation of `print` for those
2174 types to be exactly as it is for `int`, above:
2177 # trait Printable { fn print(&self); }
2178 impl Printable for f32 {
2179 fn print(&self) { println!("{:?}", *self) }
2182 impl Printable for bool {
2183 fn print(&self) { println!("{:?}", *self) }
2190 This works fine, but we've now repeated the same definition of `print`
2191 in three places. Instead of doing that, we can simply include the
2192 definition of `print` right in the trait definition, instead of just
2193 giving its signature. That is, we can write the following:
2197 // Default method implementation
2198 fn print(&self) { println!("{:?}", *self) }
2201 impl Printable for int {}
2203 impl Printable for ~str {
2204 fn print(&self) { println!("{}", *self) }
2207 impl Printable for bool {}
2209 impl Printable for f32 {}
2217 Here, the impls of `Printable` for `int`, `bool`, and `f32` don't
2218 need to provide an implementation of `print`, because in the absence
2219 of a specific implementation, Rust just uses the _default method_
2220 provided in the trait definition. Depending on the trait, default
2221 methods can save a great deal of boilerplate code from having to be
2222 written in impls. Of course, individual impls can still override the
2223 default method for `print`, as is being done above in the impl for
2226 ## Type-parameterized traits
2228 Traits may be parameterized by type variables. For example, a trait
2229 for generalized sequence types might look like the following:
2233 fn length(&self) -> uint;
2236 impl<T> Seq<T> for ~[T] {
2237 fn length(&self) -> uint { self.len() }
2241 The implementation has to explicitly declare the type parameter that
2242 it binds, `T`, before using it to specify its trait type. Rust
2243 requires this declaration because the `impl` could also, for example,
2244 specify an implementation of `Seq<int>`. The trait type (appearing
2245 between `impl` and `for`) *refers* to a type, rather than
2248 The type parameters bound by a trait are in scope in each of the
2249 method declarations. So, re-declaring the type parameter
2250 `T` as an explicit type parameter for `len`, in either the trait or
2251 the impl, would be a compile-time error.
2253 Within a trait definition, `Self` is a special type that you can think
2254 of as a type parameter. An implementation of the trait for any given
2255 type `T` replaces the `Self` type parameter with `T`. The following
2256 trait describes types that support an equality operation:
2259 // In a trait, `self` refers to the self argument.
2260 // `Self` refers to the type implementing the trait.
2262 fn equals(&self, other: &Self) -> bool;
2265 // In an impl, `self` refers just to the value of the receiver
2267 fn equals(&self, other: &int) -> bool { *other == *self }
2271 Notice that in the trait definition, `equals` takes a
2272 second parameter of type `Self`.
2273 In contrast, in the `impl`, `equals` takes a second parameter of
2274 type `int`, only using `self` as the name of the receiver.
2276 Just as in type implementations, traits can define standalone (static)
2277 methods. These methods are called by prefixing the method name with the trait
2278 name and a double colon. The compiler uses type inference to decide which
2279 implementation to use.
2282 use std::f64::consts::PI;
2283 trait Shape { fn new(area: f64) -> Self; }
2284 struct Circle { radius: f64 }
2285 struct Square { length: f64 }
2287 impl Shape for Circle {
2288 fn new(area: f64) -> Circle { Circle { radius: (area / PI).sqrt() } }
2290 impl Shape for Square {
2291 fn new(area: f64) -> Square { Square { length: (area).sqrt() } }
2295 let c: Circle = Shape::new(area);
2296 let s: Square = Shape::new(area);
2299 ## Bounded type parameters and static method dispatch
2301 Traits give us a language for defining predicates on types, or
2302 abstract properties that types can have. We can use this language to
2303 define _bounds_ on type parameters, so that we can then operate on
2307 # trait Printable { fn print(&self); }
2308 fn print_all<T: Printable>(printable_things: ~[T]) {
2309 for thing in printable_things.iter() {
2315 Declaring `T` as conforming to the `Printable` trait (as we earlier
2316 did with `Clone`) makes it possible to call methods from that trait
2317 on values of type `T` inside the function. It will also cause a
2318 compile-time error when anyone tries to call `print_all` on an array
2319 whose element type does not have a `Printable` implementation.
2321 Type parameters can have multiple bounds by separating them with `+`,
2322 as in this version of `print_all` that copies elements.
2325 # trait Printable { fn print(&self); }
2326 fn print_all<T: Printable + Clone>(printable_things: ~[T]) {
2328 while i < printable_things.len() {
2329 let copy_of_thing = printable_things[i].clone();
2330 copy_of_thing.print();
2336 Method calls to bounded type parameters are _statically dispatched_,
2337 imposing no more overhead than normal function invocation, so are
2338 the preferred way to use traits polymorphically.
2340 This usage of traits is similar to Haskell type classes.
2342 ## Trait objects and dynamic method dispatch
2344 The above allows us to define functions that polymorphically act on
2345 values of a single unknown type that conforms to a given trait.
2346 However, consider this function:
2349 # type Circle = int; type Rectangle = int;
2350 # impl Drawable for int { fn draw(&self) {} }
2351 # fn new_circle() -> int { 1 }
2352 trait Drawable { fn draw(&self); }
2354 fn draw_all<T: Drawable>(shapes: ~[T]) {
2355 for shape in shapes.iter() { shape.draw(); }
2357 # let c: Circle = new_circle();
2361 You can call that on an array of circles, or an array of rectangles
2362 (assuming those have suitable `Drawable` traits defined), but not on
2363 an array containing both circles and rectangles. When such behavior is
2364 needed, a trait name can alternately be used as a type, called
2368 # trait Drawable { fn draw(&self); }
2369 fn draw_all(shapes: &[@Drawable]) {
2370 for shape in shapes.iter() { shape.draw(); }
2374 In this example, there is no type parameter. Instead, the `@Drawable`
2375 type denotes any managed box value that implements the `Drawable`
2376 trait. To construct such a value, you use the `as` operator to cast a
2380 # type Circle = int; type Rectangle = bool;
2381 # trait Drawable { fn draw(&self); }
2382 # fn new_circle() -> Circle { 1 }
2383 # fn new_rectangle() -> Rectangle { true }
2384 # fn draw_all(shapes: &[@Drawable]) {}
2386 impl Drawable for Circle { fn draw(&self) { ... } }
2387 impl Drawable for Rectangle { fn draw(&self) { ... } }
2389 let c: @Circle = @new_circle();
2390 let r: @Rectangle = @new_rectangle();
2391 draw_all([c as @Drawable, r as @Drawable]);
2394 We omit the code for `new_circle` and `new_rectangle`; imagine that
2395 these just return `Circle`s and `Rectangle`s with a default size. Note
2396 that, like strings and vectors, objects have dynamic size and may
2397 only be referred to via one of the pointer types.
2398 Other pointer types work as well.
2399 Casts to traits may only be done with compatible pointers so,
2400 for example, an `@Circle` may not be cast to an `~Drawable`.
2403 # type Circle = int; type Rectangle = int;
2404 # trait Drawable { fn draw(&self); }
2405 # impl Drawable for int { fn draw(&self) {} }
2406 # fn new_circle() -> int { 1 }
2407 # fn new_rectangle() -> int { 2 }
2409 let boxy: @Drawable = @new_circle() as @Drawable;
2411 let owny: ~Drawable = ~new_circle() as ~Drawable;
2412 // A borrowed object
2413 let stacky: &Drawable = &new_circle() as &Drawable;
2416 Method calls to trait types are _dynamically dispatched_. Since the
2417 compiler doesn't know specifically which functions to call at compile
2418 time, it uses a lookup table (also known as a vtable or dictionary) to
2419 select the method to call at runtime.
2421 This usage of traits is similar to Java interfaces.
2423 By default, each of the three storage classes for traits enforce a
2424 particular set of built-in kinds that their contents must fulfill in
2425 order to be packaged up in a trait object of that storage class.
2427 * The contents of owned traits (`~Trait`) must fulfill the `Send` bound.
2428 * The contents of managed traits (`@Trait`) must fulfill the `'static` bound.
2429 * The contents of reference traits (`&Trait`) are not constrained by any bound.
2431 Consequently, the trait objects themselves automatically fulfill their
2432 respective kind bounds. However, this default behavior can be overridden by
2433 specifying a list of bounds on the trait type, for example, by writing `~Trait:`
2434 (which indicates that the contents of the owned trait need not fulfill any
2435 bounds), or by writing `~Trait:Send+Freeze`, which indicates that in addition
2436 to fulfilling `Send`, contents must also fulfill `Freeze`, and as a consequence,
2437 the trait itself fulfills `Freeze`.
2439 * `~Trait:Send` is equivalent to `~Trait`.
2440 * `@Trait:'static` is equivalent to `@Trait`.
2441 * `&Trait:` is equivalent to `&Trait`.
2443 Builtin kind bounds can also be specified on closure types in the same way (for
2444 example, by writing `fn:Freeze()`), and the default behaviours are the same as
2445 for traits of the same storage class.
2447 ## Trait inheritance
2449 We can write a trait declaration that _inherits_ from other traits, called _supertraits_.
2450 Types that implement a trait must also implement its supertraits.
2452 we can define a `Circle` trait that inherits from `Shape`.
2455 trait Shape { fn area(&self) -> f64; }
2456 trait Circle : Shape { fn radius(&self) -> f64; }
2459 Now, we can implement `Circle` on a type only if we also implement `Shape`.
2462 use std::f64::consts::PI;
2463 # trait Shape { fn area(&self) -> f64; }
2464 # trait Circle : Shape { fn radius(&self) -> f64; }
2465 # struct Point { x: f64, y: f64 }
2466 # fn square(x: f64) -> f64 { x * x }
2467 struct CircleStruct { center: Point, radius: f64 }
2468 impl Circle for CircleStruct {
2469 fn radius(&self) -> f64 { (self.area() / PI).sqrt() }
2471 impl Shape for CircleStruct {
2472 fn area(&self) -> f64 { PI * square(self.radius) }
2476 Notice that methods of `Circle` can call methods on `Shape`, as our
2477 `radius` implementation calls the `area` method.
2478 This is a silly way to compute the radius of a circle
2479 (since we could just return the `radius` field), but you get the idea.
2481 In type-parameterized functions,
2482 methods of the supertrait may be called on values of subtrait-bound type parameters.
2483 Refering to the previous example of `trait Circle : Shape`:
2486 # trait Shape { fn area(&self) -> f64; }
2487 # trait Circle : Shape { fn radius(&self) -> f64; }
2488 fn radius_times_area<T: Circle>(c: T) -> f64 {
2489 // `c` is both a Circle and a Shape
2490 c.radius() * c.area()
2494 Likewise, supertrait methods may also be called on trait objects.
2497 use std::f64::consts::PI;
2498 # trait Shape { fn area(&self) -> f64; }
2499 # trait Circle : Shape { fn radius(&self) -> f64; }
2500 # struct Point { x: f64, y: f64 }
2501 # struct CircleStruct { center: Point, radius: f64 }
2502 # impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / PI).sqrt() } }
2503 # impl Shape for CircleStruct { fn area(&self) -> f64 { PI * square(self.radius) } }
2505 let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f};
2506 let mycircle: @Circle = concrete as @Circle;
2507 let nonsense = mycircle.radius() * mycircle.area();
2510 > ***Note:*** Trait inheritance does not actually work with objects yet
2512 ## Deriving implementations for traits
2514 A small number of traits in `std` and `extra` can have implementations
2515 that can be automatically derived. These instances are specified by
2516 placing the `deriving` attribute on a data type declaration. For
2517 example, the following will mean that `Circle` has an implementation
2518 for `Eq` and can be used with the equality operators, and that a value
2519 of type `ABC` can be randomly generated and converted to a string:
2523 struct Circle { radius: f64 }
2525 #[deriving(Rand, ToStr)]
2526 enum ABC { A, B, C }
2529 The full list of derivable traits is `Eq`, `TotalEq`, `Ord`,
2530 `TotalOrd`, `Encodable` `Decodable`, `Clone`, `DeepClone`,
2531 `IterBytes`, `Rand`, `Default`, `Zero`, and `ToStr`.
2533 # Crates and the module system
2535 Rust's module system is very powerful, but because of that also somewhat complex.
2536 Nevertheless, this section will try to explain every important aspect of it.
2540 In order to speak about the module system, we first need to define the medium it exists in:
2542 Let's say you've written a program or a library, compiled it, and got the resulting binary.
2543 In Rust, the content of all source code that the compiler directly had to compile in order to end up with
2544 that binary is collectively called a 'crate'.
2546 For example, for a simple hello world program your crate only consists of this code:
2551 println!("Hello world!");
2555 A crate is also the unit of independent compilation in Rust: `rustc` always compiles a single crate at a time,
2556 from which it produces either a library or an executable.
2558 Note that merely using an already compiled library in your code does not make it part of your crate.
2560 ## The module hierarchy
2562 For every crate, all the code in it is arranged in a hierarchy of modules starting with a single
2563 root module. That root module is called the 'crate root'.
2565 All modules in a crate below the crate root are declared with the `mod` keyword:
2568 // This is the crate root
2571 // This is the body of module 'farm' declared in the crate root.
2573 fn chicken() { println!("cluck cluck"); }
2574 fn cow() { println!("mooo"); }
2577 // Body of module 'barn'
2579 fn hay() { println!("..."); }
2584 println!("Hello farm!");
2588 As you can see, your module hierarchy is now three modules deep: There is the crate root, which contains your `main()`
2589 function, and the module `farm`. The module `farm` also contains two functions and a third module `barn`,
2590 which contains a function `hay`.
2592 (In case you already stumbled over `extern mod`: It isn't directly related to a bare `mod`, we'll get to it later. )
2594 ## Paths and visibility
2596 We've now defined a nice module hierarchy. But how do we access the items in it from our `main` function?
2597 One way to do it is to simply fully qualifying it:
2601 fn chicken() { println!("cluck cluck"); }
2606 println!("Hello chicken!");
2608 ::farm::chicken(); // Won't compile yet, see further down
2612 The `::farm::chicken` construct is what we call a 'path'.
2614 Because it's starting with a `::`, it's also a 'global path', which qualifies
2615 an item by its full path in the module hierarchy relative to the crate root.
2617 If the path were to start with a regular identifier, like `farm::chicken`, it
2618 would be a 'local path' instead. We'll get to them later.
2620 Now, if you actually tried to compile this code example, you'll notice that you
2621 get a `function 'chicken' is private` error. That's because by default, items
2622 (`fn`, `struct`, `static`, `mod`, ...) are private.
2624 To make them visible outside their containing modules, you need to mark them
2625 _public_ with `pub`:
2629 pub fn chicken() { println!("cluck cluck"); }
2630 pub fn cow() { println!("mooo"); }
2635 println!("Hello chicken!");
2636 ::farm::chicken(); // This compiles now
2640 Visibility restrictions in Rust exist only at module boundaries. This
2641 is quite different from most object-oriented languages that also
2642 enforce restrictions on objects themselves. That's not to say that
2643 Rust doesn't support encapsulation: both struct fields and methods can
2644 be private. But this encapsulation is at the module level, not the
2647 For convenience, fields are _public_ by default, and can be made _private_ with
2652 # pub type Chicken = int;
2653 # struct Human(int);
2654 # impl Human { pub fn rest(&self) { } }
2655 # pub fn make_me_a_farm() -> Farm { Farm { chickens: ~[], farmer: Human(0) } }
2657 priv chickens: ~[Chicken],
2662 fn feed_chickens(&self) { ... }
2663 pub fn add_chicken(&self, c: Chicken) { ... }
2666 pub fn feed_animals(farm: &Farm) {
2667 farm.feed_chickens();
2672 let f = make_me_a_farm();
2673 f.add_chicken(make_me_a_chicken());
2674 farm::feed_animals(&f);
2677 // This wouldn't compile because both are private:
2678 // f.feed_chickens();
2679 // let chicken_counter = f.chickens.len();
2681 # fn make_me_a_farm() -> farm::Farm { farm::make_me_a_farm() }
2682 # fn make_me_a_chicken() -> farm::Chicken { 0 }
2685 Exact details and specifications about visibility rules can be found in the Rust
2688 ## Files and modules
2690 One important aspect about Rusts module system is that source files are not important:
2691 You define a module hierarchy, populate it with all your definitions, define visibility,
2692 maybe put in a `fn main()`, and that's it: No need to think about source files.
2694 The only file that's relevant is the one that contains the body of your crate root,
2695 and it's only relevant because you have to pass that file to `rustc` to compile your crate.
2697 And in principle, that's all you need: You can write any Rust program as one giant source file that contains your
2698 crate root and everything below it in `mod ... { ... }` declarations.
2700 However, in practice you usually want to split you code up into multiple source files to make it more manageable.
2701 In order to do that, Rust allows you to move the body of any module into it's own source file, which works like this:
2703 If you declare a module without its body, like `mod foo;`, the compiler will look for the
2704 files `foo.rs` and `foo/mod.rs` inside some directory (usually the same as of the source file containing
2705 the `mod foo;`). If it finds either, it uses the content of that file as the body of the module.
2706 If it finds both, that's a compile error.
2708 So, if we want to move the content of `mod farm` into it's own file, it would look like this:
2711 // main.rs - contains body of the crate root
2712 mod farm; // Compiler will look for 'farm.rs' and 'farm/mod.rs'
2715 println!("Hello farm!");
2721 // farm.rs - contains body of module 'farm' in the crate root
2722 pub fn chicken() { println!("cluck cluck"); }
2723 pub fn cow() { println!("mooo"); }
2726 pub fn hay() { println!("..."); }
2731 In short, `mod foo;` is just syntactic sugar for `mod foo { /* content of <...>/foo.rs or <...>/foo/mod.rs */ }`.
2733 This also means that having two or more identical `mod foo;` somewhere
2734 in your crate hierarchy is generally a bad idea,
2735 just like copy-and-paste-ing a module into two or more places is one.
2736 Both will result in duplicate and mutually incompatible definitions.
2738 The directory the compiler looks in for those two files is determined by starting with
2739 the same directory as the source file that contains the `mod foo;` declaration, and concatenating to that a
2740 path equivalent to the relative path of all nested `mod { ... }` declarations the `mod foo;`
2741 is contained in, if any.
2743 For example, given a file with this module body:
2756 The compiler would then try all these files:
2763 src/animals/fish/mod.rs
2765 src/animals/mammals/humans.rs
2766 src/animals/mammals/humans/mod.rs
2769 Keep in mind that identical module hierachies can still lead to different path lookups
2770 depending on how and where you've moved a module body to its own file.
2771 For example, if we move the `animals` module above into its own file...
2780 // src/animals.rs or src/animals/mod.rs
2787 ...then the source files of `mod animals`'s submodules can
2788 either be placed right next to that of its parents, or in a subdirectory if `animals` source file is:
2794 src/animals.rs - if file sits next to that of parent module's:
2798 src/mammals/humans.rs
2799 src/mammals/humans/mod.rs
2801 src/animals/mod.rs - if file is in it's own subdirectory:
2803 src/animals/fish/mod.rs
2805 src/animals/mammals/humans.rs
2806 src/animals/mammals/humans/mod.rs
2810 These rules allow you to have both small modules that only need
2811 to consist of one source file each and can be conveniently placed right next to each other,
2812 and big complicated modules that group the source files of submodules in subdirectories.
2814 If you need to circumvent the defaults, you can also overwrite the path a `mod foo;` would take:
2817 #[path="../../area51/alien.rs"]
2821 ## Importing names into the local scope
2823 Always referring to definitions in other modules with their global
2824 path gets old really fast, so Rust has a way to import
2825 them into the local scope of your module: `use`-statements.
2827 They work like this: At the beginning of any module body, `fn` body, or any other block
2828 you can write a list of `use`-statements, consisting of the keyword `use` and a __global path__ to an item
2829 without the `::` prefix. For example, this imports `cow` into the local scope:
2833 # mod farm { pub fn cow() { println!("I'm a hidden ninja cow!") } }
2834 # fn main() { cow() }
2837 The path you give to `use` is per default global, meaning relative to the crate root,
2838 no matter how deep the module hierarchy is, or whether the module body it's written in
2839 is contained in its own file (remember: files are irrelevant).
2841 This is different to other languages, where you often only find a single import construct that combines the semantic
2842 of `mod foo;` and `use`-statements, and which tend to work relative to the source file or use an absolute file path
2843 - Rubys `require` or C/C++'s `#include` come to mind.
2845 However, it's also possible to import things relative to the module of the `use`-statement:
2846 Adding a `super::` in front of the path will start in the parent module,
2847 while adding a `self::` prefix will start in the current module:
2851 # pub fn some_parent_item(){ println!("...") }
2853 use super::some_parent_item;
2854 use self::some_child_module::some_item;
2855 # pub fn bar() { some_parent_item(); some_item() }
2856 # pub mod some_child_module { pub fn some_item() {} }
2861 Again - relative to the module, not to the file.
2863 Imports are also shadowed by local definitions:
2864 For each name you mention in a module/block, `rust`
2865 will first look at all items that are defined locally,
2866 and only if that results in no match look at items you brought in
2867 scope with corresponding `use` statements.
2870 # // FIXME: Allow unused import in doc test
2873 # mod farm { pub fn cow() { println!("Hidden ninja cow is hidden.") } }
2874 fn cow() { println!("Mooo!") }
2877 cow() // resolves to the locally defined cow() function
2881 To make this behavior more obvious, the rule has been made that `use`-statement always need to be written
2882 before any declaration, like in the example above. This is a purely artificial rule introduced
2883 because people always assumed they shadowed each other based on order, despite the fact that all items in rust are
2884 mutually recursive, order independent definitions.
2886 One odd consequence of that rule is that `use` statements also go in front of any `mod` declaration,
2887 even if they refer to things inside them:
2892 pub fn cow() { println!("Moooooo?") }
2898 This is what our `farm` example looks like with `use` statements:
2906 pub fn chicken() { println!("cluck cluck"); }
2907 pub fn cow() { println!("mooo"); }
2910 pub fn hay() { println!("..."); }
2915 println!("Hello farm!");
2917 // Can now refer to those names directly:
2924 And here an example with multiple files:
2927 // a.rs - crate root
2930 fn main() { foo(); }
2937 pub fn foo() { bar(); }
2942 pub fn bar() { println!("Baz!"); }
2946 There also exist two short forms for importing multiple names at once:
2948 1. Explicit mention multiple names as the last element of an `use` path:
2951 use farm::{chicken, cow};
2953 # pub fn cow() { println!("Did I already mention how hidden and ninja I am?") }
2954 # pub fn chicken() { println!("I'm Bat-chicken, guardian of the hidden tutorial code.") }
2956 # fn main() { cow(); chicken() }
2959 2. Import everything in a module with a wildcard:
2964 # pub fn cow() { println!("Bat-chicken? What a stupid name!") }
2965 # pub fn chicken() { println!("Says the 'hidden ninja' cow.") }
2967 # fn main() { cow(); chicken() }
2970 > ***Note:*** This feature of the compiler is currently gated behind the
2971 > `#[feature(globs)]` directive. More about these directives can be found in
2974 However, that's not all. You can also rename an item while you're bringing it into scope:
2977 use egg_layer = farm::chicken;
2978 # mod farm { pub fn chicken() { println!("Laying eggs is fun!") } }
2986 In general, `use` creates an local alias:
2987 An alternate path and a possibly different name to access the same item,
2988 without touching the original, and with both being interchangeable.
2990 ## Reexporting names
2992 It is also possible to reexport items to be accessible under your module.
2994 For that, you write `pub use`:
2998 pub use self::barn::hay;
3000 pub fn chicken() { println!("cluck cluck"); }
3001 pub fn cow() { println!("mooo"); }
3004 pub fn hay() { println!("..."); }
3015 Just like in normal `use` statements, the exported names
3016 merely represent an alias to the same thing and can also be renamed.
3018 The above example also demonstrate what you can use `pub use` for:
3019 The nested `barn` module is private, but the `pub use` allows users
3020 of the module `farm` to access a function from `barn` without needing
3021 to know that `barn` exists.
3023 In other words, you can use them to decouple an public api from their internal implementation.
3027 So far we've only talked about how to define and structure your own crate.
3029 However, most code out there will want to use preexisting libraries,
3030 as there really is no reason to start from scratch each time you start a new project.
3032 In Rust terminology, we need a way to refer to other crates.
3034 For that, Rust offers you the `extern mod` declaration:
3038 // extra ships with Rust, you'll find more details further down.
3041 // The rational number '1/2':
3042 let one_half = ::extra::rational::Ratio::new(1, 2);
3046 Despite its name, `extern mod` is a distinct construct from regular `mod` declarations:
3047 A statement of the form `extern mod foo;` will cause `rustc` to search for the crate `foo`,
3048 and if it finds a matching binary it lets you use it from inside your crate.
3050 The effect it has on your module hierarchy mirrors aspects of both `mod` and `use`:
3052 - Like `mod`, it causes `rustc` to actually emit code:
3053 The linkage information the binary needs to use the library `foo`.
3055 - But like `use`, all `extern mod` statements that refer to the same library are interchangeable,
3056 as each one really just presents an alias to an external module (the crate root of the library
3057 you're linking against).
3059 Remember how `use`-statements have to go before local declarations because the latter shadows the former?
3060 Well, `extern mod` statements also have their own rules in that regard:
3061 Both `use` and local declarations can shadow them, so the rule is that `extern mod` has to go in front
3062 of both `use` and local declarations.
3064 Which can result in something like this:
3070 use extra::rational::Ratio;
3073 pub fn dog() { println!("woof"); }
3078 let a_third = Ratio::new(1, 3);
3082 It's a bit weird, but it's the result of shadowing rules that have been set that way because
3083 they model most closely what people expect to shadow.
3087 If you use `extern mod`, per default `rustc` will look for libraries in the library search path (which you can
3088 extend with the `-L` switch).
3090 However, Rust also ships with rustpkg, a package manager that is able to automatically download and build
3091 libraries if you use it for building your crate. How it works is explained [here][rustpkg],
3092 but for this tutorial it's only important to know that you can optionally annotate an
3093 `extern mod` statement with a package id that rustpkg can use to identify it:
3096 extern mod rust = "github.com/mozilla/rust"; // pretend Rust is a simple library
3099 ## Crate metadata and settings
3101 For every crate you can define a number of metadata items, such as link name, version or author.
3102 You can also toggle settings that have crate-global consequences. Both mechanism
3103 work by providing attributes in the crate root.
3105 For example, Rust uniquely identifies crates by their link metadata, which includes
3106 the link name and the version. It also hashes the filename and the symbols in a binary
3107 based on the link metadata, allowing you to use two different versions of the same library in a crate
3110 Therefore, if you plan to compile your crate as a library, you should annotate it with that information:
3115 # #[crate_type = "lib"];
3117 #[crate_id = "farm#2.5"];
3123 You can also specify package ID information in a `extern mod` statement. For
3124 example, these `extern mod` statements would both accept and select the
3129 extern mod farm = "farm#2.5";
3130 extern mod my_farm = "farm";
3133 Other crate settings and metadata include things like enabling/disabling certain errors or warnings,
3134 or setting the crate type (library or executable) explicitly:
3140 // This crate is a library ("bin" is the default)
3141 #[crate_id = "farm#2.5"];
3142 #[crate_type = "lib"];
3144 // Turn on a warning
3145 #[warn(non_camel_case_types)]
3149 > ***Note:*** The rules regarding package IDs, both as attributes and as used
3150 in `extern mod`, as well as their interaction with `rustpkg` are
3151 currently not clearly defined and will likely change in the
3154 ## A minimal example
3156 Now for something that you can actually compile yourself.
3158 We define two crates, and use one of them as a library in the other.
3162 #[crate_id = "world#0.42"];
3164 pub fn explore() -> &'static str { "world" }
3171 fn main() { println!("hello {}", world::explore()); }
3174 Now compile and run like this (adjust to your platform if necessary):
3177 > rustc --lib world.rs # compiles libworld-<HASH>-0.42.so
3178 > rustc main.rs -L . # compiles main
3183 Notice that the library produced contains the version in the file name
3184 as well as an inscrutable string of alphanumerics. As explained in the previous paragraph,
3185 these are both part of Rust's library versioning scheme. The alphanumerics are
3186 a hash representing the crates package ID.
3188 ## The standard library and the prelude
3190 While reading the examples in this tutorial, you might have asked yourself where all
3191 those magical predefined items like `range` are coming from.
3193 The truth is, there's nothing magical about them: They are all defined normally
3194 in the `std` library, which is a crate that ships with Rust.
3196 The only magical thing that happens is that `rustc` automatically inserts this line into your crate root:
3202 As well as this line into every module body:
3205 use std::prelude::*;
3208 The role of the `prelude` module is to re-export common definitions from `std`.
3210 This allows you to use common types and functions like `Option<T>` or `range`
3211 without needing to import them. And if you need something from `std` that's not in the prelude,
3212 you just have to import it with an `use` statement.
3214 For example, it re-exports `range` which is defined in `std::iter::range`:
3217 use iter_range = std::iter::range;
3220 // range is imported by default
3221 for _ in range(0, 10) {}
3223 // Doesn't hinder you from importing it under a different name yourself
3224 for _ in iter_range(0, 10) {}
3226 // Or from not using the automatic import.
3227 for _ in ::std::iter::range(0, 10) {}
3231 Both auto-insertions can be disabled with an attribute if necessary:
3234 // In the crate root:
3240 #[no_implicit_prelude];
3243 See the [API documentation][stddoc] for details.
3245 [stddoc]: std/index.html
3247 ## The extra library
3249 Rust also ships with the [extra library], an accumulation of useful things,
3250 that are however not important enough to deserve a place in the standard
3251 library. You can use them by linking to `extra` with an `extern mod extra;`.
3253 [extra library]: extra/index.html
3255 Right now `extra` contains those definitions directly, but in the future it will likely just
3256 re-export a bunch of 'officially blessed' crates that get managed with `rustpkg`.
3260 Now that you know the essentials, check out any of the additional
3261 guides on individual topics.
3263 * [Pointers][pointers]
3264 * [Lifetimes][lifetimes]
3265 * [Tasks and communication][tasks]
3267 * [The foreign function interface][ffi]
3268 * [Containers and iterators][container]
3269 * [Error-handling and Conditions][conditions]
3270 * [Packaging up Rust code][rustpkg]
3271 * [Documenting Rust code][rustdoc]
3272 * [Testing Rust code][testing]
3273 * [The Rust Runtime][runtime]
3275 There is further documentation on the [wiki], however those tend to be even more out of date as this document.
3277 [pointers]: guide-pointers.html
3278 [lifetimes]: guide-lifetimes.html
3279 [tasks]: guide-tasks.html
3280 [macros]: guide-macros.html
3281 [ffi]: guide-ffi.html
3282 [container]: guide-container.html
3283 [conditions]: guide-conditions.html
3284 [rustpkg]: guide-rustpkg.html
3285 [testing]: guide-testing.html
3286 [runtime]: guide-runtime.html
3287 [rustdoc]: rustdoc.html
3288 [wiki]: https://github.com/mozilla/rust/wiki/Docs
3290 [wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools