1 % Rust Reference Manual
5 This document is the reference manual for the Rust programming language. It
6 provides three kinds of material:
8 - Chapters that formally define the language grammar and, for each
9 construct, informally describe its semantics and give examples of its
11 - Chapters that informally describe the memory model, concurrency model,
12 runtime services, linkage model and debugging facilities.
13 - Appendix chapters providing rationale and references to languages that
14 influenced the design.
16 This document does not serve as a tutorial introduction to the
17 language. Background familiarity with the language is assumed. A separate
18 [tutorial] document is available to help acquire such background familiarity.
20 This document also does not serve as a reference to the [core] or [standard]
21 libraries included in the language distribution. Those libraries are
22 documented separately by extracting documentation attributes from their
25 [tutorial]: tutorial.html
26 [core]: core/index.html
27 [standard]: std/index.html
31 Rust is a work in progress. The language continues to evolve as the design
32 shifts and is fleshed out in working code. Certain parts work, certain parts
33 do not, certain parts will be removed or changed.
35 This manual is a snapshot written in the present tense. All features described
36 exist in working code unless otherwise noted, but some are quite primitive or
37 remain to be further modified by planned work. Some may be temporary. It is a
38 *draft*, and we ask that you not take anything you read here as final.
40 If you have suggestions to make, please try to focus them on *reductions* to
41 the language: possible features that can be combined or omitted. We aim to
42 keep the size and complexity of the language under control.
44 > **Note:** The grammar for Rust given in this document is rough and
45 > very incomplete; only a modest number of sections have accompanying grammar
46 > rules. Formalizing the grammar accepted by the Rust parser is ongoing work,
47 > but future versions of this document will contain a complete
48 > grammar. Moreover, we hope that this grammar will be extracted and verified
49 > as LL(1) by an automated grammar-analysis tool, and further tested against the
50 > Rust sources. Preliminary versions of this automation exist, but are not yet
55 Rust's grammar is defined over Unicode codepoints, each conventionally
56 denoted `U+XXXX`, for 4 or more hexadecimal digits `X`. _Most_ of Rust's
57 grammar is confined to the ASCII range of Unicode, and is described in this
58 document by a dialect of Extended Backus-Naur Form (EBNF), specifically a
59 dialect of EBNF supported by common automated LL(k) parsing tools such as
60 `llgen`, rather than the dialect given in ISO 14977. The dialect can be
61 defined self-referentially as follows:
63 ~~~~~~~~ {.ebnf .notation}
66 rule : nonterminal ':' productionrule ';' ;
67 productionrule : production [ '|' production ] * ;
69 term : element repeats ;
70 element : LITERAL | IDENTIFIER | '[' productionrule ']' ;
71 repeats : [ '*' | '+' ] NUMBER ? | NUMBER ? | '?' ;
77 - Whitespace in the grammar is ignored.
78 - Square brackets are used to group rules.
79 - `LITERAL` is a single printable ASCII character, or an escaped hexadecimal
80 ASCII code of the form `\xQQ`, in single quotes, denoting the corresponding
81 Unicode codepoint `U+00QQ`.
82 - `IDENTIFIER` is a nonempty string of ASCII letters and underscores.
83 - The `repeat` forms apply to the adjacent `element`, and are as follows:
84 - `?` means zero or one repetition
85 - `*` means zero or more repetitions
86 - `+` means one or more repetitions
87 - NUMBER trailing a repeat symbol gives a maximum repetition count
88 - NUMBER on its own gives an exact repetition count
90 This EBNF dialect should hopefully be familiar to many readers.
92 ## Unicode productions
94 A few productions in Rust's grammar permit Unicode codepoints outside the ASCII range.
95 We define these productions in terms of character properties specified in the Unicode standard,
96 rather than in terms of ASCII-range codepoints.
97 The section [Special Unicode Productions](#special-unicode-productions) lists these productions.
99 ## String table productions
101 Some rules in the grammar -- notably [unary
102 operators](#unary-operator-expressions), [binary
103 operators](#binary-operator-expressions), and [keywords](#keywords) --
104 are given in a simplified form: as a listing of a table of unquoted,
105 printable whitespace-separated strings. These cases form a subset of
106 the rules regarding the [token](#tokens) rule, and are assumed to be
107 the result of a lexical-analysis phase feeding the parser, driven by a
108 DFA, operating over the disjunction of all such string table entries.
110 When such a string enclosed in double-quotes (`"`) occurs inside the
111 grammar, it is an implicit reference to a single member of such a string table
112 production. See [tokens](#tokens) for more information.
119 Rust input is interpreted as a sequence of Unicode codepoints encoded in UTF-8,
120 normalized to Unicode normalization form NFKC.
121 Most Rust grammar rules are defined in terms of printable ASCII-range codepoints,
122 but a small number are defined in terms of Unicode properties or explicit codepoint lists.
123 ^[Substitute definitions for the special Unicode productions are provided to the grammar verifier, restricted to ASCII range, when verifying the grammar in this document.]
125 ## Special Unicode Productions
127 The following productions in the Rust grammar are defined in terms of Unicode properties:
128 `ident`, `non_null`, `non_star`, `non_eol`, `non_slash_or_star`, `non_single_quote` and `non_double_quote`.
132 The `ident` production is any nonempty Unicode string of the following form:
134 - The first character has property `XID_start`
135 - The remaining characters have property `XID_continue`
137 that does _not_ occur in the set of [keywords](#keywords).
139 Note: `XID_start` and `XID_continue` as character properties cover the
140 character ranges used to form the more familiar C and Java language-family
143 ### Delimiter-restricted productions
145 Some productions are defined by exclusion of particular Unicode characters:
147 - `non_null` is any single Unicode character aside from `U+0000` (null)
148 - `non_eol` is `non_null` restricted to exclude `U+000A` (`'\n'`)
149 - `non_star` is `non_null` restricted to exclude `U+002A` (`*`)
150 - `non_slash_or_star` is `non_null` restricted to exclude `U+002F` (`/`) and `U+002A` (`*`)
151 - `non_single_quote` is `non_null` restricted to exclude `U+0027` (`'`)
152 - `non_double_quote` is `non_null` restricted to exclude `U+0022` (`"`)
156 ~~~~~~~~ {.ebnf .gram}
157 comment : block_comment | line_comment ;
158 block_comment : "/*" block_comment_body * '*' + '/' ;
159 block_comment_body : non_star * | '*' + non_slash_or_star ;
160 line_comment : "//" non_eol * ;
163 Comments in Rust code follow the general C++ style of line and block-comment forms,
164 with no nesting of block-comment delimiters.
166 Line comments beginning with _three_ slashes (`///`),
167 and block comments beginning with a repeated asterisk in the block-open sequence (`/**`),
168 are interpreted as a special syntax for `doc` [attributes](#attributes).
169 That is, they are equivalent to writing `#[doc "..."]` around the comment's text.
171 Non-doc comments are interpreted as a form of whitespace.
175 ~~~~~~~~ {.ebnf .gram}
176 whitespace_char : '\x20' | '\x09' | '\x0a' | '\x0d' ;
177 whitespace : [ whitespace_char | comment ] + ;
180 The `whitespace_char` production is any nonempty Unicode string consisting of any
181 of the following Unicode characters: `U+0020` (space, `' '`), `U+0009` (tab,
182 `'\t'`), `U+000A` (LF, `'\n'`), `U+000D` (CR, `'\r'`).
184 Rust is a "free-form" language, meaning that all forms of whitespace serve
185 only to separate _tokens_ in the grammar, and have no semantic significance.
187 A Rust program has identical meaning if each whitespace element is replaced
188 with any other legal whitespace element, such as a single space character.
192 ~~~~~~~~ {.ebnf .gram}
193 simple_token : keyword | unop | binop ;
194 token : simple_token | ident | literal | symbol | whitespace token ;
197 Tokens are primitive productions in the grammar defined by regular
198 (non-recursive) languages. "Simple" tokens are given in [string table
199 production](#string-table-productions) form, and occur in the rest of the
200 grammar as double-quoted strings. Other tokens have exact rules given.
204 The keywords are the following strings:
218 self static struct super
224 Each of these keywords has special meaning in its grammar,
225 and all of them are excluded from the `ident` rule.
229 A literal is an expression consisting of a single token, rather than a
230 sequence of tokens, that immediately and directly denotes the value it
231 evaluates to, rather than referring to it by name or some other evaluation
232 rule. A literal is a form of constant expression, so is evaluated (primarily)
235 ~~~~~~~~ {.ebnf .gram}
236 literal : string_lit | char_lit | num_lit ;
239 #### Character and string literals
241 ~~~~~~~~ {.ebnf .gram}
242 char_lit : '\x27' char_body '\x27' ;
243 string_lit : '"' string_body * '"' ;
245 char_body : non_single_quote
246 | '\x5c' [ '\x27' | common_escape ] ;
248 string_body : non_double_quote
249 | '\x5c' [ '\x22' | common_escape ] ;
251 common_escape : '\x5c'
257 hex_digit : 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
258 | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'
260 dec_digit : '0' | nonzero_dec ;
261 nonzero_dec: '1' | '2' | '3' | '4'
262 | '5' | '6' | '7' | '8' | '9' ;
265 A _character literal_ is a single Unicode character enclosed within two
266 `U+0027` (single-quote) characters, with the exception of `U+0027` itself,
267 which must be _escaped_ by a preceding U+005C character (`\`).
269 A _string literal_ is a sequence of any Unicode characters enclosed within
270 two `U+0022` (double-quote) characters, with the exception of `U+0022`
271 itself, which must be _escaped_ by a preceding `U+005C` character (`\`).
273 Some additional _escapes_ are available in either character or string
274 literals. An escape starts with a `U+005C` (`\`) and continues with one of
277 * An _8-bit codepoint escape_ escape starts with `U+0078` (`x`) and is
278 followed by exactly two _hex digits_. It denotes the Unicode codepoint
279 equal to the provided hex value.
280 * A _16-bit codepoint escape_ starts with `U+0075` (`u`) and is followed
281 by exactly four _hex digits_. It denotes the Unicode codepoint equal to
282 the provided hex value.
283 * A _32-bit codepoint escape_ starts with `U+0055` (`U`) and is followed
284 by exactly eight _hex digits_. It denotes the Unicode codepoint equal to
285 the provided hex value.
286 * A _whitespace escape_ is one of the characters `U+006E` (`n`), `U+0072`
287 (`r`), or `U+0074` (`t`), denoting the unicode values `U+000A` (LF),
288 `U+000D` (CR) or `U+0009` (HT) respectively.
289 * The _backslash escape_ is the character U+005C (`\`) which must be
290 escaped in order to denote *itself*.
294 ~~~~~~~~ {.ebnf .gram}
296 num_lit : nonzero_dec [ dec_digit | '_' ] * num_suffix ?
297 | '0' [ [ dec_digit | '_' ] + num_suffix ?
298 | 'b' [ '1' | '0' | '_' ] + int_suffix ?
299 | 'x' [ hex_digit | '_' ] + int_suffix ? ] ;
301 num_suffix : int_suffix | float_suffix ;
303 int_suffix : 'u' int_suffix_size ?
304 | 'i' int_suffix_size ;
305 int_suffix_size : [ '8' | '1' '6' | '3' '2' | '6' '4' ] ;
307 float_suffix : [ exponent | '.' dec_lit exponent ? ] float_suffix_ty ? ;
308 float_suffix_ty : 'f' [ '3' '2' | '6' '4' ] ;
309 exponent : ['E' | 'e'] ['-' | '+' ] ? dec_lit ;
310 dec_lit : [ dec_digit | '_' ] + ;
313 A _number literal_ is either an _integer literal_ or a _floating-point
314 literal_. The grammar for recognizing the two kinds of literals is mixed,
315 as they are differentiated by suffixes.
317 ##### Integer literals
319 An _integer literal_ has one of three forms:
321 * A _decimal literal_ starts with a *decimal digit* and continues with any
322 mixture of *decimal digits* and _underscores_.
323 * A _hex literal_ starts with the character sequence `U+0030` `U+0078`
324 (`0x`) and continues as any mixture hex digits and underscores.
325 * A _binary literal_ starts with the character sequence `U+0030` `U+0062`
326 (`0b`) and continues as any mixture binary digits and underscores.
328 An integer literal may be followed (immediately, without any spaces) by an
329 _integer suffix_, which changes the type of the literal. There are two kinds
330 of integer literal suffix:
332 * The `i` and `u` suffixes give the literal type `int` or `uint`,
334 * Each of the signed and unsigned machine types `u8`, `i8`,
335 `u16`, `i16`, `u32`, `i32`, `u64` and `i64`
336 give the literal the corresponding machine type.
338 The type of an _unsuffixed_ integer literal is determined by type inference.
339 If a integer type can be _uniquely_ determined from the surrounding program
340 context, the unsuffixed integer literal has that type. If the program context
341 underconstrains the type, the unsuffixed integer literal's type is `int`; if
342 the program context overconstrains the type, it is considered a static type
345 Examples of integer literals of various forms:
348 123; 0xff00; // type determined by program context
349 // defaults to int in absence of type
355 0b1111_1111_1001_0000_i32; // type i32
358 ##### Floating-point literals
360 A _floating-point literal_ has one of two forms:
362 * Two _decimal literals_ separated by a period
363 character `U+002E` (`.`), with an optional _exponent_ trailing after the
364 second decimal literal.
365 * A single _decimal literal_ followed by an _exponent_.
367 By default, a floating-point literal is of type `float`. A
368 floating-point literal may be followed (immediately, without any
369 spaces) by a _floating-point suffix_, which changes the type of the
370 literal. There are three floating-point suffixes: `f` (for the base
371 `float` type), `f32`, and `f64` (the 32-bit and 64-bit floating point
374 Examples of floating-point literals of various forms:
381 12E+99_f64; // type f64
384 ##### Unit and boolean literals
386 The _unit value_, the only value of the type that has the same name, is written as `()`.
387 The two values of the boolean type are written `true` and `false`.
391 ~~~~~~~~ {.ebnf .gram}
393 | '#' | '[' | ']' | '(' | ')' | '{' | '}'
397 Symbols are a general class of printable [token](#tokens) that play structural
398 roles in a variety of grammar productions. They are catalogued here for
399 completeness as the set of remaining miscellaneous printable tokens that do not
400 otherwise appear as [unary operators](#unary-operator-expressions), [binary
401 operators](#binary-operator-expressions), or [keywords](#keywords).
406 ~~~~~~~~ {.ebnf .gram}
408 expr_path : ident [ "::" expr_path_tail ] + ;
409 expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'
412 type_path : ident [ type_path_tail ] + ;
413 type_path_tail : '<' type_expr [ ',' type_expr ] + '>'
418 A _path_ is a sequence of one or more path components _logically_ separated by
419 a namespace qualifier (`::`). If a path consists of only one component, it may
420 refer to either an [item](#items) or a [slot](#memory-slots) in a local
421 control scope. If a path has multiple components, it refers to an item.
423 Every item has a _canonical path_ within its crate, but the path naming an
424 item is only meaningful within a given crate. There is no global namespace
425 across crates; an item's canonical path merely identifies it within the crate.
427 Two examples of simple paths consisting of only identifier components:
434 Path components are usually [identifiers](#identifiers), but the trailing
435 component of a path may be an angle-bracket-enclosed list of type
436 arguments. In [expression](#expressions) context, the type argument list is
437 given after a final (`::`) namespace qualifier in order to disambiguate it
438 from a relational expression involving the less-than symbol (`<`). In type
439 expression context, the final namespace qualifier is omitted.
441 Two examples of paths with type arguments:
444 # use core::hashmap::HashMap;
446 # fn id<T:Copy>(t: T) -> T { t }
447 type t = HashMap<int,~str>; // Type arguments used in a type expression
448 let x = id::<int>(10); // Type arguments used in a call expression
454 A number of minor features of Rust are not central enough to have their own
455 syntax, and yet are not implementable as functions. Instead, they are given
456 names, and invoked through a consistent syntax: `name!(...)`. Examples
459 * `fmt!` : format data into a string
460 * `env!` : look up an environment variable's value at compile time
461 * `stringify!` : pretty-print the Rust expression given as an argument
462 * `proto!` : define a protocol for inter-task communication
463 * `include!` : include the Rust expression in the given file
464 * `include_str!` : include the contents of the given file as a string
465 * `include_bin!` : include the contents of the given file as a binary blob
466 * `error!`, `warn!`, `info!`, `debug!` : provide diagnostic information.
468 All of the above extensions, with the exception of `proto!`, are expressions
469 with values. `proto!` is an item, defining a new name.
473 ~~~~~~~~ {.ebnf .gram}
475 expr_macro_rules : "macro_rules" '!' ident '(' macro_rule * ')'
476 macro_rule : '(' matcher * ')' "=>" '(' transcriber * ')' ';'
477 matcher : '(' matcher * ')' | '[' matcher * ']'
478 | '{' matcher * '}' | '$' ident ':' ident
479 | '$' '(' matcher * ')' sep_token? [ '*' | '+' ]
481 transcriber : '(' transcriber * ')' | '[' transcriber * ']'
482 | '{' transcriber * '}' | '$' ident
483 | '$' '(' transcriber * ')' sep_token? [ '*' | '+' ]
488 User-defined syntax extensions are called "macros",
489 and the `macro_rules` syntax extension defines them.
490 Currently, user-defined macros can expand to expressions, statements, or items.
492 (A `sep_token` is any token other than `*` and `+`.
493 A `non_special_token` is any token other than a delimiter or `$`.)
495 The macro expander looks up macro invocations by name,
496 and tries each macro rule in turn.
497 It transcribes the first successful match.
498 Matching and transcription are closely related to each other,
499 and we will describe them together.
503 The macro expander matches and transcribes every token that does not begin with a `$` literally, including delimiters.
504 For parsing reasons, delimiters must be balanced, but they are otherwise not special.
506 In the matcher, `$` _name_ `:` _designator_ matches the nonterminal in the
507 Rust syntax named by _designator_. Valid designators are `item`, `block`,
508 `stmt`, `pat`, `expr`, `ty` (type), `ident`, `path`, `matchers` (lhs of the `=>` in macro rules),
509 `tt` (rhs of the `=>` in macro rules). In the transcriber, the designator is already known, and so only
510 the name of a matched nonterminal comes after the dollar sign.
512 In both the matcher and transcriber, the Kleene star-like operator indicates repetition.
513 The Kleene star operator consists of `$` and parens, optionally followed by a separator token, followed by `*` or `+`.
514 `*` means zero or more repetitions, `+` means at least one repetition.
515 The parens are not matched or transcribed.
516 On the matcher side, a name is bound to _all_ of the names it
517 matches, in a structure that mimics the structure of the repetition
518 encountered on a successful match. The job of the transcriber is to sort that
521 The rules for transcription of these repetitions are called "Macro By Example".
522 Essentially, one "layer" of repetition is discharged at a time, and all of
523 them must be discharged by the time a name is transcribed. Therefore,
524 `( $( $i:ident ),* ) => ( $i )` is an invalid macro, but
525 `( $( $i:ident ),* ) => ( $( $i:ident ),* )` is acceptable (if trivial).
527 When Macro By Example encounters a repetition, it examines all of the `$`
528 _name_ s that occur in its body. At the "current layer", they all must repeat
529 the same number of times, so
530 ` ( $( $i:ident ),* ; $( $j:ident ),* ) => ( $( ($i,$j) ),* )` is valid if
531 given the argument `(a,b,c ; d,e,f)`, but not `(a,b,c ; d,e)`. The repetition
532 walks through the choices at that layer in lockstep, so the former input
533 transcribes to `( (a,d), (b,e), (c,f) )`.
535 Nested repetitions are allowed.
537 ### Parsing limitations
539 The parser used by the macro system is reasonably powerful, but the parsing of
540 Rust syntax is restricted in two ways:
542 1. The parser will always parse as much as possible. If it attempts to match
543 `$i:expr [ , ]` against `8 [ , ]`, it will attempt to parse `i` as an array
544 index operation and fail. Adding a separator can solve this problem.
545 2. The parser must have eliminated all ambiguity by the time it reaches a `$` _name_ `:` _designator_.
546 This requirement most often affects name-designator pairs when they occur at the beginning of, or immediately after, a `$(...)*`; requiring a distinctive token in front can solve the problem.
549 ## Syntax extensions useful for the macro author
551 * `log_syntax!` : print out the arguments at compile time
552 * `trace_macros!` : supply `true` or `false` to enable or disable macro expansion logging
553 * `stringify!` : turn the identifier argument into a string literal
554 * `concat_idents!` : create a new identifier by concatenating the arguments
556 # Crates and source files
558 Rust is a *compiled* language.
559 Its semantics obey a *phase distinction* between compile-time and run-time.
560 Those semantic rules that have a *static interpretation* govern the success or failure of compilation.
561 We refer to these rules as "static semantics".
562 Semantic rules called "dynamic semantics" govern the behavior of programs at run-time.
563 A program that fails to compile due to violation of a compile-time rule has no defined dynamic semantics; the compiler should halt with an error report, and produce no executable artifact.
565 The compilation model centres on artifacts called _crates_.
566 Each compilation processes a single crate in source form, and if successful, produces a single crate in binary form: either an executable or a library.^[A crate is somewhat
567 analogous to an *assembly* in the ECMA-335 CLI model, a *library* in the
568 SML/NJ Compilation Manager, a *unit* in the Owens and Flatt module system,
569 or a *configuration* in Mesa.]
571 A _crate_ is a unit of compilation and linking, as well as versioning, distribution and runtime loading.
572 A crate contains a _tree_ of nested [module](#modules) scopes.
573 The top level of this tree is a module that is anonymous (from the point of view of paths within the module) and any item within a crate has a canonical [module path](#paths) denoting its location within the crate's module tree.
575 The Rust compiler is always invoked with a single source file as input, and always produces a single output crate.
576 The processing of that source file may result in other source files being loaded as modules.
577 Source files typically have the extension `.rs` but, by convention,
578 source files that represent crates have the extension `.rc`, called *crate files*.
580 A Rust source file describes a module, the name and
581 location of which -- in the module tree of the current crate -- are defined
582 from outside the source file: either by an explicit `mod_item` in
583 a referencing source file, or by the name of the crate itself.
585 Each source file contains a sequence of zero or more `item` definitions,
586 and may optionally begin with any number of `attributes` that apply to the containing module.
587 Atributes on the anonymous crate module define important metadata that influences
588 the behavior of the compiler.
591 // Linkage attributes
592 #[ link(name = "projx",
594 uuid = "9cccc5d5-aceb-4af5-8285-811211826b82") ];
596 // Additional metadata attributes
597 #[ desc = "Project X" ];
598 #[ license = "BSD" ];
599 #[ author = "Jane Doe" ];
601 // Specify the output type
602 #[ crate_type = "lib" ];
605 #[ warn(non_camel_case_types) ];
608 A crate that contains a `main` function can be compiled to an executable.
609 If a `main` function is present, its return type must be [`unit`](#primitive-types) and it must take no arguments.
612 # Items and attributes
614 Crates contain [items](#items),
615 each of which may have some number of [attributes](#attributes) attached to it.
619 ~~~~~~~~ {.ebnf .gram}
620 item : mod_item | fn_item | type_item | struct_item | enum_item
621 | static_item | trait_item | impl_item | foreign_mod_item ;
624 An _item_ is a component of a crate; some module items can be defined in crate
625 files, but most are defined in source files. Items are organized within a
626 crate by a nested set of [modules](#modules). Every crate has a single
627 "outermost" anonymous module; all further items within the crate have
628 [paths](#paths) within the module tree of the crate.
630 Items are entirely determined at compile-time, generally remain fixed during
631 execution, and may reside in read-only memory.
633 There are several kinds of item:
635 * [modules](#modules)
636 * [functions](#functions)
637 * [type definitions](#type-definitions)
638 * [structures](#structures)
639 * [enumerations](#enumerations)
640 * [static items](#static-items)
642 * [implementations](#implementations)
644 Some items form an implicit scope for the declaration of sub-items. In other
645 words, within a function or module, declarations of items can (in many cases)
646 be mixed with the statements, control blocks, and similar artifacts that
647 otherwise compose the item body. The meaning of these scoped items is the same
648 as if the item was declared outside the scope -- it is still a static item --
649 except that the item's *path name* within the module namespace is qualified by
650 the name of the enclosing item, or is private to the enclosing item (in the
652 The grammar specifies the exact locations in which sub-item declarations may appear.
656 All items except modules may be *parameterized* by type. Type parameters are
657 given as a comma-separated list of identifiers enclosed in angle brackets
658 (`<...>`), after the name of the item and before its definition.
659 The type parameters of an item are considered "part of the name", not part of the type of the item.
660 A referencing [path](#paths) must (in principle) provide type arguments as a list of comma-separated types enclosed within angle brackets, in order to refer to the type-parameterized item.
661 In practice, the type-inference system can usually infer such argument types from context.
662 There are no general type-parametric types, only type-parametric items.
663 That is, Rust has no notion of type abstraction: there are no first-class "forall" types.
667 ~~~~~~~~ {.ebnf .gram}
668 mod_item : "mod" ident ( ';' | '{' mod '}' );
669 mod : [ view_item | item ] * ;
672 A module is a container for zero or more [view items](#view-items) and zero or
673 more [items](#items). The view items manage the visibility of the items
674 defined within the module, as well as the visibility of names from outside the
675 module when referenced from inside the module.
677 A _module item_ is a module, surrounded in braces, named, and prefixed with
678 the keyword `mod`. A module item introduces a new, named module into the tree
679 of modules making up a crate. Modules can nest arbitrarily.
681 An example of a module:
685 type complex = (f64, f64);
686 fn sin(f: f64) -> f64 {
690 fn cos(f: f64) -> f64 {
694 fn tan(f: f64) -> f64 {
701 Modules and types share the same namespace.
702 Declaring a named type that has the same name as a module in scope is forbidden:
703 that is, a type definition, trait, struct, enumeration, or type parameter
704 can't shadow the name of a module in scope, or vice versa.
706 A module without a body is loaded from an external file, by default with the same
707 name as the module, plus the `.rs` extension.
708 When a nested submodule is loaded from an external file,
709 it is loaded from a subdirectory path that mirrors the module hierarchy.
712 // Load the `vec` module from `vec.rs`
716 // Load the `local_data` module from `task/local_data.rs`
721 The directories and files used for loading external file modules can be influenced
722 with the `path` attribute.
725 #[path = "task_files"]
727 // Load the `local_data` module from `task_files/tls.rs`
735 ~~~~~~~~ {.ebnf .gram}
736 view_item : extern_mod_decl | use_decl ;
739 A view item manages the namespace of a module.
740 View items do not define new items, but rather, simply change other items' visibility.
741 There are several kinds of view item:
743 * [`extern mod` declarations](#extern-mod-declarations)
744 * [`use` declarations](#use-declarations)
746 ##### Extern mod declarations
748 ~~~~~~~~ {.ebnf .gram}
749 extern_mod_decl : "extern" "mod" ident [ '(' link_attrs ')' ] ? ;
750 link_attrs : link_attr [ ',' link_attrs ] + ;
751 link_attr : ident '=' literal ;
754 An _`extern mod` declaration_ specifies a dependency on an external crate.
755 The external crate is then bound into the declaring scope as the `ident` provided in the `extern_mod_decl`.
757 The external crate is resolved to a specific `soname` at compile time, and a
758 runtime linkage requirement to that `soname` is passed to the linker for
759 loading at runtime. The `soname` is resolved at compile time by scanning the
760 compiler's library path and matching the `link_attrs` provided in the
761 `use_decl` against any `#link` attributes that were declared on the external
762 crate when it was compiled. If no `link_attrs` are provided, a default `name`
763 attribute is assumed, equal to the `ident` given in the `use_decl`.
765 Three examples of `extern mod` declarations:
767 ~~~~~~~~{.xfail-test}
768 extern mod pcre (uuid = "54aba0f8-a7b1-4beb-92f1-4cf625264841");
770 extern mod std; // equivalent to: extern mod std ( name = "std" );
772 extern mod ruststd (name = "std"); // linking to 'std' under another name
775 ##### Use declarations
777 ~~~~~~~~ {.ebnf .gram}
778 use_decl : "pub"? "use" ident [ '=' path
781 path_glob : ident [ "::" path_glob ] ?
783 | '{' ident [ ',' ident ] * '}'
786 A _use declaration_ creates one or more local name bindings synonymous
787 with some other [path](#paths).
788 Usually a `use` declaration is used to shorten the path required to refer to a module item.
790 *Note*: Unlike in many languages,
791 `use` declarations in Rust do *not* declare linkage dependency with external crates.
792 Rather, [`extern mod` declarations](#extern-mod-declarations) declare linkage dependencies.
794 Use declarations support a number of convenient shortcuts:
796 * Rebinding the target name as a new local name, using the syntax `use x = p::q::r;`.
797 * Simultaneously binding a list of paths differing only in their final element,
798 using the glob-like brace syntax `use a::b::{c,d,e,f};`
799 * Binding all paths matching a given prefix, using the asterisk wildcard syntax `use a::b::*;`
801 An example of `use` declarations:
804 use core::float::sin;
805 use core::str::{slice, contains};
806 use core::option::Some;
809 // Equivalent to 'info!(core::float::sin(1.0));'
812 // Equivalent to 'info!(core::option::Some(1.0));'
816 // 'info!(core::str::contains(core::str::slice("foo", 0, 1), "oo"));'
817 info!(contains(slice("foo", 0, 1), "oo"));
821 Like items, `use` declarations are private to the containing module, by default.
822 Also like items, a `use` declaration can be public, if qualified by the `pub` keyword.
823 Such a `use` declaration serves to _re-export_ a name.
824 A public `use` declaration can therefore _redirect_ some public name to a different target definition:
825 even a definition with a private canonical path, inside a different module.
826 If a sequence of such redirections form a cycle or cannot be resolved unambiguously,
827 they represent a compile-time error.
829 An example of re-exporting:
833 pub use quux::foo::*;
842 In this example, the module `quux` re-exports all of the public names defined in `foo`.
844 Also note that the paths contained in `use` items are relative to the crate root.
845 So, in the previous example, the `use` refers to `quux::foo::*`, and not simply to `foo::*`.
849 A _function item_ defines a sequence of [statements](#statements) and an optional final [expression](#expressions), along with a name and a set of parameters.
850 Functions are declared with the keyword `fn`.
851 Functions declare a set of *input* [*slots*](#memory-slots) as parameters, through which the caller passes arguments into the function, and an *output* [*slot*](#memory-slots) through which the function passes results back to the caller.
853 A function may also be copied into a first class *value*, in which case the
854 value has the corresponding [*function type*](#function-types), and can be
855 used otherwise exactly as a function item (with a minor additional cost of
856 calling the function indirectly).
858 Every control path in a function logically ends with a `return` expression or a
859 diverging expression. If the outermost block of a function has a
860 value-producing expression in its final-expression position, that expression
861 is interpreted as an implicit `return` expression applied to the
864 An example of a function:
867 fn add(x: int, y: int) -> int {
872 As with `let` bindings, function arguments are irrefutable patterns,
873 so any pattern that is valid in a let binding is also valid as an argument.
876 fn first((value, _): (int, int)) -> int { value }
880 #### Generic functions
882 A _generic function_ allows one or more _parameterized types_ to
883 appear in its signature. Each type parameter must be explicitly
884 declared, in an angle-bracket-enclosed, comma-separated list following
888 fn iter<T>(seq: &[T], f: &fn(T)) {
889 for seq.each |elt| { f(elt); }
891 fn map<T, U>(seq: &[T], f: &fn(T) -> U) -> ~[U] {
893 for seq.each |elt| { acc.push(f(elt)); }
898 Inside the function signature and body, the name of the type parameter
899 can be used as a type name.
901 When a generic function is referenced, its type is instantiated based
902 on the context of the reference. For example, calling the `iter`
903 function defined above on `[1, 2]` will instantiate type parameter `T`
904 with `int`, and require the closure parameter to have type
907 The type parameters can also be explicitly supplied in a trailing
908 [path](#paths) component after the function name. This might be necessary
909 if there is not sufficient context to determine the type parameters. For
910 example, `sys::size_of::<u32>() == 4`.
912 Since a parameter type is opaque to the generic function, the set of
913 operations that can be performed on it is limited. Values of parameter
914 type can always be moved, but they can only be copied when the
915 parameter is given a [`Copy` bound](#type-kinds).
918 fn id<T: Copy>(x: T) -> T { x }
921 Similarly, [trait](#traits) bounds can be specified for type
922 parameters to allow methods with that trait to be called on values
926 #### Unsafe functions
928 Unsafe functions are those containing unsafe operations that are not contained in an [`unsafe` block](#unsafe-blocks).
929 Such a function must be prefixed with the keyword `unsafe`.
931 Unsafe operations are those that potentially violate the memory-safety guarantees of Rust's static semantics.
932 Specifically, the following operations are considered unsafe:
934 - Dereferencing a [raw pointer](#pointer-types).
935 - Casting a [raw pointer](#pointer-types) to a safe pointer type.
936 - Calling an unsafe function.
940 A block of code can also be prefixed with the `unsafe` keyword, to permit a sequence of unsafe operations in an otherwise-safe function.
941 This facility exists because the static semantics of Rust are a necessary approximation of the dynamic semantics.
942 When a programmer has sufficient conviction that a sequence of unsafe operations is actually safe, they can encapsulate that sequence (taken as a whole) within an `unsafe` block. The compiler will consider uses of such code "safe", to the surrounding context.
945 #### Diverging functions
947 A special kind of function can be declared with a `!` character where the
948 output slot type would normally be. For example:
951 fn my_err(s: &str) -> ! {
957 We call such functions "diverging" because they never return a value to the
958 caller. Every control path in a diverging function must end with a
959 `fail!()` or a call to another diverging function on every
960 control path. The `!` annotation does *not* denote a type. Rather, the result
961 type of a diverging function is a special type called $\bot$ ("bottom") that
962 unifies with any type. Rust has no syntax for $\bot$.
964 It might be necessary to declare a diverging function because as mentioned
965 previously, the typechecker checks that every control path in a function ends
966 with a [`return`](#return-expressions) or diverging expression. So, if `my_err`
967 were declared without the `!` annotation, the following code would not
971 # fn my_err(s: &str) -> ! { fail!() }
973 fn f(i: int) -> int {
978 my_err("Bad number!");
983 This will not compile without the `!` annotation on `my_err`,
984 since the `else` branch of the conditional in `f` does not return an `int`,
985 as required by the signature of `f`.
986 Adding the `!` annotation to `my_err` informs the typechecker that,
987 should control ever enter `my_err`, no further type judgments about `f` need to hold,
988 since control will never resume in any context that relies on those judgments.
989 Thus the return type on `f` only needs to reflect the `if` branch of the conditional.
992 #### Extern functions
994 Extern functions are part of Rust's foreign function interface,
995 providing the opposite functionality to [foreign modules](#foreign-modules).
996 Whereas foreign modules allow Rust code to call foreign code,
997 extern functions with bodies defined in Rust code _can be called by foreign code_.
998 They are defined in the same way as any other Rust function,
999 except that they have the `extern` modifier.
1002 extern fn new_vec() -> ~[int] { ~[] }
1005 Extern functions may not be called from Rust code,
1006 but Rust code may take their value as a raw `u8` pointer.
1009 # extern fn new_vec() -> ~[int] { ~[] }
1010 let fptr: *u8 = new_vec;
1013 The primary motivation for extern functions is
1014 to create callbacks for foreign functions that expect to receive function pointers.
1016 ### Type definitions
1018 A _type definition_ defines a new name for an existing [type](#types). Type
1019 definitions are declared with the keyword `type`. Every value has a single,
1020 specific type; the type-specified aspects of a value include:
1022 * Whether the value is composed of sub-values or is indivisible.
1023 * Whether the value represents textual or numerical information.
1024 * Whether the value represents integral or floating-point information.
1025 * The sequence of memory operations required to access the value.
1026 * The [kind](#type-kinds) of the type.
1028 For example, the type `(u8, u8)` defines the set of immutable values that are composite pairs,
1029 each containing two unsigned 8-bit integers accessed by pattern-matching and laid out in memory with the `x` component preceding the `y` component.
1033 A _structure_ is a nominal [structure type](#structure-types) defined with the keyword `struct`.
1035 An example of a `struct` item and its use:
1038 struct Point {x: int, y: int}
1039 let p = Point {x: 10, y: 11};
1043 A _tuple structure_ is a nominal [tuple type](#tuple-types), also defined with the keyword `struct`.
1047 struct Point(int, int);
1048 let p = Point(10, 11);
1049 let px: int = match p { Point(x, _) => x };
1052 A _unit-like struct_ is a structure without any fields, defined by leaving off the list of fields entirely.
1053 Such types will have a single value, just like the [unit value `()`](#unit-and-boolean-literals) of the unit type.
1058 let c = [Cookie, Cookie, Cookie, Cookie];
1063 An _enumeration_ is a simultaneous definition of a nominal [enumerated type](#enumerated-types) as well as a set of *constructors*,
1064 that can be used to create or pattern-match values of the corresponding enumerated type.
1066 Enumerations are declared with the keyword `enum`.
1068 An example of an `enum` item and its use:
1076 let mut a: Animal = Dog;
1080 Enumeration constructors can have either named or unnamed fields:
1084 Cat { name: ~str, weight: float }
1087 let mut a: Animal = Dog(~"Cocoa", 37.2);
1088 a = Cat{ name: ~"Spotty", weight: 2.7 };
1091 In this example, `Cat` is a _struct-like enum variant_,
1092 whereas `Dog` is simply called an enum variant.
1096 ~~~~~~~~ {.ebnf .gram}
1097 static_item : "static" ident ':' type '=' expr ';' ;
1100 A *static item* is a named _constant value_ stored in the global data section of a crate.
1101 Immutable static items are stored in the read-only data section.
1102 The constant value bound to a static item is, like all constant values, evaluated at compile time.
1103 Static items have the `static` lifetime, which outlives all other lifetimes in a Rust program.
1104 Static items are declared with the `static` keyword.
1105 A static item must have a _constant expression_ giving its definition.
1107 Static items must be explicitly typed.
1108 The type may be ```bool```, ```char```, a number, or a type derived from those primitive types.
1109 The derived types are borrowed pointers with the `'static` lifetime,
1110 fixed-size arrays, tuples, and structs.
1113 static bit1: uint = 1 << 0;
1114 static bit2: uint = 1 << 1;
1116 static bits: [uint, ..2] = [bit1, bit2];
1117 static string: &'static str = "bitstring";
1119 struct BitsNStrings<'self> {
1120 mybits: [uint, ..2],
1121 mystring: &'self str
1124 static bits_n_strings: BitsNStrings<'static> = BitsNStrings {
1132 A _trait_ describes a set of method types.
1134 Traits can include default implementations of methods,
1135 written in terms of some unknown [`self` type](#self-types);
1136 the `self` type may either be completely unspecified,
1137 or constrained by some other trait.
1139 Traits are implemented for specific types through separate [implementations](#implementations).
1142 # type Surface = int;
1143 # type BoundingBox = int;
1146 fn draw(&self, Surface);
1147 fn bounding_box(&self) -> BoundingBox;
1151 This defines a trait with two methods.
1152 All values that have [implementations](#implementations) of this trait in scope can have their `draw` and `bounding_box` methods called,
1153 using `value.bounding_box()` [syntax](#method-call-expressions).
1155 Type parameters can be specified for a trait to make it generic.
1156 These appear after the trait name, using the same syntax used in [generic functions](#generic-functions).
1160 fn len(&self) -> uint;
1161 fn elt_at(&self, n: uint) -> T;
1162 fn iter(&self, &fn(T));
1166 Generic functions may use traits as _bounds_ on their type parameters.
1167 This will have two effects: only types that have the trait may instantiate the parameter,
1168 and within the generic function,
1169 the methods of the trait can be called on values that have the parameter's type.
1173 # type Surface = int;
1174 # trait Shape { fn draw(&self, Surface); }
1176 fn draw_twice<T: Shape>(surface: Surface, sh: T) {
1182 Traits also define an [object type](#object-types) with the same name as the trait.
1183 Values of this type are created by [casting](#type-cast-expressions) pointer values
1184 (pointing to a type for which an implementation of the given trait is in scope)
1185 to pointers to the trait name, used as a type.
1189 # impl Shape for int { }
1192 let myshape: @Shape = @mycircle as @Shape;
1195 The resulting value is a managed box containing the value that was cast,
1196 along with information that identifies the methods of the implementation that was used.
1197 Values with a trait type can have [methods called](#method-call-expressions) on them,
1198 for any method in the trait,
1199 and can be used to instantiate type parameters that are bounded by the trait.
1201 Trait methods may be static,
1202 which means that they lack a `self` argument.
1203 This means that they can only be called with function call syntax (`f(x)`)
1204 and not method call syntax (`obj.f()`).
1205 The way to refer to the name of a static method is to qualify it with the trait name,
1206 treating the trait name like a module.
1211 fn from_int(n: int) -> Self;
1213 impl Num for float {
1214 fn from_int(n: int) -> float { n as float }
1216 let x: float = Num::from_int(42);
1219 Traits may inherit from other traits. For example, in
1222 trait Shape { fn area() -> float; }
1223 trait Circle : Shape { fn radius() -> float; }
1226 the syntax `Circle : Shape` means that types that implement `Circle` must also have an implementation for `Shape`.
1227 Multiple supertraits are separated by spaces, `trait Circle : Shape Eq { }`.
1228 In an implementation of `Circle` for a given type `T`, methods can refer to `Shape` methods,
1229 since the typechecker checks that any type with an implementation of `Circle` also has an implementation of `Shape`.
1231 In type-parameterized functions,
1232 methods of the supertrait may be called on values of subtrait-bound type parameters.
1233 Refering to the previous example of `trait Circle : Shape`:
1236 # trait Shape { fn area(&self) -> float; }
1237 # trait Circle : Shape { fn radius(&self) -> float; }
1238 fn radius_times_area<T: Circle>(c: T) -> float {
1239 // `c` is both a Circle and a Shape
1240 c.radius() * c.area()
1244 Likewise, supertrait methods may also be called on trait objects.
1247 # trait Shape { fn area(&self) -> float; }
1248 # trait Circle : Shape { fn radius(&self) -> float; }
1249 # impl Shape for int { fn area(&self) -> float { 0.0 } }
1250 # impl Circle for int { fn radius(&self) -> float { 0.0 } }
1253 let mycircle: Circle = @mycircle as @Circle;
1254 let nonsense = mycircle.radius() * mycircle.area();
1259 An _implementation_ is an item that implements a [trait](#traits) for a specific type.
1261 Implementations are defined with the keyword `impl`.
1264 # struct Point {x: float, y: float};
1265 # type Surface = int;
1266 # struct BoundingBox {x: float, y: float, width: float, height: float};
1267 # trait Shape { fn draw(&self, Surface); fn bounding_box(&self) -> BoundingBox; }
1268 # fn do_draw_circle(s: Surface, c: Circle) { }
1275 impl Shape for Circle {
1276 fn draw(&self, s: Surface) { do_draw_circle(s, *self); }
1277 fn bounding_box(&self) -> BoundingBox {
1278 let r = self.radius;
1279 BoundingBox{x: self.center.x - r, y: self.center.y - r,
1280 width: 2.0 * r, height: 2.0 * r}
1285 It is possible to define an implementation without referring to a trait.
1286 The methods in such an implementation can only be used
1287 as direct calls on the values of the type that the implementation targets.
1288 In such an implementation, the trait type and `for` after `impl` are omitted.
1289 Such implementations are limited to nominal types (enums, structs),
1290 and the implementation must appear in the same module or a sub-module as the `self` type.
1292 When a trait _is_ specified in an `impl`,
1293 all methods declared as part of the trait must be implemented,
1294 with matching types and type parameter counts.
1296 An implementation can take type parameters,
1297 which can be different from the type parameters taken by the trait it implements.
1298 Implementation parameters are written after after the `impl` keyword.
1303 impl<T> Seq<T> for ~[T] {
1306 impl Seq<bool> for u32 {
1307 /* Treat the integer as a sequence of bits */
1314 foreign_mod_item : "extern mod" ident '{' foreign_mod '} ;
1315 foreign_mod : [ foreign_fn ] * ;
1318 Foreign modules form the basis for Rust's foreign function interface. A
1319 foreign module describes functions in external, non-Rust
1321 Functions within foreign modules are declared in the same way as other Rust functions,
1322 with the exception that they may not have a body and are instead terminated by a semicolon.
1325 # use core::libc::{c_char, FILE};
1329 fn fopen(filename: *c_char, mode: *c_char) -> *FILE;
1333 Functions within foreign modules may be called by Rust code, just like functions defined in Rust.
1334 The Rust compiler automatically translates between the Rust ABI and the foreign ABI.
1336 The name of the foreign module has special meaning to the Rust compiler in
1337 that it will treat the module name as the name of a library to link to,
1338 performing the linking as appropriate for the target platform. The name
1339 given for the foreign module will be transformed in a platform-specific way
1340 to determine the name of the library. For example, on Linux the name of the
1341 foreign module is prefixed with 'lib' and suffixed with '.so', so the
1342 foreign mod 'rustrt' would be linked to a library named 'librustrt.so'.
1344 A number of [attributes](#attributes) control the behavior of foreign
1347 By default foreign modules assume that the library they are calling use the
1348 standard C "cdecl" ABI. Other ABIs may be specified using the `abi`
1352 // Interface to the Windows API
1354 extern mod kernel32 { }
1357 The `link_name` attribute allows the default library naming behavior to
1358 be overridden by explicitly specifying the name of the library.
1361 #[link_name = "crypto"]
1362 extern mod mycrypto { }
1365 The `nolink` attribute tells the Rust compiler not to do any linking for the foreign module.
1366 This is particularly useful for creating foreign
1367 modules for libc, which tends to not follow standard library naming
1368 conventions and is linked to all Rust programs anyway.
1372 ~~~~~~~~{.ebnf .gram}
1373 attribute : '#' '[' attr_list ']' ;
1374 attr_list : attr [ ',' attr_list ]*
1375 attr : ident [ '=' literal
1376 | '(' attr_list ')' ] ? ;
1379 Static entities in Rust -- crates, modules and items -- may have _attributes_
1380 applied to them. ^[Attributes in Rust are modeled on Attributes in ECMA-335,
1382 An attribute is a general, free-form metadatum that is interpreted according to name, convention, and language and compiler version.
1383 Attributes may appear as any of
1385 * A single identifier, the attribute name
1386 * An identifier followed by the equals sign '=' and a literal, providing a key/value pair
1387 * An identifier followed by a parenthesized list of sub-attribute arguments
1389 Attributes terminated by a semi-colon apply to the entity that the attribute is declared
1390 within. Attributes that are not terminated by a semi-colon apply to the next entity.
1392 An example of attributes:
1394 ~~~~~~~~{.xfail-test}
1395 // General metadata applied to the enclosing module or crate.
1398 // A function marked as a unit test
1404 // A conditionally-compiled module
1405 #[cfg(target_os="linux")]
1410 // A lint attribute used to suppress a warning/error
1411 #[allow(non_camel_case_types)]
1412 pub type int8_t = i8;
1415 > **Note:** In future versions of Rust, user-provided extensions to the compiler will be able to interpret attributes.
1416 > When this facility is provided, the compiler will distinguish between language-reserved and user-available attributes.
1418 At present, only the Rust compiler interprets attributes, so all attribute
1419 names are effectively reserved. Some significant attributes include:
1421 * The `doc` attribute, for documenting code in-place.
1422 * The `cfg` attribute, for conditional-compilation by build-configuration.
1423 * The `lang` attribute, for custom definitions of traits and functions that are known to the Rust compiler (see [Language items](#language-items)).
1424 * The `link` attribute, for describing linkage metadata for a crate.
1425 * The `test` attribute, for marking functions as unit tests.
1426 * The `allow`, `warn`, `forbid`, and `deny` attributes, for controlling lint checks. Lint checks supported
1427 by the compiler can be found via `rustc -W help`.
1429 Other attributes may be added or removed during development of the language.
1433 Some primitive Rust operations are defined in Rust code,
1434 rather than being implemented directly in C or assembly language.
1435 The definitions of these operations have to be easy for the compiler to find.
1436 The `lang` attribute makes it possible to declare these operations.
1437 For example, the `str` module in the Rust core library defines the string equality function:
1441 pub fn eq_slice(a: &str, b: &str) -> bool {
1446 The name `str_eq` has a special meaning to the Rust compiler,
1447 and the presence of this definition means that it will use this definition
1448 when generating calls to the string equality function.
1450 A complete list of the built-in language items follows:
1455 : Cannot be mutated.
1457 : Can be implicitly copied.
1459 : Are uniquely owned.
1461 : Contain borrowed pointers.
1465 : Elements can be added (for example, integers and floats).
1467 : Elements can be subtracted.
1469 : Elements can be multiplied.
1471 : Elements have a division operation.
1473 : Elements have a remainder operation.
1475 : Elements can be negated arithmetically.
1477 : Elements can be negated logically.
1479 : Elements have an exclusive-or operation.
1481 : Elements have a bitwise `and` operation.
1483 : Elements have a bitwise `or` operation.
1485 : Elements have a left shift operation.
1487 : Elements have a right shift operation.
1489 : Elements can be indexed.
1491 : Elements can be compared for equality.
1493 : Elements have a partial ordering.
1498 : Compare two strings for equality.
1500 : Compare two owned strings for equality.
1502 : Destroy a box before freeing it.
1504 : Generically print a string representation of any type.
1506 : Abort the program with an error.
1508 : Abort the program with a bounds check error.
1510 : Allocate memory on the exchange heap.
1512 : Free memory that was allocated on the exchange heap.
1514 : Allocate memory on the managed heap.
1516 : Free memory that was allocated on the managed heap.
1518 : Create an immutable borrowed pointer to a mutable value.
1520 : Release a borrowed pointer created with `return_to_mut`
1521 `check_not_borrowed`
1522 : Fail if a value has existing borrowed pointers to it.
1524 : Return a new unique string containing a copy of the contents of a unique string.
1526 > **Note:** This list is likely to become out of date. We should auto-generate it
1527 > from `librustc/middle/lang_items.rs`.
1529 # Statements and expressions
1531 Rust is _primarily_ an expression language. This means that most forms of
1532 value-producing or effect-causing evaluation are directed by the uniform
1533 syntax category of _expressions_. Each kind of expression can typically _nest_
1534 within each other kind of expression, and rules for evaluation of expressions
1535 involve specifying both the value produced by the expression and the order in
1536 which its sub-expressions are themselves evaluated.
1538 In contrast, statements in Rust serve _mostly_ to contain and explicitly
1539 sequence expression evaluation.
1543 A _statement_ is a component of a block, which is in turn a component of an
1544 outer [expression](#expressions) or [function](#functions).
1546 Rust has two kinds of statement:
1547 [declaration statements](#declaration-statements) and
1548 [expression statements](#expression-statements).
1550 ### Declaration statements
1552 A _declaration statement_ is one that introduces one or more *names* into the enclosing statement block.
1553 The declared names may denote new slots or new items.
1555 #### Item declarations
1557 An _item declaration statement_ has a syntactic form identical to an
1558 [item](#items) declaration within a module. Declaring an item -- a function,
1559 enumeration, structure, type, static, trait, implementation or module -- locally
1560 within a statement block is simply a way of restricting its scope to a narrow
1561 region containing all of its uses; it is otherwise identical in meaning to
1562 declaring the item outside the statement block.
1564 Note: there is no implicit capture of the function's dynamic environment when
1565 declaring a function-local item.
1568 #### Slot declarations
1570 ~~~~~~~~{.ebnf .gram}
1571 let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
1572 init : [ '=' ] expr ;
1575 A _slot declaration_ introduces a new set of slots, given by a pattern.
1576 The pattern may be followed by a type annotation, and/or an initializer expression.
1577 When no type annotation is given, the compiler will infer the type,
1578 or signal an error if insufficient type information is available for definite inference.
1579 Any slots introduced by a slot declaration are visible from the point of declaration until the end of the enclosing block scope.
1581 ### Expression statements
1583 An _expression statement_ is one that evaluates an [expression](#expressions)
1584 and ignores its result.
1585 The type of an expression statement `e;` is always `()`, regardless of the type of `e`.
1586 As a rule, an expression statement's purpose is to trigger the effects of evaluating its expression.
1590 An expression may have two roles: it always produces a *value*, and it may have *effects*
1591 (otherwise known as "side effects").
1592 An expression *evaluates to* a value, and has effects during *evaluation*.
1593 Many expressions contain sub-expressions (operands).
1594 The meaning of each kind of expression dictates several things:
1595 * Whether or not to evaluate the sub-expressions when evaluating the expression
1596 * The order in which to evaluate the sub-expressions
1597 * How to combine the sub-expressions' values to obtain the value of the expression.
1599 In this way, the structure of expressions dictates the structure of execution.
1600 Blocks are just another kind of expression,
1601 so blocks, statements, expressions, and blocks again can recursively nest inside each other
1602 to an arbitrary depth.
1604 #### Lvalues, rvalues and temporaries
1606 Expressions are divided into two main categories: _lvalues_ and _rvalues_.
1607 Likewise within each expression, sub-expressions may occur in _lvalue context_ or _rvalue context_.
1608 The evaluation of an expression depends both on its own category and the context it occurs within.
1610 [Path](#path-expressions), [field](#field-expressions) and [index](#index-expressions) expressions are lvalues.
1611 All other expressions are rvalues.
1613 The left operand of an [assignment](#assignment-expressions),
1614 [binary move](#binary-move-expressions) or
1615 [compound-assignment](#compound-assignment-expressions) expression is an lvalue context,
1616 as is the single operand of a unary [borrow](#unary-operator-expressions),
1617 or [move](#unary-move-expressions) expression,
1618 and _both_ operands of a [swap](#swap-expressions) expression.
1619 All other expression contexts are rvalue contexts.
1621 When an lvalue is evaluated in an _lvalue context_, it denotes a memory location;
1622 when evaluated in an _rvalue context_, it denotes the value held _in_ that memory location.
1624 When an rvalue is used in lvalue context, a temporary un-named lvalue is created and used instead.
1625 A temporary's lifetime equals the largest lifetime of any borrowed pointer that points to it.
1627 #### Moved and copied types
1629 When a [local variable](#memory-slots) is used as an [rvalue](#lvalues-rvalues-and-temporaries)
1630 the variable will either be [moved](#move-expressions) or [copied](#copy-expressions),
1631 depending on its type.
1632 For types that contain mutable fields or [owning pointers](#owning-pointers), the variable is moved.
1633 All other types are copied.
1636 ### Literal expressions
1638 A _literal expression_ consists of one of the [literal](#literals)
1639 forms described earlier. It directly describes a number, character,
1640 string, boolean value, or the unit value.
1642 ~~~~~~~~ {.literals}
1644 "hello"; // string type
1645 '5'; // character type
1649 ### Path expressions
1651 A [path](#paths) used as an expression context denotes either a local variable or an item.
1652 Path expressions are [lvalues](#lvalues-rvalues-and-temporaries).
1654 ### Tuple expressions
1656 Tuples are written by enclosing one or more comma-separated
1657 expressions in parentheses. They are used to create [tuple-typed](#tuple-types)
1666 ### Structure expressions
1668 ~~~~~~~~{.ebnf .gram}
1669 struct_expr : expr_path '{' ident ':' expr
1670 [ ',' ident ':' expr ] *
1673 [ ',' expr ] * ')' |
1677 There are several forms of structure expressions.
1678 A _structure expression_ consists of the [path](#paths) of a [structure item](#structures),
1679 followed by a brace-enclosed list of one or more comma-separated name-value pairs,
1680 providing the field values of a new instance of the structure.
1681 A field name can be any identifier, and is separated from its value expression by a colon.
1682 The location denoted by a structure field is mutable if and only if the enclosing structure is mutable.
1684 A _tuple structure expression_ consists of the [path](#paths) of a [structure item](#structures),
1685 followed by a parenthesized list of one or more comma-separated expressions
1686 (in other words, the path of a structure item followed by a tuple expression).
1687 The structure item must be a tuple structure item.
1689 A _unit-like structure expression_ consists only of the [path](#paths) of a [structure item](#structures).
1691 The following are examples of structure expressions:
1694 # struct Point { x: float, y: float }
1695 # struct TuplePoint(float, float);
1696 # mod game { pub struct User<'self> { name: &'self str, age: uint, score: uint } }
1697 # struct Cookie; fn some_fn<T>(t: T) {}
1698 Point {x: 10f, y: 20f};
1699 TuplePoint(10f, 20f);
1700 let u = game::User {name: "Joe", age: 35, score: 100_000};
1701 some_fn::<Cookie>(Cookie);
1704 A structure expression forms a new value of the named structure type.
1705 Note that for a given *unit-like* structure type, this will always be the same value.
1707 A structure expression can terminate with the syntax `..` followed by an expression to denote a functional update.
1708 The expression following `..` (the base) must have the same structure type as the new structure type being formed.
1709 The entire expression denotes the result of allocating a new structure
1710 (with the same type as the base expression)
1711 with the given values for the fields that were explicitly specified
1712 and the values in the base record for all other fields.
1715 # struct Point3d { x: int, y: int, z: int }
1716 let base = Point3d {x: 1, y: 2, z: 3};
1717 Point3d {y: 0, z: 10, .. base};
1720 ### Record expressions
1722 ~~~~~~~~{.ebnf .gram}
1723 rec_expr : '{' ident ':' expr
1724 [ ',' ident ':' expr ] *
1728 ### Method-call expressions
1730 ~~~~~~~~{.ebnf .gram}
1731 method_call_expr : expr '.' ident paren_expr_list ;
1734 A _method call_ consists of an expression followed by a single dot, an identifier, and a parenthesized expression-list.
1735 Method calls are resolved to methods on specific traits,
1736 either statically dispatching to a method if the exact `self`-type of the left-hand-side is known,
1737 or dynamically dispatching if the left-hand-side expression is an indirect [object type](#object-types).
1740 ### Field expressions
1742 ~~~~~~~~{.ebnf .gram}
1743 field_expr : expr '.' ident
1746 A _field expression_ consists of an expression followed by a single dot and an identifier,
1747 when not immediately followed by a parenthesized expression-list (the latter is a [method call expression](#method-call-expressions)).
1748 A field expression denotes a field of a [structure](#structure-types).
1755 A field access on a record is an [lvalue](#lvalues-rvalues-and-temporaries) referring to the value of that field.
1756 When the field is mutable, it can be [assigned](#assignment-expressions) to.
1758 When the type of the expression to the left of the dot is a pointer to a record or structure,
1759 it is automatically derferenced to make the field access possible.
1762 ### Vector expressions
1764 ~~~~~~~~{.ebnf .gram}
1765 vec_expr : '[' "mut"? vec_elems? ']'
1767 vec_elems : [expr [',' expr]*] | [expr ',' ".." expr]
1770 A [_vector_](#vector-types) _expression_ is written by enclosing zero or
1771 more comma-separated expressions of uniform type in square brackets.
1773 In the `[expr ',' ".." expr]` form, the expression after the `".."`
1774 must be a constant expression that can be evaluated at compile time, such
1775 as a [literal](#literals) or a [static item](#static-items).
1779 ["a", "b", "c", "d"];
1780 [0, ..128]; // vector with 128 zeros
1781 [0u8, 0u8, 0u8, 0u8];
1784 ### Index expressions
1786 ~~~~~~~~{.ebnf .gram}
1787 idx_expr : expr '[' expr ']'
1791 [Vector](#vector-types)-typed expressions can be indexed by writing a
1792 square-bracket-enclosed expression (the index) after them. When the
1793 vector is mutable, the resulting [lvalue](#lvalues-rvalues-and-temporaries) can be assigned to.
1795 Indices are zero-based, and may be of any integral type. Vector access
1796 is bounds-checked at run-time. When the check fails, it will put the
1797 task in a _failing state_.
1800 # do task::spawn_unlinked {
1803 (["a", "b"])[10]; // fails
1808 ### Unary operator expressions
1810 Rust defines six symbolic unary operators,
1811 in addition to the unary [copy](#unary-copy-expressions) and [move](#unary-move-expressions) operators.
1812 They are all written as prefix operators, before the expression they apply to.
1815 : Negation. May only be applied to numeric types.
1817 : Dereference. When applied to a [pointer](#pointer-types) it denotes the pointed-to location.
1818 For pointers to mutable locations, the resulting [lvalue](#lvalues-rvalues-and-temporaries) can be assigned to.
1819 For [enums](#enumerated-types) that have only a single variant, containing a single parameter,
1820 the dereference operator accesses this parameter.
1822 : Logical negation. On the boolean type, this flips between `true` and
1823 `false`. On integer types, this inverts the individual bits in the
1824 two's complement representation of the value.
1826 : [Boxing](#pointer-types) operators. Allocate a box to hold the value they are applied to,
1827 and store the value in it. `@` creates a managed box, whereas `~` creates an owned box.
1829 : Borrow operator. Returns a borrowed pointer, pointing to its operand.
1830 The operand of a borrowed pointer is statically proven to outlive the resulting pointer.
1831 If the borrow-checker cannot prove this, it is a compilation error.
1833 ### Binary operator expressions
1835 ~~~~~~~~{.ebnf .gram}
1836 binop_expr : expr binop expr ;
1839 Binary operators expressions are given in terms of
1840 [operator precedence](#operator-precedence).
1842 #### Arithmetic operators
1844 Binary arithmetic expressions are syntactic sugar for calls to built-in traits,
1845 defined in the `core::ops` module of the `core` library.
1846 This means that arithmetic operators can be overridden for user-defined types.
1847 The default meaning of the operators on standard types is given here.
1850 : Addition and vector/string concatenation.
1851 Calls the `add` method on the `core::ops::Add` trait.
1854 Calls the `sub` method on the `core::ops::Sub` trait.
1857 Calls the `mul` method on the `core::ops::Mul` trait.
1860 Calls the `div` method on the `core::ops::Div` trait.
1863 Calls the `rem` method on the `core::ops::Rem` trait.
1865 #### Bitwise operators
1867 Like the [arithmetic operators](#arithmetic-operators), bitwise operators
1868 are syntactic sugar for calls to methods of built-in traits.
1869 This means that bitwise operators can be overridden for user-defined types.
1870 The default meaning of the operators on standard types is given here.
1874 Calls the `bitand` method of the `core::ops::BitAnd` trait.
1877 Calls the `bitor` method of the `core::ops::BitOr` trait.
1880 Calls the `bitxor` method of the `core::ops::BitXor` trait.
1882 : Logical left shift.
1883 Calls the `shl` method of the `core::ops::Shl` trait.
1885 : Logical right shift.
1886 Calls the `shr` method of the `core::ops::Shr` trait.
1888 #### Lazy boolean operators
1890 The operators `||` and `&&` may be applied to operands of boolean type.
1891 The `||` operator denotes logical 'or', and the `&&` operator denotes logical 'and'.
1892 They differ from `|` and `&` in that the right-hand operand is only evaluated
1893 when the left-hand operand does not already determine the result of the expression.
1894 That is, `||` only evaluates its right-hand operand
1895 when the left-hand operand evaluates to `false`, and `&&` only when it evaluates to `true`.
1897 #### Comparison operators
1899 Comparison operators are, like the [arithmetic operators](#arithmetic-operators),
1900 and [bitwise operators](#bitwise-operators),
1901 syntactic sugar for calls to built-in traits.
1902 This means that comparison operators can be overridden for user-defined types.
1903 The default meaning of the operators on standard types is given here.
1907 Calls the `eq` method on the `core::cmp::Eq` trait.
1910 Calls the `ne` method on the `core::cmp::Eq` trait.
1913 Calls the `lt` method on the `core::cmp::Ord` trait.
1916 Calls the `gt` method on the `core::cmp::Ord` trait.
1918 : Less than or equal.
1919 Calls the `le` method on the `core::cmp::Ord` trait.
1921 : Greater than or equal.
1922 Calls the `ge` method on the `core::cmp::Ord` trait.
1925 #### Type cast expressions
1927 A type cast expression is denoted with the binary operator `as`.
1929 Executing an `as` expression casts the value on the left-hand side to the type
1930 on the right-hand side.
1932 A numeric value can be cast to any numeric type.
1933 A raw pointer value can be cast to or from any integral type or raw pointer type.
1934 Any other cast is unsupported and will fail to compile.
1936 An example of an `as` expression:
1939 # fn sum(v: &[float]) -> float { 0.0 }
1940 # fn len(v: &[float]) -> int { 0 }
1942 fn avg(v: &[float]) -> float {
1943 let sum: float = sum(v);
1944 let sz: float = len(v) as float;
1949 #### Swap expressions
1951 A _swap expression_ consists of an [lvalue](#lvalues-rvalues-and-temporaries) followed by a bi-directional arrow (`<->`) and another [lvalue](#lvalues-rvalues-and-temporaries).
1953 Evaluating a swap expression causes, as a side effect, the values held in the left-hand-side and right-hand-side [lvalues](#lvalues-rvalues-and-temporaries) to be exchanged indivisibly.
1955 Evaluating a swap expression neither changes reference counts,
1956 nor deeply copies any owned structure pointed to by the moved [rvalue](#lvalues-rvalues-and-temporaries).
1957 Instead, the swap expression represents an indivisible *exchange of ownership*,
1958 between the right-hand-side and the left-hand-side of the expression.
1959 No allocation or destruction is entailed.
1961 An example of three different swap expressions:
1964 # let mut x = &mut [0];
1965 # let mut a = &mut [0];
1967 # struct S1 { z: int };
1968 # struct S2 { c: int };
1969 # let mut y = S1{z: 0};
1970 # let mut b = S2{c: 0};
1978 #### Assignment expressions
1980 An _assignment expression_ consists of an [lvalue](#lvalues-rvalues-and-temporaries) expression followed by an
1981 equals sign (`=`) and an [rvalue](#lvalues-rvalues-and-temporaries) expression.
1983 Evaluating an assignment expression [either copies or moves](#moved-and-copied-types) its right-hand operand to its left-hand operand.
1992 #### Compound assignment expressions
1994 The `+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `<<`, and `>>`
1995 operators may be composed with the `=` operator. The expression `lval
1996 OP= val` is equivalent to `lval = lval OP val`. For example, `x = x +
1997 1` may be written as `x += 1`.
1999 Any such expression always has the [`unit`](#primitive-types) type.
2001 #### Operator precedence
2003 The precedence of Rust binary operators is ordered as follows, going
2004 from strong to weak:
2021 Operators at the same precedence level are evaluated left-to-right.
2023 ### Grouped expressions
2025 An expression enclosed in parentheses evaluates to the result of the enclosed
2026 expression. Parentheses can be used to explicitly specify evaluation order
2027 within an expression.
2029 ~~~~~~~~{.ebnf .gram}
2030 paren_expr : '(' expr ')' ;
2033 An example of a parenthesized expression:
2036 let x = (2 + 3) * 4;
2039 ### Unary copy expressions
2041 ~~~~~~~~{.ebnf .gram}
2042 copy_expr : "copy" expr ;
2045 > **Note:** `copy` expressions are deprecated. It's preferable to use
2046 > the `Clone` trait and `clone()` method.
2048 A _unary copy expression_ consists of the unary `copy` operator applied to
2049 some argument expression.
2051 Evaluating a copy expression first evaluates the argument expression, then
2052 copies the resulting value, allocating any memory necessary to hold the new
2055 [Managed boxes](#pointer-types) (type `@`) are, as usual, shallow-copied,
2056 as are raw and borrowed pointers.
2057 [Owned boxes](#pointer-types), [owned vectors](#vector-types) and similar owned types are deep-copied.
2059 Since the binary [assignment operator](#assignment-expressions) `=` performs a copy or move implicitly,
2060 the unary copy operator is typically only used to cause an argument to a function to be copied and passed by value.
2062 An example of a copy expression:
2065 fn mutate(mut vec: ~[int]) {
2071 mutate(copy v); // Pass a copy
2073 assert!(v[0] == 1); // Original was not modified
2076 ### Unary move expressions
2078 ~~~~~~~~{.ebnf .gram}
2079 move_expr : "move" expr ;
2082 A _unary move expression_ is similar to a [unary copy](#unary-copy-expressions) expression,
2083 except that it can only be applied to a [local variable](#memory-slots),
2084 and it performs a _move_ on its operand, rather than a copy.
2085 That is, the memory location denoted by its operand is de-initialized after evaluation,
2086 and the resulting value is a shallow copy of the operand,
2087 even if the operand is an [owning type](#type-kinds).
2090 > **Note:** In future versions of Rust, `move` may be removed as a separate operator;
2091 > moves are now [automatically performed](#moved-and-copied-types) for most cases `move` would be appropriate.
2094 ### Call expressions
2096 ~~~~~~~~ {.abnf .gram}
2097 expr_list : [ expr [ ',' expr ]* ] ? ;
2098 paren_expr_list : '(' expr_list ')' ;
2099 call_expr : expr paren_expr_list ;
2102 A _call expression_ invokes a function, providing zero or more input slots and
2103 an optional reference slot to serve as the function's output, bound to the
2104 `lval` on the right hand side of the call. If the function eventually returns,
2105 then the expression completes.
2107 Some examples of call expressions:
2110 # use core::from_str::FromStr::from_str;
2111 # fn add(x: int, y: int) -> int { 0 }
2113 let x: int = add(1, 2);
2114 let pi = from_str::<f32>("3.14");
2117 ### Lambda expressions
2119 ~~~~~~~~ {.abnf .gram}
2120 ident_list : [ ident [ ',' ident ]* ] ? ;
2121 lambda_expr : '|' ident_list '|' expr ;
2124 A _lambda expression_ (sometimes called an "anonymous function expression") defines a function and denotes it as a value,
2125 in a single expression.
2126 A lambda expression is a pipe-symbol-delimited (`|`) list of identifiers followed by an expression.
2128 A lambda expression denotes a function that maps a list of parameters (`ident_list`)
2129 onto the expression that follows the `ident_list`.
2130 The identifiers in the `ident_list` are the parameters to the function.
2131 These parameters' types need not be specified, as the compiler infers them from context.
2133 Lambda expressions are most useful when passing functions as arguments to other functions,
2134 as an abbreviation for defining and capturing a separate function.
2136 Significantly, lambda expressions _capture their environment_,
2137 which regular [function definitions](#functions) do not.
2138 The exact type of capture depends on the [function type](#function-types) inferred for the lambda expression.
2139 In the simplest and least-expensive form (analogous to a ```&fn() { }``` expression),
2140 the lambda expression captures its environment by reference,
2141 effectively borrowing pointers to all outer variables mentioned inside the function.
2142 Alternately, the compiler may infer that a lambda expression should copy or move values (depending on their type.)
2143 from the environment into the lambda expression's captured environment.
2145 In this example, we define a function `ten_times` that takes a higher-order function argument,
2146 and call it with a lambda expression as an argument.
2149 fn ten_times(f: &fn(int)) {
2157 ten_times(|j| io::println(fmt!("hello, %d", j)));
2163 ~~~~~~~~{.ebnf .gram}
2164 while_expr : "while" expr '{' block '}' ;
2167 A `while` loop begins by evaluating the boolean loop conditional expression.
2168 If the loop conditional expression evaluates to `true`, the loop body block
2169 executes and control returns to the loop conditional expression. If the loop
2170 conditional expression evaluates to `false`, the `while` expression completes.
2178 io::println("hello\n");
2185 The keyword `loop` in Rust appears both in _loop expressions_ and in _continue expressions_.
2186 A loop expression denotes an infinite loop;
2187 see [Continue expressions](#continue-expressions) for continue expressions.
2189 ~~~~~~~~{.ebnf .gram}
2190 loop_expr : [ lifetime ':' ] "loop" '{' block '}';
2193 A `loop` expression may optionally have a _label_.
2194 If a label is present,
2195 then labeled `break` and `loop` expressions nested within this loop may exit out of this loop or return control to its head.
2196 See [Break expressions](#break-expressions).
2198 ### Break expressions
2200 ~~~~~~~~{.ebnf .gram}
2201 break_expr : "break" [ lifetime ];
2204 A `break` expression has an optional `label`.
2205 If the label is absent, then executing a `break` expression immediately terminates the innermost loop enclosing it.
2206 It is only permitted in the body of a loop.
2207 If the label is present, then `break foo` terminates the loop with label `foo`,
2208 which need not be the innermost label enclosing the `break` expression,
2209 but must enclose it.
2211 ### Continue expressions
2213 ~~~~~~~~{.ebnf .gram}
2214 continue_expr : "loop" [ lifetime ];
2217 A continue expression, written `loop`, also has an optional `label`.
2218 If the label is absent,
2219 then executing a `loop` expression immediately terminates the current iteration of the innermost loop enclosing it,
2220 returning control to the loop *head*.
2221 In the case of a `while` loop,
2222 the head is the conditional expression controlling the loop.
2223 In the case of a `for` loop, the head is the call-expression controlling the loop.
2224 If the label is present, then `loop foo` returns control to the head of the loop with label `foo`,
2225 which need not be the innermost label enclosing the `break` expression,
2226 but must enclose it.
2228 A `loop` expression is only permitted in the body of a loop.
2233 ~~~~~~~~{.ebnf .gram}
2234 do_expr : "do" expr [ '|' ident_list '|' ] ? '{' block '}' ;
2237 A _do expression_ provides a more-familiar block-syntax for a [lambda expression](#lambda-expressions),
2238 including a special translation of [return expressions](#return-expressions) inside the supplied block.
2240 The optional `ident_list` and `block` provided in a `do` expression are parsed as though they constitute a lambda expression;
2241 if the `ident_list` is missing, an empty `ident_list` is implied.
2243 The lambda expression is then provided as a _trailing argument_
2244 to the outermost [call](#call-expressions) or [method call](#method-call-expressions) expression
2245 in the `expr` following `do`.
2246 If the `expr` is a [path expression](#path-expressions), it is parsed as though it is a call expression.
2247 If the `expr` is a [field expression](#field-expressions), it is parsed as though it is a method call expression.
2249 In this example, both calls to `f` are equivalent:
2252 # fn f(f: &fn(int)) { }
2262 In this example, both calls to the (binary) function `k` are equivalent:
2265 # fn k(x:int, f: &fn(int)) { }
2278 ~~~~~~~~{.ebnf .gram}
2279 for_expr : "for" expr [ '|' ident_list '|' ] ? '{' block '}' ;
2282 A _for expression_ is similar to a [`do` expression](#do-expressions),
2283 in that it provides a special block-form of lambda expression,
2284 suited to passing the `block` function to a higher-order function implementing a loop.
2286 Like a `do` expression, a `return` expression inside a `for` expresison is rewritten,
2287 to access a local flag that causes an early return in the caller.
2289 Additionally, any occurrence of a [return expression](#return-expressions)
2290 inside the `block` of a `for` expression is rewritten
2291 as a reference to an (anonymous) flag set in the caller's environment,
2292 which is checked on return from the `expr` and, if set,
2293 causes a corresponding return from the caller.
2294 In this way, the meaning of `return` statements in language built-in control blocks is preserved,
2295 if they are rewritten using lambda functions and `do` expressions as abstractions.
2297 Like `return` expressions, any [`break`](#break-expressions) and [`loop`](#loop-expressions) expressions
2298 are rewritten inside `for` expressions, with a combination of local flag variables,
2299 and early boolean-valued returns from the `block` function,
2300 such that the meaning of `break` and `loop` is preserved in a primitive loop
2301 when rewritten as a `for` loop controlled by a higher order function.
2303 An example of a for loop over the contents of a vector:
2307 # fn bar(f: foo) { }
2308 # let a = 0, b = 0, c = 0;
2310 let v: &[foo] = &[a, b, c];
2317 An example of a for loop over a series of integers:
2320 # fn bar(b:uint) { }
2321 for uint::range(0, 256) |i| {
2328 ~~~~~~~~{.ebnf .gram}
2329 if_expr : "if" expr '{' block '}'
2332 else_tail : "else" [ if_expr
2336 An `if` expression is a conditional branch in program control. The form of
2337 an `if` expression is a condition expression, followed by a consequent
2338 block, any number of `else if` conditions and blocks, and an optional
2339 trailing `else` block. The condition expressions must have type
2340 `bool`. If a condition expression evaluates to `true`, the
2341 consequent block is executed and any subsequent `else if` or `else`
2342 block is skipped. If a condition expression evaluates to `false`, the
2343 consequent block is skipped and any subsequent `else if` condition is
2344 evaluated. If all `if` and `else if` conditions evaluate to `false`
2345 then any `else` block is executed.
2348 ### Match expressions
2350 ~~~~~~~~{.ebnf .gram}
2351 match_expr : "match" expr '{' match_arm [ '|' match_arm ] * '}' ;
2353 match_arm : match_pat '=>' [ expr "," | '{' block '}' ] ;
2355 match_pat : pat [ ".." pat ] ? [ "if" expr ] ;
2359 A `match` expression branches on a *pattern*. The exact form of matching that
2360 occurs depends on the pattern. Patterns consist of some combination of
2361 literals, destructured enum constructors, structures, records and tuples, variable binding
2362 specifications, wildcards (`*`), and placeholders (`_`). A `match` expression has a *head
2363 expression*, which is the value to compare to the patterns. The type of the
2364 patterns must equal the type of the head expression.
2366 In a pattern whose head expression has an `enum` type, a placeholder (`_`) stands for a
2367 *single* data field, whereas a wildcard `*` stands for *all* the fields of a particular
2368 variant. For example:
2371 enum List<X> { Nil, Cons(X, @List<X>) }
2373 let x: List<int> = Cons(10, @Cons(11, @Nil));
2376 Cons(_, @Nil) => fail!(~"singleton list"),
2378 Nil => fail!(~"empty list")
2382 The first pattern matches lists constructed by applying `Cons` to any head value, and a
2383 tail value of `@Nil`. The second pattern matches _any_ list constructed with `Cons`,
2384 ignoring the values of its arguments. The difference between `_` and `*` is that the pattern `C(_)` is only type-correct if
2385 `C` has exactly one argument, while the pattern `C(*)` is type-correct for any enum variant `C`, regardless of how many arguments `C` has.
2387 To execute an `match` expression, first the head expression is evaluated, then
2388 its value is sequentially compared to the patterns in the arms until a match
2389 is found. The first arm with a matching pattern is chosen as the branch target
2390 of the `match`, any variables bound by the pattern are assigned to local
2391 variables in the arm's block, and control enters the block.
2393 An example of an `match` expression:
2397 # fn process_pair(a: int, b: int) { }
2398 # fn process_ten() { }
2400 enum List<X> { Nil, Cons(X, @List<X>) }
2402 let x: List<int> = Cons(10, @Cons(11, @Nil));
2405 Cons(a, @Cons(b, _)) => {
2420 Patterns that bind variables default to binding to a copy of the matched value. This can be made
2421 explicit using the ```copy``` keyword, changed to bind to a borrowed pointer by using the ```ref```
2422 keyword, or to a mutable borrowed pointer using ```ref mut```, or the value can be moved into
2423 the new binding using ```move```.
2425 A pattern that's just an identifier,
2426 like `Nil` in the previous answer,
2427 could either refer to an enum variant that's in scope,
2428 or bind a new variable.
2429 The compiler resolves this ambiguity by forbidding variable bindings that occur in ```match``` patterns from shadowing names of variants that are in scope.
2430 For example, wherever ```List``` is in scope,
2431 a ```match``` pattern would not be able to bind ```Nil``` as a new name.
2432 The compiler interprets a variable pattern `x` as a binding _only_ if there is no variant named `x` in scope.
2433 A convention you can use to avoid conflicts is simply to name variants with upper-case letters,
2434 and local variables with lower-case letters.
2436 Multiple match patterns may be joined with the `|` operator.
2437 A range of values may be specified with `..`.
2443 let message = match x {
2444 0 | 1 => "not many",
2450 Range patterns only work on scalar types
2451 (like integers and characters; not like vectors and structs, which have sub-components).
2452 A range pattern may not be a sub-range of another range pattern inside the same `match`.
2454 Finally, match patterns can accept *pattern guards* to further refine the
2455 criteria for matching a case. Pattern guards appear after the pattern and
2456 consist of a bool-typed expression following the `if` keyword. A pattern
2457 guard may refer to the variables bound within the pattern they follow.
2460 # let maybe_digit = Some(0);
2461 # fn process_digit(i: int) { }
2462 # fn process_other(i: int) { }
2464 let message = match maybe_digit {
2465 Some(x) if x < 10 => process_digit(x),
2466 Some(x) => process_other(x),
2471 ### Return expressions
2473 ~~~~~~~~{.ebnf .gram}
2474 return_expr : "return" expr ? ;
2477 Return expressions are denoted with the keyword `return`. Evaluating a `return`
2478 expression moves its argument into the output slot of the current
2479 function, destroys the current function activation frame, and transfers
2480 control to the caller frame.
2482 An example of a `return` expression:
2485 fn max(a: int, b: int) -> int {
2498 Every slot, item and value in a Rust program has a type. The _type_ of a *value*
2499 defines the interpretation of the memory holding it.
2501 Built-in types and type-constructors are tightly integrated into the language,
2502 in nontrivial ways that are not possible to emulate in user-defined
2503 types. User-defined types have limited capabilities.
2507 The primitive types are the following:
2509 * The "unit" type `()`, having the single "unit" value `()` (occasionally called "nil").
2510 ^[The "unit" value `()` is *not* a sentinel "null pointer" value for reference slots; the "unit" type is the implicit return type from functions otherwise lacking a return type, and can be used in other contexts (such as message-sending or type-parametric code) as a zero-size type.]
2511 * The boolean type `bool` with values `true` and `false`.
2512 * The machine types.
2513 * The machine-dependent integer and floating-point types.
2517 The machine types are the following:
2520 * The unsigned word types `u8`, `u16`, `u32` and `u64`, with values drawn from
2521 the integer intervals $[0, 2^8 - 1]$, $[0, 2^{16} - 1]$, $[0, 2^{32} - 1]$ and
2522 $[0, 2^{64} - 1]$ respectively.
2524 * The signed two's complement word types `i8`, `i16`, `i32` and `i64`, with
2525 values drawn from the integer intervals $[-(2^7), 2^7 - 1]$,
2526 $[-(2^{15}), 2^{15} - 1]$, $[-(2^{31}), 2^{31} - 1]$, $[-(2^{63}), 2^{63} - 1]$
2529 * The IEEE 754-2008 `binary32` and `binary64` floating-point types: `f32` and
2530 `f64`, respectively.
2532 #### Machine-dependent integer types
2534 The Rust type `uint`^[A Rust `uint` is analogous to a C99 `uintptr_t`.] is an
2535 unsigned integer type with target-machine-dependent size. Its size, in
2536 bits, is equal to the number of bits required to hold any memory address on
2539 The Rust type `int`^[A Rust `int` is analogous to a C99 `intptr_t`.] is a
2540 two's complement signed integer type with target-machine-dependent size. Its
2541 size, in bits, is equal to the size of the rust type `uint` on the same target
2545 #### Machine-dependent floating point type
2547 The Rust type `float` is a machine-specific type equal to one of the supported
2548 Rust floating-point machine types (`f32` or `f64`). It is the largest
2549 floating-point type that is directly supported by hardware on the target
2550 machine, or if the target machine has no floating-point hardware support, the
2551 largest floating-point type supported by the software floating-point library
2552 used to support the other floating-point machine types.
2554 Note that due to the preference for hardware-supported floating-point, the
2555 type `float` may not be equal to the largest *supported* floating-point type.
2560 The types `char` and `str` hold textual data.
2562 A value of type `char` is a Unicode character,
2563 represented as a 32-bit unsigned word holding a UCS-4 codepoint.
2565 A value of type `str` is a Unicode string,
2566 represented as a vector of 8-bit unsigned bytes holding a sequence of UTF-8 codepoints.
2567 Since `str` is of unknown size, it is not a _first class_ type,
2568 but can only be instantiated through a pointer type,
2569 such as `&str`, `@str` or `~str`.
2574 The tuple type-constructor forms a new heterogeneous product of values similar
2575 to the record type-constructor. The differences are as follows:
2577 * tuple elements cannot be mutable, unlike record fields
2578 * tuple elements are not named and can be accessed only by pattern-matching
2580 Tuple types and values are denoted by listing the types or values of their
2581 elements, respectively, in a parenthesized, comma-separated
2584 The members of a tuple are laid out in memory contiguously, like a record, in
2585 order specified by the tuple type.
2587 An example of a tuple type and its use:
2590 type Pair<'self> = (int,&'self str);
2591 let p: Pair<'static> = (10,"hello");
2593 assert!(b != "world");
2599 The vector type constructor represents a homogeneous array of values of a given type.
2600 A vector has a fixed size.
2601 (Operations like `vec::push` operate solely on owned vectors.)
2602 A vector type can be annotated with a _definite_ size,
2603 written with a trailing asterisk and integer literal, such as `[int * 10]`.
2604 Such a definite-sized vector type is a first-class type, since its size is known statically.
2605 A vector without such a size is said to be of _indefinite_ size,
2606 and is therefore not a _first-class_ type.
2607 An indefinite-size vector can only be instantiated through a pointer type,
2608 such as `&[T]`, `@[T]` or `~[T]`.
2609 The kind of a vector type depends on the kind of its element type,
2610 as with other simple structural types.
2612 Expressions producing vectors of definite size cannot be evaluated in a
2613 context expecting a vector of indefinite size; one must copy the
2614 definite-sized vector contents into a distinct vector of indefinite size.
2616 An example of a vector type and its use:
2619 let v: &[int] = &[7, 5, 3];
2624 All in-bounds elements of a vector are always initialized,
2625 and access to a vector is always bounds-checked.
2630 A `struct` *type* is a heterogeneous product of other types, called the *fields* of the type.
2631 ^[`struct` types are analogous `struct` types in C,
2632 the *record* types of the ML family,
2633 or the *structure* types of the Lisp family.]
2635 New instances of a `struct` can be constructed with a [struct expression](#struct-expressions).
2637 The memory order of fields in a `struct` is given by the item defining it.
2638 Fields may be given in any order in a corresponding struct *expression*;
2639 the resulting `struct` value will always be laid out in memory in the order specified by the corresponding *item*.
2641 The fields of a `struct` may be qualified by [visibility modifiers](#visibility-modifiers),
2642 to restrict access to implementation-private data in a structure.
2644 A _tuple struct_ type is just like a structure type, except that the fields are anonymous.
2646 A _unit-like struct_ type is like a structure type, except that it has no fields.
2647 The one value constructed by the associated [structure expression](#structure-expression) is the only value that inhabits such a type.
2649 ### Enumerated types
2651 An *enumerated type* is a nominal, heterogeneous disjoint union type,
2652 denoted by the name of an [`enum` item](#enumerations).
2653 ^[The `enum` type is analogous to a `data` constructor declaration in ML,
2654 or a *pick ADT* in Limbo.]
2656 An [`enum` item](#enumerations) declares both the type and a number of *variant constructors*,
2657 each of which is independently named and takes an optional tuple of arguments.
2659 New instances of an `enum` can be constructed by calling one of the variant constructors,
2660 in a [call expression](#call-expressions).
2662 Any `enum` value consumes as much memory as the largest variant constructor for its corresponding `enum` type.
2664 Enum types cannot be denoted *structurally* as types,
2665 but must be denoted by named reference to an [`enum` item](#enumerations).
2670 Nominal types -- [enumerations](#enumerated-types) and [structures](#structure-types) -- may be recursive.
2671 That is, each `enum` constructor or `struct` field may refer, directly or indirectly, to the enclosing `enum` or `struct` type itself.
2672 Such recursion has restrictions:
2674 * Recursive types must include a nominal type in the recursion
2675 (not mere [type definitions](#type-definitions),
2676 or other structural types such as [vectors](#vector-types) or [tuples](#tuple-types)).
2677 * A recursive `enum` item must have at least one non-recursive constructor
2678 (in order to give the recursion a basis case).
2679 * The size of a recursive type must be finite;
2680 in other words the recursive fields of the type must be [pointer types](#pointer-types).
2681 * Recursive type definitions can cross module boundaries, but not module *visibility* boundaries,
2682 or crate boundaries (in order to simplify the module system and type checker).
2684 An example of a *recursive* type and its use:
2692 let a: List<int> = Cons(7, @Cons(13, @Nil));
2698 All pointers in Rust are explicit first-class values.
2699 They can be copied, stored into data structures, and returned from functions.
2700 There are four varieties of pointer in Rust:
2702 Managed pointers (`@`)
2703 : These point to managed heap allocations (or "boxes") in the task-local, managed heap.
2704 Managed pointers are written `@content`,
2705 for example `@int` means a managed pointer to a managed box containing an integer.
2706 Copying a managed pointer is a "shallow" operation:
2707 it involves only copying the pointer itself
2708 (as well as any reference-count or GC-barriers required by the managed heap).
2709 Dropping a managed pointer does not necessarily release the box it points to;
2710 the lifecycles of managed boxes are subject to an unspecified garbage collection algorithm.
2712 Owning pointers (`~`)
2713 : These point to owned heap allocations (or "boxes") in the shared, inter-task heap.
2714 Each owned box has a single owning pointer; pointer and pointee retain a 1:1 relationship at all times.
2715 Owning pointers are written `~content`,
2716 for example `~int` means an owning pointer to an owned box containing an integer.
2717 Copying an owned box is a "deep" operation:
2718 it involves allocating a new owned box and copying the contents of the old box into the new box.
2719 Releasing an owning pointer immediately releases its corresponding owned box.
2721 Borrowed pointers (`&`)
2722 : These point to memory _owned by some other value_.
2723 Borrowed pointers arise by (automatic) conversion from owning pointers, managed pointers,
2724 or by applying the borrowing operator `&` to some other value,
2725 including [lvalues, rvalues or temporaries](#lvalues-rvalues-and-temporaries).
2726 Borrowed pointers are written `&content`, or in some cases `&f/content` for some lifetime-variable `f`,
2727 for example `&int` means a borrowed pointer to an integer.
2728 Copying a borrowed pointer is a "shallow" operation:
2729 it involves only copying the pointer itself.
2730 Releasing a borrowed pointer typically has no effect on the value it points to,
2731 with the exception of temporary values,
2732 which are released when the last borrowed pointer to them is released.
2735 : Raw pointers are pointers without safety or liveness guarantees.
2736 Raw pointers are written `*content`,
2737 for example `*int` means a raw pointer to an integer.
2738 Copying or dropping a raw pointer is has no effect on the lifecycle of any other value.
2739 Dereferencing a raw pointer or converting it to any other pointer type is an [`unsafe` operation](#unsafe-functions).
2740 Raw pointers are generally discouraged in Rust code;
2741 they exist to support interoperability with foreign code,
2742 and writing performance-critical or low-level functions.
2747 The function type constructor `fn` forms new function types.
2748 A function type consists of a possibly-empty set of function-type modifiers
2749 (such as `unsafe` or `extern`), a sequence of input types and an output type.
2751 An example of a `fn` type:
2754 fn add(x: int, y: int) -> int {
2758 let mut x = add(5,7);
2760 type Binop<'self> = &'self fn(int,int) -> int;
2761 let bo: Binop = add;
2767 Every trait item (see [traits](#traits)) defines a type with the same name as the trait.
2768 This type is called the _object type_ of the trait.
2769 Object types permit "late binding" of methods, dispatched using _virtual method tables_ ("vtables").
2770 Whereas most calls to trait methods are "early bound" (statically resolved) to specific implementations at compile time,
2771 a call to a method on an object type is only resolved to a vtable entry at compile time.
2772 The actual implementation for each vtable entry can vary on an object-by-object basis.
2774 Given a pointer-typed expression `E` of type `&T`, `~T` or `@T`, where `T` implements trait `R`,
2775 casting `E` to the corresponding pointer type `&R`, `~R` or `@R` results in a value of the _object type_ `R`.
2776 This result is represented as a pair of pointers:
2777 the vtable pointer for the `T` implementation of `R`, and the pointer value of `E`.
2779 An example of an object type:
2783 fn to_str(&self) -> ~str;
2786 impl Printable for int {
2787 fn to_str(&self) -> ~str { int::to_str(*self) }
2790 fn print(a: @Printable) {
2791 io::println(a.to_str());
2795 print(@10 as @Printable);
2799 In this example, the trait `Printable` occurs as an object type in both the type signature of `print`,
2800 and the cast expression in `main`.
2804 Within the body of an item that has type parameter declarations, the names of its type parameters are types:
2807 fn map<A: Copy, B: Copy>(f: &fn(A) -> B, xs: &[A]) -> ~[B] {
2808 if xs.len() == 0 { return ~[]; }
2809 let first: B = f(xs[0]);
2810 let rest: ~[B] = map(f, xs.slice(1, xs.len()));
2811 return ~[first] + rest;
2815 Here, `first` has type `B`, referring to `map`'s `B` type parameter; and `rest` has
2816 type `~[B]`, a vector type with element type `B`.
2820 The special type `self` has a meaning within methods inside an
2821 impl item. It refers to the type of the implicit `self` argument. For
2826 fn make_string(&self) -> ~str;
2829 impl Printable for ~str {
2830 fn make_string(&self) -> ~str { copy *self }
2834 `self` refers to the value of type `~str` that is the receiver for a
2835 call to the method `make_string`.
2839 Types in Rust are categorized into kinds, based on various properties of the components of the type.
2843 : Types of this kind are deeply immutable;
2844 they contain no mutable memory locations directly or indirectly via pointers.
2846 : Types of this kind can be safely sent between tasks.
2847 This kind includes scalars, owning pointers, owned closures, and
2848 structural types containing only other owned types. All `Owned` types are `Static`.
2850 : Types of this kind do not contain any borrowed pointers;
2851 this can be a useful guarantee for code that breaks borrowing assumptions using [`unsafe` operations](#unsafe-functions).
2853 : This kind includes all types that can be copied. All types with
2854 sendable kind are copyable, as are managed boxes, managed closures,
2855 trait types, and structural types built out of these.
2856 Types with destructors (types that implement `Drop`) can not implement `Copy`.
2858 : This is not strictly a kind, but its presence interacts with kinds: the `Drop`
2859 trait provides a single method `finalize` that takes no parameters, and is run
2860 when values of the type are dropped. Such a method is called a "destructor",
2861 and are always executed in "top-down" order: a value is completely destroyed
2862 before any of the values it owns run their destructors. Only `Owned` types
2863 that do not implement `Copy` can implement `Drop`.
2865 > **Note:** The `finalize` method may be renamed in future versions of Rust.
2868 : Types with destructors, closure environments,
2869 and various other _non-first-class_ types,
2870 are not copyable at all.
2871 Such types can usually only be accessed through pointers,
2872 or in some cases, moved between mutable locations.
2874 Kinds can be supplied as _bounds_ on type parameters, like traits,
2875 in which case the parameter is constrained to types satisfying that kind.
2877 By default, type parameters do not carry any assumed kind-bounds at all.
2879 Any operation that causes a value to be copied requires the type of that value to be of copyable kind,
2880 so the `Copy` bound is frequently required on function type parameters.
2881 For example, this is not a valid program:
2884 fn box<T>(x: T) -> @T { @x }
2887 Putting `x` into a managed box involves copying, and the `T` parameter has the default (non-copyable) kind.
2888 To change that, a bound is declared:
2891 fn box<T: Copy>(x: T) -> @T { @x }
2894 Calling this second version of `box` on a noncopyable type is not
2895 allowed. When instantiating a type parameter, the kind bounds on the
2896 parameter are checked to be the same or narrower than the kind of the
2897 type that it is instantiated with.
2899 Sending operations are not part of the Rust language, but are
2900 implemented in the library. Generic functions that send values bound
2901 the kind of these values to sendable.
2903 # Memory and concurrency models
2905 Rust has a memory model centered around concurrently-executing _tasks_. Thus
2906 its memory model and its concurrency model are best discussed simultaneously,
2907 as parts of each only make sense when considered from the perspective of the
2910 When reading about the memory model, keep in mind that it is partitioned in
2911 order to support tasks; and when reading about tasks, keep in mind that their
2912 isolation and communication mechanisms are only possible due to the ownership
2913 and lifetime semantics of the memory model.
2917 A Rust program's memory consists of a static set of *items*, a set of
2918 [tasks](#tasks) each with its own *stack*, and a *heap*. Immutable portions of
2919 the heap may be shared between tasks, mutable portions may not.
2921 Allocations in the stack consist of *slots*, and allocations in the heap
2925 ### Memory allocation and lifetime
2927 The _items_ of a program are those functions, modules and types
2928 that have their value calculated at compile-time and stored uniquely in the
2929 memory image of the rust process. Items are neither dynamically allocated nor
2932 A task's _stack_ consists of activation frames automatically allocated on
2933 entry to each function as the task executes. A stack allocation is reclaimed
2934 when control leaves the frame containing it.
2936 The _heap_ is a general term that describes two separate sets of boxes:
2937 managed boxes -- which may be subject to garbage collection -- and owned
2938 boxes. The lifetime of an allocation in the heap depends on the lifetime of
2939 the box values pointing to it. Since box values may themselves be passed in
2940 and out of frames, or stored in the heap, heap allocations may outlive the
2941 frame they are allocated within.
2943 ### Memory ownership
2945 A task owns all memory it can *safely* reach through local variables,
2946 as well as managed, owning and borrowed pointers.
2948 When a task sends a value that has the `Owned` trait to another task,
2949 it loses ownership of the value sent and can no longer refer to it.
2950 This is statically guaranteed by the combined use of "move semantics",
2951 and the compiler-checked _meaning_ of the `Owned` trait:
2952 it is only instantiated for (transitively) sendable kinds of data constructor and pointers,
2953 never including managed or borrowed pointers.
2955 When a stack frame is exited, its local allocations are all released, and its
2956 references to boxes (both managed and owned) are dropped.
2958 A managed box may (in the case of a recursive, mutable managed type) be cyclic;
2959 in this case the release of memory inside the managed structure may be deferred
2960 until task-local garbage collection can reclaim it. Code can ensure no such
2961 delayed deallocation occurs by restricting itself to owned boxes and similar
2962 unmanaged kinds of data.
2964 When a task finishes, its stack is necessarily empty and it therefore has no
2965 references to any boxes; the remainder of its heap is immediately freed.
2970 A task's stack contains slots.
2972 A _slot_ is a component of a stack frame, either a function parameter,
2973 a [temporary](#lvalues-rvalues-and-temporaries), or a local variable.
2975 A _local variable_ (or *stack-local* allocation) holds a value directly,
2976 allocated within the stack's memory. The value is a part of the stack frame.
2978 Local variables are immutable unless declared with `let mut`. The
2979 `mut` keyword applies to all local variables declared within that
2980 declaration (so `let mut x, y` declares two mutable variables, `x` and
2983 Function parameters are immutable unless declared with `mut`. The
2984 `mut` keyword applies only to the following parameter (so `|mut x, y|`
2985 and `fn f(mut x: ~int, y: ~int)` declare one mutable variable `x` and
2986 one immutable variable `y`).
2988 Local variables are not initialized when allocated; the entire frame worth of
2989 local variables are allocated at once, on frame-entry, in an uninitialized
2990 state. Subsequent statements within a function may or may not initialize the
2991 local variables. Local variables can be used only after they have been
2992 initialized; this is enforced by the compiler.
2997 A _box_ is a reference to a heap allocation holding another value. There
2998 are two kinds of boxes: *managed boxes* and *owned boxes*.
3000 A _managed box_ type or value is constructed by the prefix *at* sigil `@`.
3002 An _owned box_ type or value is constructed by the prefix *tilde* sigil `~`.
3004 Multiple managed box values can point to the same heap allocation; copying a
3005 managed box value makes a shallow copy of the pointer (optionally incrementing
3006 a reference count, if the managed box is implemented through
3007 reference-counting).
3009 Owned box values exist in 1:1 correspondence with their heap allocation;
3010 copying an owned box value makes a deep copy of the heap allocation and
3011 produces a pointer to the new allocation.
3013 An example of constructing one managed box type and value, and one owned box
3021 Some operations (such as field selection) implicitly dereference boxes. An
3022 example of an _implicit dereference_ operation performed on box values:
3025 struct Foo { y: int }
3026 let x = @Foo{y: 10};
3030 Other operations act on box values as single-word-sized address values. For
3031 these operations, to access the value held in the box requires an explicit
3032 dereference of the box value. Explicitly dereferencing a box is indicated with
3033 the unary *star* operator `*`. Examples of such _explicit dereference_
3036 * copying box values (`x = y`)
3037 * passing box values to functions (`f(x,y)`)
3040 An example of an explicit-dereference operation performed on box values:
3043 fn takes_boxed(b: @int) {
3046 fn takes_unboxed(b: int) {
3058 An executing Rust program consists of a tree of tasks.
3059 A Rust _task_ consists of an entry function, a stack,
3060 a set of outgoing communication channels and incoming communication ports,
3061 and ownership of some portion of the heap of a single operating-system process.
3062 (We expect that many programs will not use channels and ports directly,
3063 but will instead use higher-level abstractions provided in standard libraries,
3066 Multiple Rust tasks may coexist in a single operating-system process.
3067 The runtime scheduler maps tasks to a certain number of operating-system threads.
3068 By default, the scheduler chooses the number of threads based on
3069 the number of concurrent physical CPUs detected at startup.
3070 It's also possible to override this choice at runtime.
3071 When the number of tasks exceeds the number of threads -- which is likely --
3072 the scheduler multiplexes the tasks onto threads.^[
3073 This is an M:N scheduler,
3074 which is known to give suboptimal results for CPU-bound concurrency problems.
3075 In such cases, running with the same number of threads and tasks can yield better results.
3076 Rust has M:N scheduling in order to support very large numbers of tasks
3077 in contexts where threads are too resource-intensive to use in large number.
3078 The cost of threads varies substantially per operating system, and is sometimes quite low,
3079 so this flexibility is not always worth exploiting.]
3082 ### Communication between tasks
3084 Rust tasks are isolated and generally unable to interfere with one another's memory directly,
3085 except through [`unsafe` code](#unsafe-functions).
3086 All contact between tasks is mediated by safe forms of ownership transfer,
3087 and data races on memory are prohibited by the type system.
3089 Inter-task communication and co-ordination facilities are provided in the standard library.
3092 - synchronous and asynchronous communication channels with various communication topologies
3093 - read-only and read-write shared variables with various safe mutual exclusion patterns
3094 - simple locks and semaphores
3096 When such facilities carry values, the values are restricted to the [`Owned` type-kind](#type-kinds).
3097 Restricting communication interfaces to this kind ensures that no borrowed or managed pointers move between tasks.
3098 Thus access to an entire data structure can be mediated through its owning "root" value;
3099 no further locking or copying is required to avoid data races within the substructure of such a value.
3104 The _lifecycle_ of a task consists of a finite set of states and events
3105 that cause transitions between the states. The lifecycle states of a task are:
3112 A task begins its lifecycle -- once it has been spawned -- in the *running*
3113 state. In this state it executes the statements of its entry function, and any
3114 functions called by the entry function.
3116 A task may transition from the *running* state to the *blocked*
3117 state any time it makes a blocking communication call. When the
3118 call can be completed -- when a message arrives at a sender, or a
3119 buffer opens to receive a message -- then the blocked task will
3120 unblock and transition back to *running*.
3122 A task may transition to the *failing* state at any time, due being
3123 killed by some external event or internally, from the evaluation of a
3124 `fail!()` macro. Once *failing*, a task unwinds its stack and
3125 transitions to the *dead* state. Unwinding the stack of a task is done by
3126 the task itself, on its own control stack. If a value with a destructor is
3127 freed during unwinding, the code for the destructor is run, also on the task's
3128 control stack. Running the destructor code causes a temporary transition to a
3129 *running* state, and allows the destructor code to cause any subsequent
3130 state transitions. The original task of unwinding and failing thereby may
3131 suspend temporarily, and may involve (recursive) unwinding of the stack of a
3132 failed destructor. Nonetheless, the outermost unwinding activity will continue
3133 until the stack is unwound and the task transitions to the *dead*
3134 state. There is no way to "recover" from task failure. Once a task has
3135 temporarily suspended its unwinding in the *failing* state, failure
3136 occurring from within this destructor results in *hard* failure. The
3137 unwinding procedure of hard failure frees resources but does not execute
3138 destructors. The original (soft) failure is still resumed at the point where
3139 it was temporarily suspended.
3141 A task in the *dead* state cannot transition to other states; it exists
3142 only to have its termination status inspected by other tasks, and/or to await
3143 reclamation when the last reference to it drops.
3148 The currently scheduled task is given a finite *time slice* in which to
3149 execute, after which it is *descheduled* at a loop-edge or similar
3150 preemption point, and another task within is scheduled, pseudo-randomly.
3152 An executing task can yield control at any time, by making a library call to
3153 `core::task::yield`, which deschedules it immediately. Entering any other
3154 non-executing state (blocked, dead) similarly deschedules the task.
3157 # Runtime services, linkage and debugging
3160 The Rust _runtime_ is a relatively compact collection of C++ and Rust code
3161 that provides fundamental services and datatypes to all Rust tasks at
3162 run-time. It is smaller and simpler than many modern language runtimes. It is
3163 tightly integrated into the language's execution model of memory, tasks,
3164 communication and logging.
3166 > **Note:** The runtime library will merge with the `core` library in future versions of Rust.
3168 ### Memory allocation
3170 The runtime memory-management system is based on a _service-provider interface_,
3171 through which the runtime requests blocks of memory from its environment
3172 and releases them back to its environment when they are no longer needed.
3173 The default implementation of the service-provider interface
3174 consists of the C runtime functions `malloc` and `free`.
3176 The runtime memory-management system, in turn, supplies Rust tasks
3177 with facilities for allocating, extending and releasing stacks,
3178 as well as allocating and freeing heap data.
3182 The runtime provides C and Rust code to assist with various built-in types,
3183 such as vectors, strings, and the low level communication system (ports,
3186 Support for other built-in types such as simple types, tuples, records, and
3187 enums is open-coded by the Rust compiler.
3191 ### Task scheduling and communication
3193 The runtime provides code to manage inter-task communication. This includes
3194 the system of task-lifecycle state transitions depending on the contents of
3195 queues, as well as code to copy values between queues and their recipients and
3196 to serialize values for transmission over operating-system inter-process
3197 communication facilities.
3202 The runtime contains a system for directing [logging
3203 expressions](#log-expressions) to a logging console and/or internal logging
3204 buffers. Logging can be enabled per module.
3206 Logging output is enabled by setting the `RUST_LOG` environment
3207 variable. `RUST_LOG` accepts a logging specification made up of a
3208 comma-separated list of paths, with optional log levels. For each
3209 module containing log expressions, if `RUST_LOG` contains the path to
3210 that module or a parent of that module, then logs of the appropriate
3211 level will be output to the console.
3213 The path to a module consists of the crate name, any parent modules,
3214 then the module itself, all separated by double colons (`::`). The
3215 optional log level can be appended to the module path with an equals
3216 sign (`=`) followed by the log level, from 1 to 4, inclusive. Level 1
3217 is the error level, 2 is warning, 3 info, and 4 debug. Any logs
3218 less than or equal to the specified level will be output. If not
3219 specified then log level 4 is assumed.
3221 As an example, to see all the logs generated by the compiler, you would set
3222 `RUST_LOG` to `rustc`, which is the crate name (as specified in its `link`
3223 [attribute](#attributes)). To narrow down the logs to just crate resolution,
3224 you would set it to `rustc::metadata::creader`. To see just error logging
3227 Note that when compiling either `.rs` or `.rc` files that don't specify a
3228 crate name the crate is given a default name that matches the source file,
3229 with the extension removed. In that case, to turn on logging for a program
3230 compiled from, e.g. `helloworld.rs`, `RUST_LOG` should be set to `helloworld`.
3232 As a convenience, the logging spec can also be set to a special pseudo-crate,
3233 `::help`. In this case, when the application starts, the runtime will
3234 simply output a list of loaded modules containing log expressions, then exit.
3236 The Rust runtime itself generates logging information. The runtime's logs are
3237 generated for a number of artificial modules in the `::rt` pseudo-crate,
3238 and can be enabled just like the logs for any standard module. The full list
3239 of runtime logging modules follows.
3241 * `::rt::mem` Memory management
3242 * `::rt::comm` Messaging and task communication
3243 * `::rt::task` Task management
3244 * `::rt::dom` Task scheduling
3245 * `::rt::trace` Unused
3246 * `::rt::cache` Type descriptor cache
3247 * `::rt::upcall` Compiler-generated runtime calls
3248 * `::rt::timer` The scheduler timer
3249 * `::rt::gc` Garbage collection
3250 * `::rt::stdlib` Functions used directly by the standard library
3251 * `::rt::kern` The runtime kernel
3252 * `::rt::backtrace` Log a backtrace on task failure
3253 * `::rt::callback` Unused
3255 #### Logging Expressions
3257 Rust provides several macros to log information. Here's a simple Rust program
3258 that demonstrates all four of them:
3262 error!("This is an error log")
3263 warn!("This is a warn log")
3264 info!("this is an info log")
3265 debug!("This is a debug log")
3269 These four log levels correspond to levels 1-4, as controlled by `RUST_LOG`:
3272 $ RUST_LOG=rust=3 ./rust
3273 rust: ~"\"This is an error log\""
3274 rust: ~"\"This is a warn log\""
3275 rust: ~"\"this is an info log\""
3278 # Appendix: Rationales and design tradeoffs
3282 # Appendix: Influences and further references
3287 > The essential problem that must be solved in making a fault-tolerant
3288 > software system is therefore that of fault-isolation. Different programmers
3289 > will write different modules, some modules will be correct, others will have
3290 > errors. We do not want the errors in one module to adversely affect the
3291 > behaviour of a module which does not have any errors.
3293 > — Joe Armstrong
3296 > In our approach, all data is private to some process, and processes can
3297 > only communicate through communications channels. *Security*, as used
3298 > in this paper, is the property which guarantees that processes in a system
3299 > cannot affect each other except by explicit communication.
3301 > When security is absent, nothing which can be proven about a single module
3302 > in isolation can be guaranteed to hold when that module is embedded in a
3305 > — Robert Strom and Shaula Yemini
3308 > Concurrent and applicative programming complement each other. The
3309 > ability to send messages on channels provides I/O without side effects,
3310 > while the avoidance of shared data helps keep concurrent processes from
3316 Rust is not a particularly original language. It may however appear unusual
3317 by contemporary standards, as its design elements are drawn from a number of
3318 "historical" languages that have, with a few exceptions, fallen out of
3319 favour. Five prominent lineages contribute the most, though their influences
3320 have come and gone during the course of Rust's development:
3322 * The NIL (1981) and Hermes (1990) family. These languages were developed by
3323 Robert Strom, Shaula Yemini, David Bacon and others in their group at IBM
3324 Watson Research Center (Yorktown Heights, NY, USA).
3326 * The Erlang (1987) language, developed by Joe Armstrong, Robert Virding, Claes
3327 Wikström, Mike Williams and others in their group at the Ericsson Computer
3328 Science Laboratory (Älvsjö, Stockholm, Sweden) .
3330 * The Sather (1990) language, developed by Stephen Omohundro, Chu-Cheow Lim,
3331 Heinz Schmidt and others in their group at The International Computer
3332 Science Institute of the University of California, Berkeley (Berkeley, CA,
3335 * The Newsqueak (1988), Alef (1995), and Limbo (1996) family. These
3336 languages were developed by Rob Pike, Phil Winterbottom, Sean Dorward and
3337 others in their group at Bell Labs Computing Sciences Research Center
3338 (Murray Hill, NJ, USA).
3340 * The Napier (1985) and Napier88 (1988) family. These languages were
3341 developed by Malcolm Atkinson, Ron Morrison and others in their group at
3342 the University of St. Andrews (St. Andrews, Fife, UK).
3344 Additional specific influences can be seen from the following languages:
3346 * The stack-growth implementation of Go.
3347 * The structural algebraic types and compilation manager of SML.
3348 * The attribute and assembly systems of C#.
3349 * The references and deterministic destructor system of C++.
3350 * The memory region systems of the ML Kit and Cyclone.
3351 * The typeclass system of Haskell.
3352 * The lexical identifier rule of Python.
3353 * The block syntax of Ruby.