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 The Rust compiler currently must be built from a [tarball], unless you
61 are on Windows, in which case using the [installer][win-exe] is
64 Since the Rust compiler is written in Rust, it must be built by
65 a precompiled "snapshot" version of itself (made in an earlier state
66 of development). As such, source builds require a connection to
67 the Internet, to fetch snapshots, and an OS that can execute the
68 available snapshot binaries.
70 Snapshot binaries are currently built and tested on several platforms:
72 * Windows (7, Server 2008 R2), x86 only
73 * Linux (various distributions), x86 and x86-64
74 * OSX 10.6 ("Snow Leopard") or greater, x86 and x86-64
76 You may find that other platforms work, but these are our "tier 1"
77 supported build environments that are most likely to work.
79 > ***Note:*** Windows users should read the detailed
80 > "[getting started][wiki-start]" notes on the wiki. Even when using
81 > the binary installer, the Windows build requires a MinGW installation,
82 > the precise details of which are not discussed here. Finally, `rustc` may
83 > need to be [referred to as `rustc.exe`][bug-3319]. It's a bummer, we
86 [bug-3319]: https://github.com/mozilla/rust/issues/3319
87 [wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust
89 To build from source you will also need the following prerequisite
92 * g++ 4.4 or clang++ 3.x
93 * python 2.6 or later (but not 3.x)
95 * gnu make 3.81 or later
98 If you've fulfilled those prerequisites, something along these lines
102 $ curl -O http://static.rust-lang.org/dist/rust-0.7.tar.gz
103 $ tar -xzf rust-0.7.tar.gz
106 $ make && make install
109 You may need to use `sudo make install` if you do not normally have
110 permission to modify the destination directory. The install locations
111 can be adjusted by passing a `--prefix` argument to
112 `configure`. Various other options are also supported: pass `--help`
113 for more information on them.
115 When complete, `make install` will place several programs into
116 `/usr/local/bin`: `rustc`, the Rust compiler; `rustdoc`, the
117 API-documentation tool; `rustpkg`, the Rust package manager;
118 `rusti`, the Rust REPL; and `rust`, a tool which acts both as a unified
119 interface for them, and for a few common command line scenarios.
121 [tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz
122 [win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe
124 ## Compiling your first program
126 Rust program files are, by convention, given the extension `.rs`. Say
127 we have a file `hello.rs` containing this program:
135 If the Rust compiler was installed successfully, running `rustc
136 hello.rs` will produce an executable called `hello` (or `hello.exe` on
137 Windows) which, upon running, will likely do exactly what you expect.
139 The Rust compiler tries to provide useful information when it encounters an
140 error. If you introduce an error into the program (for example, by changing
141 `println` to some nonexistent function), and then compile it, you'll see
142 an error message like this:
145 hello.rs:2:4: 2:16 error: unresolved name: print_with_unicorns
146 hello.rs:2 print_with_unicorns("hello?");
147 ^~~~~~~~~~~~~~~~~~~~~~~
150 In its simplest form, a Rust program is a `.rs` file with some types
151 and functions defined in it. If it has a `main` function, it can be
152 compiled to an executable. Rust does not allow code that's not a
153 declaration to appear at the top level of the file: all statements must
154 live inside a function. Rust programs can also be compiled as
155 libraries, and included in other programs.
157 ## Using the rust tool
159 While using `rustc` directly to generate your executables, and then
160 running them manually is a perfectly valid way to test your code,
161 for smaller projects, prototypes, or if you're a beginner, it might be
162 more convenient to use the `rust` tool.
164 The `rust` tool provides central access to the other rust tools,
165 as well as handy shortcuts for directly running source files.
166 For example, if you have a file `foo.rs` in your current directory,
167 `rust run foo.rs` would attempt to compile it and, if successful,
168 directly run the resulting binary.
170 To get a list of all available commands, simply call `rust` without any
175 There are vim highlighting and indentation scripts in the Rust source
176 distribution under `src/etc/vim/`. There is an emacs mode under
177 `src/etc/emacs/` called `rust-mode`, but do read the instructions
178 included in that directory. In particular, if you are running emacs
179 24, then using emacs's internal package manager to install `rust-mode`
180 is the easiest way to keep it up to date. There is also a package for
181 Sublime Text 2, available both [standalone][sublime] and through
182 [Sublime Package Control][sublime-pkg], and support for Kate
183 under `src/etc/kate`.
185 There is ctags support via `src/etc/ctags.rust`, but many other
186 tools and editors are not yet supported. If you end up writing a Rust
187 mode for your favorite editor, let us know so that we can link to it.
189 [sublime]: http://github.com/dbp/sublime-rust
190 [sublime-pkg]: http://wbond.net/sublime_packages/package_control
194 Assuming you've programmed in any C-family language (C++, Java,
195 JavaScript, C#, or PHP), Rust will feel familiar. Code is arranged
196 in blocks delineated by curly braces; there are control structures
197 for branching and looping, like the familiar `if` and `while`; function
198 calls are written `myfunc(arg1, arg2)`; operators are written the same
199 and mostly have the same precedence as in C; comments are again like C;
200 module names are separated with double-colon (`::`) as with C++.
202 The main surface difference to be aware of is that the condition at
203 the head of control structures like `if` and `while` does not require
204 parentheses, while their bodies *must* be wrapped in
205 braces. Single-statement, unbraced bodies are not allowed.
208 # mod universe { pub fn recalibrate() -> bool { true } }
212 // A tricky calculation
213 if universe::recalibrate() {
220 The `let` keyword introduces a local variable. Variables are immutable by
221 default. To introduce a local variable that you can re-assign later, use `let
229 println(fmt!("count: %?", count));
234 Although Rust can almost always infer the types of local variables, you
235 can specify a variable's type by following it with a colon, then the type
236 name. Static items, on the other hand, always require a type annotation.
239 static MONSTER_FACTOR: float = 57.8;
240 let monster_size = MONSTER_FACTOR * 10.0;
241 let monster_size: int = 50;
244 Local variables may shadow earlier declarations, as in the previous example:
245 `monster_size` was first declared as a `float`, and then a second
246 `monster_size` was declared as an `int`. If you were to actually compile this
247 example, though, the compiler would determine that the first `monster_size` is
248 unused and issue a warning (because this situation is likely to indicate a
249 programmer error). For occasions where unused variables are intentional, their
250 names may be prefixed with an underscore to silence the warning, like `let
251 _monster_size = 50;`.
253 Rust identifiers start with an alphabetic
254 character or an underscore, and after that may contain any sequence of
255 alphabetic characters, numbers, or underscores. The preferred style is to
256 write function, variable, and module names with lowercase letters, using
257 underscores where they help readability, while writing types in camel case.
260 let my_variable = 100;
261 type MyType = int; // primitive types are _not_ camel case
264 ## Expressions and semicolons
266 Though it isn't apparent in all code, there is a fundamental
267 difference between Rust's syntax and predecessors like C.
268 Many constructs that are statements in C are expressions
269 in Rust, allowing code to be more concise. For example, you might
270 write a piece of code like this:
273 # let item = "salad";
277 } else if item == "muffin" {
284 But, in Rust, you don't have to repeat the name `price`:
287 # let item = "salad";
291 } else if item == "muffin" {
298 Both pieces of code are exactly equivalent: they assign a value to
299 `price` depending on the condition that holds. Note that there
300 are no semicolons in the blocks of the second snippet. This is
301 important: the lack of a semicolon after the last statement in a
302 braced block gives the whole block the value of that last expression.
304 Put another way, the semicolon in Rust *ignores the value of an expression*.
305 Thus, if the branches of the `if` had looked like `{ 4; }`, the above example
306 would simply assign `()` (nil or void) to `price`. But without the semicolon, each
307 branch has a different value, and `price` gets the value of the branch that
310 In short, everything that's not a declaration (declarations are `let` for
311 variables; `fn` for functions; and any top-level named items such as
312 [traits](#traits), [enum types](#enums), and static items) is an
313 expression, including function bodies.
316 fn is_four(x: int) -> bool {
317 // No need for a return statement. The result of the expression
318 // is used as the return value.
323 ## Primitive types and literals
325 There are general signed and unsigned integer types, `int` and `uint`,
326 as well as 8-, 16-, 32-, and 64-bit variants, `i8`, `u16`, etc.
327 Integers can be written in decimal (`144`), hexadecimal (`0x90`), or
328 binary (`0b10010000`) base. Each integral type has a corresponding literal
329 suffix that can be used to indicate the type of a literal: `i` for `int`,
330 `u` for `uint`, `i8` for the `i8` type.
332 In the absence of an integer literal suffix, Rust will infer the
333 integer type based on type annotations and function signatures in the
334 surrounding program. In the absence of any type information at all,
335 Rust will assume that an unsuffixed integer literal has type
339 let a = 1; // a is an int
340 let b = 10i; // b is an int, due to the 'i' suffix
341 let c = 100u; // c is a uint
342 let d = 1000i32; // d is an i32
345 There are three floating-point types: `float`, `f32`, and `f64`.
346 Floating-point numbers are written `0.0`, `1e6`, or `2.1e-4`.
347 Like integers, floating-point literals are inferred to the correct type.
348 Suffixes `f`, `f32`, and `f64` can be used to create literals of a specific type.
350 The keywords `true` and `false` produce literals of type `bool`.
352 Characters, the `char` type, are four-byte Unicode codepoints,
353 whose literals are written between single quotes, as in `'x'`.
354 Just like C, Rust understands a number of character escapes, using the backslash
355 character, such as `\n`, `\r`, and `\t`. String literals,
356 written between double quotes, allow the same escape sequences.
357 More on strings [later](#vectors-and-strings).
359 The nil type, written `()`, has a single value, also written `()`.
363 Rust's set of operators contains very few surprises. Arithmetic is done with
364 `*`, `/`, `%`, `+`, and `-` (multiply, quotient, remainder, add, and subtract). `-` is
365 also a unary prefix operator that negates numbers. As in C, the bitwise operators
366 `>>`, `<<`, `&`, `|`, and `^` are also supported.
368 Note that, if applied to an integer value, `!` flips all the bits (like `~` in
371 The comparison operators are the traditional `==`, `!=`, `<`, `>`,
372 `<=`, and `>=`. Short-circuiting (lazy) boolean operators are written
373 `&&` (and) and `||` (or).
375 For type casting, Rust uses the binary `as` operator. It takes an
376 expression on the left side and a type on the right side and will,
377 if a meaningful conversion exists, convert the result of the
378 expression to the given type.
382 let y: uint = x as uint;
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 `fmt!`, a `sprintf`-style text formatter that you will
393 often see in examples.
395 `fmt!` supports most of the directives that [printf][pf] supports, but unlike
396 printf, will give you a compile-time error when the types of the directives
397 don't match the types of the arguments.
400 # let mystery_object = ();
402 println(fmt!("%s is %d", "the answer", 43));
404 // %? will conveniently print any type
405 println(fmt!("what is this thing: %?", mystery_object));
408 [pf]: http://en.cppreference.com/w/cpp/io/c/fprintf
410 You can define your own syntax extensions with the macro system. For details, see the [macro tutorial][macros].
416 We've seen `if` expressions a few times already. To recap, braces are
417 compulsory, an `if` can have an optional `else` clause, and multiple
418 `if`/`else` constructs can be chained together:
422 println("that's odd");
426 println("neither true nor false");
430 The condition given to an `if` construct *must* be of type `bool` (no
431 implicit conversion happens). If the arms are blocks that have a
432 value, this value must be of the same type for every arm in which
433 control reaches the end of the block:
436 fn signum(x: int) -> int {
445 Rust's `match` construct is a generalized, cleaned-up version of C's
446 `switch` construct. You provide it with a value and a number of
447 *arms*, each labelled with a pattern, and the code compares the value
448 against each pattern in order until one matches. The matching pattern
449 executes its corresponding arm.
454 0 => println("zero"),
455 1 | 2 => println("one or two"),
456 3..10 => println("three to ten"),
457 _ => println("something else")
461 Unlike in C, there is no "falling through" between arms: only one arm
462 executes, and it doesn't have to explicitly `break` out of the
463 construct when it is finished.
465 A `match` arm consists of a *pattern*, then an arrow `=>`, followed by
466 an *action* (expression). Literals are valid patterns and match only
467 their own value. A single arm may match multiple different patterns by
468 combining them with the pipe operator (`|`), so long as every pattern
469 binds the same set of variables. Ranges of numeric literal patterns
470 can be expressed with two dots, as in `M..N`. The underscore (`_`) is
471 a wildcard pattern that matches any single value. The asterisk (`*`)
472 is a different wildcard that can match one or more fields in an `enum`
475 The patterns in a match arm are followed by a fat arrow, `=>`, then an
476 expression to evaluate. Each case is separated by commas. It's often
477 convenient to use a block expression for each case, in which case the
483 0 => { println("zero") }
484 _ => { println("something else") }
488 `match` constructs must be *exhaustive*: they must have an arm
489 covering every possible case. For example, the typechecker would
490 reject the previous example if the arm with the wildcard pattern was
493 A powerful application of pattern matching is *destructuring*:
494 matching in order to bind names to the contents of data
497 > ***Note:*** The following code makes use of tuples (`(float, float)`) which
498 > are explained in section 5.3. For now you can think of tuples as a list of
504 fn angle(vector: (float, float)) -> float {
505 let pi = float::consts::pi;
507 (0f, y) if y < 0f => 1.5 * pi,
509 (x, y) => atan(y / x)
514 A variable name in a pattern matches any value, *and* binds that name
515 to the value of the matched value inside of the arm's action. Thus, `(0f,
516 y)` matches any tuple whose first element is zero, and binds `y` to
517 the second element. `(x, y)` matches any two-element tuple, and binds both
518 elements to variables.
520 Any `match` arm can have a guard clause (written `if EXPR`), called a
521 *pattern guard*, which is an expression of type `bool` that
522 determines, after the pattern is found to match, whether the arm is
523 taken or not. The variables bound by the pattern are in scope in this
524 guard expression. The first arm in the `angle` example shows an
525 example of a pattern guard.
527 You've already seen simple `let` bindings, but `let` is a little
528 fancier than you've been led to believe. It, too, supports destructuring
529 patterns. For example, you can write this to extract the fields from a
530 tuple, introducing two variables at once: `a` and `b`.
533 # fn get_tuple_of_two_ints() -> (int, int) { (1, 1) }
534 let (a, b) = get_tuple_of_two_ints();
537 Let bindings only work with _irrefutable_ patterns: that is, patterns
538 that can never fail to match. This excludes `let` from matching
539 literals and most `enum` variants.
543 `while` denotes a loop that iterates as long as its given condition
544 (which must have type `bool`) evaluates to `true`. Inside a loop, the
545 keyword `break` aborts the loop, and `loop` aborts the current
546 iteration and continues with the next.
549 let mut cake_amount = 8;
550 while cake_amount > 0 {
555 `loop` denotes an infinite loop, and is the preferred way of writing `while true`:
561 if x % 5 == 0 { break; }
566 This code prints out a weird sequence of numbers and stops as soon as
567 it finds one that can be divided by five.
573 Rust struct types must be declared before they are used using the `struct`
574 syntax: `struct Name { field1: T1, field2: T2 [, ...] }`, where `T1`, `T2`,
575 ... denote types. To construct a struct, use the same syntax, but leave off
576 the `struct`: for example: `Point { x: 1.0, y: 2.0 }`.
578 Structs are quite similar to C structs and are even laid out the same way in
579 memory (so you can read from a Rust struct in C, and vice-versa). Use the dot
580 operator to access struct fields, as in `mypoint.x`.
589 Inherited mutability means that any field of a struct may be mutable, if the
590 struct is in a mutable slot (or a field of a struct in a mutable slot, and
593 With a value (say, `mypoint`) of such a type in a mutable location, you can do
594 `mypoint.y += 1.0`. But in an immutable location, such an assignment to a
595 struct without inherited mutability would result in a type error.
598 # struct Point { x: float, y: float }
599 let mut mypoint = Point { x: 1.0, y: 1.0 };
600 let origin = Point { x: 0.0, y: 0.0 };
602 mypoint.y += 1.0; // mypoint is mutable, and its fields as well
603 origin.y += 1.0; // ERROR: assigning to immutable field
606 `match` patterns destructure structs. The basic syntax is
607 `Name { fieldname: pattern, ... }`:
610 # struct Point { x: float, y: float }
611 # let mypoint = Point { x: 0.0, y: 0.0 };
613 Point { x: 0.0, y: yy } => { println(yy.to_str()); }
614 Point { x: xx, y: yy } => { println(xx.to_str() + " " + yy.to_str()); }
618 In general, the field names of a struct do not have to appear in the same
619 order they appear in the type. When you are not interested in all
620 the fields of a struct, a struct pattern may end with `, _` (as in
621 `Name { field1, _ }`) to indicate that you're ignoring all other fields.
622 Additionally, struct fields have a shorthand matching form that simply
623 reuses the field name as the binding name.
626 # struct Point { x: float, y: float }
627 # let mypoint = Point { x: 0.0, y: 0.0 };
629 Point { x, _ } => { println(x.to_str()) }
635 Enums are datatypes that have several alternate representations. For
636 example, consider the type shown earlier:
639 # struct Point { x: float, y: float }
641 Circle(Point, float),
642 Rectangle(Point, Point)
646 A value of this type is either a `Circle`, in which case it contains a
647 `Point` struct and a float, or a `Rectangle`, in which case it contains
648 two `Point` structs. The run-time representation of such a value
649 includes an identifier of the actual form that it holds, much like the
650 "tagged union" pattern in C, but with better static guarantees.
652 The above declaration will define a type `Shape` that can refer to
653 such shapes, and two functions, `Circle` and `Rectangle`, which can be
654 used to construct values of the type (taking arguments of the
655 specified types). So `Circle(Point { x: 0f, y: 0f }, 10f)` is the way to
658 Enum variants need not have parameters. This `enum` declaration,
659 for example, is equivalent to a C enum:
670 This declaration defines `North`, `East`, `South`, and `West` as constants,
671 all of which have type `Direction`.
673 When an enum is C-like (that is, when none of the variants have
674 parameters), it is possible to explicitly set the discriminator values
685 If an explicit discriminator is not specified for a variant, the value
686 defaults to the value of the previous variant plus one. If the first
687 variant does not have a discriminator, it defaults to 0. For example,
688 the value of `North` is 0, `East` is 1, `South` is 2, and `West` is 3.
690 When an enum is C-like, you can apply the `as` cast operator to
691 convert it to its discriminator value as an `int`.
693 For enum types with multiple variants, destructuring is the only way to
694 get at their contents. All variant constructors can be used as
695 patterns, as in this definition of `area`:
699 # struct Point {x: float, y: float}
700 # enum Shape { Circle(Point, float), Rectangle(Point, Point) }
701 fn area(sh: Shape) -> float {
703 Circle(_, size) => float::consts::pi * size * size,
704 Rectangle(Point { x, y }, Point { x: x2, y: y2 }) => (x2 - x) * (y2 - y)
709 You can write a lone `_` to ignore an individual field, and can
710 ignore all fields of a variant like: `Circle(*)`. As in their
711 introduction form, nullary enum patterns are written without
715 # struct Point { x: float, y: float }
716 # enum Direction { North, East, South, West }
717 fn point_from_direction(dir: Direction) -> Point {
719 North => Point { x: 0f, y: 1f },
720 East => Point { x: 1f, y: 0f },
721 South => Point { x: 0f, y: -1f },
722 West => Point { x: -1f, y: 0f }
727 Enum variants may also be structs. For example:
731 # struct Point { x: float, y: float }
732 # fn square(x: float) -> float { x * x }
734 Circle { center: Point, radius: float },
735 Rectangle { top_left: Point, bottom_right: Point }
737 fn area(sh: Shape) -> float {
739 Circle { radius: radius, _ } => float::consts::pi * square(radius),
740 Rectangle { top_left: top_left, bottom_right: bottom_right } => {
741 (bottom_right.x - top_left.x) * (bottom_right.y - top_left.y)
749 Tuples in Rust behave exactly like structs, except that their fields
750 do not have names. Thus, you cannot access their fields with dot notation.
751 Tuples can have any arity except for 0 (though you may consider
752 unit, `()`, as the empty tuple if you like).
755 let mytup: (int, int, float) = (10, 20, 30.0);
757 (a, b, c) => info!(a + b + (c as int))
763 Rust also has _tuple structs_, which behave like both structs and tuples,
764 except that, unlike tuples, tuple structs have names (so `Foo(1, 2)` has a
765 different type from `Bar(1, 2)`), and tuple structs' _fields_ do not have
770 struct MyTup(int, int, float);
771 let mytup: MyTup = MyTup(10, 20, 30.0);
773 MyTup(a, b, c) => info!(a + b + (c as int))
777 <a name="newtype"></a>
779 There is a special case for tuple structs with a single field, which are
780 sometimes called "newtypes" (after Haskell's "newtype" feature). These are
781 used to define new types in such a way that the new name is not just a
782 synonym for an existing type but is rather its own distinct type.
788 For convenience, you can extract the contents of such a struct with the
789 dereference (`*`) unary operator:
792 # struct GizmoId(int);
793 let my_gizmo_id: GizmoId = GizmoId(10);
794 let id_int: int = *my_gizmo_id;
797 Types like this can be useful to differentiate between data that have
798 the same type but must be used in different ways.
802 struct Centimeters(int);
805 The above definitions allow for a simple way for programs to avoid
806 confusing numbers that correspond to different units.
810 We've already seen several function definitions. Like all other static
811 declarations, such as `type`, functions can be declared both at the
812 top level and inside other functions (or in modules, which we'll come
813 back to [later](#modules-and-crates)). The `fn` keyword introduces a
814 function. A function has an argument list, which is a parenthesized
815 list of `expr: type` pairs separated by commas. An arrow `->`
816 separates the argument list and the function's return type.
819 fn line(a: int, b: int, x: int) -> int {
824 The `return` keyword immediately returns from the body of a function. It
825 is optionally followed by an expression to return. A function can
826 also return a value by having its top-level block produce an
830 fn line(a: int, b: int, x: int) -> int {
835 It's better Rust style to write a return value this way instead of
836 writing an explicit `return`. The utility of `return` comes in when
837 returning early from a function. Functions that do not return a value
838 are said to return nil, `()`, and both the return type and the return
839 value may be omitted from the definition. The following two functions
843 fn do_nothing_the_hard_way() -> () { return (); }
845 fn do_nothing_the_easy_way() { }
848 Ending the function with a semicolon like so is equivalent to returning `()`.
851 fn line(a: int, b: int, x: int) -> int { a * x + b }
852 fn oops(a: int, b: int, x: int) -> () { a * x + b; }
854 assert!(8 == line(5, 3, 1));
855 assert!(() == oops(5, 3, 1));
858 As with `match` expressions and `let` bindings, function arguments support
859 pattern destructuring. Like `let`, argument patterns must be irrefutable,
860 as in this example that unpacks the first value from a tuple and returns it.
863 fn first((value, _): (int, float)) -> int { value }
868 A *destructor* is a function responsible for cleaning up the resources used by
869 an object when it is no longer accessible. Destructors can be defined to handle
870 the release of resources like files, sockets and heap memory.
872 Objects are never accessible after their destructor has been called, so there
873 are no dynamic failures from accessing freed resources. When a task fails, the
874 destructors of all objects in the task are called.
876 The `~` sigil represents a unique handle for a memory allocation on the heap:
880 // an integer allocated on the heap
883 // the destructor frees the heap memory as soon as `y` goes out of scope
886 Rust includes syntax for heap memory allocation in the language since it's
887 commonly used, but the same semantics can be implemented by a type with a
892 Rust formalizes the concept of object ownership to delegate management of an
893 object's lifetime to either a variable or a task-local garbage collector. An
894 object's owner is responsible for managing the lifetime of the object by
895 calling the destructor, and the owner determines whether the object is mutable.
897 Ownership is recursive, so mutability is inherited recursively and a destructor
898 destroys the contained tree of owned objects. Variables are top-level owners
899 and destroy the contained object when they go out of scope. A box managed by
900 the garbage collector starts a new ownership tree, and the destructor is called
901 when it is collected.
904 // the struct owns the objects contained in the `x` and `y` fields
905 struct Foo { x: int, y: ~int }
908 // `a` is the owner of the struct, and thus the owner of the struct's fields
909 let a = Foo { x: 5, y: ~10 };
911 // when `a` goes out of scope, the destructor for the `~int` in the struct's
914 // `b` is mutable, and the mutability is inherited by the objects it owns
915 let mut b = Foo { x: 5, y: ~10 };
919 If an object doesn't contain garbage-collected boxes, it consists of a single
920 ownership tree and is given the `Owned` trait which allows it to be sent
921 between tasks. Custom destructors can only be implemented directly on types
922 that are `Owned`, but garbage-collected boxes can still *contain* types with
927 Many modern languages represent values as pointers to heap memory by
928 default. In contrast, Rust, like C and C++, represents such types directly.
929 Another way to say this is that aggregate data in Rust are *unboxed*. This
930 means that if you `let x = Point { x: 1f, y: 1f };`, you are creating a struct
931 on the stack. If you then copy it into a data structure, you copy the entire
932 struct, not just a pointer.
934 For small structs like `Point`, this is usually more efficient than allocating
935 memory and indirecting through a pointer. But for big structs, or mutable
936 state, it can be useful to have a single copy on the stack or on the heap, and
937 refer to that through a pointer.
941 An owned box (`~`) is a uniquely owned allocation on the heap. It inherits the
942 mutability and lifetime of the owner as it would if there was no box:
945 let x = 5; // immutable
946 let mut y = 5; // mutable
949 let x = ~5; // immutable
950 let mut y = ~5; // mutable
951 *y += 2; // the * operator is needed to access the contained value
954 The purpose of an owned box is to add a layer of indirection in order to create
955 recursive data structures or cheaply pass around an object larger than a
956 pointer. Since an owned box has a unique owner, it can only be used to
957 represent a tree data structure.
959 The following struct won't compile, because the lack of indirection would mean
960 it has an infinite size:
968 > ***Note:*** The `Option` type is an enum that represents an *optional* value.
969 > It's comparable to a nullable pointer in many other languages, but stores the
970 > contained value unboxed.
972 Adding indirection with an owned pointer allocates the child outside of the
973 struct on the heap, which makes it a finite size and won't result in a
984 A managed box (`@`) is a heap allocation with the lifetime managed by a
985 task-local garbage collector. It will be destroyed at some point after there
986 are no references left to the box, no later than the end of the task. Managed
987 boxes lack an owner, so they start a new ownership tree and don't inherit
988 mutability. They do own the contained object, and mutability is defined by the
989 type of the managed box (`@` or `@mut`). An object containing a managed box is
990 not `Owned`, and can't be sent between tasks.
993 let a = @5; // immutable
995 let mut b = @5; // mutable variable, immutable box
998 let c = @mut 5; // immutable variable, mutable box
1001 let mut d = @mut 5; // mutable variable, mutable box
1006 A mutable variable and an immutable variable can refer to the same box, given
1007 that their types are compatible. Mutability of a box is a property of its type,
1008 however, so for example a mutable handle to an immutable box cannot be
1009 assigned a reference to a mutable box.
1012 let a = @1; // immutable box
1013 let b = @mut 2; // mutable box
1015 let mut c : @int; // declare a variable with type managed immutable int
1016 let mut d : @mut int; // and one of type managed mutable int
1018 c = a; // box type is the same, okay
1019 d = b; // box type is the same, okay
1023 // but b cannot be assigned to c, or a to d
1029 Rust uses a shallow copy for parameter passing, assignment and returning values
1030 from functions. A shallow copy is considered a move of ownership if the
1031 ownership tree of the copied value includes an owned box or a type with a
1032 custom destructor. After a value has been moved, it can no longer be used from
1033 the source location and will not be destroyed there.
1037 let y = x.clone(); // y is a newly allocated box
1038 let z = x; // no new memory allocated, x can no longer be used
1041 Since in owned boxes mutability is a property of the owner, not the
1042 box, mutable boxes may become immutable when they are moved, and vice-versa.
1046 let mut s = r; // box becomes mutable
1048 let t = s; // box becomes immutable
1053 Rust's borrowed pointers are a general purpose reference type. In contrast with
1054 owned boxes, where the holder of an owned box is the owner of the pointed-to
1055 memory, borrowed pointers never imply ownership. A pointer can be borrowed to
1056 any object, and the compiler verifies that it cannot outlive the lifetime of
1059 As an example, consider a simple struct type, `Point`:
1068 We can use this simple definition to allocate points in many different
1069 ways. For example, in this code, each of these three local variables
1070 contains a point, but allocated in a different location:
1073 # struct Point { x: float, y: float }
1074 let on_the_stack : Point = Point { x: 3.0, y: 4.0 };
1075 let managed_box : @Point = @Point { x: 5.0, y: 1.0 };
1076 let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };
1079 Suppose we want to write a procedure that computes the distance
1080 between any two points, no matter where they are stored. For example,
1081 we might like to compute the distance between `on_the_stack` and
1082 `managed_box`, or between `managed_box` and `owned_box`. One option is
1083 to define a function that takes two arguments of type point—that is,
1084 it takes the points by value. But this will cause the points to be
1085 copied when we call the function. For points, this is probably not so
1086 bad, but often copies are expensive. So we’d like to define a function
1087 that takes the points by pointer. We can use borrowed pointers to do this:
1090 # struct Point { x: float, y: float }
1091 # fn sqrt(f: float) -> float { 0f }
1092 fn compute_distance(p1: &Point, p2: &Point) -> float {
1093 let x_d = p1.x - p2.x;
1094 let y_d = p1.y - p2.y;
1095 sqrt(x_d * x_d + y_d * y_d)
1099 Now we can call `compute_distance()` in various ways:
1102 # struct Point{ x: float, y: float };
1103 # let on_the_stack : Point = Point { x: 3.0, y: 4.0 };
1104 # let managed_box : @Point = @Point { x: 5.0, y: 1.0 };
1105 # let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };
1106 # fn compute_distance(p1: &Point, p2: &Point) -> float { 0f }
1107 compute_distance(&on_the_stack, managed_box);
1108 compute_distance(managed_box, owned_box);
1111 Here the `&` operator is used to take the address of the variable
1112 `on_the_stack`; this is because `on_the_stack` has the type `Point`
1113 (that is, a struct value) and we have to take its address to get a
1114 value. We also call this _borrowing_ the local variable
1115 `on_the_stack`, because we are creating an alias: that is, another
1116 route to the same data.
1118 In the case of the boxes `managed_box` and `owned_box`, however, no
1119 explicit action is necessary. The compiler will automatically convert
1120 a box like `@point` or `~point` to a borrowed pointer like
1121 `&point`. This is another form of borrowing; in this case, the
1122 contents of the managed/owned box are being lent out.
1124 Whenever a value is borrowed, there are some limitations on what you
1125 can do with the original. For example, if the contents of a variable
1126 have been lent out, you cannot send that variable to another task, nor
1127 will you be permitted to take actions that might cause the borrowed
1128 value to be freed or to change its type. This rule should make
1129 intuitive sense: you must wait for a borrowed value to be returned
1130 (that is, for the borrowed pointer to go out of scope) before you can
1131 make full use of it again.
1133 For a more in-depth explanation of borrowed pointers, read the
1134 [borrowed pointer tutorial][borrowtut].
1136 [borrowtut]: tutorial-borrowed-ptr.html
1140 Borrowing an immutable pointer to an object freezes it and prevents mutation.
1141 `Owned` objects have freezing enforced statically at compile-time.
1146 let y = &x; // x is now frozen, it cannot be modified
1148 // x is now unfrozen again
1152 Mutable managed boxes handle freezing dynamically when any of their contents
1153 are borrowed, and the task will fail if an attempt to modify them is made while
1160 let z = &*y; // the managed box is now frozen
1161 // modifying it through x or y will cause a task failure
1163 // the box is now unfrozen again
1166 # Dereferencing pointers
1168 Rust uses the unary star operator (`*`) to access the contents of a
1169 box or pointer, similarly to C.
1176 let sum = *managed + *owned + *borrowed;
1179 Dereferenced mutable pointers may appear on the left hand side of
1180 assignments. Such an assignment modifies the value that the pointer
1184 let managed = @mut 10;
1185 let mut owned = ~20;
1188 let borrowed = &mut value;
1190 *managed = *owned + 10;
1191 *owned = *borrowed + 100;
1192 *borrowed = *managed + 1000;
1195 Pointers have high operator precedence, but lower precedence than the
1196 dot operator used for field and method access. This precedence order
1197 can sometimes make code awkward and parenthesis-filled.
1200 # struct Point { x: float, y: float }
1201 # enum Shape { Rectangle(Point, Point) }
1202 # impl Shape { fn area(&self) -> int { 0 } }
1203 let start = @Point { x: 10f, y: 20f };
1204 let end = ~Point { x: (*start).x + 100f, y: (*start).y + 100f };
1205 let rect = &Rectangle(*start, *end);
1206 let area = (*rect).area();
1209 To combat this ugliness the dot operator applies _automatic pointer
1210 dereferencing_ to the receiver (the value on the left-hand side of the
1211 dot), so in most cases, explicitly dereferencing the receiver is not necessary.
1214 # struct Point { x: float, y: float }
1215 # enum Shape { Rectangle(Point, Point) }
1216 # impl Shape { fn area(&self) -> int { 0 } }
1217 let start = @Point { x: 10f, y: 20f };
1218 let end = ~Point { x: start.x + 100f, y: start.y + 100f };
1219 let rect = &Rectangle(*start, *end);
1220 let area = rect.area();
1223 You can write an expression that dereferences any number of pointers
1224 automatically. For example, if you feel inclined, you could write
1225 something silly like
1228 # struct Point { x: float, y: float }
1229 let point = &@~Point { x: 10f, y: 20f };
1230 println(fmt!("%f", point.x));
1233 The indexing operator (`[]`) also auto-dereferences.
1235 # Vectors and strings
1237 A vector is a contiguous section of memory containing zero or more
1238 values of the same type. Like other types in Rust, vectors can be
1239 stored on the stack, the local heap, or the exchange heap. Borrowed
1240 pointers to vectors are also called 'slices'.
1244 # Almond, AntiqueBrass, Apricot,
1245 # Aquamarine, Asparagus, AtomicTangerine,
1246 # BananaMania, Beaver, Bittersweet,
1247 # Black, BlizzardBlue, Blue
1249 // A fixed-size stack vector
1250 let stack_crayons: [Crayon, ..3] = [Almond, AntiqueBrass, Apricot];
1252 // A borrowed pointer to stack-allocated vector
1253 let stack_crayons: &[Crayon] = &[Aquamarine, Asparagus, AtomicTangerine];
1255 // A local heap (managed) vector of crayons
1256 let local_crayons: @[Crayon] = @[BananaMania, Beaver, Bittersweet];
1258 // An exchange heap (owned) vector of crayons
1259 let exchange_crayons: ~[Crayon] = ~[Black, BlizzardBlue, Blue];
1262 The `+` operator means concatenation when applied to vector types.
1265 # enum Crayon { Almond, AntiqueBrass, Apricot,
1266 # Aquamarine, Asparagus, AtomicTangerine,
1267 # BananaMania, Beaver, Bittersweet };
1268 # impl Clone for Crayon {
1269 # fn clone(&self) -> Crayon {
1274 let my_crayons = ~[Almond, AntiqueBrass, Apricot];
1275 let your_crayons = ~[BananaMania, Beaver, Bittersweet];
1277 // Add two vectors to create a new one
1278 let our_crayons = my_crayons + your_crayons;
1280 // .push_all() will append to a vector, provided it lives in a mutable slot
1281 let mut my_crayons = my_crayons;
1282 my_crayons.push_all(your_crayons);
1285 > ***Note:*** The above examples of vector addition use owned
1286 > vectors. Some operations on slices and stack vectors are
1287 > not yet well-supported. Owned vectors are often the most
1290 Square brackets denote indexing into a vector:
1293 # enum Crayon { Almond, AntiqueBrass, Apricot,
1294 # Aquamarine, Asparagus, AtomicTangerine,
1295 # BananaMania, Beaver, Bittersweet };
1296 # fn draw_scene(c: Crayon) { }
1297 let crayons: [Crayon, ..3] = [BananaMania, Beaver, Bittersweet];
1299 Bittersweet => draw_scene(crayons[0]),
1304 A vector can be destructured using pattern matching:
1307 let numbers: &[int] = &[1, 2, 3];
1308 let score = match numbers {
1311 [a, b] => a * 6 + b * 4,
1312 [a, b, c, ..rest] => a * 5 + b * 3 + c * 2 + rest.len() as int
1316 The elements of a vector _inherit the mutability of the vector_,
1317 and as such, individual elements may not be reassigned when the
1318 vector lives in an immutable slot.
1321 # enum Crayon { Almond, AntiqueBrass, Apricot,
1322 # Aquamarine, Asparagus, AtomicTangerine,
1323 # BananaMania, Beaver, Bittersweet };
1324 let crayons: ~[Crayon] = ~[BananaMania, Beaver, Bittersweet];
1326 crayons[0] = Apricot; // ERROR: Can't assign to immutable vector
1329 Moving it into a mutable slot makes the elements assignable.
1332 # enum Crayon { Almond, AntiqueBrass, Apricot,
1333 # Aquamarine, Asparagus, AtomicTangerine,
1334 # BananaMania, Beaver, Bittersweet };
1335 let crayons: ~[Crayon] = ~[BananaMania, Beaver, Bittersweet];
1337 // Put the vector into a mutable slot
1338 let mut mutable_crayons = crayons;
1340 // Now it's mutable to the bone
1341 mutable_crayons[0] = Apricot;
1344 This is a simple example of Rust's _dual-mode data structures_, also
1345 referred to as _freezing and thawing_.
1347 Strings are implemented with vectors of `u8`, though they have a
1348 distinct type. They support most of the same allocation options as
1349 vectors, though the string literal without a storage sigil (for
1350 example, `"foo"`) is treated differently than a comparable vector
1351 (`[foo]`). Whereas plain vectors are stack-allocated fixed-length
1352 vectors, plain strings are borrowed pointers to read-only (static)
1353 memory. All strings are immutable.
1356 // A plain string is a slice to read-only (static) memory
1357 let stack_crayons: &str = "Almond, AntiqueBrass, Apricot";
1359 // The same thing, but with the `&`
1360 let stack_crayons: &str = &"Aquamarine, Asparagus, AtomicTangerine";
1362 // A local heap (managed) string
1363 let local_crayons: @str = @"BananaMania, Beaver, Bittersweet";
1365 // An exchange heap (owned) string
1366 let exchange_crayons: ~str = ~"Black, BlizzardBlue, Blue";
1369 Both vectors and strings support a number of useful
1370 [methods](#methods), defined in [`std::vec`]
1371 and [`std::str`]. Here are some examples.
1373 [`std::vec`]: std/vec.html
1374 [`std::str`]: std/str.html
1378 # Almond, AntiqueBrass, Apricot,
1379 # Aquamarine, Asparagus, AtomicTangerine,
1380 # BananaMania, Beaver, Bittersweet
1382 # fn unwrap_crayon(c: Crayon) -> int { 0 }
1383 # fn eat_crayon_wax(i: int) { }
1384 # fn store_crayon_in_nasal_cavity(i: uint, c: Crayon) { }
1385 # fn crayon_to_str(c: Crayon) -> &str { "" }
1387 let crayons = [Almond, AntiqueBrass, Apricot];
1389 // Check the length of the vector
1390 assert!(crayons.len() == 3);
1391 assert!(!crayons.is_empty());
1393 // Iterate over a vector, obtaining a pointer to each element
1394 // (`for` is explained in the container/iterator tutorial)
1395 for crayon in crayons.iter() {
1396 let delicious_crayon_wax = unwrap_crayon(*crayon);
1397 eat_crayon_wax(delicious_crayon_wax);
1400 // Map vector elements
1401 let crayon_names = crayons.map(|v| crayon_to_str(*v));
1402 let favorite_crayon_name = crayon_names[0];
1404 // Remove whitespace from before and after the string
1405 let new_favorite_crayon_name = favorite_crayon_name.trim();
1407 if favorite_crayon_name.len() > 5 {
1408 // Create a substring
1409 println(favorite_crayon_name.slice_chars(0, 5));
1415 Named functions, like those we've seen so far, may not refer to local
1416 variables declared outside the function: they do not close over their
1417 environment (sometimes referred to as "capturing" variables in their
1418 environment). For example, you couldn't write the following:
1424 return foo; // `bar` cannot refer to `foo`
1428 Rust also supports _closures_, functions that can access variables in
1429 the enclosing scope.
1432 fn call_closure_with_ten(b: &fn(int)) { b(10); }
1434 let captured_var = 20;
1435 let closure = |arg| println(fmt!("captured_var=%d, arg=%d", captured_var, arg));
1437 call_closure_with_ten(closure);
1440 Closures begin with the argument list between vertical bars and are followed by
1441 a single expression. Remember that a block, `{ <expr1>; <expr2>; ... }`, is
1442 considered a single expression: it evaluates to the result of the last
1443 expression it contains if that expression is not followed by a semicolon,
1444 otherwise the block evaluates to `()`.
1446 The types of the arguments are generally omitted, as is the return type,
1447 because the compiler can almost always infer them. In the rare case where the
1448 compiler needs assistance, though, the arguments and return types may be
1452 let square = |x: int| -> uint { (x * x) as uint };
1455 There are several forms of closure, each with its own role. The most
1456 common, called a _stack closure_, has type `&fn` and can directly
1457 access local variables in the enclosing scope.
1461 [1, 2, 3].map(|x| if *x > max { max = *x });
1464 Stack closures are very efficient because their environment is
1465 allocated on the call stack and refers by pointer to captured
1466 locals. To ensure that stack closures never outlive the local
1467 variables to which they refer, stack closures are not
1468 first-class. That is, they can only be used in argument position; they
1469 cannot be stored in data structures or returned from
1470 functions. Despite these limitations, stack closures are used
1471 pervasively in Rust code.
1475 When you need to store a closure in a data structure, a stack closure
1476 will not do, since the compiler will refuse to let you store it. For
1477 this purpose, Rust provides a type of closure that has an arbitrary
1478 lifetime, written `@fn` (boxed closure, analogous to the `@` pointer
1479 type described earlier). This type of closure *is* first-class.
1481 A managed closure does not directly access its environment, but merely
1482 copies out the values that it closes over into a private data
1483 structure. This means that it can not assign to these variables, and
1484 cannot observe updates to them.
1486 This code creates a closure that adds a given string to its argument,
1487 returns it from a function, and then calls it:
1490 fn mk_appender(suffix: ~str) -> @fn(~str) -> ~str {
1491 // The compiler knows that we intend this closure to be of type @fn
1492 return |s| s + suffix;
1496 let shout = mk_appender(~"!");
1497 println(shout(~"hey ho, let's go"));
1503 Owned closures, written `~fn` in analogy to the `~` pointer type,
1504 hold on to things that can safely be sent between
1505 processes. They copy the values they close over, much like managed
1506 closures, but they also own them: that is, no other code can access
1507 them. Owned closures are used in concurrent code, particularly
1508 for spawning [tasks][tasks].
1510 ## Closure compatibility
1512 Rust closures have a convenient subtyping property: you can pass any kind of
1513 closure (as long as the arguments and return types match) to functions
1514 that expect a `&fn()`. Thus, when writing a higher-order function that
1515 only calls its function argument, and does nothing else with it, you
1516 should almost always declare the type of that argument as `&fn()`. That way,
1517 callers may pass any kind of closure.
1520 fn call_twice(f: &fn()) { f(); f(); }
1521 let closure = || { "I'm a closure, and it doesn't matter what type I am"; };
1522 fn function() { "I'm a normal function"; }
1523 call_twice(closure);
1524 call_twice(function);
1527 > ***Note:*** Both the syntax and the semantics will be changing
1528 > in small ways. At the moment they can be unsound in some
1529 > scenarios, particularly with non-copyable types.
1533 The `do` expression provides a way to treat higher-order functions
1534 (functions that take closures as arguments) as control structures.
1536 Consider this function that iterates over a vector of
1537 integers, passing in a pointer to each integer in the vector:
1540 fn each(v: &[int], op: &fn(v: &int)) {
1549 As a caller, if we use a closure to provide the final operator
1550 argument, we can write it in a way that has a pleasant, block-like
1554 # fn each(v: &[int], op: &fn(v: &int)) { }
1555 # fn do_some_work(i: &int) { }
1556 each([1, 2, 3], |n| {
1561 This is such a useful pattern that Rust has a special form of function
1562 call that can be written more like a built-in control structure:
1565 # fn each(v: &[int], op: &fn(v: &int)) { }
1566 # fn do_some_work(i: &int) { }
1567 do each([1, 2, 3]) |n| {
1572 The call is prefixed with the keyword `do` and, instead of writing the
1573 final closure inside the argument list, it appears outside of the
1574 parentheses, where it looks more like a typical block of
1577 `do` is a convenient way to create tasks with the `task::spawn`
1578 function. `spawn` has the signature `spawn(fn: ~fn())`. In other
1579 words, it is a function that takes an owned closure that takes no
1583 use std::task::spawn;
1586 debug!("I'm a task, whatever");
1590 Look at all those bars and parentheses -- that's two empty argument
1591 lists back to back. Since that is so unsightly, empty argument lists
1592 may be omitted from `do` expressions.
1595 use std::task::spawn;
1602 If you want to see the output of `debug!` statements, you will need to turn on `debug!` logging.
1603 To enable `debug!` logging, set the RUST_LOG environment variable to the name of your crate, which, for a file named `foo.rs`, will be `foo` (e.g., with bash, `export RUST_LOG=foo`).
1607 Methods are like functions except that they always begin with a special argument,
1609 which has the type of the method's receiver. The
1610 `self` argument is like `this` in C++ and many other languages.
1611 Methods are called with dot notation, as in `my_vec.len()`.
1613 _Implementations_, written with the `impl` keyword, can define
1614 methods on most Rust types, including structs and enums.
1615 As an example, let's define a `draw` method on our `Shape` enum.
1618 # fn draw_circle(p: Point, f: float) { }
1619 # fn draw_rectangle(p: Point, p: Point) { }
1626 Circle(Point, float),
1627 Rectangle(Point, Point)
1633 Circle(p, f) => draw_circle(p, f),
1634 Rectangle(p1, p2) => draw_rectangle(p1, p2)
1639 let s = Circle(Point { x: 1f, y: 2f }, 3f);
1643 This defines an _implementation_ for `Shape` containing a single
1644 method, `draw`. In most respects the `draw` method is defined
1645 like any other function, except for the name `self`.
1647 The type of `self` is the type on which the method is implemented,
1648 or a pointer thereof. As an argument it is written either `self`,
1649 `&self`, `@self`, or `~self`.
1650 A caller must in turn have a compatible pointer type to call the method.
1653 # fn draw_circle(p: Point, f: float) { }
1654 # fn draw_rectangle(p: Point, p: Point) { }
1655 # struct Point { x: float, y: float }
1657 # Circle(Point, float),
1658 # Rectangle(Point, Point)
1661 fn draw_borrowed(&self) { ... }
1662 fn draw_managed(@self) { ... }
1663 fn draw_owned(~self) { ... }
1664 fn draw_value(self) { ... }
1667 let s = Circle(Point { x: 1f, y: 2f }, 3f);
1669 (@s).draw_managed();
1671 (&s).draw_borrowed();
1675 Methods typically take a borrowed pointer self type,
1676 so the compiler will go to great lengths to convert a callee
1677 to a borrowed pointer.
1680 # fn draw_circle(p: Point, f: float) { }
1681 # fn draw_rectangle(p: Point, p: Point) { }
1682 # struct Point { x: float, y: float }
1684 # Circle(Point, float),
1685 # Rectangle(Point, Point)
1688 # fn draw_borrowed(&self) { ... }
1689 # fn draw_managed(@self) { ... }
1690 # fn draw_owned(~self) { ... }
1691 # fn draw_value(self) { ... }
1693 # let s = Circle(Point { x: 1f, y: 2f }, 3f);
1694 // As with typical function arguments, managed and owned pointers
1695 // are automatically converted to borrowed pointers
1697 (@s).draw_borrowed();
1698 (~s).draw_borrowed();
1700 // Unlike typical function arguments, the self value will
1701 // automatically be referenced ...
1704 // ... and dereferenced
1705 (& &s).draw_borrowed();
1707 // ... and dereferenced and borrowed
1708 (&@~s).draw_borrowed();
1711 Implementations may also define standalone (sometimes called "static")
1712 methods. The absence of a `self` parameter distinguishes such methods.
1713 These methods are the preferred way to define constructor functions.
1717 fn area(&self) -> float { ... }
1718 fn new(area: float) -> Circle { ... }
1722 To call such a method, just prefix it with the type name and a double colon:
1725 use std::float::consts::pi;
1726 struct Circle { radius: float }
1728 fn new(area: float) -> Circle { Circle { radius: (area / pi).sqrt() } }
1730 let c = Circle::new(42.5);
1735 Throughout this tutorial, we've been defining functions that act only
1736 on specific data types. With type parameters we can also define
1737 functions whose arguments have generic types, and which can be invoked
1738 with a variety of types. Consider a generic `map` function, which
1739 takes a function `function` and a vector `vector` and returns a new
1740 vector consisting of the result of applying `function` to each element
1744 fn map<T, U>(vector: &[T], function: &fn(v: &T) -> U) -> ~[U] {
1745 let mut accumulator = ~[];
1746 for element in vector.iter() {
1747 accumulator.push(function(element));
1753 When defined with type parameters, as denoted by `<T, U>`, this
1754 function can be applied to any type of vector, as long as the type of
1755 `function`'s argument and the type of the vector's contents agree with
1758 Inside a generic function, the names of the type parameters
1759 (capitalized by convention) stand for opaque types. All you can do
1760 with instances of these types is pass them around: you can't apply any
1761 operations to them or pattern-match on them. Note that instances of
1762 generic types are often passed by pointer. For example, the parameter
1763 `function()` is supplied with a pointer to a value of type `T` and not
1764 a value of type `T` itself. This ensures that the function works with
1765 the broadest set of types possible, since some types are expensive or
1766 illegal to copy and pass by value.
1768 Generic `type`, `struct`, and `enum` declarations follow the same pattern:
1771 use std::hashmap::HashMap;
1772 type Set<T> = HashMap<T, ()>;
1784 These declarations can be instantiated to valid types like `Set<int>`,
1785 `Stack<int>`, and `Option<int>`.
1787 The last type in that example, `Option`, appears frequently in Rust code.
1788 Because Rust does not have null pointers (except in unsafe code), we need
1789 another way to write a function whose result isn't defined on every possible
1790 combination of arguments of the appropriate types. The usual way is to write
1791 a function that returns `Option<T>` instead of `T`.
1794 # struct Point { x: float, y: float }
1795 # enum Shape { Circle(Point, float), Rectangle(Point, Point) }
1796 fn radius(shape: Shape) -> Option<float> {
1798 Circle(_, radius) => Some(radius),
1799 Rectangle(*) => None
1804 The Rust compiler compiles generic functions very efficiently by
1805 *monomorphizing* them. *Monomorphization* is a fancy name for a simple
1806 idea: generate a separate copy of each generic function at each call site,
1807 a copy that is specialized to the argument
1808 types and can thus be optimized specifically for them. In this
1809 respect, Rust's generics have similar performance characteristics to
1814 Within a generic function the operations available on generic types
1815 are very limited. After all, since the function doesn't know what
1816 types it is operating on, it can't safely modify or query their
1817 values. This is where _traits_ come into play. Traits are Rust's most
1818 powerful tool for writing polymorphic code. Java developers will see
1819 them as similar to Java interfaces, and Haskellers will notice their
1820 similarities to type classes. Rust's traits are a form of *bounded
1821 polymorphism*: a trait is a way of limiting the set of possible types
1822 that a type parameter could refer to.
1824 As motivation, let us consider copying in Rust.
1825 The `clone` method is not defined for all Rust types.
1826 One reason is user-defined destructors:
1827 copying a type that has a destructor
1828 could result in the destructor running multiple times.
1829 Therefore, types with destructors cannot be copied
1830 unless you explicitly implement `Clone` for them.
1832 This complicates handling of generic functions.
1833 If you have a type parameter `T`, can you copy values of that type?
1835 and if you try to run the following code the compiler will complain.
1838 // This does not compile
1839 fn head_bad<T>(v: &[T]) -> T {
1840 v[0] // error: copying a non-copyable value
1844 However, we can tell the compiler
1845 that the `head` function is only for copyable types:
1846 that is, those that implement the `Clone` trait.
1848 we can explicitly create a second copy of the value we are returning
1849 using the `clone` keyword:
1853 fn head<T: Clone>(v: &[T]) -> T {
1858 This says that we can call `head` on any type `T`
1859 as long as that type implements the `Clone` trait.
1860 When instantiating a generic function,
1861 you can only instantiate it with types
1862 that implement the correct trait,
1863 so you could not apply `head` to a type
1864 that does not implement `Clone`.
1866 While most traits can be defined and implemented by user code,
1867 three traits are automatically derived and implemented
1868 for all applicable types by the compiler,
1869 and may not be overridden:
1871 * `Send` - Sendable types.
1873 unless they contain managed boxes, managed closures, or borrowed pointers.
1875 * `Freeze` - Constant (immutable) types.
1876 These are types that do not contain anything intrinsically mutable.
1877 Intrinsically mutable values include `@mut`
1878 and `Cell` in the standard library.
1880 * `'static` - Non-borrowed types.
1881 These are types that do not contain any data whose lifetime is bound to
1882 a particular stack frame. These are types that do not contain any
1883 borrowed pointers, or types where the only contained borrowed pointers
1884 have the `'static` lifetime.
1886 > ***Note:*** These two traits were referred to as 'kinds' in earlier
1887 > iterations of the language, and often still are.
1889 Additionally, the `Drop` trait is used to define destructors. This
1890 trait defines one method called `drop`, which is automatically
1891 called when a value of the type that implements this trait is
1892 destroyed, either because the value went out of scope or because the
1893 garbage collector reclaimed it.
1900 impl Drop for TimeBomb {
1902 for _ in range(0, self.explosivity) {
1909 It is illegal to call `drop` directly. Only code inserted by the compiler
1912 ## Declaring and implementing traits
1914 A trait consists of a set of methods without bodies,
1915 or may be empty, as is the case with `Send` and `Freeze`.
1916 For example, we could declare the trait
1917 `Printable` for things that can be printed to the console,
1918 with a single method:
1926 Traits may be implemented for specific types with [impls]. An impl
1927 that implements a trait includes the name of the trait at the start of
1928 the definition, as in the following impls of `Printable` for `int`
1934 # trait Printable { fn print(&self); }
1935 impl Printable for int {
1936 fn print(&self) { println(fmt!("%d", *self)) }
1939 impl Printable for ~str {
1940 fn print(&self) { println(*self) }
1947 Methods defined in an implementation of a trait may be called just like
1948 any other method, using dot notation, as in `1.print()`. Traits may
1949 themselves contain type parameters. A trait for generalized sequence
1950 types might look like the following:
1954 fn length(&self) -> uint;
1957 impl<T> Seq<T> for ~[T] {
1958 fn length(&self) -> uint { self.len() }
1962 The implementation has to explicitly declare the type parameter that
1963 it binds, `T`, before using it to specify its trait type. Rust
1964 requires this declaration because the `impl` could also, for example,
1965 specify an implementation of `Seq<int>`. The trait type (appearing
1966 between `impl` and `for`) *refers* to a type, rather than
1969 The type parameters bound by a trait are in scope in each of the
1970 method declarations. So, re-declaring the type parameter
1971 `T` as an explicit type parameter for `len`, in either the trait or
1972 the impl, would be a compile-time error.
1974 Within a trait definition, `Self` is a special type that you can think
1975 of as a type parameter. An implementation of the trait for any given
1976 type `T` replaces the `Self` type parameter with `T`. The following
1977 trait describes types that support an equality operation:
1980 // In a trait, `self` refers to the self argument.
1981 // `Self` refers to the type implementing the trait.
1983 fn equals(&self, other: &Self) -> bool;
1986 // In an impl, `self` refers just to the value of the receiver
1988 fn equals(&self, other: &int) -> bool { *other == *self }
1992 Notice that in the trait definition, `equals` takes a
1993 second parameter of type `Self`.
1994 In contrast, in the `impl`, `equals` takes a second parameter of
1995 type `int`, only using `self` as the name of the receiver.
1997 Just as in type implementations, traits can define standalone (static)
1998 methods. These methods are called by prefixing the method name with the trait
1999 name and a double colon. The compiler uses type inference to decide which
2000 implementation to use.
2003 use std::float::consts::pi;
2004 trait Shape { fn new(area: float) -> Self; }
2005 struct Circle { radius: float }
2006 struct Square { length: float }
2008 impl Shape for Circle {
2009 fn new(area: float) -> Circle { Circle { radius: (area / pi).sqrt() } }
2011 impl Shape for Square {
2012 fn new(area: float) -> Square { Square { length: (area).sqrt() } }
2016 let c: Circle = Shape::new(area);
2017 let s: Square = Shape::new(area);
2020 ## Bounded type parameters and static method dispatch
2022 Traits give us a language for defining predicates on types, or
2023 abstract properties that types can have. We can use this language to
2024 define _bounds_ on type parameters, so that we can then operate on
2028 # trait Printable { fn print(&self); }
2029 fn print_all<T: Printable>(printable_things: ~[T]) {
2030 for thing in printable_things.iter() {
2036 Declaring `T` as conforming to the `Printable` trait (as we earlier
2037 did with `Clone`) makes it possible to call methods from that trait
2038 on values of type `T` inside the function. It will also cause a
2039 compile-time error when anyone tries to call `print_all` on an array
2040 whose element type does not have a `Printable` implementation.
2042 Type parameters can have multiple bounds by separating them with `+`,
2043 as in this version of `print_all` that copies elements.
2046 # trait Printable { fn print(&self); }
2047 fn print_all<T: Printable + Clone>(printable_things: ~[T]) {
2049 while i < printable_things.len() {
2050 let copy_of_thing = printable_things[i].clone();
2051 copy_of_thing.print();
2057 Method calls to bounded type parameters are _statically dispatched_,
2058 imposing no more overhead than normal function invocation, so are
2059 the preferred way to use traits polymorphically.
2061 This usage of traits is similar to Haskell type classes.
2063 ## Trait objects and dynamic method dispatch
2065 The above allows us to define functions that polymorphically act on
2066 values of a single unknown type that conforms to a given trait.
2067 However, consider this function:
2070 # type Circle = int; type Rectangle = int;
2071 # impl Drawable for int { fn draw(&self) {} }
2072 # fn new_circle() -> int { 1 }
2073 trait Drawable { fn draw(&self); }
2075 fn draw_all<T: Drawable>(shapes: ~[T]) {
2076 for shape in shapes.iter() { shape.draw(); }
2078 # let c: Circle = new_circle();
2082 You can call that on an array of circles, or an array of rectangles
2083 (assuming those have suitable `Drawable` traits defined), but not on
2084 an array containing both circles and rectangles. When such behavior is
2085 needed, a trait name can alternately be used as a type, called
2089 # trait Drawable { fn draw(&self); }
2090 fn draw_all(shapes: &[@Drawable]) {
2091 for shape in shapes.iter() { shape.draw(); }
2095 In this example, there is no type parameter. Instead, the `@Drawable`
2096 type denotes any managed box value that implements the `Drawable`
2097 trait. To construct such a value, you use the `as` operator to cast a
2101 # type Circle = int; type Rectangle = bool;
2102 # trait Drawable { fn draw(&self); }
2103 # fn new_circle() -> Circle { 1 }
2104 # fn new_rectangle() -> Rectangle { true }
2105 # fn draw_all(shapes: &[@Drawable]) {}
2107 impl Drawable for Circle { fn draw(&self) { ... } }
2108 impl Drawable for Rectangle { fn draw(&self) { ... } }
2110 let c: @Circle = @new_circle();
2111 let r: @Rectangle = @new_rectangle();
2112 draw_all([c as @Drawable, r as @Drawable]);
2115 We omit the code for `new_circle` and `new_rectangle`; imagine that
2116 these just return `Circle`s and `Rectangle`s with a default size. Note
2117 that, like strings and vectors, objects have dynamic size and may
2118 only be referred to via one of the pointer types.
2119 Other pointer types work as well.
2120 Casts to traits may only be done with compatible pointers so,
2121 for example, an `@Circle` may not be cast to an `~Drawable`.
2124 # type Circle = int; type Rectangle = int;
2125 # trait Drawable { fn draw(&self); }
2126 # impl Drawable for int { fn draw(&self) {} }
2127 # fn new_circle() -> int { 1 }
2128 # fn new_rectangle() -> int { 2 }
2130 let boxy: @Drawable = @new_circle() as @Drawable;
2132 let owny: ~Drawable = ~new_circle() as ~Drawable;
2133 // A borrowed object
2134 let stacky: &Drawable = &new_circle() as &Drawable;
2137 Method calls to trait types are _dynamically dispatched_. Since the
2138 compiler doesn't know specifically which functions to call at compile
2139 time, it uses a lookup table (also known as a vtable or dictionary) to
2140 select the method to call at runtime.
2142 This usage of traits is similar to Java interfaces.
2144 By default, each of the three storage classes for traits enforce a
2145 particular set of built-in kinds that their contents must fulfill in
2146 order to be packaged up in a trait object of that storage class.
2148 * The contents of owned traits (`~Trait`) must fulfill the `Send` bound.
2149 * The contents of managed traits (`@Trait`) must fulfill the `'static` bound.
2150 * The contents of borrowed traits (`&Trait`) are not constrained by any bound.
2152 Consequently, the trait objects themselves automatically fulfill their
2153 respective kind bounds. However, this default behavior can be overridden by
2154 specifying a list of bounds on the trait type, for example, by writing `~Trait:`
2155 (which indicates that the contents of the owned trait need not fulfill any
2156 bounds), or by writing `~Trait:Send+Freeze`, which indicates that in addition
2157 to fulfilling `Send`, contents must also fulfill `Freeze`, and as a consequence,
2158 the trait itself fulfills `Freeze`.
2160 * `~Trait:Send` is equivalent to `~Trait`.
2161 * `@Trait:'static` is equivalent to `@Trait`.
2162 * `&Trait:` is equivalent to `&Trait`.
2164 Builtin kind bounds can also be specified on closure types in the same way (for
2165 example, by writing `fn:Freeze()`), and the default behaviours are the same as
2166 for traits of the same storage class.
2168 ## Trait inheritance
2170 We can write a trait declaration that _inherits_ from other traits, called _supertraits_.
2171 Types that implement a trait must also implement its supertraits.
2173 we can define a `Circle` trait that inherits from `Shape`.
2176 trait Shape { fn area(&self) -> float; }
2177 trait Circle : Shape { fn radius(&self) -> float; }
2180 Now, we can implement `Circle` on a type only if we also implement `Shape`.
2183 use std::float::consts::pi;
2184 # trait Shape { fn area(&self) -> float; }
2185 # trait Circle : Shape { fn radius(&self) -> float; }
2186 # struct Point { x: float, y: float }
2187 # fn square(x: float) -> float { x * x }
2188 struct CircleStruct { center: Point, radius: float }
2189 impl Circle for CircleStruct {
2190 fn radius(&self) -> float { (self.area() / pi).sqrt() }
2192 impl Shape for CircleStruct {
2193 fn area(&self) -> float { pi * square(self.radius) }
2197 Notice that methods of `Circle` can call methods on `Shape`, as our
2198 `radius` implementation calls the `area` method.
2199 This is a silly way to compute the radius of a circle
2200 (since we could just return the `radius` field), but you get the idea.
2202 In type-parameterized functions,
2203 methods of the supertrait may be called on values of subtrait-bound type parameters.
2204 Refering to the previous example of `trait Circle : Shape`:
2207 # trait Shape { fn area(&self) -> float; }
2208 # trait Circle : Shape { fn radius(&self) -> float; }
2209 fn radius_times_area<T: Circle>(c: T) -> float {
2210 // `c` is both a Circle and a Shape
2211 c.radius() * c.area()
2215 Likewise, supertrait methods may also be called on trait objects.
2218 use std::float::consts::pi;
2219 # trait Shape { fn area(&self) -> float; }
2220 # trait Circle : Shape { fn radius(&self) -> float; }
2221 # struct Point { x: float, y: float }
2222 # struct CircleStruct { center: Point, radius: float }
2223 # impl Circle for CircleStruct { fn radius(&self) -> float { (self.area() / pi).sqrt() } }
2224 # impl Shape for CircleStruct { fn area(&self) -> float { pi * square(self.radius) } }
2226 let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f};
2227 let mycircle: @Circle = concrete as @Circle;
2228 let nonsense = mycircle.radius() * mycircle.area();
2231 > ***Note:*** Trait inheritance does not actually work with objects yet
2233 ## Deriving implementations for traits
2235 A small number of traits in `std` and `extra` can have implementations
2236 that can be automatically derived. These instances are specified by
2237 placing the `deriving` attribute on a data type declaration. For
2238 example, the following will mean that `Circle` has an implementation
2239 for `Eq` and can be used with the equality operators, and that a value
2240 of type `ABC` can be randomly generated and converted to a string:
2244 struct Circle { radius: float }
2246 #[deriving(Rand, ToStr)]
2247 enum ABC { A, B, C }
2250 The full list of derivable traits is `Eq`, `TotalEq`, `Ord`,
2251 `TotalOrd`, `Encodable` `Decodable`, `Clone`, `DeepClone`,
2252 `IterBytes`, `Rand`, `Default`, `Zero`, and `ToStr`.
2254 # Crates and the module system
2256 Rust's module system is very powerful, but because of that also somewhat complex.
2257 Nevertheless, this section will try to explain every important aspect of it.
2261 In order to speak about the module system, we first need to define the medium it exists in:
2263 Let's say you've written a program or a library, compiled it, and got the resulting binary.
2264 In Rust, the content of all source code that the compiler directly had to compile in order to end up with
2265 that binary is collectively called a 'crate'.
2267 For example, for a simple hello world program your crate only consists of this code:
2272 println("Hello world!");
2276 A crate is also the unit of independent compilation in Rust: `rustc` always compiles a single crate at a time,
2277 from which it produces either a library or an executable.
2279 Note that merely using an already compiled library in your code does not make it part of your crate.
2281 ## The module hierarchy
2283 For every crate, all the code in it is arranged in a hierarchy of modules starting with a single
2284 root module. That root module is called the 'crate root'.
2286 All modules in a crate below the crate root are declared with the `mod` keyword:
2289 // This is the crate root
2292 // This is the body of module 'farm' declared in the crate root.
2294 fn chicken() { println("cluck cluck"); }
2295 fn cow() { println("mooo"); }
2298 // Body of module 'barn'
2300 fn hay() { println("..."); }
2305 println("Hello farm!");
2309 As you can see, your module hierarchy is now three modules deep: There is the crate root, which contains your `main()`
2310 function, and the module `farm`. The module `farm` also contains two functions and a third module `barn`,
2311 which contains a function `hay`.
2313 (In case you already stumbled over `extern mod`: It isn't directly related to a bare `mod`, we'll get to it later. )
2315 ## Paths and visibility
2317 We've now defined a nice module hierarchy. But how do we access the items in it from our `main` function?
2318 One way to do it is to simply fully qualifying it:
2322 fn chicken() { println("cluck cluck"); }
2327 println("Hello chicken!");
2329 ::farm::chicken(); // Won't compile yet, see further down
2333 The `::farm::chicken` construct is what we call a 'path'.
2335 Because it's starting with a `::`, it's also a 'global path',
2336 which qualifies an item by its full path in the module hierarchy
2337 relative to the crate root.
2339 If the path were to start with a regular identifier, like `farm::chicken`, it would be
2340 a 'local path' instead. We'll get to them later.
2342 Now, if you actually tried to compile this code example, you'll notice
2343 that you get a `unresolved name: 'farm::chicken'` error. That's because per default,
2344 items (`fn`, `struct`, `static`, `mod`, ...) are only visible inside the module
2345 they are defined in.
2347 To make them visible outside their containing modules, you need to mark them _public_ with `pub`:
2351 pub fn chicken() { println("cluck cluck"); }
2352 pub fn cow() { println("mooo"); }
2357 println("Hello chicken!");
2358 ::farm::chicken(); // This compiles now
2362 Visibility restrictions in Rust exist only at module boundaries. This
2363 is quite different from most object-oriented languages that also
2364 enforce restrictions on objects themselves. That's not to say that
2365 Rust doesn't support encapsulation: both struct fields and methods can
2366 be private. But this encapsulation is at the module level, not the
2369 For convenience, fields are _public_ by default, and can be made _private_ with the `priv` keyword:
2373 # pub type Chicken = int;
2374 # struct Human(int);
2375 # impl Human { fn rest(&self) { } }
2376 # pub fn make_me_a_farm() -> Farm { Farm { chickens: ~[], farmer: Human(0) } }
2378 priv chickens: ~[Chicken],
2383 fn feed_chickens(&self) { ... }
2384 pub fn add_chicken(&self, c: Chicken) { ... }
2387 pub fn feed_animals(farm: &Farm) {
2388 farm.feed_chickens();
2393 let f = make_me_a_farm();
2394 f.add_chicken(make_me_a_chicken());
2395 farm::feed_animals(&f);
2398 // This wouldn't compile because both are private:
2399 // f.feed_chickens();
2400 // let chicken_counter = f.chickens.len();
2402 # fn make_me_a_farm() -> farm::Farm { farm::make_me_a_farm() }
2403 # fn make_me_a_chicken() -> farm::Chicken { 0 }
2406 > ***Note:*** Visibility rules are currently buggy and not fully defined, you might have to add or remove `pub` along a path until it works.
2408 ## Files and modules
2410 One important aspect about Rusts module system is that source files are not important:
2411 You define a module hierarchy, populate it with all your definitions, define visibility,
2412 maybe put in a `fn main()`, and that's it: No need to think about source files.
2414 The only file that's relevant is the one that contains the body of your crate root,
2415 and it's only relevant because you have to pass that file to `rustc` to compile your crate.
2417 And in principle, that's all you need: You can write any Rust program as one giant source file that contains your
2418 crate root and everything below it in `mod ... { ... }` declarations.
2420 However, in practice you usually want to split you code up into multiple source files to make it more manageable.
2421 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:
2423 If you declare a module without its body, like `mod foo;`, the compiler will look for the
2424 files `foo.rs` and `foo/mod.rs`. If it finds either, it uses the content of that file as the body of the module.
2425 If it finds both, that's a compile error.
2427 So, if we want to move the content of `mod farm` into it's own file, it would look like this:
2430 // main.rs - contains body of the crate root
2431 mod farm; // Compiler will look for 'farm.rs' and 'farm/mod.rs'
2434 println("Hello farm!");
2440 // farm.rs - contains body of module 'farm' in the crate root
2441 pub fn chicken() { println("cluck cluck"); }
2442 pub fn cow() { println("mooo"); }
2445 pub fn hay() { println("..."); }
2450 So, in short `mod foo;` is just syntactic sugar for `mod foo { /* include content of foo.rs or foo/mod.rs here */ }`.
2452 This also means that having two or more identical `mod foo;` somewhere
2453 in your crate hierarchy is generally a bad idea,
2454 just like copy-and-paste-ing a module into two or more places is one.
2455 Both will result in duplicate and mutually incompatible definitions.
2457 The directory the compiler looks in for those two files is determined by starting with
2458 the same directory as the source file that contains the `mod foo;` declaration, and concatenating to that a
2459 path equivalent to the relative path of all nested `mod { ... }` declarations the `mod foo;` is contained in, if any.
2461 For example, given a file with this module body:
2475 The compiler would then try all these files:
2485 src/animals/fish/mod.rs
2487 src/animals/mammals/humans.rs
2488 src/animals/mammals/humans/mod.rs
2491 These rules per default result in any directory structure mirroring
2492 the crates's module hierarchy, and allow you to have both small modules that only need
2493 to consist of one source file, and big modules that group the source files of submodules together.
2495 If you need to circumvent those defaults, you can also overwrite the path a `mod foo;` would take:
2498 #[path="../../area51/classified.rs"]
2502 ## Importing names into the local scope
2504 Always referring to definitions in other modules with their global
2505 path gets old really fast, so Rust has a way to import
2506 them into the local scope of your module: `use`-statements.
2508 They work like this: At the beginning of any module body, `fn` body, or any other block
2509 you can write a list of `use`-statements, consisting of the keyword `use` and a __global path__ to an item
2510 without the `::` prefix. For example, this imports `cow` into the local scope:
2514 # mod farm { pub fn cow() { println("I'm a hidden ninja cow!") } }
2515 # fn main() { cow() }
2518 The path you give to `use` is per default global, meaning relative to the crate root,
2519 no matter how deep the module hierarchy is, or whether the module body it's written in
2520 is contained in its own file (remember: files are irrelevant).
2522 This is different to other languages, where you often only find a single import construct that combines the semantic
2523 of `mod foo;` and `use`-statements, and which tend to work relative to the source file or use an absolute file path
2524 - Rubys `require` or C/C++'s `#include` come to mind.
2526 However, it's also possible to import things relative to the module of the `use`-statement:
2527 Adding a `super::` in front of the path will start in the parent module,
2528 while adding a `self::` prefix will start in the current module:
2532 # pub fn some_parent_item(){ println("...") }
2534 use super::some_parent_item;
2535 use self::some_child_module::some_item;
2536 # pub fn bar() { some_parent_item(); some_item() }
2537 # pub mod some_child_module { pub fn some_item() {} }
2542 Again - relative to the module, not to the file.
2544 Imports are also shadowed by local definitions:
2545 For each name you mention in a module/block, `rust`
2546 will first look at all items that are defined locally,
2547 and only if that results in no match look at items you brought in
2548 scope with corresponding `use` statements.
2551 # // XXX: Allow unused import in doc test
2554 # mod farm { pub fn cow() { println("Hidden ninja cow is hidden.") } }
2555 fn cow() { println("Mooo!") }
2558 cow() // resolves to the locally defined cow() function
2562 To make this behavior more obvious, the rule has been made that `use`-statement always need to be written
2563 before any declaration, like in the example above. This is a purely artificial rule introduced
2564 because people always assumed they shadowed each other based on order, despite the fact that all items in rust are
2565 mutually recursive, order independent definitions.
2567 One odd consequence of that rule is that `use` statements also go in front of any `mod` declaration,
2568 even if they refer to things inside them:
2573 pub fn cow() { println("Moooooo?") }
2579 This is what our `farm` example looks like with `use` statements:
2587 pub fn chicken() { println("cluck cluck"); }
2588 pub fn cow() { println("mooo"); }
2591 pub fn hay() { println("..."); }
2596 println("Hello farm!");
2598 // Can now refer to those names directly:
2605 And here an example with multiple files:
2607 // a.rs - crate root
2610 fn main() { foo(); }
2616 pub fn foo() { bar(); }
2620 pub fn bar() { println("Baz!"); }
2623 There also exist two short forms for importing multiple names at once:
2625 1. Explicit mention multiple names as the last element of an `use` path:
2627 use farm::{chicken, cow};
2629 # pub fn cow() { println("Did I already mention how hidden and ninja I am?") }
2630 # pub fn chicken() { println("I'm Bat-chicken, guardian of the hidden tutorial code.") }
2632 # fn main() { cow(); chicken() }
2635 2. Import everything in a module with a wildcard:
2639 # pub fn cow() { println("Bat-chicken? What a stupid name!") }
2640 # pub fn chicken() { println("Says the 'hidden ninja' cow.") }
2642 # fn main() { cow(); chicken() }
2645 However, that's not all. You can also rename an item while you're bringing it into scope:
2648 use egg_layer = farm::chicken;
2649 # mod farm { pub fn chicken() { println("Laying eggs is fun!") } }
2657 In general, `use` creates an local alias:
2658 An alternate path and a possibly different name to access the same item,
2659 whiteout touching the original, and with both being interchangeable.
2661 ## Reexporting names
2663 It is also possible to reexport items to be accessible under your module.
2665 For that, you write `pub use`:
2669 pub use self::barn::hay;
2671 pub fn chicken() { println("cluck cluck"); }
2672 pub fn cow() { println("mooo"); }
2675 pub fn hay() { println("..."); }
2686 Just like in normal `use` statements, the exported names
2687 merely represent an alias to the same thing and can also be renamed.
2689 The above example also demonstrate what you can use `pub use` for:
2690 The nested `barn` module is private, but the `pub use` allows users
2691 of the module `farm` to access a function from `barn` without needing
2692 to know that `barn` exists.
2694 In other words, you can use them to decouple an public api from their internal implementation.
2698 So far we've only talked about how to define and structure your own crate.
2700 However, most code out there will want to use preexisting libraries,
2701 as there really is no reason to start from scratch each time you start a new project.
2703 In Rust terminology, we need a way to refer to other crates.
2705 For that, Rust offers you the `extern mod` declaration:
2709 // extra ships with Rust, you'll find more details further down.
2712 // The rational number '1/2':
2713 let one_half = ::extra::rational::Ratio::new(1, 2);
2717 Despite its name, `extern mod` is a distinct construct from regular `mod` declarations:
2718 A statement of the form `extern mod foo;` will cause `rustc` to search for the crate `foo`,
2719 and if it finds a matching binary it lets you use it from inside your crate.
2721 The effect it has on your module hierarchy mirrors aspects of both `mod` and `use`:
2723 - Like `mod`, it causes `rustc` to actually emit code:
2724 The linkage information the binary needs to use the library `foo`.
2726 - But like `use`, all `extern mod` statements that refer to the same library are interchangeable,
2727 as each one really just presents an alias to an external module (the crate root of the library your linking against).
2729 Remember how `use`-statements have to go before local declarations because the latter shadows the former?
2730 Well, `extern mod` statements also have their own rules in that regard:
2731 Both `use` and local declarations can shadow them, so the rule is that `extern mod` has to go in front
2732 of both `use` and local declarations.
2734 Which can result in something like this:
2740 use extra::rational::Ratio;
2743 pub fn dog() { println("woof"); }
2748 let a_third = Ratio::new(1, 3);
2752 It's a bit weird, but it's the result of shadowing rules that have been set that way because
2753 they model most closely what people expect to shadow.
2757 If you use `extern mod`, per default `rustc` will look for libraries in the the library search path (which you can
2758 extend with the `-L` switch).
2760 However, Rust also ships with rustpkg, a package manager that is able to automatically download and build
2761 libraries if you use it for building your crate. How it works is explained [here][rustpkg],
2762 but for this tutorial it's only important to know that you can optionally annotate an
2763 `extern mod` statement with an package id that rustpkg can use to identify it:
2766 extern mod rust = "github.com/mozilla/rust"; // pretend Rust is an simple library
2769 [rustpkg]: rustpkg.html
2771 ## Crate metadata and settings
2773 For every crate you can define a number of metadata items, such as link name, version or author.
2774 You can also toggle settings that have crate-global consequences. Both mechanism
2775 work by providing attributes in the crate root.
2777 For example, Rust uniquely identifies crates by their link metadate, which includes
2778 the link name and the version. It also hashes the filename and the symbols in a binary
2779 based on the link metadata, allowing you to use two different versions of the same library in a crate
2782 Therefor, if you plan to compile your crate as a library, you should annotate it with that information:
2787 # #[crate_type = "lib"];
2788 // Crate linkage metadata
2789 #[link(name = "farm", vers = "2.5")];
2795 You can also in turn require in a `extern mod` statement that certain link metadata items match some criteria.
2796 For that, Rust currently parses a comma-separated list of name/value pairs that appear after
2797 it, and ensures that they match the attributes provided in the `link` attribute of a crate file.
2798 This enables you to, eg, pick a a crate based on it's version number, or to link an library under an
2799 different name. For example, this two mod statements would both accept and select the crate define above:
2802 extern mod farm(vers = "2.5");
2803 extern mod my_farm(name = "farm", vers = "2.5");
2806 Other crate settings and metadata include things like enabling/disabling certain errors or warnings,
2807 or setting the crate type (library or executable) explicitly:
2813 // This crate is a library ("bin" is the default)
2814 #[crate_type = "lib"];
2816 // Turn on a warning
2817 #[warn(non_camel_case_types)]
2821 If you're compiling your crate with `rustpkg`,
2822 link annotations will not be necessary, because they get
2823 inferred by `rustpkg` based on the Package id and naming conventions.
2826 > ***Note:*** The rules regarding link metadata, both as attributes and on `extern mod`,
2827 as well as their interaction with `rustpkg`
2828 are currently not clearly defined and will likely change in the future.
2830 ## A minimal example
2832 Now for something that you can actually compile yourself.
2834 We define two crates, and use one of them as a library in the other.
2838 #[link(name = "world", vers = "0.42")];
2839 pub fn explore() -> &'static str { "world" }
2845 fn main() { println("hello " + world::explore()); }
2848 Now compile and run like this (adjust to your platform if necessary):
2851 > rustc --lib world.rs # compiles libworld-<HASH>-0.42.so
2852 > rustc main.rs -L . # compiles main
2857 Notice that the library produced contains the version in the file name
2858 as well as an inscrutable string of alphanumerics. As explained in the previous paragraph,
2859 these are both part of Rust's library versioning scheme. The alphanumerics are
2860 a hash representing the crates link metadata.
2862 ## The standard library and the prelude
2864 While reading the examples in this tutorial, you might have asked yourself where all
2865 those magical predefined items like `println()` are coming from.
2867 The truth is, there's nothing magical about them: They are all defined normally
2868 in the `std` library, which is a crate that ships with Rust.
2870 The only magical thing that happens is that `rustc` automatically inserts this line into your crate root:
2876 As well as this line into every module body:
2879 use std::prelude::*;
2882 The role of the `prelude` module is to re-exports common definitions from `std`.
2884 This allows you to use common types and functions like `Option<T>` or `println`
2885 without needing to import them. And if you need something from `std` that's not in the prelude,
2886 you just have to import it with an `use` statement.
2888 For example, it re-exports `println` which is defined in `std::io::println`:
2891 use puts = std::io::println;
2894 println("println is imported per default.");
2895 puts("Doesn't hinder you from importing it under an different name yourself.");
2896 ::std::io::println("Or from not using the automatic import.");
2900 Both auto-insertions can be disabled with an attribute if necessary:
2903 // In the crate root:
2909 #[no_implicit_prelude];
2912 ## The standard library in detail
2914 The Rust standard library provides runtime features required by the language,
2915 including the task scheduler and memory allocators, as well as library
2916 support for Rust built-in types, platform abstractions, and other commonly
2919 [`std`] includes modules corresponding to each of the integer types, each of
2920 the floating point types, the [`bool`] type, [tuples], [characters], [strings],
2921 [vectors], [managed boxes], [owned boxes],
2922 and unsafe and borrowed [pointers]. Additionally, `std` provides
2923 some pervasive types ([`option`] and [`result`]),
2924 [task] creation and [communication] primitives,
2925 platform abstractions ([`os`] and [`path`]), basic
2926 I/O abstractions ([`io`]), [containers] like [`hashmap`],
2927 common traits ([`kinds`], [`ops`], [`cmp`], [`num`],
2928 [`to_str`], [`clone`]), and complete bindings to the C standard library ([`libc`]).
2930 The full documentation for `std` can be found here: [standard library].
2932 [standard library]: std/index.html
2933 [`std`]: std/index.html
2934 [`bool`]: std/bool.html
2935 [tuples]: std/tuple.html
2936 [characters]: std/char.html
2937 [strings]: std/str.html
2938 [vectors]: std/vec.html
2939 [managed boxes]: std/managed.html
2940 [owned boxes]: std/owned.html
2941 [pointers]: std/ptr.html
2942 [`option`]: std/option.html
2943 [`result`]: std/result.html
2944 [task]: std/task.html
2945 [communication]: std/comm.html
2947 [`path`]: std/path.html
2949 [containers]: std/container.html
2950 [`hashmap`]: std/hashmap.html
2951 [`kinds`]: std/kinds.html
2952 [`ops`]: std/ops.html
2953 [`cmp`]: std/cmp.html
2954 [`num`]: std/num.html
2955 [`to_str`]: std/to_str.html
2956 [`clone`]: std/clone.html
2957 [`libc`]: std/libc.html
2959 ## The extra library
2961 Rust also ships with the [extra library], an accumulation of
2962 useful things, that are however not important enough
2963 to deserve a place in the standard library.
2964 You can use them by linking to `extra` with an `extern mod extra;`.
2966 [extra library]: extra/index.html
2968 Right now `extra` contains those definitions directly, but in the future it will likely just
2969 re-export a bunch of 'officially blessed' crates that get managed with `rustpkg`.
2973 Now that you know the essentials, check out any of the additional
2974 tutorials on individual topics.
2976 * [Borrowed pointers][borrow]
2977 * [Tasks and communication][tasks]
2979 * [The foreign function interface][ffi]
2980 * [Containers and iterators](tutorial-container.html)
2981 * [Error-handling and Conditions](tutorial-conditions.html)
2983 There is further documentation on the [wiki], however those tend to be even more out of date as this document.
2985 [borrow]: tutorial-borrowed-ptr.html
2986 [tasks]: tutorial-tasks.html
2987 [macros]: tutorial-macros.html
2988 [ffi]: tutorial-ffi.html
2990 [wiki]: https://github.com/mozilla/rust/wiki/Docs