% Rust Language Tutorial # Introduction ## Scope This is a tutorial for the Rust programming language. It assumes the reader is familiar with the basic concepts of programming, and has programmed in one or more other languages before. The tutorial covers the whole language, though not with the depth and precision of the [language reference](rust.html). ## Disclaimer Rust is a language under development. The general flavor of the language has settled, but details will continue to change as it is further refined. Nothing in this tutorial is final, and though we try to keep it updated, it is possible that the text occasionally does not reflect the actual state of the language. ## First Impressions Though syntax is something you get used to, an initial encounter with a language can be made easier if the notation looks familiar. Rust is a curly-brace language in the tradition of C, C++, and JavaScript. ~~~~ fn fac(n: int) -> int { let mut result = 1, i = 1; while i <= n { result *= i; i += 1; } ret result; } ~~~~ Several differences from C stand out. Types do not come before, but after variable names (preceded by a colon). In local variables (introduced with `let`), they are optional, and will be inferred when left off. Constructs like `while` and `if` do not require parentheses around the condition (though they allow them). Also, there's a tendency towards aggressive abbreviation in the keywords—`fn` for function, `ret` for return. You should, however, not conclude that Rust is simply an evolution of C. As will become clear in the rest of this tutorial, it goes in quite a different direction. ## Conventions Throughout the tutorial, words that indicate language keywords or identifiers defined in the example code are displayed in `code font`. Code snippets are indented, and also shown in a monospaced font. Not all snippets constitute whole programs. For brevity, we'll often show fragments of programs that don't compile on their own. To try them out, you might have to wrap them in `fn main() { ... }`, and make sure they don't contain references to things that aren't actually defined. # Getting started ## Installation The Rust compiler currently must be built from a [tarball][]. We hope to be distributing binary packages for various operating systems in the future. ***Note:*** The Rust compiler is slightly unusual in that it is written in Rust and therefore must be built by a precompiled "snapshot" version of itself (made in an earlier state of development). As such, source builds require that: * You are connected to the internet, to fetch snapshots. * You can at least execute snapshot binaries of one of the forms we offer them in. Currently we build and test snapshots on: * Windows (7, server 2008 r2) x86 only * Linux 2.6.x (various distributions) x86 and x86-64 * OSX 10.6 ("Snow leopard") or 10.7 ("Lion") x86 and x86-64 You may find other platforms work, but these are our "tier 1" supported build environments that are most likely to work. Further platforms will be added to the list in the future via cross-compilation. To build from source you will also need the following prerequisite packages: * g++ 4.4 or clang++ 3.x * python 2.6 or later * perl 5.0 or later * gnu make 3.81 or later * curl Assuming you're on a relatively modern Linux system and have met the prerequisites, something along these lines should work. Building from source on Windows requires some extra steps: please see the [getting started][wiki-get-started] page on the Rust wiki. ~~~~ {.notrust} $ wget http://dl.rust-lang.org/dist/rust-0.1.tar.gz $ tar -xzf rust-0.1.tar.gz $ cd rust-0.1 $ ./configure $ make && make install ~~~~ You may need to use `sudo make install` if you do not normally have permission to modify the destination directory (either `/usr/local/bin` or the directory specified with to `configure` with `--prefix`). When complete, `make install` will place the following programs into `/usr/local/bin`: * `rustc`, the Rust compiler * `rustdoc`, the API-documentation tool * `cargo`, the Rust package manager In addition to a manual page under `/usr/local/share/man` and a set of host and target libraries under `/usr/local/lib/rustc`. The install locations can be adjusted by passing a `--prefix` argument to `configure`. Various other options are also supported, pass `--help` for more information on them. [wiki-get-started]: https://github.com/mozilla/rust/wiki/Doc-getting-started [tarball]: http://dl.rust-lang.org/dist/rust-0.1.tar.gz ## Compiling your first program Rust program files are, by convention, given the extension `.rs`. Say we have a file `hello.rs` containing this program: ~~~~ fn main(args: [str]) { io::println("hello world from '" + args[0] + "'!"); } ~~~~ If the Rust compiler was installed successfully, running `rustc hello.rs` will produce a binary called `hello` (or `hello.exe`). If you modify the program to make it invalid (for example, change the function to an unknown name), and then compile it, you'll see an error message like this: ~~~~ {.notrust} hello.rs:2:4: 2:16 error: unresolved name: io::print_it hello.rs:2 io::print_it("hello world from '" + args[0] + "'!"); ^~~~~~~~~~~~ ~~~~ The Rust compiler tries to provide useful information when it runs into an error. ## Anatomy of a Rust program In its simplest form, a Rust program is simply a `.rs` file with some types and functions defined in it. If it has a `main` function, it can be compiled to an executable. Rust does not allow code that's not a declaration to appear at the top level of the file—all statements must live inside a function. Rust programs can also be compiled as libraries, and included in other programs. The `use std` directive that appears at the top of a lot of examples imports the [standard library][std]. This is described in more detail [later on](#modules-and-crates). [std]: http://doc.rust-lang.org/doc/std ## Editing Rust code There are Vim highlighting and indentation scripts in the Rust source distribution under `src/etc/vim/`, and an emacs mode under `src/etc/emacs/`. Other editors are not provided for yet. If you end up writing a Rust mode for your favorite editor, let us know so that we can link to it. # Syntax Basics ## Braces Assuming you've programmed in any C-family language (C++, Java, JavaScript, C#, or PHP), Rust will feel familiar. The main surface difference to be aware of is that the bodies of `if` statements and of `while` loops *have* to be wrapped in brackets. Single-statement, bracket-less bodies are not allowed. If the verbosity of that bothers you, consider the fact that this allows you to omit the parentheses around the condition in `if`, `while`, and similar constructs. This will save you two characters every time. As a bonus, you no longer have to spend any mental energy on deciding whether you need to add braces or not, or on adding them after the fact when adding a statement to an `if` branch. Accounting for these differences, the surface syntax of Rust statements and expressions is C-like. Function calls are written `myfunc(arg1, arg2)`, operators have mostly the same name and precedence that they have in C, comments look the same, and constructs like `if` and `while` are available: ~~~~ # fn call_a_function(_a: int) {} fn main() { if 1 < 2 { while false { call_a_function(10 * 4); } } else if 4 < 3 || 3 < 4 { // Comments are C++-style too } else { /* Multi-line comment syntax */ } } ~~~~ ## Expression syntax Though it isn't apparent in all code, there is a fundamental difference between Rust's syntax and the predecessors in this family of languages. A lot of things that are statements in C are expressions in Rust. This allows for useless things like this (which passes nil—the void type—to a function): ~~~~ # fn a_function(_a: ()) {} a_function(while false {}); ~~~~ But also useful things like this: ~~~~ # fn the_stars_align() -> bool { false } # fn something_else() -> bool { true } let x = if the_stars_align() { 4 } else if something_else() { 3 } else { 0 }; ~~~~ This piece of code will bind the variable `x` to a value depending on the conditions. Note the condition bodies, which look like `{ expression }`. The lack of a semicolon after the last statement in a braced block gives the whole block the value of that last expression. If the branches of the `if` had looked like `{ 4; }`, the above example would simply assign nil (void) to `x`. But without the semicolon, each branch has a different value, and `x` gets the value of the branch that was taken. This also works for function bodies. This function returns a boolean: ~~~~ fn is_four(x: int) -> bool { x == 4 } ~~~~ In short, everything that's not a declaration (`let` for variables, `fn` for functions, et cetera) is an expression. If all those things are expressions, you might conclude that you have to add a terminating semicolon after *every* statement, even ones that are not traditionally terminated with a semicolon in C (like `while`). That is not the case, though. Expressions that end in a block only need a semicolon if that block contains a trailing expression. `while` loops do not allow trailing expressions, and `if` statements tend to only have a trailing expression when you want to use their value for something—in which case you'll have embedded it in a bigger statement, like the `let x = ...` example above. ## Identifiers Rust identifiers must start with an alphabetic character or an underscore, and after that may contain any alphanumeric character, and more underscores. NOTE: The parser doesn't currently recognize non-ascii alphabetic characters. This is a bug that will eventually be fixed. The double-colon (`::`) is used as a module separator, so `io::println` means 'the thing named `println` in the module named `io`'. Rust will normally emit warnings about unused variables. These can be suppressed by using a variable name that starts with an underscore. ~~~~ fn this_warns(x: int) {} fn this_doesnt(_x: int) {} ~~~~ ## Variable declaration The `let` keyword, as we've seen, introduces a local variable. Local variables are immutable by default: `let mut` can be used to introduce a local variable that can be reassigned. Global constants can be defined with `const`: ~~~~ use std; const repeat: uint = 5u; fn main() { let hi = "Hi!"; let mut count = 0u; while count < repeat { io::println(hi); count += 1u; } } ~~~~ ## Types The `-> bool` in the `is_four` example is the way a function's return type is written. For functions that do not return a meaningful value (these conceptually return nil in Rust), you can optionally say `-> ()` (`()` is how nil is written), but usually the return annotation is simply left off, as in the `fn main() { ... }` examples we've seen earlier. Every argument to a function must have its type declared (for example, `x: int`). Inside the function, type inference will be able to automatically deduce the type of most locals (generic functions, which we'll come back to later, will occasionally need additional annotation). Locals can be written either with or without a type annotation: ~~~~ // The type of this vector will be inferred based on its use. let x = []; # vec::map(x, fn&(&&_y:int) -> int { _y }); // Explicitly say this is a vector of integers. let y: [int] = []; ~~~~ The basic types are written like this: `()` : Nil, the type that has only a single value. `bool` : Boolean type, with values `true` and `false`. `int` : A machine-pointer-sized integer. `uint` : A machine-pointer-sized unsigned integer. `i8`, `i16`, `i32`, `i64` : Signed integers with a specific size (in bits). `u8`, `u16`, `u32`, `u64` : Unsigned integers with a specific size. `f32`, `f64` : Floating-point types. `float` : The largest floating-point type efficiently supported on the target machine. `char` : A character is a 32-bit Unicode code point. `str` : String type. A string contains a UTF-8 encoded sequence of characters. These can be combined in composite types, which will be described in more detail later on (the `T`s here stand for any other type): `[T]` : Vector type. `[mut T]` : Mutable vector type. `(T1, T2)` : Tuple type. Any arity above 1 is supported. `{field1: T1, field2: T2}` : Record type. `fn(arg1: T1, arg2: T2) -> T3`, `fn@()`, `fn~()`, `fn&()` : Function types. `@T`, `~T`, `*T` : Pointer types. Types can be given names with `type` declarations: ~~~~ type monster_size = uint; ~~~~ This will provide a synonym, `monster_size`, for unsigned integers. It will not actually create a new type—`monster_size` and `uint` can be used interchangeably, and using one where the other is expected is not a type error. Read about [single-variant enums](#single_variant_enum) further on if you need to create a type name that's not just a synonym. ## Literals Integers can be written in decimal (`144`), hexadecimal (`0x90`), and binary (`0b10010000`) base. Without a suffix, an integer literal is considered to be of type `int`. Add a `u` (`144u`) to make it a `uint` instead. Literals of the fixed-size integer types can be created by the literal with the type name (`255u8`, `50i64`, etc). Note that, in Rust, no implicit conversion between integer types happens. If you are adding one to a variable of type `uint`, you must type `v += 1u`—saying `+= 1` will give you a type error. Floating point numbers are written `0.0`, `1e6`, or `2.1e-4`. Without a suffix, the literal is assumed to be of type `float`. Suffixes `f32` and `f64` can be used to create literals of a specific type. The suffix `f` can be used to write `float` literals without a dot or exponent: `3f`. The nil literal is written just like the type: `()`. The keywords `true` and `false` produce the boolean literals. Character literals are written between single quotes, as in `'x'`. You may put non-ascii characters between single quotes (your source files should be encoded as UTF-8). Rust understands a number of character escapes, using the backslash character: `\n` : A newline (Unicode character 32). `\r` : A carriage return (13). `\t` : A tab character (9). `\\`, `\'`, `\"` : Simply escapes the following character. `\xHH`, `\uHHHH`, `\UHHHHHHHH` : Unicode escapes, where the `H` characters are the hexadecimal digits that form the character code. String literals allow the same escape sequences. They are written between double quotes (`"hello"`). Rust strings may contain newlines. When a newline is preceded by a backslash, it, and all white space following it, will not appear in the resulting string literal. So this is equivalent to `"abc"`: ~~~~ let s = "a\ b\ c"; ~~~~ ## Operators Rust's set of operators contains very few surprises. The main difference with C is that `++` and `--` are missing, and that the logical bitwise operators have higher precedence—in C, `x & 2 > 0` comes out as `x & (2 > 0)`, in Rust, it means `(x & 2) > 0`, which is more likely to be what you expect (unless you are a C veteran). Thus, binary arithmetic is done with `*`, `/`, `%`, `+`, and `-` (multiply, divide, remainder, plus, minus). `-` is also a unary prefix operator (there are no unary postfix operators in Rust) that does negation. Binary shifting is done with `>>` (shift right), and `<<` (shift left). Shift right is arithmetic if the value is signed and logical if the value is unsigned. Logical bitwise operators are `&`, `|`, and `^` (and, or, and exclusive or), and unary `!` for bitwise negation (or boolean negation when applied to a boolean value). The comparison operators are the traditional `==`, `!=`, `<`, `>`, `<=`, and `>=`. Short-circuiting (lazy) boolean operators are written `&&` (and) and `||` (or). For type casting, Rust uses the binary `as` operator, which has high precedence, just lower than multiplication and division. It takes an expression on the left side, and a type on the right side, and will, if a meaningful conversion exists, convert the result of the expression to the given type. ~~~~ let x: float = 4.0; let y: uint = x as uint; assert y == 4u; ~~~~ ## Attributes Every definition can be annotated with attributes. Attributes are meta information that can serve a variety of purposes. One of those is conditional compilation: ~~~~ #[cfg(target_os = "win32")] fn register_win_service() { /* ... */ } ~~~~ This will cause the function to vanish without a trace during compilation on a non-Windows platform, much like `#ifdef` in C (it allows `cfg(flag=value)` and `cfg(flag)` forms, where the second simply checks whether the configuration flag is defined at all). Flags for `target_os` and `target_arch` are set by the compiler. It is possible to set additional flags with the `--cfg` command-line option. Attributes are always wrapped in hash-braces (`#[attr]`). Inside the braces, a small minilanguage is supported, whose interpretation depends on the attribute that's being used. The simplest form is a plain name (as in `#[test]`, which is used by the [built-in test framework](#testing)). A name-value pair can be provided using an `=` character followed by a literal (as in `#[license = "BSD"]`, which is a valid way to annotate a Rust program as being released under a BSD-style license). Finally, you can have a name followed by a comma-separated list of nested attributes, as in the `cfg` example above, or in this [crate](#modules-and-crates) metadata declaration: ~~~~ {.ignore} #[link(name = "std", vers = "0.1", url = "http://rust-lang.org/src/std")]; ~~~~ An attribute without a semicolon following it applies to the definition that follows it. When terminated with a semicolon, it applies to the module or crate in which it appears. ## Syntax extensions There are plans to support user-defined syntax (macros) in Rust. This currently only exists in very limited form. The compiler defines a few built-in syntax extensions. The most useful one is `#fmt`, a printf-style text formatting macro that is expanded at compile time. ~~~~ io::println(#fmt("%s is %d", "the answer", 42)); ~~~~ `#fmt` supports most of the directives that [printf][pf] supports, but will give you a compile-time error when the types of the directives don't match the types of the arguments. [pf]: http://en.cppreference.com/w/cpp/io/c/fprintf All syntax extensions look like `#word`. Another built-in one is `#env`, which will look up its argument as an environment variable at compile-time. ~~~~ io::println(#env("PATH")); ~~~~ # Control structures ## Conditionals We've seen `if` pass by a few times already. To recap, braces are compulsory, an optional `else` clause can be appended, and multiple `if`/`else` constructs can be chained together: ~~~~ if false { io::println("that's odd"); } else if true { io::println("right"); } else { io::println("neither true nor false"); } ~~~~ The condition given to an `if` construct *must* be of type boolean (no implicit conversion happens). If the arms return a value, this value must be of the same type for every arm in which control reaches the end of the block: ~~~~ fn signum(x: int) -> int { if x < 0 { -1 } else if x > 0 { 1 } else { ret 0; } } ~~~~ The `ret` (return) and its semicolon could have been left out without changing the meaning of this function, but it illustrates that you will not get a type error in this case, although the last arm doesn't have type `int`, because control doesn't reach the end of that arm (`ret` is jumping out of the function). ## Pattern matching Rust's `alt` construct is a generalized, cleaned-up version of C's `switch` construct. You provide it with a value and a number of arms, each labelled with a pattern, and it will execute the arm that matches the value. ~~~~ # let my_number = 1; alt my_number { 0 { io::println("zero"); } 1 | 2 { io::println("one or two"); } 3 to 10 { io::println("three to ten"); } _ { io::println("something else"); } } ~~~~ There is no 'falling through' between arms, as in C—only one arm is executed, and it doesn't have to explicitly `break` out of the construct when it is finished. The part to the left of each arm is called the pattern. Literals are valid patterns, and will match only their own value. The pipe operator (`|`) can be used to assign multiple patterns to a single arm. Ranges of numeric literal patterns can be expressed with `to`. The underscore (`_`) is a wildcard pattern that matches everything. If the arm with the wildcard pattern was left off in the above example, running it on a number greater than ten (or negative) would cause a run-time failure. When no arm matches, `alt` constructs do not silently fall through—they blow up instead. A powerful application of pattern matching is *destructuring*, where you use the matching to get at the contents of data types. Remember that `(float, float)` is a tuple of two floats: ~~~~ fn angle(vec: (float, float)) -> float { alt vec { (0f, y) if y < 0f { 1.5 * float::consts::pi } (0f, y) { 0.5 * float::consts::pi } (x, y) { float::atan(y / x) } } } ~~~~ A variable name in a pattern matches everything, *and* binds that name to the value of the matched thing inside of the arm block. Thus, `(0f, y)` matches any tuple whose first element is zero, and binds `y` to the second element. `(x, y)` matches any tuple, and binds both elements to a variable. Any `alt` arm can have a guard clause (written `if EXPR`), which is an expression of type `bool` that determines, after the pattern is found to match, whether the arm is taken or not. The variables bound by the pattern are available in this guard expression. ## Destructuring let To a limited extent, it is possible to use destructuring patterns when declaring a variable with `let`. For example, you can say this to extract the fields from a tuple: ~~~~ # fn get_tuple_of_two_ints() -> (int, int) { (1, 1) } let (a, b) = get_tuple_of_two_ints(); ~~~~ This will introduce two new variables, `a` and `b`, bound to the content of the tuple. You may only use irrevocable patterns—patterns that can never fail to match—in let bindings, though. Things like literals, which only match a specific value, are not allowed. ## Loops `while` produces a loop that runs as long as its given condition (which must have type `bool`) evaluates to true. Inside a loop, the keyword `break` can be used to abort the loop, and `cont` can be used to abort the current iteration and continue with the next. ~~~~ let mut cake_amount = 8; while cake_amount > 0 { cake_amount -= 1; } ~~~~ `loop` is the preferred way of writing `while true`: ~~~~ let mut x = 5; while true { x += x - 3; if x % 5 == 0 { break; } io::println(int::str(x)); } ~~~~ This code prints out a weird sequence of numbers and stops as soon as it finds one that can be divided by five. For more involved iteration, such as going over the elements of a collection, Rust uses higher-order functions. We'll come back to those in a moment. ## Failure The `fail` keyword causes the current [task](#tasks) to fail. You use it to indicate unexpected failure, much like you'd use `exit(1)` in a C program, except that in Rust, it is possible for other tasks to handle the failure, allowing the program to continue running. `fail` takes an optional argument, which must have type `str`. Trying to access a vector out of bounds, or running a pattern match with no matching clauses, both result in the equivalent of a `fail`. ## Logging Rust has a built-in logging mechanism, using the `log` statement. Logging is polymorphic—any type of value can be logged, and the runtime will do its best to output a textual representation of the value. ~~~~ log(warn, "hi"); log(error, (1, [2.5, -1.8])); ~~~~ The first argument is the log level (levels `debug`, `info`, `warn`, and `error` are predefined), and the second is the value to log. By default, you *will not* see the output of that first log statement, which has `warn` level. The environment variable `RUST_LOG` controls which log level is used. It can contain a comma-separated list of paths for modules that should be logged. For example, running `rustc` with `RUST_LOG=rustc::front::attr` will turn on logging in its attribute parser. If you compile a program named `foo.rs`, its top-level module will be called `foo`, and you can set `RUST_LOG` to `foo` to enable `warn`, `info` and `debug` logging for the module. Turned-off `log` statements impose minimal overhead on the code that contains them, because the arguments to `log` are evaluated lazily. So except in code that needs to be really, really fast, you should feel free to scatter around debug logging statements, and leave them in. Three macros that combine text-formatting (as with `#fmt`) and logging are available. These take a string and any number of format arguments, and will log the formatted string: ~~~~ # fn get_error_string() -> str { "boo" } #warn("only %d seconds remaining", 10); #error("fatal: %s", get_error_string()); ~~~~ Because the macros `#debug`, `#warn`, and `#error` expand to calls to `log`, their arguments are also lazily evaluated. ## Assertions The keyword `assert`, followed by an expression with boolean type, will check that the given expression results in `true`, and cause a failure otherwise. It is typically used to double-check things that *should* hold at a certain point in a program. ~~~~ let mut x = 100; while (x > 10) { x -= 10; } assert x == 10; ~~~~ # Functions Functions (like all other static declarations, such as `type`) can be declared both at the top level and inside other functions (or modules, which we'll come back to in moment). The `ret` keyword immediately returns from a function. It is optionally followed by an expression to return. In functions that return `()`, the returned expression can be left off. A function can also return a value by having its top level block produce an expression (by omitting the final semicolon). Some functions (such as the C function `exit`) never return normally. In Rust, these are annotated with the pseudo-return type '`!`': ~~~~ fn dead_end() -> ! { fail; } ~~~~ This helps the compiler avoid spurious error messages. For example, the following code would be a type error if `dead_end` would be expected to return. ~~~~ # fn can_go_left() -> bool { true } # fn can_go_right() -> bool { true } # enum dir { left, right } # fn dead_end() -> ! { fail; } let dir = if can_go_left() { left } else if can_go_right() { right } else { dead_end(); }; ~~~~ ## Closures Named functions, like those in the previous section, do not close over their environment. Rust also includes support for closures, which are functions that can access variables in the scope in which they are created. There are several forms of closures, each with its own role. The most common type is called a 'stack closure'; this is a closure which has full access to its environment. ~~~~ fn call_closure_with_ten(b: fn(int)) { b(10); } let x = 20; call_closure_with_ten({|arg| #info("x=%d, arg=%d", x, arg); }); ~~~~ This defines a function that accepts a closure, and then calls it with a simple stack closure that executes a log statement, accessing both its argument and the variable `x` from its environment. Stack closures are called stack closures because they directly access the stack frame in which they are created. This makes them very lightweight to construct and lets them modify local variables from the enclosing scope, but it also makes it unsafe for the closure to survive the scope in which it was created. To prevent them from being used after the creating scope has returned, stack closures can only be used in a restricted way: they are allowed to appear in function argument position and in call position, but nowhere else. ### Boxed closures When you need to store a closure in a data structure, a stack closure will not do, since the compiler will refuse to let you store it. For this purpose, Rust provides a type of closure that has an arbitrary lifetime, written `fn@` (boxed closure, analogous to the `@` pointer type described in the next section). A boxed closure does not directly access its environment, but merely copies out the values that it closes over into a private data structure. This means that it can not assign to these variables, and will not 'see' updates to them. This code creates a closure that adds a given string to its argument, returns it from a function, and then calls it: ~~~~ use std; fn mk_appender(suffix: str) -> fn@(str) -> str { let f = fn@(s: str) -> str { s + suffix }; ret f; } fn main() { let shout = mk_appender("!"); io::println(shout("hey ho, let's go")); } ~~~~ ### Closure compatibility A nice property of Rust closures is that you can pass any kind of closure (as long as the arguments and return types match) to functions that expect a `fn()`. Thus, when writing a higher-order function that wants to do nothing with its function argument beyond calling it, you should almost always specify the type of that argument as `fn()`, so that callers have the flexibility to pass whatever they want. ~~~~ fn call_twice(f: fn()) { f(); f(); } call_twice({|| "I am a stack closure"; }); call_twice(fn@() { "I am a boxed closure"; }); fn bare_function() { "I am a plain function"; } call_twice(bare_function); ~~~~ ### Unique closures Unique closures, written `fn~` in analogy to the `~` pointer type (see next section), hold on to things that can safely be sent between processes. They copy the values they close over, much like boxed closures, but they also 'own' them—meaning no other code can access them. Unique closures mostly exist for spawning new [tasks](#tasks). ### Shorthand syntax The compact syntax used for stack closures (`{|arg1, arg2| body}`) can also be used to express boxed and unique closures in situations where the closure style can be unambiguously derived from the context. Most notably, when calling a higher-order function you do not have to use the long-hand syntax for the function you're passing, since the compiler can look at the argument type to find out what the parameter types are. As a further simplification, if the final parameter to a function is a closure, the closure need not be placed within parentheses. You could, for example, write... ~~~~ let doubled = vec::map([1, 2, 3]) {|x| x*2}; ~~~~ `vec::map` is a function in the core library that applies its last argument to every element of a vector, producing a new vector. Even when a closure takes no parameters, you must still write the bars for the parameter list, as in `{|| ...}`. ## Binding Partial application is done using the `bind` keyword in Rust. ~~~~ let daynum = bind vec::position_elem(["mo", "tu", "we", "th", "fr", "sa", "su"], _); ~~~~ Binding a function produces a boxed closure (`fn@` type) in which some of the arguments to the bound function have already been provided. `daynum` will be a function taking a single string argument, and returning the day of the week that string corresponds to (if any). ## Iteration Functions taking closures provide a good way to define non-trivial iteration constructs. For example, this one iterates over a vector of integers backwards: ~~~~ fn for_rev(v: [int], act: fn(int)) { let mut i = vec::len(v); while (i > 0u) { i -= 1u; act(v[i]); } } ~~~~ To run such an iteration, you could do this: ~~~~ # fn for_rev(v: [int], act: fn(int)) {} for_rev([1, 2, 3], {|n| log(error, n); }); ~~~~ Making use of the shorthand where a final closure argument can be moved outside of the parentheses permits the following, which looks quite like a normal loop: ~~~~ # fn for_rev(v: [int], act: fn(int)) {} for_rev([1, 2, 3]) {|n| log(error, n); } ~~~~ Note that, because `for_rev()` returns unit type, no semicolon is needed when the final closure is pulled outside of the parentheses. # For loops To allow breaking out of loops, many iteration functions, such as `vec::each`, take a function that returns a boolean, and can return `false` to break off iteration. ~~~~ vec::each([2, 4, 8, 5, 16]) {|n| if n % 2 != 0 { io::println("found odd number!"); false } else { true } } ~~~~ You can see how that gets noisy. As a syntactic convenience, if the call is preceded by the keyword `for`, the block will implicitly return `true`, and `break` and `cont` can be used, much like in a `while` loop, to explicitly return `false` or `true`. ~~~~ for vec::each([2, 4, 8, 5, 16]) {|n| if n % 2 != 0 { io::println("found odd number!"); break; } } ~~~~ As an added bonus, you can use the `ret` keyword, which is not normally allowed in blocks, in a block that appears as the body of a `for` loop — this will cause a return to happen from the outer function, not just the loop body. ~~~~ fn contains(v: [int], elt: int) -> bool { for vec::each(v) {|x| if (x == elt) { ret true; } } false } ~~~~ # Datatypes Rust datatypes are, by default, immutable. The core datatypes of Rust are structural records and 'enums' (tagged unions, algebraic data types). ~~~~ type point = {x: float, y: float}; enum shape { circle(point, float), rectangle(point, point) } let my_shape = circle({x: 0.0, y: 0.0}, 10.0); ~~~~ ## Records Rust record types are written `{field1: T1, field2: T2 [, ...]}`, where `T1`, `T2`, ... denote types. Record literals are written in the same way, but with expressions instead of types. They are quite similar to C structs, and even laid out the same way in memory (so you can read from a Rust struct in C, and vice-versa). The dot operator is used to access record fields (`mypoint.x`). Fields that you want to mutate must be explicitly marked as such. For example... ~~~~ type stack = {content: [int], mut head: uint}; ~~~~ With such a type, you can do `mystack.head += 1u`. If `mut` were omitted from the type, such an assignment would result in a type error. To 'update' an immutable record, you use functional record update syntax, by ending a record literal with the keyword `with`: ~~~~ let oldpoint = {x: 10f, y: 20f}; let newpoint = {x: 0f with oldpoint}; assert newpoint == {x: 0f, y: 20f}; ~~~~ This will create a new struct, copying all the fields from `oldpoint` into it, except for the ones that are explicitly set in the literal. Rust record types are *structural*. This means that `{x: float, y: float}` is not just a way to define a new type, but is the actual name of the type. Record types can be used without first defining them. If module A defines `type point = {x: float, y: float}`, and module B, without knowing anything about A, defines a function that returns an `{x: float, y: float}`, you can use that return value as a `point` in module A. (Remember that `type` defines an additional name for a type, not an actual new type.) ## Record patterns Records can be destructured in `alt` patterns. The basic syntax is `{fieldname: pattern, ...}`, but the pattern for a field can be omitted as a shorthand for simply binding the variable with the same name as the field. ~~~~ # let mypoint = {x: 0f, y: 0f}; alt mypoint { {x: 0f, y: y_name} { /* Provide sub-patterns for fields */ } {x, y} { /* Simply bind the fields */ } } ~~~~ The field names of a record do not have to appear in a pattern in the same order they appear in the type. When you are not interested in all the fields of a record, a record pattern may end with `, _` (as in `{field1, _}`) to indicate that you're ignoring all other fields. ## Enums Enums are datatypes that have several different representations. For example, the type shown earlier: ~~~~ # type point = {x: float, y: float}; enum shape { circle(point, float), rectangle(point, point) } ~~~~ A value of this type is either a circle, in which case it contains a point record and a float, or a rectangle, in which case it contains two point records. The run-time representation of such a value includes an identifier of the actual form that it holds, much like the 'tagged union' pattern in C, but with better ergonomics. The above declaration will define a type `shape` that can be used to refer to such shapes, and two functions, `circle` and `rectangle`, which can be used to construct values of the type (taking arguments of the specified types). So `circle({x: 0f, y: 0f}, 10f)` is the way to create a new circle. Enum variants do not have to have parameters. This, for example, is equivalent to a C enum: ~~~~ enum direction { north, east, south, west } ~~~~ This will define `north`, `east`, `south`, and `west` as constants, all of which have type `direction`. When an enum is C-like, that is, when none of the variants have parameters, it is possible to explicitly set the discriminator values to an integer value: ~~~~ enum color { red = 0xff0000, green = 0x00ff00, blue = 0x0000ff } ~~~~ If an explicit discriminator is not specified for a variant, the value defaults to the value of the previous variant plus one. If the first variant does not have a discriminator, it defaults to 0. For example, the value of `north` is 0, `east` is 1, etc. When an enum is C-like the `as` cast operator can be used to get the discriminator's value. There is a special case for enums with a single variant. These are used to define new types in such a way that the new name is not just a synonym for an existing type, but its own distinct type. If you say: ~~~~ enum gizmo_id = int; ~~~~ That is a shorthand for this: ~~~~ enum gizmo_id { gizmo_id(int) } ~~~~ Enum types like this can have their content extracted with the dereference (`*`) unary operator: ~~~~ # enum gizmo_id = int; let my_gizmo_id = gizmo_id(10); let id_int: int = *my_gizmo_id; ~~~~ ## Enum patterns For enum types with multiple variants, destructuring is the only way to get at their contents. All variant constructors can be used as patterns, as in this definition of `area`: ~~~~ # type point = {x: float, y: float}; # enum shape { circle(point, float), rectangle(point, point) } fn area(sh: shape) -> float { alt sh { circle(_, size) { float::consts::pi * size * size } rectangle({x, y}, {x: x2, y: y2}) { (x2 - x) * (y2 - y) } } } ~~~~ Another example, matching nullary enum variants: ~~~~ # type point = {x: float, y: float}; # enum direction { north, east, south, west } fn point_from_direction(dir: direction) -> point { alt dir { north { {x: 0f, y: 1f} } east { {x: 1f, y: 0f} } south { {x: 0f, y: -1f} } west { {x: -1f, y: 0f} } } } ~~~~ ## Tuples Tuples in Rust behave exactly like records, except that their fields do not have names (and can thus not be accessed with dot notation). Tuples can have any arity except for 0 or 1 (though you may see nil, `()`, as the empty tuple if you like). ~~~~ let mytup: (int, int, float) = (10, 20, 30.0); alt mytup { (a, b, c) { log(info, a + b + (c as int)); } } ~~~~ ## Pointers In contrast to a lot of modern languages, record and enum types in Rust are not represented as pointers to allocated memory. They are, like in C and C++, represented directly. This means that if you `let x = {x: 1f, y: 1f};`, you are creating a record on the stack. If you then copy it into a data structure, the whole record is copied, not just a pointer. For small records like `point`, this is usually more efficient than allocating memory and going through a pointer. But for big records, or records with mutable fields, it can be useful to have a single copy on the heap, and refer to that through a pointer. Rust supports several types of pointers. The simplest is the unsafe pointer, written `*T`, which is a completely unchecked pointer type only used in unsafe code (and thus, in typical Rust code, very rarely). The safe pointer types are `@T` for shared, reference-counted boxes, and `~T`, for uniquely-owned pointers. All pointer types can be dereferenced with the `*` unary operator. ### Shared boxes Shared boxes are pointers to heap-allocated, reference counted memory. A cycle collector ensures that circular references do not result in memory leaks. Creating a shared box is done by simply applying the unary `@` operator to an expression. The result of the expression will be boxed, resulting in a box of the right type. For example: ~~~~ let x = @10; // New box, refcount of 1 let y = x; // Copy the pointer, increase refcount // When x and y go out of scope, refcount goes to 0, box is freed ~~~~ NOTE: We may in the future switch to garbage collection, rather than reference counting, for shared boxes. Shared boxes never cross task boundaries. ### Unique boxes In contrast to shared boxes, unique boxes are not reference counted. Instead, it is statically guaranteed that only a single owner of the box exists at any time. ~~~~ let x = ~10; let y <- x; ~~~~ This is where the 'move' (`<-`) operator comes in. It is similar to `=`, but it de-initializes its source. Thus, the unique box can move from `x` to `y`, without violating the constraint that it only has a single owner (if you used assignment instead of the move operator, the box would, in principle, be copied). Unique boxes, when they do not contain any shared boxes, can be sent to other tasks. The sending task will give up ownership of the box, and won't be able to access it afterwards. The receiving task will become the sole owner of the box. ### Mutability All pointer types have a mutable variant, written `@mut T` or `~mut T`. Given such a pointer, you can write to its contents by combining the dereference operator with a mutating action. ~~~~ fn increase_contents(pt: @mut int) { *pt += 1; } ~~~~ ## Vectors Rust vectors are always heap-allocated and unique. A value of type `[T]` is represented by a pointer to a section of heap memory containing any number of values of type `T`. NOTE: This uniqueness is turning out to be quite awkward in practice, and might change in the future. Vector literals are enclosed in square brackets. Dereferencing is done with square brackets (zero-based): ~~~~ let myvec = [true, false, true, false]; if myvec[1] { io::println("boom"); } ~~~~ By default, vectors are immutable—you can not replace their elements. The type written as `[mut T]` is a vector with mutable elements. Mutable vector literals are written `[mut]` (empty) or `[mut 1, 2, 3]` (with elements). The `+` operator means concatenation when applied to vector types. Growing a vector in Rust is not as inefficient as it looks : ~~~~ let mut myvec = [], i = 0; while i < 100 { myvec += [i]; i += 1; } ~~~~ Because a vector is unique, replacing it with a longer one (which is what `+= [i]` does) is indistinguishable from appending to it in-place. Vector representations are optimized to grow logarithmically, so the above code generates about the same amount of copying and reallocation as `push` implementations in most other languages. ## Strings The `str` type in Rust is represented exactly the same way as a vector of bytes (`[u8]`), except that it is guaranteed to have a trailing null byte (for interoperability with C APIs). This sequence of bytes is interpreted as an UTF-8 encoded sequence of characters. This has the advantage that UTF-8 encoded I/O (which should really be the default for modern systems) is very fast, and that strings have, for most intents and purposes, a nicely compact representation. It has the disadvantage that you only get constant-time access by byte, not by character. A lot of algorithms don't need constant-time indexed access (they iterate over all characters, which `str::chars` helps with), and for those that do, many don't need actual characters, and can operate on bytes. For algorithms that do really need to index by character, there's the option to convert your string to a character vector (using `str::chars`). Like vectors, strings are always unique. You can wrap them in a shared box to share them. Unlike vectors, there is no mutable variant of strings. They are always immutable. ## Resources Resources are data types that have a destructor associated with them. ~~~~ # fn close_file_desc(x: int) {} resource file_desc(fd: int) { close_file_desc(fd); } ~~~~ This defines a type `file_desc` and a constructor of the same name, which takes an integer. The type has an associated destructor procedure, whose contents are specified by the block. Values of such a type can not be copied, and when they are destroyed (by going out of scope, or, when boxed, when their box is cleaned up), their body runs. In the example above, this would cause the given file descriptor to be closed. NOTE: We're considering alternative approaches for data types with destructors. Resources might go away in the future. # Argument passing Rust datatypes are not trivial to copy (the way, for example, JavaScript values can be copied by simply taking one or two machine words and plunking them somewhere else). Shared boxes require reference count updates, and big records, enums, or unique pointers require an arbitrary amount of data to be copied (plus updating the reference counts of shared boxes hanging off them). For this reason, the default calling convention for Rust functions leaves ownership of the arguments with the caller. The caller guarantees that the arguments will outlive the call, the callee merely gets access to them. ## Safe references There is one catch with this approach: sometimes the compiler can *not* statically guarantee that the argument value at the caller side will survive to the end of the call. Another argument might indirectly refer to it and be used to overwrite it, or a closure might assign a new value to it. Fortunately, Rust tasks are single-threaded worlds, which share no data with other tasks, and most data is immutable. This allows most argument-passing situations to be proved safe without further difficulty. Take the following program: ~~~~ # fn get_really_big_record() -> int { 1 } # fn myfunc(a: int) {} fn main() { let x = get_really_big_record(); myfunc(x); } ~~~~ Here we know for sure that no one else has access to the `x` variable in `main`, so we're good. But the call could also look like this: ~~~~ # fn myfunc(a: int, b: fn()) {} # fn get_another_record() -> int { 1 } # let mut x = 1; myfunc(x, {|| x = get_another_record(); }); ~~~~ Now, if `myfunc` first calls its second argument and then accesses its first argument, it will see a different value from the one that was passed to it. In such a case, the compiler will insert an implicit copy of `x`, *except* if `x` contains something mutable, in which case a copy would result in code that behaves differently. If copying `x` might be expensive (for example, if it holds a vector), the compiler will emit a warning. There are even more tricky cases, in which the Rust compiler is forced to pessimistically assume a value will get mutated, even though it is not sure. ~~~~ fn for_each(v: [mut @int], iter: fn(@int)) { for v.each {|elt| iter(elt); } } ~~~~ For all this function knows, calling `iter` (which is a closure that might have access to the vector that's passed as `v`) could cause the elements in the vector to be mutated, with the effect that it can not guarantee that the boxes will live for the duration of the call. So it has to copy them. In this case, this will happen implicitly (bumping a reference count is considered cheap enough to not warn about it). ## The copy operator If the `for_each` function given above were to take a vector of `{mut a: int}` instead of `@int`, it would not be able to implicitly copy, since if the `iter` function changes a copy of a mutable record, the changes won't be visible in the record itself. If we *do* want to allow copies there, we have to explicitly allow it with the `copy` operator: ~~~~ type mutrec = {mut x: int}; fn for_each(v: [mut mutrec], iter: fn(mutrec)) { for v.each {|elt| iter(copy elt); } } ~~~~ Adding a `copy` operator is also the way to muffle warnings about implicit copies. ## Other uses of safe references Safe references are not only used for argument passing. When you destructure on a value in an `alt` expression, or loop over a vector with `for`, variables bound to the inside of the given data structure will use safe references, not copies. This means such references are very cheap, but you'll occasionally have to copy them to ensure safety. ~~~~ let mut my_rec = {a: 4, b: [1, 2, 3]}; alt my_rec { {a, b} { log(info, b); // This is okay my_rec = {a: a + 1, b: b + [a]}; log(info, b); // Here reference b has become invalid } } ~~~~ ## Argument passing styles The fact that arguments are conceptually passed by safe reference does not mean all arguments are passed by pointer. Composite types like records and enums *are* passed by pointer, but single-word values, like integers and pointers, are simply passed by value. Most of the time, the programmer does not have to worry about this, as the compiler will simply pick the most efficient passing style. There is one exception, which will be described in the section on [generics](#generics). To explicitly set the passing-style for a parameter, you prefix the argument name with a sigil. There are three special passing styles that are often useful. The first is by-mutable-pointer, written with a single `&`: ~~~~ fn vec_push(&v: [int], elt: int) { v += [elt]; } ~~~~ This allows the function to mutate the value of the argument, *in the caller's context*. Clearly, you are only allowed to pass things that can actually be mutated to such a function. Then there is the by-copy style, written `+`. This indicates that the function wants to take ownership of the argument value. If the caller does not use the argument after the call, it will be 'given' to the callee. Otherwise a copy will be made. This mode is mostly used for functions that construct data structures. The argument will end up being owned by the data structure, so if that can be done without a copy, that's a win. ~~~~ type person = {name: str, address: str}; fn make_person(+name: str, +address: str) -> person { ret {name: name, address: address}; } ~~~~ Finally there is by-move style, written `-`. This indicates that the function will take ownership of the argument, like with by-copy style, but a copy must not be made. The caller is (statically) obliged to not use the argument after the call; it is de-initialized as part of the call. This is used to support ownership-passing in the presence of non-copyable types. # Generics ## Generic functions Throughout this tutorial, we've been defining functions like `for_rev` that act only on single data types. It is 2012, and we no longer expect to be defining such functions again and again for every type they apply to. Thus, Rust allows functions and datatypes to have type parameters. ~~~~ fn for_rev(v: [T], act: fn(T)) { let mut i = vec::len(v); while i > 0u { i -= 1u; act(v[i]); } } fn map(v: [T], f: fn(T) -> U) -> [U] { let mut acc = []; for v.each {|elt| acc += [f(elt)]; } ret acc; } ~~~~ When defined in this way, these functions can be applied to any type of vector, as long as the type of the closure's argument and the type of the vector's content agree with each other. Inside a parameterized (generic) function, the names of the type parameters (capitalized by convention) stand for opaque types. You can't look inside them, but you can pass them around. ## Generic datatypes Generic `type` and `enum` declarations follow the same pattern: ~~~~ type circular_buf = {start: uint, end: uint, buf: [mut T]}; enum option { some(T), none } ~~~~ You can then declare a function to take a `circular_buf` or return an `option`, or even an `option` if the function itself is generic. The `option` type given above exists in the core library and is the way Rust programs express the thing that in C would be a nullable pointer. The nice part is that you have to explicitly unpack an `option` type, so accidental null pointer dereferences become impossible. ## Type-inference and generics Rust's type inferrer works very well with generics, but there are programs that just can't be typed. ~~~~ let n = option::none; # option::iter(n, fn&(&&x:int) {}) ~~~~ If you never do anything else with `n`, the compiler will not be able to assign a type to it. (The same goes for `[]`, the empty vector.) If you really want to have such a statement, you'll have to write it like this: ~~~~ let n2: option = option::none; // or let n = option::none::; ~~~~ Note that, in a value expression, `<` already has a meaning as a comparison operator, so you'll have to write `::` to explicitly give a type to a name that denotes a generic value. Fortunately, this is rarely necessary. ## Polymorphic built-ins There are two built-in operations that, perhaps surprisingly, act on values of any type. It was already mentioned earlier that `log` can take any type of value and output it. More interesting is that Rust also defines an ordering for values of all datatypes, and allows you to meaningfully apply comparison operators (`<`, `>`, `<=`, `>=`, `==`, `!=`) to them. For structural types, the comparison happens left to right, so `"abc" < "bac"` (but note that `"bac" < "ác"`, because the ordering acts on UTF-8 sequences without any sophistication). ## Kinds Perhaps surprisingly, the 'copy' (duplicate) operation is not defined for all Rust types. Resource types (types with destructors) can not be copied, and neither can any type whose copying would require copying a resource (such as records or unique boxes containing a resource). This complicates handling of generic functions. If you have a type parameter `T`, can you copy values of that type? In Rust, you can't, unless you explicitly declare that type parameter to have copyable 'kind'. A kind is a type of type. ~~~~ {.ignore} // This does not compile fn head_bad(v: [T]) -> T { v[0] } // This does fn head(v: [T]) -> T { v[0] } ~~~~ When instantiating a generic function, you can only instantiate it with types that fit its kinds. So you could not apply `head` to a resource type. Rust has three kinds: 'noncopyable', 'copyable', and 'sendable'. By default, type parameters are considered to be noncopyable. You can annotate them with the `copy` keyword to declare them copyable, and with the `send` keyword to make them sendable. Sendable types are a subset of copyable types. They are types that do not contain shared (reference counted) types, which are thus uniquely owned by the function that owns them, and can be sent over channels to other tasks. Most of the generic functions in the core `comm` module take sendable types. ## Generic functions and argument-passing The previous section mentioned that arguments are passed by pointer or by value based on their type. There is one situation in which this is difficult. If you try this program: ~~~~{.xfail-test} fn plus1(x: int) -> int { x + 1 } vec::map([1, 2, 3], plus1); ~~~~ You will get an error message about argument passing styles disagreeing. The reason is that generic types are always passed by pointer, so `map` expects a function that takes its argument by pointer. The `plus1` you defined, however, uses the default, efficient way to pass integers, which is by value. To get around this issue, you have to explicitly mark the arguments to a function that you want to pass to a generic higher-order function as being passed by pointer, using the `&&` sigil: ~~~~ fn plus1(&&x: int) -> int { x + 1 } vec::map([1, 2, 3], plus1); ~~~~ NOTE: This is inconvenient, and we are hoping to get rid of this restriction in the future. # Modules and crates The Rust namespace is divided into modules. Each source file starts with its own module. ## Local modules The `mod` keyword can be used to open a new, local module. In the example below, `chicken` lives in the module `farm`, so, unless you explicitly import it, you must refer to it by its long name, `farm::chicken`. ~~~~ mod farm { fn chicken() -> str { "cluck cluck" } fn cow() -> str { "mooo" } } fn main() { io::println(farm::chicken()); } ~~~~ Modules can be nested to arbitrary depth. ## Crates The unit of independent compilation in Rust is the crate. Libraries tend to be packaged as crates, and your own programs may consist of one or more crates. When compiling a single `.rs` file, the file acts as the whole crate. You can compile it with the `--lib` compiler switch to create a shared library, or without, provided that your file contains a `fn main` somewhere, to create an executable. It is also possible to include multiple files in a crate. For this purpose, you create a `.rc` crate file, which references any number of `.rs` code files. A crate file could look like this: ~~~~ {.ignore} #[link(name = "farm", vers = "2.5", author = "mjh")]; #[crate_type = "lib"]; mod cow; mod chicken; mod horse; ~~~~ Compiling this file will cause `rustc` to look for files named `cow.rs`, `chicken.rs`, `horse.rs` in the same directory as the `.rc` file, compile them all together, and, depending on the presence of the `crate_type = "lib"` attribute, output a shared library or an executable. (If the line `#[crate_type = "lib"];` was omitted, `rustc` would create an executable.) The `#[link(...)]` part provides meta information about the module, which other crates can use to load the right module. More about that later. To have a nested directory structure for your source files, you can nest mods in your `.rc` file: ~~~~ {.ignore} mod poultry { mod chicken; mod turkey; } ~~~~ The compiler will now look for `poultry/chicken.rs` and `poultry/turkey.rs`, and export their content in `poultry::chicken` and `poultry::turkey`. You can also provide a `poultry.rs` to add content to the `poultry` module itself. ## Using other crates Having compiled a crate that contains the `#[crate_type = "lib"]` attribute, you can use it in another crate with a `use` directive. We've already seen `use std` in several of the examples, which loads in the [standard library][std]. [std]: http://doc.rust-lang.org/doc/std/index/General.html `use` directives can appear in a crate file, or at the top level of a single-file `.rs` crate. They will cause the compiler to search its library search path (which you can extend with `-L` switch) for a Rust crate library with the right name. It is possible to provide more specific information when using an external crate. ~~~~ {.ignore} use myfarm (name = "farm", vers = "2.7"); ~~~~ When a comma-separated list of name/value pairs is given after `use`, these are matched against the attributes provided in the `link` attribute of the crate file, and a crate is only used when the two match. A `name` value can be given to override the name used to search for the crate. So the above would import the `farm` crate under the local name `myfarm`. Our example crate declared this set of `link` attributes: ~~~~ {.ignore} #[link(name = "farm", vers = "2.5", author = "mjh")]; ~~~~ The version does not match the one provided in the `use` directive, so unless the compiler can find another crate with the right version somewhere, it will complain that no matching crate was found. ## The core library A set of basic library routines, mostly related to built-in datatypes and the task system, are always implicitly linked and included in any Rust program, unless the `--no-core` compiler switch is given. This library is documented [here][core]. [core]: http://doc.rust-lang.org/doc/core ## A minimal example Now for something that you can actually compile yourself. We have these two files: ~~~~ // mylib.rs #[link(name = "mylib", vers = "1.0")]; fn world() -> str { "world" } ~~~~ ~~~~ {.ignore} // main.rs use std; use mylib; fn main() { io::println("hello " + mylib::world()); } ~~~~ Now compile and run like this (adjust to your platform if necessary): ~~~~ {.notrust} > rustc --lib mylib.rs > rustc main.rs -L . > ./main "hello world" ~~~~ ## Importing When using identifiers from other modules, it can get tiresome to qualify them with the full module path every time (especially when that path is several modules deep). Rust allows you to import identifiers at the top of a file, module, or block. ~~~~ use std; import io::println; fn main() { println("that was easy"); } ~~~~ It is also possible to import just the name of a module (`import std::list;`, then use `list::find`), to import all identifiers exported by a given module (`import io::*`), or to import a specific set of identifiers (`import math::{min, max, pi}`). You can rename an identifier when importing using the `=` operator: ~~~~ import prnt = io::println; ~~~~ ## Exporting By default, a module exports everything that it defines. This can be restricted with `export` directives at the top of the module or file. ~~~~ mod enc { export encrypt, decrypt; const super_secret_number: int = 10; fn encrypt(n: int) -> int { n + super_secret_number } fn decrypt(n: int) -> int { n - super_secret_number } } ~~~~ This defines a rock-solid encryption algorithm. Code outside of the module can refer to the `enc::encrypt` and `enc::decrypt` identifiers just fine, but it does not have access to `enc::super_secret_number`. ## Namespaces Rust uses three different namespaces: one for modules, one for types, and one for values. This means that this code is valid: ~~~~ mod buffalo { type buffalo = int; fn buffalo(buffalo: buffalo) -> buffalo { buffalo } } fn main() { let buffalo: buffalo::buffalo = 1; buffalo::buffalo(buffalo::buffalo(buffalo)); } ~~~~ You don't want to write things like that, but it *is* very practical to not have to worry about name clashes between types, values, and modules. This allows us to have a module `core::str`, for example, even though `str` is a built-in type name. ## Resolution The resolution process in Rust simply goes up the chain of contexts, looking for the name in each context. Nested functions and modules create new contexts inside their parent function or module. A file that's part of a bigger crate will have that crate's context as its parent context. Identifiers can shadow each other. In this program, `x` is of type `int`: ~~~~ type t = str; fn main() { type t = int; let x: t; } ~~~~ An `import` directive will only import into the namespaces for which identifiers are actually found. Consider this example: ~~~~ type bar = uint; mod foo { fn bar() {} } mod baz { import foo::bar; const x: bar = 20u; } ~~~~ When resolving the type name `bar` in the `const` definition, the resolver will first look at the module context for `baz`. This has an import named `bar`, but that's a function, not a type, So it continues to the top level and finds a type named `bar` defined there. Normally, multiple definitions of the same identifier in a scope are disallowed. Local variables defined with `let` are an exception to this—multiple `let` directives can redefine the same variable in a single scope. When resolving the name of such a variable, the most recent definition is used. ~~~~ fn main() { let x = 10; let x = x + 10; assert x == 20; } ~~~~ This makes it possible to rebind a variable without actually mutating it, which is mostly useful for destructuring (which can rebind, but not assign). # Interfaces Interfaces are Rust's take on value polymorphism—the thing that object-oriented languages tend to solve with methods and inheritance. For example, writing a function that can operate on multiple types of collections. NOTE: This feature is very new, and will need a few extensions to be applicable to more advanced use cases. ## Declaration An interface consists of a set of methods. A method is a function that can be applied to a `self` value and a number of arguments, using the dot notation: `self.foo(arg1, arg2)`. For example, we could declare the interface `to_str` for things that can be converted to a string, with a single method of the same name: ~~~~ iface to_str { fn to_str() -> str; } ~~~~ ## Implementation To actually implement an interface for a given type, the `impl` form is used. This defines implementations of `to_str` for the `int` and `str` types. ~~~~ # iface to_str { fn to_str() -> str; } impl of to_str for int { fn to_str() -> str { int::to_str(self, 10u) } } impl of to_str for str { fn to_str() -> str { self } } ~~~~ Given these, we may call `1.to_str()` to get `"1"`, or `"foo".to_str()` to get `"foo"` again. This is basically a form of static overloading—when the Rust compiler sees the `to_str` method call, it looks for an implementation that matches the type with a method that matches the name, and simply calls that. ## Scoping Implementations are not globally visible. Resolving a method to an implementation requires that implementation to be in scope. You can import and export implementations using the name of the interface they implement (multiple implementations with the same name can be in scope without problems). Or you can give them an explicit name if you prefer, using this syntax: ~~~~ # iface to_str { fn to_str() -> str; } impl nil_to_str of to_str for () { fn to_str() -> str { "()" } } ~~~~ ## Bounded type parameters The useful thing about value polymorphism is that it does not have to be static. If object-oriented languages only let you call a method on an object when they knew exactly which sub-type it had, that would not get you very far. To be able to call methods on types that aren't known at compile time, it is possible to specify 'bounds' for type parameters. ~~~~ # iface to_str { fn to_str() -> str; } fn comma_sep(elts: [T]) -> str { let mut result = "", first = true; for elts.each {|elt| if first { first = false; } else { result += ", "; } result += elt.to_str(); } ret result; } ~~~~ The syntax for this is similar to the syntax for specifying that a parameter type has to be copyable (which is, in principle, another kind of bound). By declaring `T` as conforming to the `to_str` interface, it becomes possible to call methods from that interface on values of that type inside the function. It will also cause a compile-time error when anyone tries to call `comma_sep` on an array whose element type does not have a `to_str` implementation in scope. ## Polymorphic interfaces Interfaces may contain type parameters. This defines an interface for generalized sequence types: ~~~~ iface seq { fn len() -> uint; fn iter(fn(T)); } impl of seq for [T] { fn len() -> uint { vec::len(self) } fn iter(b: fn(T)) { for self.each {|elt| b(elt); } } } ~~~~ Note that the implementation has to explicitly declare the its parameter `T` before using it to specify its interface type. This is needed because it could also, for example, specify an implementation of `seq`—the `of` clause *refers* to a type, rather than defining one. ## Casting to an interface type The above allows us to define functions that polymorphically act on values of *an* unknown type that conforms to a given interface. However, consider this function: ~~~~ # iface drawable { fn draw(); } fn draw_all(shapes: [T]) { for shapes.each {|shape| shape.draw(); } } ~~~~ You can call that on an array of circles, or an array of squares (assuming those have suitable `drawable` interfaces defined), but not on an array containing both circles and squares. When this is needed, an interface name can be used as a type, causing the function to be written simply like this: ~~~~ # iface drawable { fn draw(); } fn draw_all(shapes: [drawable]) { for shapes.each {|shape| shape.draw(); } } ~~~~ There is no type parameter anymore (since there isn't a single type that we're calling the function on). Instead, the `drawable` type is used to refer to a type that is a reference-counted box containing a value for which a `drawable` implementation exists, combined with information on where to find the methods for this implementation. This is very similar to the 'vtables' used in most object-oriented languages. To construct such a value, you use the `as` operator to cast a value to an interface type: ~~~~ # type circle = int; type rectangle = int; # iface drawable { fn draw(); } # impl of drawable for int { fn draw() {} } # fn new_circle() -> int { 1 } # fn new_rectangle() -> int { 2 } # fn draw_all(shapes: [drawable]) {} let c: circle = new_circle(); let r: rectangle = new_rectangle(); draw_all([c as drawable, r as drawable]); ~~~~ This will store the value into a box, along with information about the implementation (which is looked up in the scope of the cast). The `drawable` type simply refers to such boxes, and calling methods on it always works, no matter what implementations are in scope. Note that the allocation of a box is somewhat more expensive than simply using a type parameter and passing in the value as-is, and much more expensive than statically resolved method calls. ## Interface-less implementations If you only intend to use an implementation for static overloading, and there is no interface available that it conforms to, you are free to leave off the `of` clause. ~~~~ # type currency = (); # fn mk_currency(x: int, s: str) {} impl int_util for int { fn times(b: fn(int)) { let mut i = 0; while i < self { b(i); i += 1; } } fn dollars() -> currency { mk_currency(self, "USD") } } ~~~~ This allows cutesy things like `send_payment(10.dollars())`. And the nice thing is that it's fully scoped, so the uneasy feeling that anybody with experience in object-oriented languages (with the possible exception of Rubyists) gets at the sight of such things is not justified. It's harmless! # Interacting with foreign code One of Rust's aims, as a system programming language, is to interoperate well with C code. We'll start with an example. It's a bit bigger than usual, and contains a number of new concepts. We'll go over it one piece at a time. This is a program that uses OpenSSL's `SHA1` function to compute the hash of its first command-line argument, which it then converts to a hexadecimal string and prints to standard output. If you have the OpenSSL libraries installed, it should 'just work'. ~~~~ {.xfail-test} use std; native mod crypto { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8; } fn as_hex(data: [u8]) -> str { let mut acc = ""; for data.each {|byte| acc += #fmt("%02x", byte as uint); } ret acc; } fn sha1(data: str) -> str unsafe { let bytes = str::bytes(data); let hash = crypto::SHA1(vec::unsafe::to_ptr(bytes), vec::len(bytes), ptr::null()); ret as_hex(vec::unsafe::from_buf(hash, 20u)); } fn main(args: [str]) { io::println(sha1(args[1])); } ~~~~ ## Native modules Before we can call `SHA1`, we have to declare it. That is what this part of the program is responsible for: ~~~~ {.xfail-test} native mod crypto { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8; } ~~~~ A `native` module declaration tells the compiler that the program should be linked with a library by that name, and that the given list of functions are available in that library. In this case, it'll change the name `crypto` to a shared library name in a platform-specific way (`libcrypto.so` on Linux, for example), and link that in. If you want the module to have a different name from the actual library, you can use the `"link_name"` attribute, like: ~~~~ {.xfail-test} #[link_name = "crypto"] native mod something { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8; } ~~~~ ## Native calling conventions Most native C code use the cdecl calling convention, so that is what Rust uses by default when calling native functions. Some native functions, most notably the Windows API, use other calling conventions, so Rust provides a way to hint to the compiler which is expected by using the `"abi"` attribute: ~~~~ #[cfg(target_os = "win32")] #[abi = "stdcall"] native mod kernel32 { fn SetEnvironmentVariableA(n: *u8, v: *u8) -> int; } ~~~~ The `"abi"` attribute applies to a native mod (it can not be applied to a single function within a module), and must be either `"cdecl"` or `"stdcall"`. Other conventions may be defined in the future. ## Unsafe pointers The native `SHA1` function is declared to take three arguments, and return a pointer. ~~~~ {.xfail-test} # native mod crypto { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8; # } ~~~~ When declaring the argument types to a foreign function, the Rust compiler has no way to check whether your declaration is correct, so you have to be careful. If you get the number or types of the arguments wrong, you're likely to get a segmentation fault. Or, probably even worse, your code will work on one platform, but break on another. In this case, `SHA1` is defined as taking two `unsigned char*` arguments and one `unsigned long`. The rust equivalents are `*u8` unsafe pointers and an `uint` (which, like `unsigned long`, is a machine-word-sized type). Unsafe pointers can be created through various functions in the standard lib, usually with `unsafe` somewhere in their name. You can dereference an unsafe pointer with `*` operator, but use caution—unlike Rust's other pointer types, unsafe pointers are completely unmanaged, so they might point at invalid memory, or be null pointers. ## Unsafe blocks The `sha1` function is the most obscure part of the program. ~~~~ # mod crypto { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8 { out } } # fn as_hex(data: [u8]) -> str { "hi" } fn sha1(data: str) -> str unsafe { let bytes = str::bytes(data); let hash = crypto::SHA1(vec::unsafe::to_ptr(bytes), vec::len(bytes), ptr::null()); ret as_hex(vec::unsafe::from_buf(hash, 20u)); } ~~~~ Firstly, what does the `unsafe` keyword at the top of the function mean? `unsafe` is a block modifier—it declares the block following it to be known to be unsafe. Some operations, like dereferencing unsafe pointers or calling functions that have been marked unsafe, are only allowed inside unsafe blocks. With the `unsafe` keyword, you're telling the compiler 'I know what I'm doing'. The main motivation for such an annotation is that when you have a memory error (and you will, if you're using unsafe constructs), you have some idea where to look—it will most likely be caused by some unsafe code. Unsafe blocks isolate unsafety. Unsafe functions, on the other hand, advertise it to the world. An unsafe function is written like this: ~~~~ unsafe fn kaboom() { "I'm harmless!"; } ~~~~ This function can only be called from an unsafe block or another unsafe function. ## Pointer fiddling The standard library defines a number of helper functions for dealing with unsafe data, casting between types, and generally subverting Rust's safety mechanisms. Let's look at our `sha1` function again. ~~~~ # mod crypto { fn SHA1(src: *u8, sz: uint, out: *u8) -> *u8 { out } } # fn as_hex(data: [u8]) -> str { "hi" } # fn x(data: str) -> str unsafe { let bytes = str::bytes(data); let hash = crypto::SHA1(vec::unsafe::to_ptr(bytes), vec::len(bytes), ptr::null()); ret as_hex(vec::unsafe::from_buf(hash, 20u)); # } ~~~~ The `str::bytes` function is perfectly safe, it converts a string to an `[u8]`. This byte array is then fed to `vec::unsafe::to_ptr`, which returns an unsafe pointer to its contents. This pointer will become invalid as soon as the vector it points into is cleaned up, so you should be very careful how you use it. In this case, the local variable `bytes` outlives the pointer, so we're good. Passing a null pointer as third argument to `SHA1` causes it to use a static buffer, and thus save us the effort of allocating memory ourselves. `ptr::null` is a generic function that will return an unsafe null pointer of the correct type (Rust generics are awesome like that—they can take the right form depending on the type that they are expected to return). Finally, `vec::unsafe::from_buf` builds up a new `[u8]` from the unsafe pointer that was returned by `SHA1`. SHA1 digests are always twenty bytes long, so we can pass `20u` for the length of the new vector. ## Passing structures C functions often take pointers to structs as arguments. Since Rust records are binary-compatible with C structs, Rust programs can call such functions directly. This program uses the Posix function `gettimeofday` to get a microsecond-resolution timer. ~~~~ use std; type timeval = {mut tv_sec: uint, mut tv_usec: uint}; #[nolink] native mod libc { fn gettimeofday(tv: *timeval, tz: *()) -> i32; } fn unix_time_in_microseconds() -> u64 unsafe { let x = {mut tv_sec: 0u, mut tv_usec: 0u}; libc::gettimeofday(ptr::addr_of(x), ptr::null()); ret (x.tv_sec as u64) * 1000_000_u64 + (x.tv_usec as u64); } # fn main() { assert #fmt("%?", unix_time_in_microseconds()) != ""; } ~~~~ The `#[nolink]` attribute indicates that there's no native library to link in. The standard C library is already linked with Rust programs. A `timeval`, in C, is a struct with two 32-bit integers. Thus, we define a record type with the same contents, and declare `gettimeofday` to take a pointer to such a record. The second argument to `gettimeofday` (the time zone) is not used by this program, so it simply declares it to be a pointer to the nil type. Since null pointer look the same, no matter which type they are supposed to point at, this is safe. # Tasks Rust supports a system of lightweight tasks, similar to what is found in Erlang or other actor systems. Rust tasks communicate via messages and do not share data. However, it is possible to send data without copying it by making use of [unique boxes](#unique-boxes), which allow the sending task to release ownership of a value, so that the receiving task can keep on using it. NOTE: As Rust evolves, we expect the Task API to grow and change somewhat. The tutorial documents the API as it exists today. ## Spawning a task Spawning a task is done using the various spawn functions in the module `task`. Let's begin with the simplest one, `task::spawn()`: ~~~~ let some_value = 22; task::spawn {|| io::println("This executes in the child task."); io::println(#fmt("%d", some_value)); } ~~~~ The argument to `task::spawn()` is a [unique closure](#unique-closures) of type `fn~()`, meaning that it takes no arguments and generates no return value. The effect of `task::spawn()` is to fire up a child task that will execute the closure in parallel with the creator. ## Ports and channels Now that we have spawned a child task, it would be nice if we could communicate with it. This is done by creating a *port* with an associated *channel*. A port is simply a location to receive messages of a particular type. A channel is used to send messages to a port. For example, imagine we wish to perform two expensive computations in parallel. We might write something like: ~~~~ # fn some_expensive_computation() -> int { 42 } # fn some_other_expensive_computation() {} let port = comm::port::(); let chan = comm::chan::(port); task::spawn {|| let result = some_expensive_computation(); comm::send(chan, result); } some_other_expensive_computation(); let result = comm::recv(port); ~~~~ Let's walk through this code line-by-line. The first line creates a port for receiving integers: ~~~~ let port = comm::port::(); ~~~~ This port is where we will receive the message from the child task once it is complete. The second line creates a channel for sending integers to the port `port`: ~~~~ # let port = comm::port::(); let chan = comm::chan::(port); ~~~~ The channel will be used by the child to send a message to the port. The next statement actually spawns the child: ~~~~ # fn some_expensive_computation() -> int { 42 } # let port = comm::port::(); # let chan = comm::chan::(port); task::spawn {|| let result = some_expensive_computation(); comm::send(chan, result); } ~~~~ This child will perform the expensive computation send the result over the channel. Finally, the parent continues by performing some other expensive computation and then waiting for the child's result to arrive on the port: ~~~~ # fn some_other_expensive_computation() {} # let port = comm::port::(); # let chan = comm::chan::(port); # comm::send(chan, 0); some_other_expensive_computation(); let result = comm::recv(port); ~~~~ ## Creating a task with a bi-directional communication path A very common thing to do is to spawn a child task where the parent and child both need to exchange messages with each other. The function `task::spawn_listener()` supports this pattern. We'll look briefly at how it is used. To see how `spawn_listener()` works, we will create a child task which receives `uint` messages, converts them to a string, and sends the string in response. The child terminates when `0` is received. Here is the function which implements the child task: ~~~~ fn stringifier(from_parent: comm::port, to_parent: comm::chan) { let mut value: uint; loop { value = comm::recv(from_parent); comm::send(to_parent, uint::to_str(value, 10u)); if value == 0u { break; } } } ~~~~ You can see that the function takes two parameters. The first is a port used to receive messages from the parent, and the second is a channel used to send messages to the parent. The body itself simply loops, reading from the `from_par` port and then sending its response to the `to_par` channel. The actual response itself is simply the strified version of the received value, `uint::to_str(value)`. Here is the code for the parent task: ~~~~ # fn stringifier(from_parent: comm::port, # to_parent: comm::chan) { # comm::send(to_parent, "22"); # comm::send(to_parent, "23"); # comm::send(to_parent, "0"); # } fn main() { let from_child = comm::port(); let to_parent = comm::chan(from_child); let to_child = task::spawn_listener {|from_parent| stringifier(from_parent, to_parent); }; comm::send(to_child, 22u); assert comm::recv(from_child) == "22"; comm::send(to_child, 23u); assert comm::recv(from_child) == "23"; comm::send(to_child, 0u); assert comm::recv(from_child) == "0"; } ~~~~ The parent first sets up a port to receive data from and a channel that the child can use to send data to that port. The call to `spawn_listener()` will spawn the child task, providing it with a port on which to receive data from its parent, and returning to the parent the associated channel. Finally, the closure passed to `spawn_listener()` that forms the body of the child task captures the `to_parent` channel in its environment, so both parent and child can send and receive data to and from the other. ## The supervisor relationship By default, failures in Rust propagate upward through the task tree. We say that each task is supervised by its parent, meaning that if the task fails, that failure is propagated to the parent task, which will fail sometime later. This propagation can be disabled by using the function `task::unsupervise()`, which disables error propagation from the current task to its parent. # Testing The Rust language has a facility for testing built into the language. Tests can be interspersed with other code, and annotated with the `#[test]` attribute. ~~~~{.xfail-test} # // FIXME: xfailed because test_twice is a #[test] function it's not # // getting compiled use std; fn twice(x: int) -> int { x + x } #[test] fn test_twice() { let mut i = -100; while i < 100 { assert twice(i) == 2 * i; i += 1; } } ~~~~ When you compile the program normally, the `test_twice` function will not be included. To compile and run such tests, compile with the `--test` flag, and then run the result: ~~~~ {.notrust} > rustc --test twice.rs > ./twice running 1 tests test test_twice ... ok result: ok. 1 passed; 0 failed; 0 ignored ~~~~ Or, if we change the file to fail, for example by replacing `x + x` with `x + 1`: ~~~~ {.notrust} running 1 tests test test_twice ... FAILED failures: test_twice result: FAILED. 0 passed; 1 failed; 0 ignored ~~~~ You can pass a command-line argument to a program compiled with `--test` to run only the tests whose name matches the given string. If we had, for example, test functions `test_twice`, `test_once_1`, and `test_once_2`, running our program with `./twice test_once` would run the latter two, and running it with `./twice test_once_2` would run only the last. To indicate that a test is supposed to fail instead of pass, you can give it a `#[should_fail]` attribute. ~~~~ use std; fn divide(a: float, b: float) -> float { if b == 0f { fail; } a / b } #[test] #[should_fail] fn divide_by_zero() { divide(1f, 0f); } ~~~~ To disable a test completely, add an `#[ignore]` attribute. Running a test runner (the program compiled with `--test`) with an `--ignored` command-line flag will cause it to also run the tests labelled as ignored. A program compiled as a test runner will have the configuration flag `test` defined, so that you can add code that won't be included in a normal compile with the `#[cfg(test)]` attribute (see [conditional compilation](#attributes)).