Mirrors/rust
1
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2026-05-21 17:52:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

Remove *.pot files and ignore them now.

Browse Source 
The .pot files can be generated automatically and the files contain
timestamps in their content. They can cause huge conflicts and take huge
space even if you are not a translator.

This commit is a part of improvement discussed on
https://github.com/mozilla/rust/pull/11383 .

Signed-off-by: OGINO Masanori <masanori.ogino@gmail.com>
This commit is contained in:
OGINO Masanori
2014-01-10 07:05:52 +09:00
parent d4051b6145
commit 20ec0be779
9 changed files with 1 additions and 15263 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -95,3 +95,4 @@ src/etc/dl
build/
i686-pc-mingw32/
src/librustc/lib/llvmdeps.rs
*.pot
doc/po/rust.md.pot
-6490
View File
@@ -1,6490 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-08-12 02:06+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/rust.md:2
msgid "% Rust Reference Manual"
msgstr ""
#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
msgid "# Introduction"
msgstr ""
#. type: Plain text
#: doc/rust.md:7
msgid ""
"This document is the reference manual for the Rust programming language. It "
"provides three kinds of material:"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:15
msgid ""
"Chapters that formally define the language grammar and, for each construct, "
"informally describe its semantics and give examples of its use."
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:15
msgid ""
"Chapters that informally describe the memory model, concurrency model, "
"runtime services, linkage model and debugging facilities."
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:15
msgid ""
"Appendix chapters providing rationale and references to languages that "
"influenced the design."
msgstr ""
#. type: Plain text
#: doc/rust.md:19
msgid ""
"This document does not serve as a tutorial introduction to the language. "
"Background familiarity with the language is assumed. A separate [tutorial] "
"document is available to help acquire such background familiarity."
msgstr ""
#. type: Plain text
#: doc/rust.md:24
msgid ""
"This document also does not serve as a reference to the [standard] or "
"[extra] libraries included in the language distribution. Those libraries are "
"documented separately by extracting documentation attributes from their "
"source code."
msgstr ""
#. type: Plain text
#: doc/rust.md:28
msgid ""
"[tutorial]: tutorial.html [standard]: std/index.html [extra]: extra/index."
"html"
msgstr ""
#. type: Plain text
#: doc/rust.md:30 doc/rustpkg.md:8
msgid "## Disclaimer"
msgstr ""
#. type: Plain text
#: doc/rust.md:34
msgid ""
"Rust is a work in progress. The language continues to evolve as the design "
"shifts and is fleshed out in working code. Certain parts work, certain parts "
"do not, certain parts will be removed or changed."
msgstr ""
#. type: Plain text
#: doc/rust.md:39
msgid ""
"This manual is a snapshot written in the present tense. All features "
"described exist in working code unless otherwise noted, but some are quite "
"primitive or remain to be further modified by planned work. Some may be "
"temporary. It is a *draft*, and we ask that you not take anything you read "
"here as final."
msgstr ""
#. type: Plain text
#: doc/rust.md:43
msgid ""
"If you have suggestions to make, please try to focus them on *reductions* to "
"the language: possible features that can be combined or omitted. We aim to "
"keep the size and complexity of the language under control."
msgstr ""
#. type: Plain text
#: doc/rust.md:52
msgid ""
"> **Note:** The grammar for Rust given in this document is rough and > very "
"incomplete; only a modest number of sections have accompanying grammar > "
"rules. Formalizing the grammar accepted by the Rust parser is ongoing work, "
"> but future versions of this document will contain a complete > grammar. "
"Moreover, we hope that this grammar will be extracted and verified > as "
"LL(1) by an automated grammar-analysis tool, and further tested against the "
"> Rust sources. Preliminary versions of this automation exist, but are not "
"yet > complete."
msgstr ""
#. type: Plain text
#: doc/rust.md:54
msgid "# Notation"
msgstr ""
#. type: Plain text
#: doc/rust.md:62
msgid ""
"Rust's grammar is defined over Unicode codepoints, each conventionally "
"denoted `U+XXXX`, for 4 or more hexadecimal digits `X`. _Most_ of Rust's "
"grammar is confined to the ASCII range of Unicode, and is described in this "
"document by a dialect of Extended Backus-Naur Form (EBNF), specifically a "
"dialect of EBNF supported by common automated LL(k) parsing tools such as "
"`llgen`, rather than the dialect given in ISO 14977. The dialect can be "
"defined self-referentially as follows:"
msgstr ""
#. type: Plain text
#: doc/rust.md:64
msgid "~~~~~~~~ {.ebnf .notation}"
msgstr ""
#. type: Plain text
#: doc/rust.md:72
#, no-wrap
msgid ""
"grammar : rule + ;\n"
"rule : nonterminal ':' productionrule ';' ;\n"
"productionrule : production [ '|' production ] * ;\n"
"production : term * ;\n"
"term : element repeats ;\n"
"element : LITERAL | IDENTIFIER | '[' productionrule ']' ;\n"
"repeats : [ '*' | '+' ] NUMBER ? | NUMBER ? | '?' ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:74 doc/rust.md:416 doc/rust.md:486
msgid "~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:76
msgid "Where:"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:89
msgid "Whitespace in the grammar is ignored."
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:89
msgid "Square brackets are used to group rules."
msgstr ""
#. type: Plain text
#: doc/rust.md:89
#, no-wrap
msgid ""
" - `LITERAL` is a single printable ASCII character, or an escaped hexadecimal\n"
" ASCII code of the form `\\xQQ`, in single quotes, denoting the corresponding\n"
" Unicode codepoint `U+00QQ`.\n"
" - `IDENTIFIER` is a nonempty string of ASCII letters and underscores.\n"
" - The `repeat` forms apply to the adjacent `element`, and are as follows:\n"
" - `?` means zero or one repetition\n"
" - `*` means zero or more repetitions\n"
" - `+` means one or more repetitions\n"
" - NUMBER trailing a repeat symbol gives a maximum repetition count\n"
" - NUMBER on its own gives an exact repetition count\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:91
msgid "This EBNF dialect should hopefully be familiar to many readers."
msgstr ""
#. type: Plain text
#: doc/rust.md:93
msgid "## Unicode productions"
msgstr ""
#. type: Plain text
#: doc/rust.md:98
msgid ""
"A few productions in Rust's grammar permit Unicode codepoints outside the "
"ASCII range. We define these productions in terms of character properties "
"specified in the Unicode standard, rather than in terms of ASCII-range "
"codepoints. The section [Special Unicode Productions](#special-unicode-"
"productions) lists these productions."
msgstr ""
#. type: Plain text
#: doc/rust.md:100
msgid "## String table productions"
msgstr ""
#. type: Plain text
#: doc/rust.md:109
msgid ""
"Some rules in the grammar -- notably [unary operators](#unary-operator-"
"expressions), [binary operators](#binary-operator-expressions), and "
"[keywords](#keywords) -- are given in a simplified form: as a listing of a "
"table of unquoted, printable whitespace-separated strings. These cases form "
"a subset of the rules regarding the [token](#tokens) rule, and are assumed "
"to be the result of a lexical-analysis phase feeding the parser, driven by a "
"DFA, operating over the disjunction of all such string table entries."
msgstr ""
#. type: Plain text
#: doc/rust.md:113
msgid ""
"When such a string enclosed in double-quotes (`\"`) occurs inside the "
"grammar, it is an implicit reference to a single member of such a string "
"table production. See [tokens](#tokens) for more information."
msgstr ""
#. type: Plain text
#: doc/rust.md:116
msgid "# Lexical structure"
msgstr ""
#. type: Plain text
#: doc/rust.md:118
msgid "## Input format"
msgstr ""
#. type: Plain text
#: doc/rust.md:124
msgid ""
"Rust input is interpreted as a sequence of Unicode codepoints encoded in "
"UTF-8, normalized to Unicode normalization form NFKC. Most Rust grammar "
"rules are defined in terms of printable ASCII-range codepoints, but a small "
"number are defined in terms of Unicode properties or explicit codepoint "
"lists. ^[Substitute definitions for the special Unicode productions are "
"provided to the grammar verifier, restricted to ASCII range, when verifying "
"the grammar in this document.]"
msgstr ""
#. type: Plain text
#: doc/rust.md:126
msgid "## Special Unicode Productions"
msgstr ""
#. type: Plain text
#: doc/rust.md:129
msgid ""
"The following productions in the Rust grammar are defined in terms of "
"Unicode properties: `ident`, `non_null`, `non_star`, `non_eol`, "
"`non_slash_or_star`, `non_single_quote` and `non_double_quote`."
msgstr ""
#. type: Plain text
#: doc/rust.md:131
msgid "### Identifiers"
msgstr ""
#. type: Plain text
#: doc/rust.md:133
msgid ""
"The `ident` production is any nonempty Unicode string of the following form:"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:136
msgid "The first character has property `XID_start`"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:136
msgid "The remaining characters have property `XID_continue`"
msgstr ""
#. type: Plain text
#: doc/rust.md:138
msgid "that does _not_ occur in the set of [keywords](#keywords)."
msgstr ""
#. type: Plain text
#: doc/rust.md:142
msgid ""
"Note: `XID_start` and `XID_continue` as character properties cover the "
"character ranges used to form the more familiar C and Java language-family "
"identifiers."
msgstr ""
#. type: Plain text
#: doc/rust.md:144
msgid "### Delimiter-restricted productions"
msgstr ""
#. type: Plain text
#: doc/rust.md:146
msgid ""
"Some productions are defined by exclusion of particular Unicode characters:"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:153
msgid "`non_null` is any single Unicode character aside from `U+0000` (null)"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:153
msgid "`non_eol` is `non_null` restricted to exclude `U+000A` (`'\\n'`)"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:153
msgid "`non_star` is `non_null` restricted to exclude `U+002A` (`*`)"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:153
msgid ""
"`non_slash_or_star` is `non_null` restricted to exclude `U+002F` (`/`) and `U"
"+002A` (`*`)"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:153
msgid "`non_single_quote` is `non_null` restricted to exclude `U+0027` (`'`)"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:153
msgid "`non_double_quote` is `non_null` restricted to exclude `U+0022` (`\"`)"
msgstr ""
#. type: Plain text
#: doc/rust.md:155
msgid "## Comments"
msgstr ""
#. type: Plain text
#: doc/rust.md:162
msgid ""
"~~~~~~~~ {.ebnf .gram} comment : block_comment | line_comment ; "
"block_comment : \"/*\" block_comment_body * '*' + '/' ; block_comment_body : "
"non_star * | '*' + non_slash_or_star ; line_comment : \"//\" non_eol * ; "
"~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:165
msgid ""
"Comments in Rust code follow the general C++ style of line and block-comment "
"forms, with no nesting of block-comment delimiters."
msgstr ""
#. type: Plain text
#: doc/rust.md:170
msgid ""
"Line comments beginning with _three_ slashes (`///`), and block comments "
"beginning with a repeated asterisk in the block-open sequence (`/**`), are "
"interpreted as a special syntax for `doc` [attributes](#attributes). That "
"is, they are equivalent to writing `#[doc \"...\"]` around the comment's "
"text."
msgstr ""
#. type: Plain text
#: doc/rust.md:172
msgid "Non-doc comments are interpreted as a form of whitespace."
msgstr ""
#. type: Plain text
#: doc/rust.md:174
msgid "## Whitespace"
msgstr ""
#. type: Plain text
#: doc/rust.md:179
msgid ""
"~~~~~~~~ {.ebnf .gram} whitespace_char : '\\x20' | '\\x09' | '\\x0a' | "
"'\\x0d' ; whitespace : [ whitespace_char | comment ] + ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:183
msgid ""
"The `whitespace_char` production is any nonempty Unicode string consisting "
"of any of the following Unicode characters: `U+0020` (space, `' '`), `U"
"+0009` (tab, `'\\t'`), `U+000A` (LF, `'\\n'`), `U+000D` (CR, `'\\r'`)."
msgstr ""
#. type: Plain text
#: doc/rust.md:186
msgid ""
"Rust is a \"free-form\" language, meaning that all forms of whitespace serve "
"only to separate _tokens_ in the grammar, and have no semantic significance."
msgstr ""
#. type: Plain text
#: doc/rust.md:189
msgid ""
"A Rust program has identical meaning if each whitespace element is replaced "
"with any other legal whitespace element, such as a single space character."
msgstr ""
#. type: Plain text
#: doc/rust.md:191
msgid "## Tokens"
msgstr ""
#. type: Plain text
#: doc/rust.md:196
msgid ""
"~~~~~~~~ {.ebnf .gram} simple_token : keyword | unop | binop ; token : "
"simple_token | ident | literal | symbol | whitespace token ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:201
msgid ""
"Tokens are primitive productions in the grammar defined by regular (non-"
"recursive) languages. \"Simple\" tokens are given in [string table "
"production](#string-table-productions) form, and occur in the rest of the "
"grammar as double-quoted strings. Other tokens have exact rules given."
msgstr ""
#. type: Plain text
#: doc/rust.md:203
msgid "### Keywords"
msgstr ""
#. type: Plain text
#: doc/rust.md:205
msgid "The keywords are the following strings:"
msgstr ""
#. type: Plain text
#: doc/rust.md:222
msgid ""
"~~~~~~~~ {.keyword} as break do else enum extern false fn for if impl let "
"loop match mod mut priv pub ref return self static struct super true trait "
"type unsafe use while ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:225
msgid ""
"Each of these keywords has special meaning in its grammar, and all of them "
"are excluded from the `ident` rule."
msgstr ""
#. type: Plain text
#: doc/rust.md:227
msgid "### Literals"
msgstr ""
#. type: Plain text
#: doc/rust.md:233
msgid ""
"A literal is an expression consisting of a single token, rather than a "
"sequence of tokens, that immediately and directly denotes the value it "
"evaluates to, rather than referring to it by name or some other evaluation "
"rule. A literal is a form of constant expression, so is evaluated "
"(primarily) at compile time."
msgstr ""
#. type: Plain text
#: doc/rust.md:237
msgid ""
"~~~~~~~~ {.ebnf .gram} literal : string_lit | char_lit | num_lit ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:239
msgid "#### Character and string literals"
msgstr ""
#. type: Plain text
#: doc/rust.md:243
msgid ""
"~~~~~~~~ {.ebnf .gram} char_lit : '\\x27' char_body '\\x27' ; string_lit : "
"'\"' string_body * '\"' ;"
msgstr ""
#. type: Plain text
#: doc/rust.md:246
#, no-wrap
msgid ""
"char_body : non_single_quote\n"
" | '\\x5c' [ '\\x27' | common_escape ] ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:249
#, no-wrap
msgid ""
"string_body : non_double_quote\n"
" | '\\x5c' [ '\\x22' | common_escape ] ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:255
#, no-wrap
msgid ""
"common_escape : '\\x5c'\n"
" | 'n' | 'r' | 't'\n"
" | 'x' hex_digit 2\n"
" | 'u' hex_digit 4\n"
" | 'U' hex_digit 8 ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:263
#, no-wrap
msgid ""
"hex_digit : 'a' | 'b' | 'c' | 'd' | 'e' | 'f'\n"
" | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'\n"
" | dec_digit ;\n"
"dec_digit : '0' | nonzero_dec ;\n"
"nonzero_dec: '1' | '2' | '3' | '4'\n"
" | '5' | '6' | '7' | '8' | '9' ;\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:267
msgid ""
"A _character literal_ is a single Unicode character enclosed within two `U"
"+0027` (single-quote) characters, with the exception of `U+0027` itself, "
"which must be _escaped_ by a preceding U+005C character (`\\`)."
msgstr ""
#. type: Plain text
#: doc/rust.md:271
msgid ""
"A _string literal_ is a sequence of any Unicode characters enclosed within "
"two `U+0022` (double-quote) characters, with the exception of `U+0022` "
"itself, which must be _escaped_ by a preceding `U+005C` character (`\\`)."
msgstr ""
#. type: Plain text
#: doc/rust.md:275
msgid ""
"Some additional _escapes_ are available in either character or string "
"literals. An escape starts with a `U+005C` (`\\`) and continues with one of "
"the following forms:"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:290
msgid ""
"An _8-bit codepoint escape_ escape starts with `U+0078` (`x`) and is "
"followed by exactly two _hex digits_. It denotes the Unicode codepoint equal "
"to the provided hex value."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:290
msgid ""
"A _16-bit codepoint escape_ starts with `U+0075` (`u`) and is followed by "
"exactly four _hex digits_. It denotes the Unicode codepoint equal to the "
"provided hex value."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:290
msgid ""
"A _32-bit codepoint escape_ starts with `U+0055` (`U`) and is followed by "
"exactly eight _hex digits_. It denotes the Unicode codepoint equal to the "
"provided hex value."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:290
msgid ""
"A _whitespace escape_ is one of the characters `U+006E` (`n`), `U+0072` "
"(`r`), or `U+0074` (`t`), denoting the unicode values `U+000A` (LF), `U"
"+000D` (CR) or `U+0009` (HT) respectively."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:290
msgid ""
"The _backslash escape_ is the character U+005C (`\\`) which must be escaped "
"in order to denote *itself*."
msgstr ""
#. type: Plain text
#: doc/rust.md:292
msgid "#### Number literals"
msgstr ""
#. type: Plain text
#: doc/rust.md:294 doc/rust.md:406 doc/rust.md:473
msgid "~~~~~~~~ {.ebnf .gram}"
msgstr ""
#. type: Plain text
#: doc/rust.md:299
#, no-wrap
msgid ""
"num_lit : nonzero_dec [ dec_digit | '_' ] * num_suffix ?\n"
" | '0' [ [ dec_digit | '_' ] + num_suffix ?\n"
" | 'b' [ '1' | '0' | '_' ] + int_suffix ?\n"
" | 'x' [ hex_digit | '_' ] + int_suffix ? ] ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:301
msgid "num_suffix : int_suffix | float_suffix ;"
msgstr ""
#. type: Plain text
#: doc/rust.md:305
#, no-wrap
msgid ""
"int_suffix : 'u' int_suffix_size ?\n"
" | 'i' int_suffix_size ? ;\n"
"int_suffix_size : [ '8' | '1' '6' | '3' '2' | '6' '4' ] ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:311
msgid ""
"float_suffix : [ exponent | '.' dec_lit exponent ? ] ? float_suffix_ty ? ; "
"float_suffix_ty : 'f' [ '3' '2' | '6' '4' ] ; exponent : ['E' | 'e'] ['-' | "
"'+' ] ? dec_lit ; dec_lit : [ dec_digit | '_' ] + ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:315
msgid ""
"A _number literal_ is either an _integer literal_ or a _floating-point "
"literal_. The grammar for recognizing the two kinds of literals is mixed, as "
"they are differentiated by suffixes."
msgstr ""
#. type: Plain text
#: doc/rust.md:317
msgid "##### Integer literals"
msgstr ""
#. type: Plain text
#: doc/rust.md:319
msgid "An _integer literal_ has one of four forms:"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:326
msgid ""
"A _decimal literal_ starts with a *decimal digit* and continues with any "
"mixture of *decimal digits* and _underscores_."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:326
msgid ""
"A _hex literal_ starts with the character sequence `U+0030` `U+0078` (`0x`) "
"and continues as any mixture hex digits and underscores."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:326
msgid ""
"An _octal literal_ starts with the character sequence `U+0030` `U+006F` (`0o`) "
"and continues as any mixture octal digits and underscores."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:326
msgid ""
"A _binary literal_ starts with the character sequence `U+0030` `U+0062` "
"(`0b`) and continues as any mixture binary digits and underscores."
msgstr ""
#. type: Plain text
#: doc/rust.md:330
msgid ""
"An integer literal may be followed (immediately, without any spaces) by an "
"_integer suffix_, which changes the type of the literal. There are two kinds "
"of integer literal suffix:"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:336
msgid ""
"The `i` and `u` suffixes give the literal type `int` or `uint`, respectively."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:336
msgid ""
"Each of the signed and unsigned machine types `u8`, `i8`, `u16`, `i16`, "
"`u32`, `i32`, `u64` and `i64` give the literal the corresponding machine "
"type."
msgstr ""
#. type: Plain text
#: doc/rust.md:343
msgid ""
"The type of an _unsuffixed_ integer literal is determined by type "
"inference. If a integer type can be _uniquely_ determined from the "
"surrounding program context, the unsuffixed integer literal has that type. "
"If the program context underconstrains the type, the unsuffixed integer "
"literal's type is `int`; if the program context overconstrains the type, it "
"is considered a static type error."
msgstr ""
#. type: Plain text
#: doc/rust.md:345
msgid "Examples of integer literals of various forms:"
msgstr ""
#. type: Plain text
#: doc/rust.md:350
#, no-wrap
msgid ""
"~~~~\n"
"123; 0xff00; // type determined by program context\n"
" // defaults to int in absence of type\n"
" // information\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:356
#, no-wrap
msgid ""
"123u; // type uint\n"
"123_u; // type uint\n"
"0xff_u8; // type u8\n"
"0o70_i16; // type i16\n"
"0b1111_1111_1001_0000_i32; // type i32\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:358
msgid "##### Floating-point literals"
msgstr ""
#. type: Plain text
#: doc/rust.md:360
msgid "A _floating-point literal_ has one of two forms:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:365
msgid ""
"Two _decimal literals_ separated by a period character `U+002E` (`.`), with "
"an optional _exponent_ trailing after the second decimal literal."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:365
msgid "A single _decimal literal_ followed by an _exponent_."
msgstr ""
#. type: Plain text
#: doc/rust.md:372
msgid ""
"By default, a floating-point literal is of type `float`. A floating-point "
"literal may be followed (immediately, without any spaces) by a _floating-"
"point suffix_, which changes the type of the literal. There are three "
"floating-point suffixes: `f` (for the base `float` type), `f32`, and `f64` "
"(the 32-bit and 64-bit floating point types)."
msgstr ""
#. type: Plain text
#: doc/rust.md:374
msgid "Examples of floating-point literals of various forms:"
msgstr ""
#. type: Plain text
#: doc/rust.md:382
#, no-wrap
msgid ""
"~~~~\n"
"123.0; // type float\n"
"0.1; // type float\n"
"3f; // type float\n"
"0.1f32; // type f32\n"
"12E+99_f64; // type f64\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:384
msgid "##### Unit and boolean literals"
msgstr ""
#. type: Plain text
#: doc/rust.md:387
msgid ""
"The _unit value_, the only value of the type that has the same name, is "
"written as `()`. The two values of the boolean type are written `true` and "
"`false`."
msgstr ""
#. type: Plain text
#: doc/rust.md:389
msgid "### Symbols"
msgstr ""
#. type: Plain text
#: doc/rust.md:395
#, no-wrap
msgid ""
"~~~~~~~~ {.ebnf .gram}\n"
"symbol : \"::\" \"->\"\n"
" | '#' | '[' | ']' | '(' | ')' | '{' | '}'\n"
" | ',' | ';' ;\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:401
msgid ""
"Symbols are a general class of printable [token](#tokens) that play "
"structural roles in a variety of grammar productions. They are catalogued "
"here for completeness as the set of remaining miscellaneous printable tokens "
"that do not otherwise appear as [unary operators](#unary-operator-"
"expressions), [binary operators](#binary-operator-expressions), or [keywords]"
"(#keywords)."
msgstr ""
#. type: Plain text
#: doc/rust.md:404
msgid "## Paths"
msgstr ""
#. type: Plain text
#: doc/rust.md:410
#, no-wrap
msgid ""
"expr_path : ident [ \"::\" expr_path_tail ] + ;\n"
"expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'\n"
" | expr_path ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:414
#, no-wrap
msgid ""
"type_path : ident [ type_path_tail ] + ;\n"
"type_path_tail : '<' type_expr [ ',' type_expr ] + '>'\n"
" | \"::\" type_path ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:421
msgid ""
"A _path_ is a sequence of one or more path components _logically_ separated "
"by a namespace qualifier (`::`). If a path consists of only one component, "
"it may refer to either an [item](#items) or a [slot](#memory-slots) in a "
"local control scope. If a path has multiple components, it refers to an item."
msgstr ""
#. type: Plain text
#: doc/rust.md:425
msgid ""
"Every item has a _canonical path_ within its crate, but the path naming an "
"item is only meaningful within a given crate. There is no global namespace "
"across crates; an item's canonical path merely identifies it within the "
"crate."
msgstr ""
#. type: Plain text
#: doc/rust.md:427
msgid "Two examples of simple paths consisting of only identifier components:"
msgstr ""
#. type: Plain text
#: doc/rust.md:432
msgid "~~~~{.ignore} x; x::y::z; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:439
msgid ""
"Path components are usually [identifiers](#identifiers), but the trailing "
"component of a path may be an angle-bracket-enclosed list of type arguments. "
"In [expression](#expressions) context, the type argument list is given after "
"a final (`::`) namespace qualifier in order to disambiguate it from a "
"relational expression involving the less-than symbol (`<`). In type "
"expression context, the final namespace qualifier is omitted."
msgstr ""
#. type: Plain text
#: doc/rust.md:441
msgid "Two examples of paths with type arguments:"
msgstr ""
#. type: Plain text
#: doc/rust.md:450
#, no-wrap
msgid ""
"~~~~\n"
"# use std::hashmap::HashMap;\n"
"# fn f() {\n"
"# fn id<T>(t: T) -> T { t }\n"
"type t = HashMap<int,~str>; // Type arguments used in a type expression\n"
"let x = id::<int>(10); // Type arguments used in a call expression\n"
"# }\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:452
msgid "# Syntax extensions"
msgstr ""
#. type: Plain text
#: doc/rust.md:457
msgid ""
"A number of minor features of Rust are not central enough to have their own "
"syntax, and yet are not implementable as functions. Instead, they are given "
"names, and invoked through a consistent syntax: `name!(...)`. Examples "
"include:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid "`fmt!` : format data into a string"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid "`env!` : look up an environment variable's value at compile time"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid "`stringify!` : pretty-print the Rust expression given as an argument"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid "`proto!` : define a protocol for inter-task communication"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid "`include!` : include the Rust expression in the given file"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid "`include_str!` : include the contents of the given file as a string"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid ""
"`include_bin!` : include the contents of the given file as a binary blob"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:466
msgid "`error!`, `warn!`, `info!`, `debug!` : provide diagnostic information."
msgstr ""
#. type: Plain text
#: doc/rust.md:469
msgid ""
"All of the above extensions, with the exception of `proto!`, are expressions "
"with values. `proto!` is an item, defining a new name."
msgstr ""
#. type: Plain text
#: doc/rust.md:471
msgid "## Macros"
msgstr ""
#. type: Plain text
#: doc/rust.md:484
#, no-wrap
msgid ""
"expr_macro_rules : \"macro_rules\" '!' ident '(' macro_rule * ')'\n"
"macro_rule : '(' matcher * ')' \"=>\" '(' transcriber * ')' ';'\n"
"matcher : '(' matcher * ')' | '[' matcher * ']'\n"
" | '{' matcher * '}' | '$' ident ':' ident\n"
" | '$' '(' matcher * ')' sep_token? [ '*' | '+' ]\n"
" | non_special_token\n"
"transcriber : '(' transcriber * ')' | '[' transcriber * ']'\n"
" | '{' transcriber * '}' | '$' ident\n"
" | '$' '(' transcriber * ')' sep_token? [ '*' | '+' ]\n"
" | non_special_token\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:490
msgid ""
"User-defined syntax extensions are called \"macros\", and the `macro_rules` "
"syntax extension defines them. Currently, user-defined macros can expand to "
"expressions, statements, or items."
msgstr ""
#. type: Plain text
#: doc/rust.md:493
msgid ""
"(A `sep_token` is any token other than `*` and `+`. A `non_special_token` "
"is any token other than a delimiter or `$`.)"
msgstr ""
#. type: Plain text
#: doc/rust.md:499
msgid ""
"The macro expander looks up macro invocations by name, and tries each macro "
"rule in turn. It transcribes the first successful match. Matching and "
"transcription are closely related to each other, and we will describe them "
"together."
msgstr ""
#. type: Plain text
#: doc/rust.md:501
msgid "### Macro By Example"
msgstr ""
#. type: Plain text
#: doc/rust.md:504
msgid ""
"The macro expander matches and transcribes every token that does not begin "
"with a `$` literally, including delimiters. For parsing reasons, delimiters "
"must be balanced, but they are otherwise not special."
msgstr ""
#. type: Plain text
#: doc/rust.md:510
msgid ""
"In the matcher, `$` _name_ `:` _designator_ matches the nonterminal in the "
"Rust syntax named by _designator_. Valid designators are `item`, `block`, "
"`stmt`, `pat`, `expr`, `ty` (type), `ident`, `path`, `matchers` (lhs of the "
"`=>` in macro rules), `tt` (rhs of the `=>` in macro rules). In the "
"transcriber, the designator is already known, and so only the name of a "
"matched nonterminal comes after the dollar sign."
msgstr ""
#. type: Plain text
#: doc/rust.md:519
msgid ""
"In both the matcher and transcriber, the Kleene star-like operator indicates "
"repetition. The Kleene star operator consists of `$` and parens, optionally "
"followed by a separator token, followed by `*` or `+`. `*` means zero or "
"more repetitions, `+` means at least one repetition. The parens are not "
"matched or transcribed. On the matcher side, a name is bound to _all_ of "
"the names it matches, in a structure that mimics the structure of the "
"repetition encountered on a successful match. The job of the transcriber is "
"to sort that structure out."
msgstr ""
#. type: Plain text
#: doc/rust.md:525
msgid ""
"The rules for transcription of these repetitions are called \"Macro By "
"Example\". Essentially, one \"layer\" of repetition is discharged at a "
"time, and all of them must be discharged by the time a name is transcribed. "
"Therefore, `( $( $i:ident ),* ) => ( $i )` is an invalid macro, but `( $( $i:"
"ident ),* ) => ( $( $i:ident ),* )` is acceptable (if trivial)."
msgstr ""
#. type: Plain text
#: doc/rust.md:533
msgid ""
"When Macro By Example encounters a repetition, it examines all of the `$` "
"_name_ s that occur in its body. At the \"current layer\", they all must "
"repeat the same number of times, so ` ( $( $i:ident ),* ; $( $j:ident ),* ) "
"=> ( $( ($i,$j) ),* )` is valid if given the argument `(a,b,c ; d,e,f)`, but "
"not `(a,b,c ; d,e)`. The repetition walks through the choices at that layer "
"in lockstep, so the former input transcribes to `( (a,d), (b,e), (c,f) )`."
msgstr ""
#. type: Plain text
#: doc/rust.md:535
msgid "Nested repetitions are allowed."
msgstr ""
#. type: Plain text
#: doc/rust.md:537
msgid "### Parsing limitations"
msgstr ""
#. type: Plain text
#: doc/rust.md:540
msgid ""
"The parser used by the macro system is reasonably powerful, but the parsing "
"of Rust syntax is restricted in two ways:"
msgstr ""
#. type: Plain text
#: doc/rust.md:546
#, no-wrap
msgid ""
"1. The parser will always parse as much as possible. If it attempts to match\n"
"`$i:expr [ , ]` against `8 [ , ]`, it will attempt to parse `i` as an array\n"
"index operation and fail. Adding a separator can solve this problem.\n"
"2. The parser must have eliminated all ambiguity by the time it reaches a `$` _name_ `:` _designator_.\n"
"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.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:549
msgid "## Syntax extensions useful for the macro author"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:554
msgid "`log_syntax!` : print out the arguments at compile time"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:554
msgid ""
"`trace_macros!` : supply `true` or `false` to enable or disable macro "
"expansion logging"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:554
msgid "`stringify!` : turn the identifier argument into a string literal"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:554
msgid ""
"`concat_idents!` : create a new identifier by concatenating the arguments"
msgstr ""
#. type: Plain text
#: doc/rust.md:556
msgid "# Crates and source files"
msgstr ""
#. type: Plain text
#: doc/rust.md:563
msgid ""
"Rust is a *compiled* language. Its semantics obey a *phase distinction* "
"between compile-time and run-time. Those semantic rules that have a *static "
"interpretation* govern the success or failure of compilation. We refer to "
"these rules as \"static semantics\". Semantic rules called \"dynamic "
"semantics\" govern the behavior of programs at run-time. 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."
msgstr ""
#. type: Plain text
#: doc/rust.md:569
msgid ""
"The compilation model centres on artifacts called _crates_. 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 analogous to an *assembly* in the ECMA-335 CLI model, "
"a *library* in the SML/NJ Compilation Manager, a *unit* in the Owens and "
"Flatt module system, or a *configuration* in Mesa.]"
msgstr ""
#. type: Plain text
#: doc/rust.md:573
msgid ""
"A _crate_ is a unit of compilation and linking, as well as versioning, "
"distribution and runtime loading. A crate contains a _tree_ of nested "
"[module](#modules) scopes. 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."
msgstr ""
#. type: Plain text
#: doc/rust.md:577
msgid ""
"The Rust compiler is always invoked with a single source file as input, and "
"always produces a single output crate. The processing of that source file "
"may result in other source files being loaded as modules. Source files have "
"the extension `.rs`."
msgstr ""
#. type: Plain text
#: doc/rust.md:582
msgid ""
"A Rust source file describes a module, the name and location of which -- in "
"the module tree of the current crate -- are defined from outside the source "
"file: either by an explicit `mod_item` in a referencing source file, or by "
"the name of the crate itself."
msgstr ""
#. type: Plain text
#: doc/rust.md:587
msgid ""
"Each source file contains a sequence of zero or more `item` definitions, and "
"may optionally begin with any number of `attributes` that apply to the "
"containing module. Atributes on the anonymous crate module define important "
"metadata that influences the behavior of the compiler."
msgstr ""
#. type: Plain text
#: doc/rust.md:593
#, no-wrap
msgid ""
"~~~~~~~~\n"
"// Linkage attributes\n"
"#[ link(name = \"projx\",\n"
" vers = \"2.5\",\n"
" uuid = \"9cccc5d5-aceb-4af5-8285-811211826b82\") ];\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:598
msgid ""
"// Additional metadata attributes #[ desc = \"Project X\" ]; #[ license = "
"\"BSD\" ]; #[ author = \"Jane Doe\" ];"
msgstr ""
#. type: Plain text
#: doc/rust.md:601
msgid "// Specify the output type #[ crate_type = \"lib\" ];"
msgstr ""
#. type: Plain text
#: doc/rust.md:605
msgid "// Turn on a warning #[ warn(non_camel_case_types) ]; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:608
msgid ""
"A crate that contains a `main` function can be compiled to an executable. "
"If a `main` function is present, its return type must be [`unit`](#primitive-"
"types) and it must take no arguments."
msgstr ""
#. type: Plain text
#: doc/rust.md:611
msgid "# Items and attributes"
msgstr ""
#. type: Plain text
#: doc/rust.md:614
msgid ""
"Crates contain [items](#items), each of which may have some number of "
"[attributes](#attributes) attached to it."
msgstr ""
#. type: Plain text
#: doc/rust.md:616
msgid "## Items"
msgstr ""
#. type: Plain text
#: doc/rust.md:621
#, no-wrap
msgid ""
"~~~~~~~~ {.ebnf .gram}\n"
"item : mod_item | fn_item | type_item | struct_item | enum_item\n"
" | static_item | trait_item | impl_item | extern_block ;\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:627
msgid ""
"An _item_ is a component of a crate; some module items can be defined in "
"crate files, but most are defined in source files. Items are organized "
"within a crate by a nested set of [modules](#modules). Every crate has a "
"single \"outermost\" anonymous module; all further items within the crate "
"have [paths](#paths) within the module tree of the crate."
msgstr ""
#. type: Plain text
#: doc/rust.md:630
msgid ""
"Items are entirely determined at compile-time, generally remain fixed during "
"execution, and may reside in read-only memory."
msgstr ""
#. type: Plain text
#: doc/rust.md:632
msgid "There are several kinds of item:"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[modules](#modules)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[functions](#functions)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[type definitions](#type-definitions)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[structures](#structures)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[enumerations](#enumerations)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[static items](#static-items)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[traits](#traits)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:641
msgid "[implementations](#implementations)"
msgstr ""
#. type: Plain text
#: doc/rust.md:651
msgid ""
"Some items form an implicit scope for the declaration of sub-items. In other "
"words, within a function or module, declarations of items can (in many "
"cases) be mixed with the statements, control blocks, and similar artifacts "
"that otherwise compose the item body. The meaning of these scoped items is "
"the same as if the item was declared outside the scope -- it is still a "
"static item -- except that the item's *path name* within the module "
"namespace is qualified by the name of the enclosing item, or is private to "
"the enclosing item (in the case of functions). The grammar specifies the "
"exact locations in which sub-item declarations may appear."
msgstr ""
#. type: Plain text
#: doc/rust.md:653
msgid "### Type Parameters"
msgstr ""
#. type: Plain text
#: doc/rust.md:662
msgid ""
"All items except modules may be *parameterized* by type. Type parameters are "
"given as a comma-separated list of identifiers enclosed in angle brackets "
"(`<...>`), after the name of the item and before its definition. The type "
"parameters of an item are considered \"part of the name\", not part of the "
"type of the item. 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. In practice, "
"the type-inference system can usually infer such argument types from "
"context. There are no general type-parametric types, only type-parametric "
"items. That is, Rust has no notion of type abstraction: there are no first-"
"class \"forall\" types."
msgstr ""
#. type: Plain text
#: doc/rust.md:664
msgid "### Modules"
msgstr ""
#. type: Plain text
#: doc/rust.md:669
msgid ""
"~~~~~~~~ {.ebnf .gram} mod_item : \"mod\" ident ( ';' | '{' mod '}' ); mod : "
"[ view_item | item ] * ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:674
msgid ""
"A module is a container for zero or more [view items](#view-items) and zero "
"or more [items](#items). The view items manage the visibility of the items "
"defined within the module, as well as the visibility of names from outside "
"the module when referenced from inside the module."
msgstr ""
#. type: Plain text
#: doc/rust.md:678
msgid ""
"A _module item_ is a module, surrounded in braces, named, and prefixed with "
"the keyword `mod`. A module item introduces a new, named module into the "
"tree of modules making up a crate. Modules can nest arbitrarily."
msgstr ""
#. type: Plain text
#: doc/rust.md:680
msgid "An example of a module:"
msgstr ""
#. type: Plain text
#: doc/rust.md:698
#, no-wrap
msgid ""
"~~~~~~~~\n"
"mod math {\n"
" type complex = (f64, f64);\n"
" fn sin(f: f64) -> f64 {\n"
" ...\n"
"# fail!();\n"
" }\n"
" fn cos(f: f64) -> f64 {\n"
" ...\n"
"# fail!();\n"
" }\n"
" fn tan(f: f64) -> f64 {\n"
" ...\n"
"# fail!();\n"
" }\n"
"}\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:703
msgid ""
"Modules and types share the same namespace. Declaring a named type that has "
"the same name as a module in scope is forbidden: that is, a type definition, "
"trait, struct, enumeration, or type parameter can't shadow the name of a "
"module in scope, or vice versa."
msgstr ""
#. type: Plain text
#: doc/rust.md:708
msgid ""
"A module without a body is loaded from an external file, by default with the "
"same name as the module, plus the `.rs` extension. When a nested submodule "
"is loaded from an external file, it is loaded from a subdirectory path that "
"mirrors the module hierarchy."
msgstr ""
#. type: Plain text
#: doc/rust.md:712
msgid "~~~ {.xfail-test} // Load the `vec` module from `vec.rs` mod vec;"
msgstr ""
#. type: Plain text
#: doc/rust.md:718
#, no-wrap
msgid ""
"mod task {\n"
" // Load the `local_data` module from `task/local_data.rs`\n"
" mod local_data;\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:721
msgid ""
"The directories and files used for loading external file modules can be "
"influenced with the `path` attribute."
msgstr ""
#. type: Plain text
#: doc/rust.md:730
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"#[path = \"task_files\"]\n"
"mod task {\n"
" // Load the `local_data` module from `task_files/tls.rs`\n"
" #[path = \"tls.rs\"]\n"
" mod local_data;\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:732
msgid "#### View items"
msgstr ""
#. type: Plain text
#: doc/rust.md:736
msgid ""
"~~~~~~~~ {.ebnf .gram} view_item : extern_mod_decl | use_decl ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:740
msgid ""
"A view item manages the namespace of a module. View items do not define new "
"items, but rather, simply change other items' visibility. There are several "
"kinds of view item:"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:743
msgid "[`extern mod` declarations](#extern-mod-declarations)"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:743
msgid "[`use` declarations](#use-declarations)"
msgstr ""
#. type: Plain text
#: doc/rust.md:745
msgid "##### Extern mod declarations"
msgstr ""
#. type: Plain text
#: doc/rust.md:751
msgid ""
"~~~~~~~~ {.ebnf .gram} extern_mod_decl : \"extern\" \"mod\" ident [ '(' "
"link_attrs ')' ] ? [ '=' string_lit ] ? ; link_attrs : link_attr [ ',' "
"link_attrs ] + ; link_attr : ident '=' literal ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:755
msgid ""
"An _`extern mod` declaration_ specifies a dependency on an external crate. "
"The external crate is then bound into the declaring scope as the `ident` "
"provided in the `extern_mod_decl`."
msgstr ""
#. type: Plain text
#: doc/rust.md:765
msgid ""
"The external crate is resolved to a specific `soname` at compile time, and a "
"runtime linkage requirement to that `soname` is passed to the linker for "
"loading at runtime. The `soname` is resolved at compile time by scanning "
"the compiler's library path and matching the `link_attrs` provided in the "
"`use_decl` against any `#link` attributes that were declared on the external "
"crate when it was compiled. If no `link_attrs` are provided, a default "
"`name` attribute is assumed, equal to the `ident` given in the `use_decl`."
msgstr ""
#. type: Plain text
#: doc/rust.md:775
msgid ""
"Optionally, an identifier in an `extern mod` declaration may be followed by "
"an equals sign, then a string literal denoting a relative path on the "
"filesystem. This path should exist in one of the directories in the Rust "
"path, which by default contains the `.rust` subdirectory of the current "
"directory and each of its parents, as well as any directories in the colon-"
"separated (or semicolon-separated on Windows) list of paths that is the "
"`RUST_PATH` environment variable. The meaning of `extern mod a = \"b/c/d\";"
"`, supposing that `/a` is in the RUST_PATH, is that the name `a` should be "
"taken as a reference to the crate whose absolute location is `/a/b/c/d`."
msgstr ""
#. type: Plain text
#: doc/rust.md:777
msgid "Four examples of `extern mod` declarations:"
msgstr ""
#. type: Plain text
#: doc/rust.md:780
msgid ""
"~~~~~~~~{.xfail-test} extern mod pcre (uuid = \"54aba0f8-"
"a7b1-4beb-92f1-4cf625264841\");"
msgstr ""
#. type: Plain text
#: doc/rust.md:782
msgid ""
"extern mod extra; // equivalent to: extern mod extra ( name = \"extra\" );"
msgstr ""
#. type: Plain text
#: doc/rust.md:784
msgid ""
"extern mod rustextra (name = \"extra\"); // linking to 'extra' under another "
"name"
msgstr ""
#. type: Plain text
#: doc/rust.md:787
msgid "extern mod complicated_mod = \"some-file/in/the-rust/path\"; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:789
msgid "##### Use declarations"
msgstr ""
#. type: Plain text
#: doc/rust.md:793
#, no-wrap
msgid ""
"~~~~~~~~ {.ebnf .gram}\n"
"use_decl : \"pub\"? \"use\" ident [ '=' path\n"
" | \"::\" path_glob ] ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:798
#, no-wrap
msgid ""
"path_glob : ident [ \"::\" path_glob ] ?\n"
" | '*'\n"
" | '{' ident [ ',' ident ] * '}'\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:802
msgid ""
"A _use declaration_ creates one or more local name bindings synonymous with "
"some other [path](#paths). Usually a `use` declaration is used to shorten "
"the path required to refer to a module item."
msgstr ""
#. type: Plain text
#: doc/rust.md:806
#, no-wrap
msgid ""
"*Note*: Unlike in many languages,\n"
"`use` declarations in Rust do *not* declare linkage dependency with external crates.\n"
"Rather, [`extern mod` declarations](#extern-mod-declarations) declare linkage dependencies.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:808
msgid "Use declarations support a number of convenient shortcuts:"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:813
msgid ""
"Rebinding the target name as a new local name, using the syntax `use x = p::"
"q::r;`."
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:813
msgid ""
"Simultaneously binding a list of paths differing only in their final "
"element, using the glob-like brace syntax `use a::b::{c,d,e,f};`"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:813
msgid ""
"Binding all paths matching a given prefix, using the asterisk wildcard "
"syntax `use a::b::*;`"
msgstr ""
#. type: Plain text
#: doc/rust.md:815
msgid "An example of `use` declarations:"
msgstr ""
#. type: Plain text
#: doc/rust.md:819
msgid "~~~~ use std::num::sin; use std::option::{Some, None};"
msgstr ""
#. type: Plain text
#: doc/rust.md:823
#, no-wrap
msgid ""
"fn main() {\n"
" // Equivalent to 'info!(std::num::sin(1.0));'\n"
" info!(sin(1.0));\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:828
#, no-wrap
msgid ""
" // Equivalent to 'info!(~[std::option::Some(1.0), std::option::None]);'\n"
" info!(~[Some(1.0), None]);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:836
msgid ""
"Like items, `use` declarations are private to the containing module, by "
"default. Also like items, a `use` declaration can be public, if qualified "
"by the `pub` keyword. Such a `use` declaration serves to _re-export_ a "
"name. A public `use` declaration can therefore _redirect_ some public name "
"to a different target definition: even a definition with a private canonical "
"path, inside a different module. If a sequence of such redirections form a "
"cycle or cannot be resolved unambiguously, they represent a compile-time "
"error."
msgstr ""
#. type: Plain text
#: doc/rust.md:842
#, no-wrap
msgid ""
"An example of re-exporting:\n"
"~~~~\n"
"# fn main() { }\n"
"mod quux {\n"
" pub use quux::foo::*;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:849
#, no-wrap
msgid ""
" pub mod foo {\n"
" pub fn bar() { }\n"
" pub fn baz() { }\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:851
msgid ""
"In this example, the module `quux` re-exports all of the public names "
"defined in `foo`."
msgstr ""
#. type: Plain text
#: doc/rust.md:854
msgid ""
"Also note that the paths contained in `use` items are relative to the crate "
"root. So, in the previous example, the `use` refers to `quux::foo::*`, and "
"not simply to `foo::*`."
msgstr ""
#. type: Plain text
#: doc/rust.md:856
msgid "### Functions"
msgstr ""
#. type: Plain text
#: doc/rust.md:860
msgid ""
"A _function item_ defines a sequence of [statements](#statements) and an "
"optional final [expression](#expressions), along with a name and a set of "
"parameters. Functions are declared with the keyword `fn`. 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."
msgstr ""
#. type: Plain text
#: doc/rust.md:865
msgid ""
"A function may also be copied into a first class *value*, in which case the "
"value has the corresponding [*function type*](#function-types), and can be "
"used otherwise exactly as a function item (with a minor additional cost of "
"calling the function indirectly)."
msgstr ""
#. type: Plain text
#: doc/rust.md:871
msgid ""
"Every control path in a function logically ends with a `return` expression "
"or a diverging expression. If the outermost block of a function has a value-"
"producing expression in its final-expression position, that expression is "
"interpreted as an implicit `return` expression applied to the final-"
"expression."
msgstr ""
#. type: Plain text
#: doc/rust.md:873
msgid "An example of a function:"
msgstr ""
#. type: Plain text
#: doc/rust.md:879
#, no-wrap
msgid ""
"~~~~\n"
"fn add(x: int, y: int) -> int {\n"
" return x + y;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:882
msgid ""
"As with `let` bindings, function arguments are irrefutable patterns, so any "
"pattern that is valid in a let binding is also valid as an argument."
msgstr ""
#. type: Plain text
#: doc/rust.md:886
msgid "~~~ fn first((value, _): (int, int)) -> int { value } ~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:889
msgid "#### Generic functions"
msgstr ""
#. type: Plain text
#: doc/rust.md:894
msgid ""
"A _generic function_ allows one or more _parameterized types_ to appear in "
"its signature. Each type parameter must be explicitly declared, in an angle-"
"bracket-enclosed, comma-separated list following the function name."
msgstr ""
#. type: Plain text
#: doc/rust.md:905
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"fn iter<T>(seq: &[T], f: |T|) {\n"
" for elt in seq.iter() { f(elt); }\n"
"}\n"
"fn map<T, U>(seq: &[T], f: |T| -> U) -> ~[U] {\n"
" let mut acc = ~[];\n"
" for elt in seq.iter() { acc.push(f(elt)); }\n"
" acc\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:908
msgid ""
"Inside the function signature and body, the name of the type parameter can "
"be used as a type name."
msgstr ""
#. type: Plain text
#: doc/rust.md:914
msgid ""
"When a generic function is referenced, its type is instantiated based on the "
"context of the reference. For example, calling the `iter` function defined "
"above on `[1, 2]` will instantiate type parameter `T` with `int`, and "
"require the closure parameter to have type `fn(int)`."
msgstr ""
#. type: Plain text
#: doc/rust.md:919
msgid ""
"The type parameters can also be explicitly supplied in a trailing [path]"
"(#paths) component after the function name. This might be necessary if there "
"is not sufficient context to determine the type parameters. For example, "
"`mem::size_of::<u32>() == 4`."
msgstr ""
#. type: Plain text
#: doc/rust.md:923
msgid ""
"Since a parameter type is opaque to the generic function, the set of "
"operations that can be performed on it is limited. Values of parameter type "
"can only be moved, not copied."
msgstr ""
#. type: Plain text
#: doc/rust.md:927
msgid "~~~~ fn id<T>(x: T) -> T { x } ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:931
msgid ""
"Similarly, [trait](#traits) bounds can be specified for type parameters to "
"allow methods with that trait to be called on values of that type."
msgstr ""
#. type: Plain text
#: doc/rust.md:934
msgid "#### Unsafe functions"
msgstr ""
#. type: Plain text
#: doc/rust.md:937
msgid ""
"Unsafe functions are those containing unsafe operations that are not "
"contained in an [`unsafe` block](#unsafe-blocks). Such a function must be "
"prefixed with the keyword `unsafe`."
msgstr ""
#. type: Plain text
#: doc/rust.md:940
msgid ""
"Unsafe operations are those that potentially violate the memory-safety "
"guarantees of Rust's static semantics. Specifically, the following "
"operations are considered unsafe:"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:944
msgid "Dereferencing a [raw pointer](#pointer-types)."
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:944
msgid "Casting a [raw pointer](#pointer-types) to a safe pointer type."
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:944
msgid "Calling an unsafe function."
msgstr ""
#. type: Plain text
#: doc/rust.md:946
msgid "##### Unsafe blocks"
msgstr ""
#. type: Plain text
#: doc/rust.md:950
msgid ""
"A block of code can also be prefixed with the `unsafe` keyword, to permit a "
"sequence of unsafe operations in an otherwise-safe function. This facility "
"exists because the static semantics of Rust are a necessary approximation of "
"the dynamic semantics. 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."
msgstr ""
#. type: Plain text
#: doc/rust.md:953
msgid "#### Diverging functions"
msgstr ""
#. type: Plain text
#: doc/rust.md:956
msgid ""
"A special kind of function can be declared with a `!` character where the "
"output slot type would normally be. For example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:963
#, no-wrap
msgid ""
"~~~~\n"
"fn my_err(s: &str) -> ! {\n"
" info!(s);\n"
" fail!();\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:970
msgid ""
"We call such functions \"diverging\" because they never return a value to "
"the caller. Every control path in a diverging function must end with a `fail!"
"()` or a call to another diverging function on every control path. The `!` "
"annotation does *not* denote a type. Rather, the result type of a diverging "
"function is a special type called $\\bot$ (\"bottom\") that unifies with any "
"type. Rust has no syntax for $\\bot$."
msgstr ""
#. type: Plain text
#: doc/rust.md:976
msgid ""
"It might be necessary to declare a diverging function because as mentioned "
"previously, the typechecker checks that every control path in a function "
"ends with a [`return`](#return-expressions) or diverging expression. So, if "
"`my_err` were declared without the `!` annotation, the following code would "
"not typecheck:"
msgstr ""
#. type: Plain text
#: doc/rust.md:979
msgid "~~~~ # fn my_err(s: &str) -> ! { fail!() }"
msgstr ""
#. type: Plain text
#: doc/rust.md:989
#, no-wrap
msgid ""
"fn f(i: int) -> int {\n"
" if i == 42 {\n"
" return 42;\n"
" }\n"
" else {\n"
" my_err(\"Bad number!\");\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:997
msgid ""
"This will not compile without the `!` annotation on `my_err`, since the "
"`else` branch of the conditional in `f` does not return an `int`, as "
"required by the signature of `f`. Adding the `!` annotation to `my_err` "
"informs the typechecker that, should control ever enter `my_err`, no further "
"type judgments about `f` need to hold, since control will never resume in "
"any context that relies on those judgments. Thus the return type on `f` "
"only needs to reflect the `if` branch of the conditional."
msgstr ""
#. type: Plain text
#: doc/rust.md:1000
msgid "#### Extern functions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1007
msgid ""
"Extern functions are part of Rust's foreign function interface, providing "
"the opposite functionality to [external blocks](#external-blocks). Whereas "
"external blocks allow Rust code to call foreign code, extern functions with "
"bodies defined in Rust code _can be called by foreign code_. They are "
"defined in the same way as any other Rust function, except that they have "
"the `extern` modifier."
msgstr ""
#. type: Plain text
#: doc/rust.md:1011
msgid "~~~ extern fn new_vec() -> ~[int] { ~[] } ~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1014
msgid ""
"Extern functions may not be called from Rust code, but Rust code may take "
"their value as a raw `u8` pointer."
msgstr ""
#. type: Plain text
#: doc/rust.md:1019
msgid ""
"~~~ # extern fn new_vec() -> ~[int] { ~[] } let fptr: *u8 = new_vec; ~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1023
msgid ""
"The primary motivation for extern functions is to create callbacks for "
"foreign functions that expect to receive function pointers."
msgstr ""
#. type: Plain text
#: doc/rust.md:1025
msgid "### Type definitions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1029
msgid ""
"A _type definition_ defines a new name for an existing [type](#types). Type "
"definitions are declared with the keyword `type`. Every value has a single, "
"specific type; the type-specified aspects of a value include:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1035
msgid "Whether the value is composed of sub-values or is indivisible."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1035
msgid "Whether the value represents textual or numerical information."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1035
msgid "Whether the value represents integral or floating-point information."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1035
msgid "The sequence of memory operations required to access the value."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1035
msgid "The [kind](#type-kinds) of the type."
msgstr ""
#. type: Plain text
#: doc/rust.md:1038
msgid ""
"For example, the type `(u8, u8)` defines the set of immutable values that "
"are composite pairs, each containing two unsigned 8-bit integers accessed by "
"pattern-matching and laid out in memory with the `x` component preceding the "
"`y` component."
msgstr ""
#. type: Plain text
#: doc/rust.md:1040
msgid "### Structures"
msgstr ""
#. type: Plain text
#: doc/rust.md:1042
msgid ""
"A _structure_ is a nominal [structure type](#structure-types) defined with "
"the keyword `struct`."
msgstr ""
#. type: Plain text
#: doc/rust.md:1044
msgid "An example of a `struct` item and its use:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1050
msgid ""
"~~~~ struct Point {x: int, y: int} let p = Point {x: 10, y: 11}; let px: int "
"= p.x; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1053
msgid ""
"A _tuple structure_ is a nominal [tuple type](#tuple-types), also defined "
"with the keyword `struct`. For example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1059
msgid ""
"~~~~ struct Point(int, int); let p = Point(10, 11); let px: int = match p "
"{ Point(x, _) => x }; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1063
msgid ""
"A _unit-like struct_ is a structure without any fields, defined by leaving "
"off the list of fields entirely. Such types will have a single value, just "
"like the [unit value `()`](#unit-and-boolean-literals) of the unit type. "
"For example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1068
msgid "~~~~ struct Cookie; let c = [Cookie, Cookie, Cookie, Cookie]; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1070
msgid "### Enumerations"
msgstr ""
#. type: Plain text
#: doc/rust.md:1073
msgid ""
"An _enumeration_ is a simultaneous definition of a nominal [enumerated type]"
"(#enumerated-types) as well as a set of *constructors*, that can be used to "
"create or pattern-match values of the corresponding enumerated type."
msgstr ""
#. type: Plain text
#: doc/rust.md:1075
msgid "Enumerations are declared with the keyword `enum`."
msgstr ""
#. type: Plain text
#: doc/rust.md:1077
msgid "An example of an `enum` item and its use:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1083
#, no-wrap
msgid ""
"~~~~\n"
"enum Animal {\n"
" Dog,\n"
" Cat\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1087
msgid "let mut a: Animal = Dog; a = Cat; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1094
#, no-wrap
msgid ""
"Enumeration constructors can have either named or unnamed fields:\n"
"~~~~\n"
"enum Animal {\n"
" Dog (~str, float),\n"
" Cat { name: ~str, weight: float }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1098
msgid ""
"let mut a: Animal = Dog(~\"Cocoa\", 37.2); a = Cat{ name: ~\"Spotty\", "
"weight: 2.7 }; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1101
msgid ""
"In this example, `Cat` is a _struct-like enum variant_, whereas `Dog` is "
"simply called an enum variant."
msgstr ""
#. type: Plain text
#: doc/rust.md:1103
msgid "### Static items"
msgstr ""
#. type: Plain text
#: doc/rust.md:1107
msgid ""
"~~~~~~~~ {.ebnf .gram} static_item : \"static\" ident ':' type '=' expr "
"';' ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1114
msgid ""
"A *static item* is a named _constant value_ stored in the global data "
"section of a crate. Immutable static items are stored in the read-only data "
"section. The constant value bound to a static item is, like all constant "
"values, evaluated at compile time. Static items have the `static` lifetime, "
"which outlives all other lifetimes in a Rust program. Static items are "
"declared with the `static` keyword. A static item must have a _constant "
"expression_ giving its definition."
msgstr ""
#. type: Plain text
#: doc/rust.md:1119
msgid ""
"Static items must be explicitly typed. The type may be ```bool```, "
"```char```, a number, or a type derived from those primitive types. The "
"derived types are borrowed pointers with the `'static` lifetime, fixed-size "
"arrays, tuples, and structs."
msgstr ""
#. type: Plain text
#: doc/rust.md:1123
msgid "~~~~ static BIT1: uint = 1 << 0; static BIT2: uint = 1 << 1;"
msgstr ""
#. type: Plain text
#: doc/rust.md:1126
msgid ""
"static BITS: [uint, ..2] = [BIT1, BIT2]; static STRING: &'static str = "
"\"bitstring\";"
msgstr ""
#. type: Plain text
#: doc/rust.md:1131
#, no-wrap
msgid ""
"struct BitsNStrings<'self> {\n"
" mybits: [uint, ..2],\n"
" mystring: &'self str\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1137
#, no-wrap
msgid ""
"static bits_n_strings: BitsNStrings<'static> = BitsNStrings {\n"
" mybits: BITS,\n"
" mystring: STRING\n"
"};\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1139
msgid "#### Mutable statics"
msgstr ""
#. type: Plain text
#: doc/rust.md:1147
msgid ""
"If a static item is declared with the ```mut``` keyword, then it is allowed "
"to be modified by the program. One of Rust's goals is to make concurrency "
"bugs hard to run into, and this is obviously a very large source of race "
"conditions or other bugs. For this reason, an ```unsafe``` block is required "
"when either reading or writing a mutable static variable. Care should be "
"taken to ensure that modifications to a mutable static are safe with respect "
"to other tasks running in the same process."
msgstr ""
#. type: Plain text
#: doc/rust.md:1150
msgid ""
"Mutable statics are still very useful, however. They can be used with C "
"libraries and can also be bound from C libraries (in an ```extern``` block)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1153
msgid "~~~ # fn atomic_add(_: &mut uint, _: uint) -> uint { 2 }"
msgstr ""
#. type: Plain text
#: doc/rust.md:1155
msgid "static mut LEVELS: uint = 0;"
msgstr ""
#. type: Plain text
#: doc/rust.md:1163
#, no-wrap
msgid ""
"// This violates the idea of no shared state, and this doesn't internally\n"
"// protect against races, so this function is `unsafe`\n"
"unsafe fn bump_levels_unsafe1() -> uint {\n"
" let ret = LEVELS;\n"
" LEVELS += 1;\n"
" return ret;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1170
#, no-wrap
msgid ""
"// Assuming that we have an atomic_add function which returns the old value,\n"
"// this function is \"safe\" but the meaning of the return value may not be what\n"
"// callers expect, so it's still marked as `unsafe`\n"
"unsafe fn bump_levels_unsafe2() -> uint {\n"
" return atomic_add(&mut LEVELS, 1);\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1172
msgid "~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1174
msgid "### Traits"
msgstr ""
#. type: Plain text
#: doc/rust.md:1176
msgid "A _trait_ describes a set of method types."
msgstr ""
#. type: Plain text
#: doc/rust.md:1181
msgid ""
"Traits can include default implementations of methods, written in terms of "
"some unknown [`self` type](#self-types); the `self` type may either be "
"completely unspecified, or constrained by some other trait."
msgstr ""
#. type: Plain text
#: doc/rust.md:1183
msgid ""
"Traits are implemented for specific types through separate [implementations]"
"(#implementations)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1187
msgid "~~~~ # type Surface = int; # type BoundingBox = int;"
msgstr ""
#. type: Plain text
#: doc/rust.md:1193
#, no-wrap
msgid ""
"trait Shape {\n"
" fn draw(&self, Surface);\n"
" fn bounding_box(&self) -> BoundingBox;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1197
msgid ""
"This defines a trait with two methods. All values that have "
"[implementations](#implementations) of this trait in scope can have their "
"`draw` and `bounding_box` methods called, using `value.bounding_box()` "
"[syntax](#method-call-expressions)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1200
msgid ""
"Type parameters can be specified for a trait to make it generic. These "
"appear after the trait name, using the same syntax used in [generic "
"functions](#generic-functions)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1208
#, no-wrap
msgid ""
"~~~~\n"
"trait Seq<T> {\n"
" fn len(&self) -> uint;\n"
" fn elt_at(&self, n: uint) -> T;\n"
" fn iter(&self, |T|);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1214
msgid ""
"Generic functions may use traits as _bounds_ on their type parameters. This "
"will have two effects: only types that have the trait may instantiate the "
"parameter, and within the generic function, the methods of the trait can be "
"called on values that have the parameter's type. For example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1218
msgid "~~~~ # type Surface = int; # trait Shape { fn draw(&self, Surface); }"
msgstr ""
#. type: Plain text
#: doc/rust.md:1224
#, no-wrap
msgid ""
"fn draw_twice<T: Shape>(surface: Surface, sh: T) {\n"
" sh.draw(surface);\n"
" sh.draw(surface);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1229
msgid ""
"Traits also define an [object type](#object-types) with the same name as the "
"trait. Values of this type are created by [casting](#type-cast-expressions) "
"pointer values (pointing to a type for which an implementation of the given "
"trait is in scope) to pointers to the trait name, used as a type."
msgstr ""
#. type: Plain text
#: doc/rust.md:1234
msgid "~~~~ # trait Shape { } # impl Shape for int { } # let mycircle = 0;"
msgstr ""
#. type: Plain text
#: doc/rust.md:1237
msgid "let myshape: @Shape = @mycircle as @Shape; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1243
msgid ""
"The resulting value is a managed box containing the value that was cast, "
"along with information that identifies the methods of the implementation "
"that was used. Values with a trait type can have [methods called](#method-"
"call-expressions) on them, for any method in the trait, and can be used to "
"instantiate type parameters that are bounded by the trait."
msgstr ""
#. type: Plain text
#: doc/rust.md:1251
msgid ""
"Trait methods may be static, which means that they lack a `self` argument. "
"This means that they can only be called with function call syntax (`f(x)`) "
"and not method call syntax (`obj.f()`). The way to refer to the name of a "
"static method is to qualify it with the trait name, treating the trait name "
"like a module. For example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1261
#, no-wrap
msgid ""
"~~~~\n"
"trait Num {\n"
" fn from_int(n: int) -> Self;\n"
"}\n"
"impl Num for float {\n"
" fn from_int(n: int) -> float { n as float }\n"
"}\n"
"let x: float = Num::from_int(42);\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1263
msgid "Traits may inherit from other traits. For example, in"
msgstr ""
#. type: Plain text
#: doc/rust.md:1268
msgid ""
"~~~~ trait Shape { fn area() -> float; } trait Circle : Shape { fn radius() -"
"> float; } ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1273
msgid ""
"the syntax `Circle : Shape` means that types that implement `Circle` must "
"also have an implementation for `Shape`. Multiple supertraits are separated "
"by spaces, `trait Circle : Shape Eq { }`. In an implementation of `Circle` "
"for a given type `T`, methods can refer to `Shape` methods, since the "
"typechecker checks that any type with an implementation of `Circle` also has "
"an implementation of `Shape`."
msgstr ""
#. type: Plain text
#: doc/rust.md:1277 doc/tutorial.md:2176
msgid ""
"In type-parameterized functions, methods of the supertrait may be called on "
"values of subtrait-bound type parameters. Refering to the previous example "
"of `trait Circle : Shape`:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1286 doc/tutorial.md:2185
#, no-wrap
msgid ""
"~~~\n"
"# trait Shape { fn area(&self) -> float; }\n"
"# trait Circle : Shape { fn radius(&self) -> float; }\n"
"fn radius_times_area<T: Circle>(c: T) -> float {\n"
" // `c` is both a Circle and a Shape\n"
" c.radius() * c.area()\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1288 doc/tutorial.md:2187
msgid "Likewise, supertrait methods may also be called on trait objects."
msgstr ""
#. type: Plain text
#: doc/rust.md:1295
msgid ""
"~~~ {.xfail-test} # trait Shape { fn area(&self) -> float; } # trait "
"Circle : Shape { fn radius(&self) -> float; } # impl Shape for int { fn "
"area(&self) -> float { 0.0 } } # impl Circle for int { fn radius(&self) -> "
"float { 0.0 } } # let mycircle = 0;"
msgstr ""
#. type: Plain text
#: doc/rust.md:1299
msgid ""
"let mycircle: Circle = @mycircle as @Circle; let nonsense = mycircle."
"radius() * mycircle.area(); ~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1301
msgid "### Implementations"
msgstr ""
#. type: Plain text
#: doc/rust.md:1303
msgid ""
"An _implementation_ is an item that implements a [trait](#traits) for a "
"specific type."
msgstr ""
#. type: Plain text
#: doc/rust.md:1305
msgid "Implementations are defined with the keyword `impl`."
msgstr ""
#. type: Plain text
#: doc/rust.md:1312
msgid ""
"~~~~ # struct Point {x: float, y: float}; # type Surface = int; # struct "
"BoundingBox {x: float, y: float, width: float, height: float}; # trait Shape "
"{ fn draw(&self, Surface); fn bounding_box(&self) -> BoundingBox; } # fn "
"do_draw_circle(s: Surface, c: Circle) { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:1317
#, no-wrap
msgid ""
"struct Circle {\n"
" radius: float,\n"
" center: Point,\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1327
#, no-wrap
msgid ""
"impl Shape for Circle {\n"
" fn draw(&self, s: Surface) { do_draw_circle(s, *self); }\n"
" fn bounding_box(&self) -> BoundingBox {\n"
" let r = self.radius;\n"
" BoundingBox{x: self.center.x - r, y: self.center.y - r,\n"
" width: 2.0 * r, height: 2.0 * r}\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1334
msgid ""
"It is possible to define an implementation without referring to a trait. "
"The methods in such an implementation can only be used as direct calls on "
"the values of the type that the implementation targets. In such an "
"implementation, the trait type and `for` after `impl` are omitted. Such "
"implementations are limited to nominal types (enums, structs), and the "
"implementation must appear in the same module or a sub-module as the `self` "
"type."
msgstr ""
#. type: Plain text
#: doc/rust.md:1338
msgid ""
"When a trait _is_ specified in an `impl`, all methods declared as part of "
"the trait must be implemented, with matching types and type parameter counts."
msgstr ""
#. type: Plain text
#: doc/rust.md:1342
msgid ""
"An implementation can take type parameters, which can be different from the "
"type parameters taken by the trait it implements. Implementation parameters "
"are written after the `impl` keyword."
msgstr ""
#. type: Plain text
#: doc/rust.md:1345
msgid "~~~~ # trait Seq<T> { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:1353
#, no-wrap
msgid ""
"impl<T> Seq<T> for ~[T] {\n"
" ...\n"
"}\n"
"impl Seq<bool> for u32 {\n"
" /* Treat the integer as a sequence of bits */\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1355
msgid "### External blocks"
msgstr ""
#. type: Plain text
#: doc/rust.md:1360
msgid ""
"~~~ {.ebnf .gram} extern_block_item : \"extern\" '{' extern_block '} ; "
"extern_block : [ foreign_fn ] * ; ~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1364
msgid ""
"External blocks form the basis for Rust's foreign function interface. "
"Declarations in an external block describe symbols in external, non-Rust "
"libraries."
msgstr ""
#. type: Plain text
#: doc/rust.md:1369
msgid ""
"Functions within external blocks are declared in the same way as other Rust "
"functions, with the exception that they may not have a body and are instead "
"terminated by a semicolon."
msgstr ""
#. type: Plain text
#: doc/rust.md:1373
msgid "~~~ # use std::libc::{c_char, FILE}; # #[nolink]"
msgstr ""
#. type: Plain text
#: doc/rust.md:1378
#, no-wrap
msgid ""
"extern {\n"
" fn fopen(filename: *c_char, mode: *c_char) -> *FILE;\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1383
msgid ""
"Functions within external blocks may be called by Rust code, just like "
"functions defined in Rust. The Rust compiler automatically translates "
"between the Rust ABI and the foreign ABI."
msgstr ""
#. type: Plain text
#: doc/rust.md:1386
msgid ""
"A number of [attributes](#attributes) control the behavior of external "
"blocks."
msgstr ""
#. type: Plain text
#: doc/rust.md:1390
msgid ""
"By default external blocks assume that the library they are calling uses the "
"standard C \"cdecl\" ABI. Other ABIs may be specified using the `abi` "
"attribute as in"
msgstr ""
#. type: Plain text
#: doc/rust.md:1396
msgid ""
"~~~{.xfail-test} // Interface to the Windows API #[abi = \"stdcall\"] extern "
"{ } ~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1398
msgid ""
"The `link_name` attribute allows the name of the library to be specified."
msgstr ""
#. type: Plain text
#: doc/rust.md:1403
msgid "~~~{.xfail-test} #[link_name = \"crypto\"] extern { } ~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1409
msgid ""
"The `nolink` attribute tells the Rust compiler not to do any linking for the "
"external block. This is particularly useful for creating external blocks "
"for libc, which tends to not follow standard library naming conventions and "
"is linked to all Rust programs anyway."
msgstr ""
#. type: Plain text
#: doc/rust.md:1411
msgid "## Attributes"
msgstr ""
#. type: Plain text
#: doc/rust.md:1418
#, no-wrap
msgid ""
"~~~~~~~~{.ebnf .gram}\n"
"attribute : '#' '[' attr_list ']' ;\n"
"attr_list : attr [ ',' attr_list ]*\n"
"attr : ident [ '=' literal\n"
" | '(' attr_list ')' ] ? ;\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1424
msgid ""
"Static entities in Rust -- crates, modules and items -- may have "
"_attributes_ applied to them. ^[Attributes in Rust are modeled on Attributes "
"in ECMA-335, C#] An attribute is a general, free-form metadatum that is "
"interpreted according to name, convention, and language and compiler "
"version. Attributes may appear as any of"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1428
msgid "A single identifier, the attribute name"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1428
msgid ""
"An identifier followed by the equals sign '=' and a literal, providing a key/"
"value pair"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1428
msgid ""
"An identifier followed by a parenthesized list of sub-attribute arguments"
msgstr ""
#. type: Plain text
#: doc/rust.md:1431
msgid ""
"Attributes terminated by a semi-colon apply to the entity that the attribute "
"is declared within. Attributes that are not terminated by a semi-colon apply "
"to the next entity."
msgstr ""
#. type: Plain text
#: doc/rust.md:1433
msgid "An example of attributes:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1437
msgid ""
"~~~~~~~~{.xfail-test} // General metadata applied to the enclosing module or "
"crate. #[license = \"BSD\"];"
msgstr ""
#. type: Plain text
#: doc/rust.md:1443
#, no-wrap
msgid ""
"// A function marked as a unit test\n"
"#[test]\n"
"fn test_foo() {\n"
" ...\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1449
#, no-wrap
msgid ""
"// A conditionally-compiled module\n"
"#[cfg(target_os=\"linux\")]\n"
"mod bar {\n"
" ...\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1454
msgid ""
"// A lint attribute used to suppress a warning/error "
"#[allow(non_camel_case_types)] pub type int8_t = i8; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1457
msgid ""
"> **Note:** In future versions of Rust, user-provided extensions to the "
"compiler will be able to interpret attributes. > When this facility is "
"provided, the compiler will distinguish between language-reserved and user-"
"available attributes."
msgstr ""
#. type: Plain text
#: doc/rust.md:1460
msgid ""
"At present, only the Rust compiler interprets attributes, so all attribute "
"names are effectively reserved. Some significant attributes include:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid "The `doc` attribute, for documenting code in-place."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid ""
"The `cfg` attribute, for conditional-compilation by build-configuration."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid ""
"The `lang` attribute, for custom definitions of traits and functions that "
"are known to the Rust compiler (see [Language items](#language-items))."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid "The `link` attribute, for describing linkage metadata for a crate."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid "The `test` attribute, for marking functions as unit tests."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid ""
"The `allow`, `warn`, `forbid`, and `deny` attributes, for controlling lint "
"checks (see [Lint check attributes](#lint-check-attributes))."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid ""
"The `deriving` attribute, for automatically generating implementations of "
"certain traits."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1471
msgid ""
"The `static_assert` attribute, for asserting that a static bool is true at "
"compiletime"
msgstr ""
#. type: Plain text
#: doc/rust.md:1473
msgid ""
"Other attributes may be added or removed during development of the language."
msgstr ""
#. type: Plain text
#: doc/rust.md:1475
msgid "### Lint check attributes"
msgstr ""
#. type: Plain text
#: doc/rust.md:1479
msgid ""
"A lint check names a potentially undesirable coding pattern, such as "
"unreachable code or omitted documentation, for the static entity to which "
"the attribute applies."
msgstr ""
#. type: Plain text
#: doc/rust.md:1481
msgid "For any lint check `C`:"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:1488
msgid "`warn(C)` warns about violations of `C` but continues compilation,"
msgstr ""
#. type: Bullet: ' * '
#: doc/rust.md:1488
msgid "`deny(C)` signals an error after encountering a violation of `C`,"
msgstr ""
#. type: Plain text
#: doc/rust.md:1488
#, no-wrap
msgid ""
" * `allow(C)` overrides the check for `C` so that violations will go\n"
" unreported,\n"
" * `forbid(C)` is the same as `deny(C)`, but also forbids uses of\n"
" `allow(C)` within the entity.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1491
msgid ""
"The lint checks supported by the compiler can be found via `rustc -W help`, "
"along with their default settings."
msgstr ""
#. type: Plain text
#: doc/rust.md:1497
#, no-wrap
msgid ""
"~~~{.xfail-test}\n"
"mod m1 {\n"
" // Missing documentation is ignored here\n"
" #[allow(missing_doc)]\n"
" pub fn undocumented_one() -> int { 1 }\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1501
#, no-wrap
msgid ""
" // Missing documentation signals a warning here\n"
" #[warn(missing_doc)]\n"
" pub fn undocumented_too() -> int { 2 }\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1507
#, no-wrap
msgid ""
" // Missing documentation signals an error here\n"
" #[deny(missing_doc)]\n"
" pub fn undocumented_end() -> int { 3 }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1510
msgid ""
"This example shows how one can use `allow` and `warn` to toggle a particular "
"check on and off."
msgstr ""
#. type: Plain text
#: doc/rust.md:1518
#, no-wrap
msgid ""
"~~~{.xfail-test}\n"
"#[warn(missing_doc)]\n"
"mod m2{\n"
" #[allow(missing_doc)]\n"
" mod nested {\n"
" // Missing documentation is ignored here\n"
" pub fn undocumented_one() -> int { 1 }\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1524
#, no-wrap
msgid ""
" // Missing documentation signals a warning here,\n"
" // despite the allow above.\n"
" #[warn(missing_doc)]\n"
" pub fn undocumented_two() -> int { 2 }\n"
" }\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1529
#, no-wrap
msgid ""
" // Missing documentation signals a warning here\n"
" pub fn undocumented_too() -> int { 3 }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1532
msgid ""
"This example shows how one can use `forbid` to disallow uses of `allow` for "
"that lint check."
msgstr ""
#. type: Plain text
#: doc/rust.md:1542
#, no-wrap
msgid ""
"~~~{.xfail-test}\n"
"#[forbid(missing_doc)]\n"
"mod m3 {\n"
" // Attempting to toggle warning signals an error here\n"
" #[allow(missing_doc)]\n"
" /// Returns 2.\n"
" pub fn undocumented_too() -> int { 2 }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1544
msgid "### Language items"
msgstr ""
#. type: Plain text
#: doc/rust.md:1550
msgid ""
"Some primitive Rust operations are defined in Rust code, rather than being "
"implemented directly in C or assembly language. The definitions of these "
"operations have to be easy for the compiler to find. The `lang` attribute "
"makes it possible to declare these operations. For example, the `str` "
"module in the Rust standard library defines the string equality function:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1557
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"#[lang=\"str_eq\"]\n"
"pub fn eq_slice(a: &str, b: &str) -> bool {\n"
" // details elided\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1561
msgid ""
"The name `str_eq` has a special meaning to the Rust compiler, and the "
"presence of this definition means that it will use this definition when "
"generating calls to the string equality function."
msgstr ""
#. type: Plain text
#: doc/rust.md:1563
msgid "A complete list of the built-in language items follows:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1565
msgid "#### Traits"
msgstr ""
#. type: Plain text
#: doc/rust.md:1604
#, no-wrap
msgid ""
"`const`\n"
" : Cannot be mutated.\n"
"`owned`\n"
" : Are uniquely owned.\n"
"`durable`\n"
" : Contain borrowed pointers.\n"
"`drop`\n"
" : Have finalizers.\n"
"`add`\n"
" : Elements can be added (for example, integers and floats).\n"
"`sub`\n"
" : Elements can be subtracted.\n"
"`mul`\n"
" : Elements can be multiplied.\n"
"`div`\n"
" : Elements have a division operation.\n"
"`rem`\n"
" : Elements have a remainder operation.\n"
"`neg`\n"
" : Elements can be negated arithmetically.\n"
"`not`\n"
" : Elements can be negated logically.\n"
"`bitxor`\n"
" : Elements have an exclusive-or operation.\n"
"`bitand`\n"
" : Elements have a bitwise `and` operation.\n"
"`bitor`\n"
" : Elements have a bitwise `or` operation.\n"
"`shl`\n"
" : Elements have a left shift operation.\n"
"`shr`\n"
" : Elements have a right shift operation.\n"
"`index`\n"
" : Elements can be indexed.\n"
"`eq`\n"
" : Elements can be compared for equality.\n"
"`ord`\n"
" : Elements have a partial ordering.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1606
msgid "#### Operations"
msgstr ""
#. type: Plain text
#: doc/rust.md:1636
#, no-wrap
msgid ""
"`str_eq`\n"
" : Compare two strings for equality.\n"
"`uniq_str_eq`\n"
" : Compare two owned strings for equality.\n"
"`annihilate`\n"
" : Destroy a box before freeing it.\n"
"`log_type`\n"
" : Generically print a string representation of any type.\n"
"`fail_`\n"
" : Abort the program with an error.\n"
"`fail_bounds_check`\n"
" : Abort the program with a bounds check error.\n"
"`exchange_malloc`\n"
" : Allocate memory on the exchange heap.\n"
"`exchange_free`\n"
" : Free memory that was allocated on the exchange heap.\n"
"`malloc`\n"
" : Allocate memory on the managed heap.\n"
"`free`\n"
" : Free memory that was allocated on the managed heap.\n"
"`borrow_as_imm`\n"
" : Create an immutable borrowed pointer to a mutable value.\n"
"`return_to_mut`\n"
" : Release a borrowed pointer created with `return_to_mut`\n"
"`check_not_borrowed`\n"
" : Fail if a value has existing borrowed pointers to it.\n"
"`strdup_uniq`\n"
" : Return a new unique string\n"
" containing a copy of the contents of a unique string.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1639
msgid ""
"> **Note:** This list is likely to become out of date. We should auto-"
"generate it > from `librustc/middle/lang_items.rs`."
msgstr ""
#. type: Plain text
#: doc/rust.md:1641
msgid "### Deriving"
msgstr ""
#. type: Plain text
#: doc/rust.md:1647
msgid ""
"The `deriving` attribute allows certain traits to be automatically "
"implemented for data structures. For example, the following will create an "
"`impl` for the `Eq` and `Clone` traits for `Foo`, the type parameter `T` "
"will be given the `Eq` or `Clone` constraints for the appropriate `impl`:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1655
#, no-wrap
msgid ""
"~~~\n"
"#[deriving(Eq, Clone)]\n"
"struct Foo<T> {\n"
" a: int,\n"
" b: T\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1657
msgid "The generated `impl` for `Eq` is equivalent to"
msgstr ""
#. type: Plain text
#: doc/rust.md:1664
#, no-wrap
msgid ""
"~~~\n"
"# struct Foo<T> { a: int, b: T }\n"
"impl<T: Eq> Eq for Foo<T> {\n"
" fn eq(&self, other: &Foo<T>) -> bool {\n"
" self.a == other.a && self.b == other.b\n"
" }\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1670
#, no-wrap
msgid ""
" fn ne(&self, other: &Foo<T>) -> bool {\n"
" self.a != other.a || self.b != other.b\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1672
msgid "Supported traits for `deriving` are:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1683
msgid "Comparison traits: `Eq`, `TotalEq`, `Ord`, `TotalOrd`."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1683
msgid "Serialization: `Encodable`, `Decodable`. These require `extra`."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1683
msgid "`Clone` and `DeepClone`, to perform (deep) copies."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1683
msgid "`IterBytes`, to iterate over the bytes in a data type."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1683
msgid "`Rand`, to create a random instance of a data type."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1683
msgid "`Zero`, to create an zero (or empty) instance of a data type."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:1683
msgid ""
"`ToStr`, to convert to a string. For a type with this instance, `obj."
"to_str()` has similar output as `fmt!(\"%?\", obj)`, but it differs in that "
"each constituent field of the type must also implement `ToStr` and will have "
"`field.to_str()` invoked to build up the result."
msgstr ""
#. type: Plain text
#: doc/rust.md:1685
msgid "# Statements and expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1692
msgid ""
"Rust is _primarily_ an expression language. This means that most forms of "
"value-producing or effect-causing evaluation are directed by the uniform "
"syntax category of _expressions_. Each kind of expression can typically "
"_nest_ within each other kind of expression, and rules for evaluation of "
"expressions involve specifying both the value produced by the expression and "
"the order in which its sub-expressions are themselves evaluated."
msgstr ""
#. type: Plain text
#: doc/rust.md:1695
msgid ""
"In contrast, statements in Rust serve _mostly_ to contain and explicitly "
"sequence expression evaluation."
msgstr ""
#. type: Plain text
#: doc/rust.md:1697
msgid "## Statements"
msgstr ""
#. type: Plain text
#: doc/rust.md:1700
msgid ""
"A _statement_ is a component of a block, which is in turn a component of an "
"outer [expression](#expressions) or [function](#functions)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1704
msgid ""
"Rust has two kinds of statement: [declaration statements](#declaration-"
"statements) and [expression statements](#expression-statements)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1706
msgid "### Declaration statements"
msgstr ""
#. type: Plain text
#: doc/rust.md:1709
msgid ""
"A _declaration statement_ is one that introduces one or more *names* into "
"the enclosing statement block. The declared names may denote new slots or "
"new items."
msgstr ""
#. type: Plain text
#: doc/rust.md:1711
msgid "#### Item declarations"
msgstr ""
#. type: Plain text
#: doc/rust.md:1718
msgid ""
"An _item declaration statement_ has a syntactic form identical to an [item]"
"(#items) declaration within a module. Declaring an item -- a function, "
"enumeration, structure, type, static, trait, implementation or module -- "
"locally within a statement block is simply a way of restricting its scope to "
"a narrow region containing all of its uses; it is otherwise identical in "
"meaning to declaring the item outside the statement block."
msgstr ""
#. type: Plain text
#: doc/rust.md:1721
msgid ""
"Note: there is no implicit capture of the function's dynamic environment "
"when declaring a function-local item."
msgstr ""
#. type: Plain text
#: doc/rust.md:1724
msgid "#### Slot declarations"
msgstr ""
#. type: Plain text
#: doc/rust.md:1729
msgid ""
"~~~~~~~~{.ebnf .gram} let_decl : \"let\" pat [':' type ] ? [ init ] ? ';' ; "
"init : [ '=' ] expr ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1735
msgid ""
"A _slot declaration_ introduces a new set of slots, given by a pattern. The "
"pattern may be followed by a type annotation, and/or an initializer "
"expression. When no type annotation is given, the compiler will infer the "
"type, or signal an error if insufficient type information is available for "
"definite inference. Any slots introduced by a slot declaration are visible "
"from the point of declaration until the end of the enclosing block scope."
msgstr ""
#. type: Plain text
#: doc/rust.md:1737
msgid "### Expression statements"
msgstr ""
#. type: Plain text
#: doc/rust.md:1742
msgid ""
"An _expression statement_ is one that evaluates an [expression]"
"(#expressions) and ignores its result. The type of an expression statement "
"`e;` is always `()`, regardless of the type of `e`. As a rule, an "
"expression statement's purpose is to trigger the effects of evaluating its "
"expression."
msgstr ""
#. type: Plain text
#: doc/rust.md:1744
msgid "## Expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1753
#, no-wrap
msgid ""
"An expression may have two roles: it always produces a *value*, and it may have *effects*\n"
"(otherwise known as \"side effects\").\n"
"An expression *evaluates to* a value, and has effects during *evaluation*.\n"
"Many expressions contain sub-expressions (operands).\n"
"The meaning of each kind of expression dictates several things:\n"
" * Whether or not to evaluate the sub-expressions when evaluating the expression\n"
" * The order in which to evaluate the sub-expressions\n"
" * How to combine the sub-expressions' values to obtain the value of the expression.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1758
msgid ""
"In this way, the structure of expressions dictates the structure of "
"execution. Blocks are just another kind of expression, so blocks, "
"statements, expressions, and blocks again can recursively nest inside each "
"other to an arbitrary depth."
msgstr ""
#. type: Plain text
#: doc/rust.md:1760
msgid "#### Lvalues, rvalues and temporaries"
msgstr ""
#. type: Plain text
#: doc/rust.md:1764
msgid ""
"Expressions are divided into two main categories: _lvalues_ and _rvalues_. "
"Likewise within each expression, sub-expressions may occur in _lvalue "
"context_ or _rvalue context_. The evaluation of an expression depends both "
"on its own category and the context it occurs within."
msgstr ""
#. type: Plain text
#: doc/rust.md:1767
msgid ""
"[Path](#path-expressions), [field](#field-expressions) and [index](#index-"
"expressions) expressions are lvalues. All other expressions are rvalues."
msgstr ""
#. type: Plain text
#: doc/rust.md:1775
msgid ""
"The left operand of an [assignment](#assignment-expressions), [binary move]"
"(#binary-move-expressions) or [compound-assignment](#compound-assignment-"
"expressions) expression is an lvalue context, as is the single operand of a "
"unary [borrow](#unary-operator-expressions), or [move](#unary-move-"
"expressions) expression, and _both_ operands of a [swap](#swap-expressions) "
"expression. All other expression contexts are rvalue contexts."
msgstr ""
#. type: Plain text
#: doc/rust.md:1778
msgid ""
"When an lvalue is evaluated in an _lvalue context_, it denotes a memory "
"location; when evaluated in an _rvalue context_, it denotes the value held "
"_in_ that memory location."
msgstr ""
#. type: Plain text
#: doc/rust.md:1781
msgid ""
"When an rvalue is used in lvalue context, a temporary un-named lvalue is "
"created and used instead. A temporary's lifetime equals the largest "
"lifetime of any borrowed pointer that points to it."
msgstr ""
#. type: Plain text
#: doc/rust.md:1783
msgid "#### Moved and copied types"
msgstr ""
#. type: Plain text
#: doc/rust.md:1792
msgid ""
"When a [local variable](#memory-slots) is used as an [rvalue](#lvalues-"
"rvalues-and-temporaries) the variable will either be [moved](#move-"
"expressions) or copied, depending on its type. For types that contain "
"[owning pointers](#owning-pointers) or values that implement the special "
"trait `Drop`, the variable is moved. All other types are copied."
msgstr ""
#. type: Plain text
#: doc/rust.md:1795
msgid "### Literal expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1799
msgid ""
"A _literal expression_ consists of one of the [literal](#literals) forms "
"described earlier. It directly describes a number, character, string, "
"boolean value, or the unit value."
msgstr ""
#. type: Plain text
#: doc/rust.md:1806
#, no-wrap
msgid ""
"~~~~~~~~ {.literals}\n"
"(); // unit type\n"
"\"hello\"; // string type\n"
"'5'; // character type\n"
"5; // integer type\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1808
msgid "### Path expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1811
msgid ""
"A [path](#paths) used as an expression context denotes either a local "
"variable or an item. Path expressions are [lvalues](#lvalues-rvalues-and-"
"temporaries)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1813
msgid "### Tuple expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1817
msgid ""
"Tuples are written by enclosing one or more comma-separated expressions in "
"parentheses. They are used to create [tuple-typed](#tuple-types) values."
msgstr ""
#. type: Plain text
#: doc/rust.md:1823
msgid "~~~~~~~~ {.tuple} (0,); (0f, 4.5f); (\"a\", 4u, true); ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1825
msgid "### Structure expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1834
#, no-wrap
msgid ""
"~~~~~~~~{.ebnf .gram}\n"
"struct_expr : expr_path '{' ident ':' expr\n"
" [ ',' ident ':' expr ] *\n"
" [ \"..\" expr ] '}' |\n"
" expr_path '(' expr\n"
" [ ',' expr ] * ')' |\n"
" expr_path\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1841
msgid ""
"There are several forms of structure expressions. A _structure expression_ "
"consists of the [path](#paths) of a [structure item](#structures), followed "
"by a brace-enclosed list of one or more comma-separated name-value pairs, "
"providing the field values of a new instance of the structure. A field name "
"can be any identifier, and is separated from its value expression by a "
"colon. The location denoted by a structure field is mutable if and only if "
"the enclosing structure is mutable."
msgstr ""
#. type: Plain text
#: doc/rust.md:1846
msgid ""
"A _tuple structure expression_ consists of the [path](#paths) of a "
"[structure item](#structures), followed by a parenthesized list of one or "
"more comma-separated expressions (in other words, the path of a structure "
"item followed by a tuple expression). The structure item must be a tuple "
"structure item."
msgstr ""
#. type: Plain text
#: doc/rust.md:1848
msgid ""
"A _unit-like structure expression_ consists only of the [path](#paths) of a "
"[structure item](#structures)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1850
msgid "The following are examples of structure expressions:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1861
msgid ""
"~~~~ # struct Point { x: float, y: float } # struct TuplePoint(float, "
"float); # mod game { pub struct User<'self> { name: &'self str, age: uint, "
"score: uint } } # struct Cookie; fn some_fn<T>(t: T) {} Point {x: 10f, y: "
"20f}; TuplePoint(10f, 20f); let u = game::User {name: \"Joe\", age: 35, "
"score: 100_000}; some_fn::<Cookie>(Cookie); ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1864
msgid ""
"A structure expression forms a new value of the named structure type. Note "
"that for a given *unit-like* structure type, this will always be the same "
"value."
msgstr ""
#. type: Plain text
#: doc/rust.md:1871
msgid ""
"A structure expression can terminate with the syntax `..` followed by an "
"expression to denote a functional update. The expression following `..` "
"(the base) must have the same structure type as the new structure type being "
"formed. The entire expression denotes the result of allocating a new "
"structure (with the same type as the base expression) with the given values "
"for the fields that were explicitly specified and the values in the base "
"record for all other fields."
msgstr ""
#. type: Plain text
#: doc/rust.md:1877
msgid ""
"~~~~ # struct Point3d { x: int, y: int, z: int } let base = Point3d {x: 1, "
"y: 2, z: 3}; Point3d {y: 0, z: 10, .. base}; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1879
msgid "### Record expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1885
#, no-wrap
msgid ""
"~~~~~~~~{.ebnf .gram}\n"
"rec_expr : '{' ident ':' expr\n"
" [ ',' ident ':' expr ] *\n"
" [ \"..\" expr ] '}'\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1887
msgid "### Method-call expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1891
msgid ""
"~~~~~~~~{.ebnf .gram} method_call_expr : expr '.' ident paren_expr_list ; "
"~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1896
msgid ""
"A _method call_ consists of an expression followed by a single dot, an "
"identifier, and a parenthesized expression-list. Method calls are resolved "
"to methods on specific traits, either statically dispatching to a method if "
"the exact `self`-type of the left-hand-side is known, or dynamically "
"dispatching if the left-hand-side expression is an indirect [object type]"
"(#object-types)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1899
msgid "### Field expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1903
msgid "~~~~~~~~{.ebnf .gram} field_expr : expr '.' ident ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1907
msgid ""
"A _field expression_ consists of an expression followed by a single dot and "
"an identifier, when not immediately followed by a parenthesized expression-"
"list (the latter is a [method call expression](#method-call-expressions)). "
"A field expression denotes a field of a [structure](#structure-types)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1912
msgid "~~~~~~~~ {.field} myrecord.myfield; {a: 10, b: 20}.a; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1915
msgid ""
"A field access on a record is an [lvalue](#lvalues-rvalues-and-temporaries) "
"referring to the value of that field. When the field is mutable, it can be "
"[assigned](#assignment-expressions) to."
msgstr ""
#. type: Plain text
#: doc/rust.md:1918
msgid ""
"When the type of the expression to the left of the dot is a pointer to a "
"record or structure, it is automatically derferenced to make the field "
"access possible."
msgstr ""
#. type: Plain text
#: doc/rust.md:1921
msgid "### Vector expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1924
msgid "~~~~~~~~{.ebnf .gram} vec_expr : '[' \"mut\"? vec_elems? ']'"
msgstr ""
#. type: Plain text
#: doc/rust.md:1927
msgid "vec_elems : [expr [',' expr]*] | [expr ',' \"..\" expr] ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1930
msgid ""
"A [_vector_](#vector-types) _expression_ is written by enclosing zero or "
"more comma-separated expressions of uniform type in square brackets."
msgstr ""
#. type: Plain text
#: doc/rust.md:1934
msgid ""
"In the `[expr ',' \"..\" expr]` form, the expression after the `\"..\"` must "
"be a constant expression that can be evaluated at compile time, such as a "
"[literal](#literals) or a [static item](#static-items)."
msgstr ""
#. type: Plain text
#: doc/rust.md:1941
#, no-wrap
msgid ""
"~~~~\n"
"[1, 2, 3, 4];\n"
"[\"a\", \"b\", \"c\", \"d\"];\n"
"[0, ..128]; // vector with 128 zeros\n"
"[0u8, 0u8, 0u8, 0u8];\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1943
msgid "### Index expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1947
msgid "~~~~~~~~{.ebnf .gram} idx_expr : expr '[' expr ']' ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1952
msgid ""
"[Vector](#vector-types)-typed expressions can be indexed by writing a square-"
"bracket-enclosed expression (the index) after them. When the vector is "
"mutable, the resulting [lvalue](#lvalues-rvalues-and-temporaries) can be "
"assigned to."
msgstr ""
#. type: Plain text
#: doc/rust.md:1956
msgid ""
"Indices are zero-based, and may be of any integral type. Vector access is "
"bounds-checked at run-time. When the check fails, it will put the task in a "
"_failing state_."
msgstr ""
#. type: Plain text
#: doc/rust.md:1960
msgid "~~~~ # use std::task; # do task::spawn_unlinked {"
msgstr ""
#. type: Plain text
#: doc/rust.md:1963
msgid "([1, 2, 3, 4])[0]; ([\"a\", \"b\"])[10]; // fails"
msgstr ""
#. type: Plain text
#: doc/rust.md:1966 doc/tutorial-tasks.md:648
msgid "# } ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:1968
msgid "### Unary operator expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1972
msgid ""
"Rust defines six symbolic unary operators. They are all written as prefix "
"operators, before the expression they apply to."
msgstr ""
#. type: Plain text
#: doc/rust.md:1991
#, no-wrap
msgid ""
"`-`\n"
" : Negation. May only be applied to numeric types.\n"
"`*`\n"
" : Dereference. When applied to a [pointer](#pointer-types) it denotes the pointed-to location.\n"
" For pointers to mutable locations, the resulting [lvalue](#lvalues-rvalues-and-temporaries) can be assigned to.\n"
" For [enums](#enumerated-types) that have only a single variant, containing a single parameter,\n"
" the dereference operator accesses this parameter.\n"
"`!`\n"
" : Logical negation. On the boolean type, this flips between `true` and\n"
" `false`. On integer types, this inverts the individual bits in the\n"
" two's complement representation of the value.\n"
"`@` and `~`\n"
" : [Boxing](#pointer-types) operators. Allocate a box to hold the value they are applied to,\n"
" and store the value in it. `@` creates a managed box, whereas `~` creates an owned box.\n"
"`&`\n"
" : Borrow operator. Returns a borrowed pointer, pointing to its operand.\n"
" The operand of a borrowed pointer is statically proven to outlive the resulting pointer.\n"
" If the borrow-checker cannot prove this, it is a compilation error.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1993
msgid "### Binary operator expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:1997
msgid "~~~~~~~~{.ebnf .gram} binop_expr : expr binop expr ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2000
msgid ""
"Binary operators expressions are given in terms of [operator precedence]"
"(#operator-precedence)."
msgstr ""
#. type: Plain text
#: doc/rust.md:2002
msgid "#### Arithmetic operators"
msgstr ""
#. type: Plain text
#: doc/rust.md:2007
msgid ""
"Binary arithmetic expressions are syntactic sugar for calls to built-in "
"traits, defined in the `std::ops` module of the `std` library. This means "
"that arithmetic operators can be overridden for user-defined types. The "
"default meaning of the operators on standard types is given here."
msgstr ""
#. type: Plain text
#: doc/rust.md:2023
#, no-wrap
msgid ""
"`+`\n"
" : Addition and vector/string concatenation.\n"
" Calls the `add` method on the `std::ops::Add` trait.\n"
"`-`\n"
" : Subtraction.\n"
" Calls the `sub` method on the `std::ops::Sub` trait.\n"
"`*`\n"
" : Multiplication.\n"
" Calls the `mul` method on the `std::ops::Mul` trait.\n"
"`/`\n"
" : Quotient.\n"
" Calls the `div` method on the `std::ops::Div` trait.\n"
"`%`\n"
" : Remainder.\n"
" Calls the `rem` method on the `std::ops::Rem` trait.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2025
msgid "#### Bitwise operators"
msgstr ""
#. type: Plain text
#: doc/rust.md:2030
msgid ""
"Like the [arithmetic operators](#arithmetic-operators), bitwise operators "
"are syntactic sugar for calls to methods of built-in traits. This means "
"that bitwise operators can be overridden for user-defined types. The "
"default meaning of the operators on standard types is given here."
msgstr ""
#. type: Plain text
#: doc/rust.md:2046
#, no-wrap
msgid ""
"`&`\n"
" : And.\n"
" Calls the `bitand` method of the `std::ops::BitAnd` trait.\n"
"`|`\n"
" : Inclusive or.\n"
" Calls the `bitor` method of the `std::ops::BitOr` trait.\n"
"`^`\n"
" : Exclusive or.\n"
" Calls the `bitxor` method of the `std::ops::BitXor` trait.\n"
"`<<`\n"
" : Logical left shift.\n"
" Calls the `shl` method of the `std::ops::Shl` trait.\n"
"`>>`\n"
" : Logical right shift.\n"
" Calls the `shr` method of the `std::ops::Shr` trait.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2048
msgid "#### Lazy boolean operators"
msgstr ""
#. type: Plain text
#: doc/rust.md:2055
msgid ""
"The operators `||` and `&&` may be applied to operands of boolean type. The "
"`||` operator denotes logical 'or', and the `&&` operator denotes logical "
"'and'. They differ from `|` and `&` in that the right-hand operand is only "
"evaluated when the left-hand operand does not already determine the result "
"of the expression. That is, `||` only evaluates its right-hand operand when "
"the left-hand operand evaluates to `false`, and `&&` only when it evaluates "
"to `true`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2057
msgid "#### Comparison operators"
msgstr ""
#. type: Plain text
#: doc/rust.md:2063
msgid ""
"Comparison operators are, like the [arithmetic operators](#arithmetic-"
"operators), and [bitwise operators](#bitwise-operators), syntactic sugar for "
"calls to built-in traits. This means that comparison operators can be "
"overridden for user-defined types. The default meaning of the operators on "
"standard types is given here."
msgstr ""
#. type: Plain text
#: doc/rust.md:2082
#, no-wrap
msgid ""
"`==`\n"
" : Equal to.\n"
" Calls the `eq` method on the `std::cmp::Eq` trait.\n"
"`!=`\n"
" : Unequal to.\n"
" Calls the `ne` method on the `std::cmp::Eq` trait.\n"
"`<`\n"
" : Less than.\n"
" Calls the `lt` method on the `std::cmp::Ord` trait.\n"
"`>`\n"
" : Greater than.\n"
" Calls the `gt` method on the `std::cmp::Ord` trait.\n"
"`<=`\n"
" : Less than or equal.\n"
" Calls the `le` method on the `std::cmp::Ord` trait.\n"
"`>=`\n"
" : Greater than or equal.\n"
" Calls the `ge` method on the `std::cmp::Ord` trait.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2085
msgid "#### Type cast expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2087
msgid "A type cast expression is denoted with the binary operator `as`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2090
msgid ""
"Executing an `as` expression casts the value on the left-hand side to the "
"type on the right-hand side."
msgstr ""
#. type: Plain text
#: doc/rust.md:2094
msgid ""
"A numeric value can be cast to any numeric type. A raw pointer value can be "
"cast to or from any integral type or raw pointer type. Any other cast is "
"unsupported and will fail to compile."
msgstr ""
#. type: Plain text
#: doc/rust.md:2096
msgid "An example of an `as` expression:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2100
msgid ""
"~~~~ # fn sum(v: &[float]) -> float { 0.0 } # fn len(v: &[float]) -> int "
"{ 0 }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2107
#, no-wrap
msgid ""
"fn avg(v: &[float]) -> float {\n"
" let sum: float = sum(v);\n"
" let sz: float = len(v) as float;\n"
" return sum / sz;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2109
msgid "#### Assignment expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2112
msgid ""
"An _assignment expression_ consists of an [lvalue](#lvalues-rvalues-and-"
"temporaries) expression followed by an equals sign (`=`) and an [rvalue]"
"(#lvalues-rvalues-and-temporaries) expression."
msgstr ""
#. type: Plain text
#: doc/rust.md:2114
msgid ""
"Evaluating an assignment expression [either copies or moves](#moved-and-"
"copied-types) its right-hand operand to its left-hand operand."
msgstr ""
#. type: Plain text
#: doc/rust.md:2118
msgid "~~~~ # let mut x = 0; # let y = 0;"
msgstr ""
#. type: Plain text
#: doc/rust.md:2121
msgid "x = y; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2123
msgid "#### Compound assignment expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2128
msgid ""
"The `+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `<<`, and `>>` operators may be "
"composed with the `=` operator. The expression `lval OP= val` is equivalent "
"to `lval = lval OP val`. For example, `x = x + 1` may be written as `x += 1`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2130
msgid "Any such expression always has the [`unit`](#primitive-types) type."
msgstr ""
#. type: Plain text
#: doc/rust.md:2132
msgid "#### Operator precedence"
msgstr ""
#. type: Plain text
#: doc/rust.md:2135
msgid ""
"The precedence of Rust binary operators is ordered as follows, going from "
"strong to weak:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2148
#, no-wrap
msgid ""
"~~~~ {.precedence}\n"
"* / %\n"
"as\n"
"+ -\n"
"<< >>\n"
"&\n"
"^\n"
"|\n"
"< > <= >=\n"
"== !=\n"
"&&\n"
"||\n"
"=\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2150 doc/rust.md:2237 doc/tutorial-macros.md:323
msgid "~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2153
msgid ""
"Operators at the same precedence level are evaluated left-to-right. [Unary "
"operators](#unary-operator-expressions) have the same precedence level and "
"it is stronger than any of the binary operators'."
msgstr ""
#. type: Plain text
#: doc/rust.md:2155
msgid "### Grouped expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2159
msgid ""
"An expression enclosed in parentheses evaluates to the result of the "
"enclosed expression. Parentheses can be used to explicitly specify "
"evaluation order within an expression."
msgstr ""
#. type: Plain text
#: doc/rust.md:2163
msgid "~~~~~~~~{.ebnf .gram} paren_expr : '(' expr ')' ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2165
msgid "An example of a parenthesized expression:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2169
msgid "~~~~ let x = (2 + 3) * 4; ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2172
msgid "### Call expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2178
msgid ""
"~~~~~~~~ {.abnf .gram} expr_list : [ expr [ ',' expr ]* ] ? ; "
"paren_expr_list : '(' expr_list ')' ; call_expr : expr paren_expr_list ; "
"~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2183
msgid ""
"A _call expression_ invokes a function, providing zero or more input slots "
"and an optional reference slot to serve as the function's output, bound to "
"the `lval` on the right hand side of the call. If the function eventually "
"returns, then the expression completes."
msgstr ""
#. type: Plain text
#: doc/rust.md:2185
msgid "Some examples of call expressions:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2189
msgid ""
"~~~~ # use std::from_str::FromStr; # fn add(x: int, y: int) -> int { 0 }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2193
msgid ""
"let x: int = add(1, 2); let pi = FromStr::from_str::<f32>(\"3.14\"); ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2195
msgid "### Lambda expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2200
msgid ""
"~~~~~~~~ {.abnf .gram} ident_list : [ ident [ ',' ident ]* ] ? ; "
"lambda_expr : '|' ident_list '|' expr ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2204
msgid ""
"A _lambda expression_ (sometimes called an \"anonymous function expression"
"\") defines a function and denotes it as a value, in a single expression. A "
"lambda expression is a pipe-symbol-delimited (`|`) list of identifiers "
"followed by an expression."
msgstr ""
#. type: Plain text
#: doc/rust.md:2209
msgid ""
"A lambda expression denotes a function that maps a list of parameters "
"(`ident_list`) onto the expression that follows the `ident_list`. The "
"identifiers in the `ident_list` are the parameters to the function. These "
"parameters' types need not be specified, as the compiler infers them from "
"context."
msgstr ""
#. type: Plain text
#: doc/rust.md:2212
msgid ""
"Lambda expressions are most useful when passing functions as arguments to "
"other functions, as an abbreviation for defining and capturing a separate "
"function."
msgstr ""
#. type: Plain text
#: doc/rust.md:2221
msgid ""
"Significantly, lambda expressions _capture their environment_, which regular "
"[function definitions](#functions) do not. The exact type of capture "
"depends on the [function type](#function-types) inferred for the lambda "
"expression. In the simplest and least-expensive form (analogous to a "
"```|| { }``` expression), the lambda expression captures its environment "
"by reference, effectively borrowing pointers to all outer variables "
"mentioned inside the function. Alternately, the compiler may infer that a "
"lambda expression should copy or move values (depending on their type.) "
"from the environment into the lambda expression's captured environment."
msgstr ""
#. type: Plain text
#: doc/rust.md:2224
msgid ""
"In this example, we define a function `ten_times` that takes a higher-order "
"function argument, and call it with a lambda expression as an argument."
msgstr ""
#. type: Plain text
#: doc/rust.md:2233
#, no-wrap
msgid ""
"~~~~\n"
"fn ten_times(f: |int|) {\n"
" let mut i = 0;\n"
" while i < 10 {\n"
" f(i);\n"
" i += 1;\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2235
msgid "ten_times(|j| println(fmt!(\"hello, %d\", j)));"
msgstr ""
#. type: Plain text
#: doc/rust.md:2239
msgid "### While loops"
msgstr ""
#. type: Plain text
#: doc/rust.md:2243
msgid ""
"~~~~~~~~{.ebnf .gram} while_expr : \"while\" expr '{' block '}' ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2248
msgid ""
"A `while` loop begins by evaluating the boolean loop conditional "
"expression. If the loop conditional expression evaluates to `true`, the "
"loop body block executes and control returns to the loop conditional "
"expression. If the loop conditional expression evaluates to `false`, the "
"`while` expression completes."
msgstr ""
#. type: Plain text
#: doc/rust.md:2250
msgid "An example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2253
msgid "~~~~ let mut i = 0;"
msgstr ""
#. type: Plain text
#: doc/rust.md:2259
#, no-wrap
msgid ""
"while i < 10 {\n"
" println(\"hello\\n\");\n"
" i = i + 1;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2261
msgid "### Infinite loops"
msgstr ""
#. type: Plain text
#: doc/rust.md:2265
msgid ""
"The keyword `loop` in Rust appears both in _loop expressions_ and in "
"_continue expressions_. A loop expression denotes an infinite loop; see "
"[Continue expressions](#continue-expressions) for continue expressions."
msgstr ""
#. type: Plain text
#: doc/rust.md:2269
msgid ""
"~~~~~~~~{.ebnf .gram} loop_expr : [ lifetime ':' ] \"loop\" '{' block '}'; "
"~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2274
msgid ""
"A `loop` expression may optionally have a _label_. If a label is present, "
"then labeled `break` and `loop` expressions nested within this loop may exit "
"out of this loop or return control to its head. See [Break expressions]"
"(#break-expressions)."
msgstr ""
#. type: Plain text
#: doc/rust.md:2276
msgid "### Break expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2280
msgid "~~~~~~~~{.ebnf .gram} break_expr : \"break\" [ lifetime ]; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2287
msgid ""
"A `break` expression has an optional `label`. If the label is absent, then "
"executing a `break` expression immediately terminates the innermost loop "
"enclosing it. It is only permitted in the body of a loop. If the label is "
"present, then `break foo` terminates the loop with label `foo`, which need "
"not be the innermost label enclosing the `break` expression, but must "
"enclose it."
msgstr ""
#. type: Plain text
#: doc/rust.md:2289
msgid "### Continue expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2293
msgid "~~~~~~~~{.ebnf .gram} continue_expr : \"loop\" [ lifetime ]; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2304
msgid ""
"A continue expression, written `loop`, also has an optional `label`. If the "
"label is absent, then executing a `loop` expression immediately terminates "
"the current iteration of the innermost loop enclosing it, returning control "
"to the loop *head*. In the case of a `while` loop, the head is the "
"conditional expression controlling the loop. In the case of a `for` loop, "
"the head is the call-expression controlling the loop. If the label is "
"present, then `loop foo` returns control to the head of the loop with label "
"`foo`, which need not be the innermost label enclosing the `break` "
"expression, but must enclose it."
msgstr ""
#. type: Plain text
#: doc/rust.md:2306
msgid "A `loop` expression is only permitted in the body of a loop."
msgstr ""
#. type: Plain text
#: doc/rust.md:2309
msgid "### Do expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2313
msgid ""
"~~~~~~~~{.ebnf .gram} do_expr : \"do\" expr [ '|' ident_list '|' ] ? '{' "
"block '}' ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2316
msgid ""
"A _do expression_ provides a more-familiar block-syntax for a [lambda "
"expression](#lambda-expressions), including a special translation of [return "
"expressions](#return-expressions) inside the supplied block."
msgstr ""
#. type: Plain text
#: doc/rust.md:2324
msgid ""
"Any occurrence of a [return expression](#return-expressions) inside this "
"`block` expression is rewritten as a reference to an (anonymous) flag set in "
"the caller's environment, which is checked on return from the `expr` and, if "
"set, causes a corresponding return from the caller. In this way, the "
"meaning of `return` statements in language built-in control blocks is "
"preserved, if they are rewritten using lambda functions and `do` expressions "
"as abstractions."
msgstr ""
#. type: Plain text
#: doc/rust.md:2327
msgid ""
"The optional `ident_list` and `block` provided in a `do` expression are "
"parsed as though they constitute a lambda expression; if the `ident_list` is "
"missing, an empty `ident_list` is implied."
msgstr ""
#. type: Plain text
#: doc/rust.md:2333
msgid ""
"The lambda expression is then provided as a _trailing argument_ to the "
"outermost [call](#call-expressions) or [method call](#method-call-"
"expressions) expression in the `expr` following `do`. If the `expr` is a "
"[path expression](#path-expressions), it is parsed as though it is a call "
"expression. If the `expr` is a [field expression](#field-expressions), it "
"is parsed as though it is a method call expression."
msgstr ""
#. type: Plain text
#: doc/rust.md:2335
msgid "In this example, both calls to `f` are equivalent:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2339
msgid "~~~~ # fn f(f: |int|) { } # fn g(i: int) { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2341
msgid "f(|j| g(j));"
msgstr ""
#. type: Plain text
#: doc/rust.md:2346
#, no-wrap
msgid ""
"do f |j| {\n"
" g(j);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2348
msgid ""
"In this example, both calls to the (binary) function `k` are equivalent:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2352
msgid "~~~~ # fn k(x:int, f: |int|) { } # fn l(i: int) { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2354
msgid "k(3, |j| l(j));"
msgstr ""
#. type: Plain text
#: doc/rust.md:2359
#, no-wrap
msgid ""
"do k(3) |j| {\n"
" l(j);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2362
msgid "### For expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2366
msgid ""
"~~~~~~~~{.ebnf .gram} for_expr : \"for\" expr [ '|' ident_list '|' ] ? '{' "
"block '}' ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2370
msgid ""
"A _for expression_ is similar to a [`do` expression](#do-expressions), in "
"that it provides a special block-form of lambda expression, suited to "
"passing the `block` function to a higher-order function implementing a loop."
msgstr ""
#. type: Plain text
#: doc/rust.md:2376
msgid ""
"In contrast to a `do` expression, a `for` expression is designed to work "
"with methods such as `each` and `times`, that require the body block to "
"return a boolean. The `for` expression accommodates this by implicitly "
"returning `true` at the end of each block, unless a `break` expression is "
"evaluated."
msgstr ""
#. type: Plain text
#: doc/rust.md:2383
msgid ""
"In addition, [`break`](#break-expressions) and [`loop`](#loop-expressions) "
"expressions are rewritten inside `for` expressions in the same way that "
"`return` expressions are, with a combination of local flag variables, and "
"early boolean-valued returns from the `block` function, such that the "
"meaning of `break` and `loop` is preserved in a primitive loop when "
"rewritten as a `for` loop controlled by a higher order function."
msgstr ""
#. type: Plain text
#: doc/rust.md:2385
msgid "An example of a for loop over the contents of a vector:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2392
msgid ""
"~~~~ # type foo = int; # fn bar(f: foo) { } # let a = 0; # let b = 0; # let "
"c = 0;"
msgstr ""
#. type: Plain text
#: doc/rust.md:2394
msgid "let v: &[foo] = &[a, b, c];"
msgstr ""
#. type: Plain text
#: doc/rust.md:2399
#, no-wrap
msgid ""
"for e in v.iter() {\n"
" bar(*e);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2401
msgid "An example of a for loop over a series of integers:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2408
#, no-wrap
msgid ""
"~~~~\n"
"# fn bar(b:uint) { }\n"
"for i in range(0u, 256) {\n"
" bar(i);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2410
msgid "### If expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2414
#, no-wrap
msgid ""
"~~~~~~~~{.ebnf .gram}\n"
"if_expr : \"if\" expr '{' block '}'\n"
" else_tail ? ;\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2418
#, no-wrap
msgid ""
"else_tail : \"else\" [ if_expr\n"
" | '{' block '}' ] ;\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2429
msgid ""
"An `if` expression is a conditional branch in program control. The form of "
"an `if` expression is a condition expression, followed by a consequent "
"block, any number of `else if` conditions and blocks, and an optional "
"trailing `else` block. The condition expressions must have type `bool`. If a "
"condition expression evaluates to `true`, the consequent block is executed "
"and any subsequent `else if` or `else` block is skipped. If a condition "
"expression evaluates to `false`, the consequent block is skipped and any "
"subsequent `else if` condition is evaluated. If all `if` and `else if` "
"conditions evaluate to `false` then any `else` block is executed."
msgstr ""
#. type: Plain text
#: doc/rust.md:2432
msgid "### Match expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2435
msgid ""
"~~~~~~~~{.ebnf .gram} match_expr : \"match\" expr '{' match_arm [ '|' "
"match_arm ] * '}' ;"
msgstr ""
#. type: Plain text
#: doc/rust.md:2437
msgid "match_arm : match_pat '=>' [ expr \",\" | '{' block '}' ] ;"
msgstr ""
#. type: Plain text
#: doc/rust.md:2440
msgid "match_pat : pat [ \"..\" pat ] ? [ \"if\" expr ] ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2448
msgid ""
"A `match` expression branches on a *pattern*. The exact form of matching "
"that occurs depends on the pattern. Patterns consist of some combination of "
"literals, destructured enum constructors, structures, records and tuples, "
"variable binding specifications, wildcards (`*`), and placeholders (`_`). A "
"`match` expression has a *head expression*, which is the value to compare to "
"the patterns. The type of the patterns must equal the type of the head "
"expression."
msgstr ""
#. type: Plain text
#: doc/rust.md:2452
msgid ""
"In a pattern whose head expression has an `enum` type, a placeholder (`_`) "
"stands for a *single* data field, whereas a wildcard `*` stands for *all* "
"the fields of a particular variant. For example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2455
msgid "~~~~ enum List<X> { Nil, Cons(X, @List<X>) }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2457 doc/rust.md:2486
msgid "let x: List<int> = Cons(10, @Cons(11, @Nil));"
msgstr ""
#. type: Plain text
#: doc/rust.md:2464
#, no-wrap
msgid ""
"match x {\n"
" Cons(_, @Nil) => fail!(\"singleton list\"),\n"
" Cons(*) => return,\n"
" Nil => fail!(\"empty list\")\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2469
msgid ""
"The first pattern matches lists constructed by applying `Cons` to any head "
"value, and a tail value of `@Nil`. The second pattern matches _any_ list "
"constructed with `Cons`, ignoring the values of its arguments. The "
"difference between `_` and `*` is that the pattern `C(_)` is only type-"
"correct if `C` has exactly one argument, while the pattern `C(*)` is type-"
"correct for any enum variant `C`, regardless of how many arguments `C` has."
msgstr ""
#. type: Plain text
#: doc/rust.md:2475
msgid ""
"To execute an `match` expression, first the head expression is evaluated, "
"then its value is sequentially compared to the patterns in the arms until a "
"match is found. The first arm with a matching pattern is chosen as the "
"branch target of the `match`, any variables bound by the pattern are "
"assigned to local variables in the arm's block, and control enters the block."
msgstr ""
#. type: Plain text
#: doc/rust.md:2477
msgid "An example of an `match` expression:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2482
msgid "~~~~ # fn process_pair(a: int, b: int) { } # fn process_ten() { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2484
msgid "enum List<X> { Nil, Cons(X, @List<X>) }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2502
#, no-wrap
msgid ""
"match x {\n"
" Cons(a, @Cons(b, _)) => {\n"
" process_pair(a,b);\n"
" }\n"
" Cons(10, _) => {\n"
" process_ten();\n"
" }\n"
" Nil => {\n"
" return;\n"
" }\n"
" _ => {\n"
" fail!();\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2509
msgid ""
"Patterns that bind variables default to binding to a copy or move of the "
"matched value (depending on the matched value's type). This can be changed "
"to bind to a borrowed pointer by using the ```ref``` keyword, or to a "
"mutable borrowed pointer using ```ref mut```."
msgstr ""
#. type: Plain text
#: doc/rust.md:2520
msgid ""
"A pattern that's just an identifier, like `Nil` in the previous answer, "
"could either refer to an enum variant that's in scope, or bind a new "
"variable. The compiler resolves this ambiguity by forbidding variable "
"bindings that occur in ```match``` patterns from shadowing names of variants "
"that are in scope. For example, wherever ```List``` is in scope, a "
"```match``` pattern would not be able to bind ```Nil``` as a new name. The "
"compiler interprets a variable pattern `x` as a binding _only_ if there is "
"no variant named `x` in scope. A convention you can use to avoid conflicts "
"is simply to name variants with upper-case letters, and local variables with "
"lower-case letters."
msgstr ""
#. type: Plain text
#: doc/rust.md:2524
msgid ""
"Multiple match patterns may be joined with the `|` operator. A range of "
"values may be specified with `..`. For example:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2527
msgid "~~~~ # let x = 2;"
msgstr ""
#. type: Plain text
#: doc/rust.md:2534
#, no-wrap
msgid ""
"let message = match x {\n"
" 0 | 1 => \"not many\",\n"
" 2 .. 9 => \"a few\",\n"
" _ => \"lots\"\n"
"};\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2538
msgid ""
"Range patterns only work on scalar types (like integers and characters; not "
"like vectors and structs, which have sub-components). A range pattern may "
"not be a sub-range of another range pattern inside the same `match`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2543
msgid ""
"Finally, match patterns can accept *pattern guards* to further refine the "
"criteria for matching a case. Pattern guards appear after the pattern and "
"consist of a bool-typed expression following the `if` keyword. A pattern "
"guard may refer to the variables bound within the pattern they follow."
msgstr ""
#. type: Plain text
#: doc/rust.md:2548
msgid ""
"~~~~ # let maybe_digit = Some(0); # fn process_digit(i: int) { } # fn "
"process_other(i: int) { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:2555
#, no-wrap
msgid ""
"let message = match maybe_digit {\n"
" Some(x) if x < 10 => process_digit(x),\n"
" Some(x) => process_other(x),\n"
" None => fail!()\n"
"};\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2557
msgid "### Return expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:2561
msgid "~~~~~~~~{.ebnf .gram} return_expr : \"return\" expr ? ; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2566
msgid ""
"Return expressions are denoted with the keyword `return`. Evaluating a "
"`return` expression moves its argument into the output slot of the current "
"function, destroys the current function activation frame, and transfers "
"control to the caller frame."
msgstr ""
#. type: Plain text
#: doc/rust.md:2568
msgid "An example of a `return` expression:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2577
#, no-wrap
msgid ""
"~~~~\n"
"fn max(a: int, b: int) -> int {\n"
" if a > b {\n"
" return a;\n"
" }\n"
" return b;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2580
msgid "# Type system"
msgstr ""
#. type: Plain text
#: doc/rust.md:2582
msgid "## Types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2585
msgid ""
"Every slot, item and value in a Rust program has a type. The _type_ of a "
"*value* defines the interpretation of the memory holding it."
msgstr ""
#. type: Plain text
#: doc/rust.md:2589
msgid ""
"Built-in types and type-constructors are tightly integrated into the "
"language, in nontrivial ways that are not possible to emulate in user-"
"defined types. User-defined types have limited capabilities."
msgstr ""
#. type: Plain text
#: doc/rust.md:2591
msgid "### Primitive types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2593
msgid "The primitive types are the following:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2599
msgid ""
"The \"unit\" type `()`, having the single \"unit\" value `()` (occasionally "
"called \"nil\"). ^[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.]"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2599
msgid "The boolean type `bool` with values `true` and `false`."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2599
msgid "The machine types."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2599
msgid "The machine-dependent integer and floating-point types."
msgstr ""
#. type: Plain text
#: doc/rust.md:2601
msgid "#### Machine types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2603
msgid "The machine types are the following:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2608
msgid ""
"The unsigned word types `u8`, `u16`, `u32` and `u64`, with values drawn from "
"the integer intervals $[0, 2^8 - 1]$, $[0, 2^{16} - 1]$, $[0, 2^{32} - 1]$ "
"and $[0, 2^{64} - 1]$ respectively."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2613
msgid ""
"The signed two's complement word types `i8`, `i16`, `i32` and `i64`, with "
"values drawn from the integer intervals $[-(2^7), 2^7 - 1]$, $[-(2^{15}), "
"2^{15} - 1]$, $[-(2^{31}), 2^{31} - 1]$, $[-(2^{63}), 2^{63} - 1]$ "
"respectively."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2616
msgid ""
"The IEEE 754-2008 `binary32` and `binary64` floating-point types: `f32` and "
"`f64`, respectively."
msgstr ""
#. type: Plain text
#: doc/rust.md:2618
msgid "#### Machine-dependent integer types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2623
msgid ""
"The Rust type `uint`^[A Rust `uint` is analogous to a C99 `uintptr_t`.] is "
"an unsigned integer type with target-machine-dependent size. Its size, in "
"bits, is equal to the number of bits required to hold any memory address on "
"the target machine."
msgstr ""
#. type: Plain text
#: doc/rust.md:2628
msgid ""
"The Rust type `int`^[A Rust `int` is analogous to a C99 `intptr_t`.] is a "
"two's complement signed integer type with target-machine-dependent size. Its "
"size, in bits, is equal to the size of the rust type `uint` on the same "
"target machine."
msgstr ""
#. type: Plain text
#: doc/rust.md:2631
msgid "#### Machine-dependent floating point type"
msgstr ""
#. type: Plain text
#: doc/rust.md:2638
msgid ""
"The Rust type `float` is a machine-specific type equal to one of the "
"supported Rust floating-point machine types (`f32` or `f64`). It is the "
"largest floating-point type that is directly supported by hardware on the "
"target machine, or if the target machine has no floating-point hardware "
"support, the largest floating-point type supported by the software floating-"
"point library used to support the other floating-point machine types."
msgstr ""
#. type: Plain text
#: doc/rust.md:2641
msgid ""
"Note that due to the preference for hardware-supported floating-point, the "
"type `float` may not be equal to the largest *supported* floating-point type."
msgstr ""
#. type: Plain text
#: doc/rust.md:2644
msgid "### Textual types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2646
msgid "The types `char` and `str` hold textual data."
msgstr ""
#. type: Plain text
#: doc/rust.md:2649
msgid ""
"A value of type `char` is a Unicode character, represented as a 32-bit "
"unsigned word holding a UCS-4 codepoint."
msgstr ""
#. type: Plain text
#: doc/rust.md:2655
msgid ""
"A value of type `str` is a Unicode string, represented as a vector of 8-bit "
"unsigned bytes holding a sequence of UTF-8 codepoints. Since `str` is of "
"unknown size, it is not a _first class_ type, but can only be instantiated "
"through a pointer type, such as `&str`, `@str` or `~str`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2658
msgid "### Tuple types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2661
msgid ""
"The tuple type-constructor forms a new heterogeneous product of values "
"similar to the record type-constructor. The differences are as follows:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2664
msgid "tuple elements cannot be mutable, unlike record fields"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:2664
msgid ""
"tuple elements are not named and can be accessed only by pattern-matching"
msgstr ""
#. type: Plain text
#: doc/rust.md:2668
msgid ""
"Tuple types and values are denoted by listing the types or values of their "
"elements, respectively, in a parenthesized, comma-separated list."
msgstr ""
#. type: Plain text
#: doc/rust.md:2671
msgid ""
"The members of a tuple are laid out in memory contiguously, like a record, "
"in order specified by the tuple type."
msgstr ""
#. type: Plain text
#: doc/rust.md:2673
msgid "An example of a tuple type and its use:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2680
msgid ""
"~~~~ type Pair<'self> = (int,&'self str); let p: Pair<'static> = (10,\"hello"
"\"); let (a, b) = p; assert!(b != \"world\"); ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2683
msgid "### Vector types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2696
msgid ""
"The vector type constructor represents a homogeneous array of values of a "
"given type. A vector has a fixed size. (Operations like `vec.push` operate "
"solely on owned vectors.) A vector type can be annotated with a _definite_ "
"size, written with a trailing asterisk and integer literal, such as `[int * "
"10]`. Such a definite-sized vector type is a first-class type, since its "
"size is known statically. A vector without such a size is said to be of "
"_indefinite_ size, and is therefore not a _first-class_ type. An indefinite-"
"size vector can only be instantiated through a pointer type, such as `&[T]`, "
"`@[T]` or `~[T]`. The kind of a vector type depends on the kind of its "
"element type, as with other simple structural types."
msgstr ""
#. type: Plain text
#: doc/rust.md:2700
msgid ""
"Expressions producing vectors of definite size cannot be evaluated in a "
"context expecting a vector of indefinite size; one must copy the definite-"
"sized vector contents into a distinct vector of indefinite size."
msgstr ""
#. type: Plain text
#: doc/rust.md:2702
msgid "An example of a vector type and its use:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2708
msgid ""
"~~~~ let v: &[int] = &[7, 5, 3]; let i: int = v[2]; assert!(i == 3); ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2711
msgid ""
"All in-bounds elements of a vector are always initialized, and access to a "
"vector is always bounds-checked."
msgstr ""
#. type: Plain text
#: doc/rust.md:2714
msgid "### Structure types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2719
msgid ""
"A `struct` *type* is a heterogeneous product of other types, called the "
"*fields* of the type. ^[`struct` types are analogous `struct` types in C, "
"the *record* types of the ML family, or the *structure* types of the Lisp "
"family.]"
msgstr ""
#. type: Plain text
#: doc/rust.md:2721
msgid ""
"New instances of a `struct` can be constructed with a [struct expression]"
"(#struct-expressions)."
msgstr ""
#. type: Plain text
#: doc/rust.md:2725
msgid ""
"The memory order of fields in a `struct` is given by the item defining it. "
"Fields may be given in any order in a corresponding struct *expression*; the "
"resulting `struct` value will always be laid out in memory in the order "
"specified by the corresponding *item*."
msgstr ""
#. type: Plain text
#: doc/rust.md:2728
msgid ""
"The fields of a `struct` may be qualified by [visibility modifiers]"
"(#visibility-modifiers), to restrict access to implementation-private data "
"in a structure."
msgstr ""
#. type: Plain text
#: doc/rust.md:2730
msgid ""
"A _tuple struct_ type is just like a structure type, except that the fields "
"are anonymous."
msgstr ""
#. type: Plain text
#: doc/rust.md:2733
msgid ""
"A _unit-like struct_ type is like a structure type, except that it has no "
"fields. The one value constructed by the associated [structure expression]"
"(#structure-expression) is the only value that inhabits such a type."
msgstr ""
#. type: Plain text
#: doc/rust.md:2735
msgid "### Enumerated types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2740
msgid ""
"An *enumerated type* is a nominal, heterogeneous disjoint union type, "
"denoted by the name of an [`enum` item](#enumerations). ^[The `enum` type "
"is analogous to a `data` constructor declaration in ML, or a *pick ADT* in "
"Limbo.]"
msgstr ""
#. type: Plain text
#: doc/rust.md:2743
msgid ""
"An [`enum` item](#enumerations) declares both the type and a number of "
"*variant constructors*, each of which is independently named and takes an "
"optional tuple of arguments."
msgstr ""
#. type: Plain text
#: doc/rust.md:2746
msgid ""
"New instances of an `enum` can be constructed by calling one of the variant "
"constructors, in a [call expression](#call-expressions)."
msgstr ""
#. type: Plain text
#: doc/rust.md:2748
msgid ""
"Any `enum` value consumes as much memory as the largest variant constructor "
"for its corresponding `enum` type."
msgstr ""
#. type: Plain text
#: doc/rust.md:2751
msgid ""
"Enum types cannot be denoted *structurally* as types, but must be denoted by "
"named reference to an [`enum` item](#enumerations)."
msgstr ""
#. type: Plain text
#: doc/rust.md:2754
msgid "### Recursive types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2758
msgid ""
"Nominal types -- [enumerations](#enumerated-types) and [structures]"
"(#structure-types) -- may be recursive. That is, each `enum` constructor or "
"`struct` field may refer, directly or indirectly, to the enclosing `enum` or "
"`struct` type itself. Such recursion has restrictions:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2768
#, no-wrap
msgid ""
"* Recursive types must include a nominal type in the recursion\n"
" (not mere [type definitions](#type-definitions),\n"
" or other structural types such as [vectors](#vector-types) or [tuples](#tuple-types)).\n"
"* A recursive `enum` item must have at least one non-recursive constructor\n"
" (in order to give the recursion a basis case).\n"
"* The size of a recursive type must be finite;\n"
" in other words the recursive fields of the type must be [pointer types](#pointer-types).\n"
"* Recursive type definitions can cross module boundaries, but not module *visibility* boundaries,\n"
" or crate boundaries (in order to simplify the module system and type checker).\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2770
msgid "An example of a *recursive* type and its use:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2776
#, no-wrap
msgid ""
"~~~~\n"
"enum List<T> {\n"
" Nil,\n"
" Cons(T, @List<T>)\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2779
msgid "let a: List<int> = Cons(7, @Cons(13, @Nil)); ~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2782
msgid "### Pointer types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2786
msgid ""
"All pointers in Rust are explicit first-class values. They can be copied, "
"stored into data structures, and returned from functions. There are four "
"varieties of pointer in Rust:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2796
#, no-wrap
msgid ""
"Managed pointers (`@`)\n"
" : These point to managed heap allocations (or \"boxes\") in the task-local, managed heap.\n"
" Managed pointers are written `@content`,\n"
" for example `@int` means a managed pointer to a managed box containing an integer.\n"
" Copying a managed pointer is a \"shallow\" operation:\n"
" it involves only copying the pointer itself\n"
" (as well as any reference-count or GC-barriers required by the managed heap).\n"
" Dropping a managed pointer does not necessarily release the box it points to;\n"
" the lifecycles of managed boxes are subject to an unspecified garbage collection algorithm.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2805
#, no-wrap
msgid ""
"Owning pointers (`~`)\n"
" : These point to owned heap allocations (or \"boxes\") in the shared, inter-task heap.\n"
" Each owned box has a single owning pointer; pointer and pointee retain a 1:1 relationship at all times.\n"
" Owning pointers are written `~content`,\n"
" for example `~int` means an owning pointer to an owned box containing an integer.\n"
" Copying an owned box is a \"deep\" operation:\n"
" it involves allocating a new owned box and copying the contents of the old box into the new box.\n"
" Releasing an owning pointer immediately releases its corresponding owned box.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2818
#, no-wrap
msgid ""
"Borrowed pointers (`&`)\n"
" : These point to memory _owned by some other value_.\n"
" Borrowed pointers arise by (automatic) conversion from owning pointers, managed pointers,\n"
" or by applying the borrowing operator `&` to some other value,\n"
" including [lvalues, rvalues or temporaries](#lvalues-rvalues-and-temporaries).\n"
" Borrowed pointers are written `&content`, or in some cases `&f/content` for some lifetime-variable `f`,\n"
" for example `&int` means a borrowed pointer to an integer.\n"
" Copying a borrowed pointer is a \"shallow\" operation:\n"
" it involves only copying the pointer itself.\n"
" Releasing a borrowed pointer typically has no effect on the value it points to,\n"
" with the exception of temporary values,\n"
" which are released when the last borrowed pointer to them is released.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2828
#, no-wrap
msgid ""
"Raw pointers (`*`)\n"
" : Raw pointers are pointers without safety or liveness guarantees.\n"
" Raw pointers are written `*content`,\n"
" for example `*int` means a raw pointer to an integer.\n"
" Copying or dropping a raw pointer is has no effect on the lifecycle of any other value.\n"
" Dereferencing a raw pointer or converting it to any other pointer type is an [`unsafe` operation](#unsafe-functions).\n"
" Raw pointers are generally discouraged in Rust code;\n"
" they exist to support interoperability with foreign code,\n"
" and writing performance-critical or low-level functions.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2831
msgid "### Function types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2835
msgid ""
"The function type constructor `fn` forms new function types. A function "
"type consists of a possibly-empty set of function-type modifiers (such as "
"`unsafe` or `extern`), a sequence of input types and an output type."
msgstr ""
#. type: Plain text
#: doc/rust.md:2837
msgid "An example of a `fn` type:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2842
#, no-wrap
msgid ""
"~~~~~~~~\n"
"fn add(x: int, y: int) -> int {\n"
" return x + y;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2844
msgid "let mut x = add(5,7);"
msgstr ""
#. type: Plain text
#: doc/rust.md:2849
msgid ""
"type Binop<'self> = 'self |int,int| -> int; let bo: Binop = add; x = "
"bo(5,7); ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:2851
msgid "### Object types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2858
msgid ""
"Every trait item (see [traits](#traits)) defines a type with the same name "
"as the trait. This type is called the _object type_ of the trait. Object "
"types permit \"late binding\" of methods, dispatched using _virtual method "
"tables_ (\"vtables\"). Whereas most calls to trait methods are \"early bound"
"\" (statically resolved) to specific implementations at compile time, a call "
"to a method on an object type is only resolved to a vtable entry at compile "
"time. The actual implementation for each vtable entry can vary on an object-"
"by-object basis."
msgstr ""
#. type: Plain text
#: doc/rust.md:2863
msgid ""
"Given a pointer-typed expression `E` of type `&T`, `~T` or `@T`, where `T` "
"implements trait `R`, casting `E` to the corresponding pointer type `&R`, "
"`~R` or `@R` results in a value of the _object type_ `R`. This result is "
"represented as a pair of pointers: the vtable pointer for the `T` "
"implementation of `R`, and the pointer value of `E`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2865
msgid "An example of an object type:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2871
#, no-wrap
msgid ""
"~~~~~~~~\n"
"# use std::int;\n"
"trait Printable {\n"
" fn to_str(&self) -> ~str;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2875
#, no-wrap
msgid ""
"impl Printable for int {\n"
" fn to_str(&self) -> ~str { int::to_str(*self) }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2879
#, no-wrap
msgid ""
"fn print(a: @Printable) {\n"
" println(a.to_str());\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2884
#, no-wrap
msgid ""
"fn main() {\n"
" print(@10 as @Printable);\n"
"}\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2887
msgid ""
"In this example, the trait `Printable` occurs as an object type in both the "
"type signature of `print`, and the cast expression in `main`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2889
msgid "### Type parameters"
msgstr ""
#. type: Plain text
#: doc/rust.md:2891
msgid ""
"Within the body of an item that has type parameter declarations, the names "
"of its type parameters are types:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2902
#, no-wrap
msgid ""
"~~~~~~~\n"
"fn map<A: Clone, B: Clone>(f: |A| -> B, xs: &[A]) -> ~[B] {\n"
" if xs.len() == 0 {\n"
" return ~[];\n"
" }\n"
" let first: B = f(xs[0].clone());\n"
" let rest: ~[B] = map(f, xs.slice(1, xs.len()));\n"
" return ~[first] + rest;\n"
"}\n"
"~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2905
msgid ""
"Here, `first` has type `B`, referring to `map`'s `B` type parameter; and "
"`rest` has type `~[B]`, a vector type with element type `B`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2907
msgid "### Self types"
msgstr ""
#. type: Plain text
#: doc/rust.md:2911
msgid ""
"The special type `self` has a meaning within methods inside an impl item. It "
"refers to the type of the implicit `self` argument. For example, in:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2916
#, no-wrap
msgid ""
"~~~~~~~~\n"
"trait Printable {\n"
" fn make_string(&self) -> ~str;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2923
#, no-wrap
msgid ""
"impl Printable for ~str {\n"
" fn make_string(&self) -> ~str {\n"
" (*self).clone()\n"
" }\n"
"}\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2926
msgid ""
"`self` refers to the value of type `~str` that is the receiver for a call to "
"the method `make_string`."
msgstr ""
#. type: Plain text
#: doc/rust.md:2928
msgid "## Type kinds"
msgstr ""
#. type: Plain text
#: doc/rust.md:2931
msgid ""
"Types in Rust are categorized into kinds, based on various properties of the "
"components of the type. The kinds are:"
msgstr ""
#. type: Plain text
#: doc/rust.md:2957
#, no-wrap
msgid ""
"`Freeze`\n"
" : Types of this kind are deeply immutable;\n"
" they contain no mutable memory locations\n"
" directly or indirectly via pointers.\n"
"`Send`\n"
" : Types of this kind can be safely sent between tasks.\n"
" This kind includes scalars, owning pointers, owned closures, and\n"
" structural types containing only other owned types.\n"
" All `Send` types are `'static`.\n"
"`'static`\n"
" : Types of this kind do not contain any borrowed pointers;\n"
" this can be a useful guarantee for code\n"
" that breaks borrowing assumptions\n"
" using [`unsafe` operations](#unsafe-functions).\n"
"`Drop`\n"
" : This is not strictly a kind,\n"
" but its presence interacts with kinds:\n"
" the `Drop` trait provides a single method `drop`\n"
" that takes no parameters,\n"
" and is run when values of the type are dropped.\n"
" Such a method is called a \"destructor\",\n"
" and are always executed in \"top-down\" order:\n"
" a value is completely destroyed\n"
" before any of the values it owns run their destructors.\n"
" Only `Send` types can implement `Drop`.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2964
#, no-wrap
msgid ""
"_Default_\n"
" : Types with destructors, closure environments,\n"
" and various other _non-first-class_ types,\n"
" are not copyable at all.\n"
" Such types can usually only be accessed through pointers,\n"
" or in some cases, moved between mutable locations.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:2967
msgid ""
"Kinds can be supplied as _bounds_ on type parameters, like traits, in which "
"case the parameter is constrained to types satisfying that kind."
msgstr ""
#. type: Plain text
#: doc/rust.md:2973
msgid ""
"By default, type parameters do not carry any assumed kind-bounds at all. "
"When instantiating a type parameter, the kind bounds on the parameter are "
"checked to be the same or narrower than the kind of the type that it is "
"instantiated with."
msgstr ""
#. type: Plain text
#: doc/rust.md:2978
msgid ""
"Sending operations are not part of the Rust language, but are implemented in "
"the library. Generic functions that send values bound the kind of these "
"values to sendable."
msgstr ""
#. type: Plain text
#: doc/rust.md:2980
msgid "# Memory and concurrency models"
msgstr ""
#. type: Plain text
#: doc/rust.md:2985
msgid ""
"Rust has a memory model centered around concurrently-executing _tasks_. Thus "
"its memory model and its concurrency model are best discussed "
"simultaneously, as parts of each only make sense when considered from the "
"perspective of the other."
msgstr ""
#. type: Plain text
#: doc/rust.md:2990
msgid ""
"When reading about the memory model, keep in mind that it is partitioned in "
"order to support tasks; and when reading about tasks, keep in mind that "
"their isolation and communication mechanisms are only possible due to the "
"ownership and lifetime semantics of the memory model."
msgstr ""
#. type: Plain text
#: doc/rust.md:2992
msgid "## Memory model"
msgstr ""
#. type: Plain text
#: doc/rust.md:2996
msgid ""
"A Rust program's memory consists of a static set of *items*, a set of [tasks]"
"(#tasks) each with its own *stack*, and a *heap*. Immutable portions of the "
"heap may be shared between tasks, mutable portions may not."
msgstr ""
#. type: Plain text
#: doc/rust.md:2999
msgid ""
"Allocations in the stack consist of *slots*, and allocations in the heap "
"consist of *boxes*."
msgstr ""
#. type: Plain text
#: doc/rust.md:3002
msgid "### Memory allocation and lifetime"
msgstr ""
#. type: Plain text
#: doc/rust.md:3007
msgid ""
"The _items_ of a program are those functions, modules and types that have "
"their value calculated at compile-time and stored uniquely in the memory "
"image of the rust process. Items are neither dynamically allocated nor freed."
msgstr ""
#. type: Plain text
#: doc/rust.md:3011
msgid ""
"A task's _stack_ consists of activation frames automatically allocated on "
"entry to each function as the task executes. A stack allocation is reclaimed "
"when control leaves the frame containing it."
msgstr ""
#. type: Plain text
#: doc/rust.md:3018
msgid ""
"The _heap_ is a general term that describes two separate sets of boxes: "
"managed boxes -- which may be subject to garbage collection -- and owned "
"boxes. The lifetime of an allocation in the heap depends on the lifetime of "
"the box values pointing to it. Since box values may themselves be passed in "
"and out of frames, or stored in the heap, heap allocations may outlive the "
"frame they are allocated within."
msgstr ""
#. type: Plain text
#: doc/rust.md:3020
msgid "### Memory ownership"
msgstr ""
#. type: Plain text
#: doc/rust.md:3023
msgid ""
"A task owns all memory it can *safely* reach through local variables, as "
"well as managed, owning and borrowed pointers."
msgstr ""
#. type: Plain text
#: doc/rust.md:3030
msgid ""
"When a task sends a value that has the `Send` trait to another task, it "
"loses ownership of the value sent and can no longer refer to it. This is "
"statically guaranteed by the combined use of \"move semantics\", and the "
"compiler-checked _meaning_ of the `Send` trait: it is only instantiated for "
"(transitively) sendable kinds of data constructor and pointers, never "
"including managed or borrowed pointers."
msgstr ""
#. type: Plain text
#: doc/rust.md:3033
msgid ""
"When a stack frame is exited, its local allocations are all released, and "
"its references to boxes (both managed and owned) are dropped."
msgstr ""
#. type: Plain text
#: doc/rust.md:3039
msgid ""
"A managed box may (in the case of a recursive, mutable managed type) be "
"cyclic; in this case the release of memory inside the managed structure may "
"be deferred until task-local garbage collection can reclaim it. Code can "
"ensure no such delayed deallocation occurs by restricting itself to owned "
"boxes and similar unmanaged kinds of data."
msgstr ""
#. type: Plain text
#: doc/rust.md:3042
msgid ""
"When a task finishes, its stack is necessarily empty and it therefore has no "
"references to any boxes; the remainder of its heap is immediately freed."
msgstr ""
#. type: Plain text
#: doc/rust.md:3045
msgid "### Memory slots"
msgstr ""
#. type: Plain text
#: doc/rust.md:3047
msgid "A task's stack contains slots."
msgstr ""
#. type: Plain text
#: doc/rust.md:3050
msgid ""
"A _slot_ is a component of a stack frame, either a function parameter, a "
"[temporary](#lvalues-rvalues-and-temporaries), or a local variable."
msgstr ""
#. type: Plain text
#: doc/rust.md:3053
msgid ""
"A _local variable_ (or *stack-local* allocation) holds a value directly, "
"allocated within the stack's memory. The value is a part of the stack frame."
msgstr ""
#. type: Plain text
#: doc/rust.md:3058
msgid ""
"Local variables are immutable unless declared with `let mut`. The `mut` "
"keyword applies to all local variables declared within that declaration (so "
"`let mut (x, y) = ...` declares two mutable variables, `x` and `y`)."
msgstr ""
#. type: Plain text
#: doc/rust.md:3063
msgid ""
"Function parameters are immutable unless declared with `mut`. The `mut` "
"keyword applies only to the following parameter (so `|mut x, y|` and `fn "
"f(mut x: ~int, y: ~int)` declare one mutable variable `x` and one immutable "
"variable `y`)."
msgstr ""
#. type: Plain text
#: doc/rust.md:3069
msgid ""
"Local variables are not initialized when allocated; the entire frame worth "
"of local variables are allocated at once, on frame-entry, in an "
"uninitialized state. Subsequent statements within a function may or may not "
"initialize the local variables. Local variables can be used only after they "
"have been initialized; this is enforced by the compiler."
msgstr ""
#. type: Plain text
#: doc/rust.md:3072
msgid "### Memory boxes"
msgstr ""
#. type: Plain text
#: doc/rust.md:3075
msgid ""
"A _box_ is a reference to a heap allocation holding another value. There are "
"two kinds of boxes: *managed boxes* and *owned boxes*."
msgstr ""
#. type: Plain text
#: doc/rust.md:3077
msgid ""
"A _managed box_ type or value is constructed by the prefix *at* sigil `@`."
msgstr ""
#. type: Plain text
#: doc/rust.md:3079
msgid ""
"An _owned box_ type or value is constructed by the prefix *tilde* sigil `~`."
msgstr ""
#. type: Plain text
#: doc/rust.md:3084
msgid ""
"Multiple managed box values can point to the same heap allocation; copying a "
"managed box value makes a shallow copy of the pointer (optionally "
"incrementing a reference count, if the managed box is implemented through "
"reference-counting)."
msgstr ""
#. type: Plain text
#: doc/rust.md:3086
msgid ""
"Owned box values exist in 1:1 correspondence with their heap allocation."
msgstr ""
#. type: Plain text
#: doc/rust.md:3089
msgid ""
"An example of constructing one managed box type and value, and one owned box "
"type and value:"
msgstr ""
#. type: Plain text
#: doc/rust.md:3094
msgid "~~~~~~~~ let x: @int = @10; let x: ~int = ~10; ~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:3097
msgid ""
"Some operations (such as field selection) implicitly dereference boxes. An "
"example of an _implicit dereference_ operation performed on box values:"
msgstr ""
#. type: Plain text
#: doc/rust.md:3103
msgid ""
"~~~~~~~~ struct Foo { y: int } let x = @Foo{y: 10}; assert!(x.y == 10); "
"~~~~~~~~"
msgstr ""
#. type: Plain text
#: doc/rust.md:3109
msgid ""
"Other operations act on box values as single-word-sized address values. For "
"these operations, to access the value held in the box requires an explicit "
"dereference of the box value. Explicitly dereferencing a box is indicated "
"with the unary *star* operator `*`. Examples of such _explicit dereference_ "
"operations are:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3112
msgid "copying box values (`x = y`)"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3112
msgid "passing box values to functions (`f(x,y)`)"
msgstr ""
#. type: Plain text
#: doc/rust.md:3115
msgid ""
"An example of an explicit-dereference operation performed on box values:"
msgstr ""
#. type: Plain text
#: doc/rust.md:3119
msgid "~~~~~~~~ fn takes_boxed(b: @int) { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:3122
msgid "fn takes_unboxed(b: int) { }"
msgstr ""
#. type: Plain text
#: doc/rust.md:3129
#, no-wrap
msgid ""
"fn main() {\n"
" let x: @int = @10;\n"
" takes_boxed(x);\n"
" takes_unboxed(*x);\n"
"}\n"
"~~~~~~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:3131
msgid "## Tasks"
msgstr ""
#. type: Plain text
#: doc/rust.md:3139
msgid ""
"An executing Rust program consists of a tree of tasks. A Rust _task_ "
"consists of an entry function, a stack, a set of outgoing communication "
"channels and incoming communication ports, and ownership of some portion of "
"the heap of a single operating-system process. (We expect that many "
"programs will not use channels and ports directly, but will instead use "
"higher-level abstractions provided in standard libraries, such as pipes.)"
msgstr ""
#. type: Plain text
#: doc/rust.md:3154
msgid ""
"Multiple Rust tasks may coexist in a single operating-system process. The "
"runtime scheduler maps tasks to a certain number of operating-system "
"threads. By default, the scheduler chooses the number of threads based on "
"the number of concurrent physical CPUs detected at startup. It's also "
"possible to override this choice at runtime. When the number of tasks "
"exceeds the number of threads -- which is likely -- the scheduler "
"multiplexes the tasks onto threads.^[ This is an M:N scheduler, which is "
"known to give suboptimal results for CPU-bound concurrency problems. In "
"such cases, running with the same number of threads and tasks can yield "
"better results. Rust has M:N scheduling in order to support very large "
"numbers of tasks in contexts where threads are too resource-intensive to use "
"in large number. The cost of threads varies substantially per operating "
"system, and is sometimes quite low, so this flexibility is not always worth "
"exploiting.]"
msgstr ""
#. type: Plain text
#: doc/rust.md:3157
msgid "### Communication between tasks"
msgstr ""
#. type: Plain text
#: doc/rust.md:3162
msgid ""
"Rust tasks are isolated and generally unable to interfere with one another's "
"memory directly, except through [`unsafe` code](#unsafe-functions). All "
"contact between tasks is mediated by safe forms of ownership transfer, and "
"data races on memory are prohibited by the type system."
msgstr ""
#. type: Plain text
#: doc/rust.md:3165
msgid ""
"Inter-task communication and co-ordination facilities are provided in the "
"standard library. These include:"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:3169
msgid ""
"synchronous and asynchronous communication channels with various "
"communication topologies"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:3169
msgid ""
"read-only and read-write shared variables with various safe mutual exclusion "
"patterns"
msgstr ""
#. type: Bullet: ' - '
#: doc/rust.md:3169
msgid "simple locks and semaphores"
msgstr ""
#. type: Plain text
#: doc/rust.md:3174
msgid ""
"When such facilities carry values, the values are restricted to the [`Send` "
"type-kind](#type-kinds). Restricting communication interfaces to this kind "
"ensures that no borrowed or managed pointers move between tasks. Thus "
"access to an entire data structure can be mediated through its owning \"root"
"\" value; no further locking or copying is required to avoid data races "
"within the substructure of such a value."
msgstr ""
#. type: Plain text
#: doc/rust.md:3177
msgid "### Task lifecycle"
msgstr ""
#. type: Plain text
#: doc/rust.md:3180
msgid ""
"The _lifecycle_ of a task consists of a finite set of states and events that "
"cause transitions between the states. The lifecycle states of a task are:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3185
msgid "running"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3185
msgid "blocked"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3185
msgid "failing"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3185
msgid "dead"
msgstr ""
#. type: Plain text
#: doc/rust.md:3189
msgid ""
"A task begins its lifecycle -- once it has been spawned -- in the *running* "
"state. In this state it executes the statements of its entry function, and "
"any functions called by the entry function."
msgstr ""
#. type: Plain text
#: doc/rust.md:3195
msgid ""
"A task may transition from the *running* state to the *blocked* state any "
"time it makes a blocking communication call. When the call can be completed "
"-- when a message arrives at a sender, or a buffer opens to receive a "
"message -- then the blocked task will unblock and transition back to "
"*running*."
msgstr ""
#. type: Plain text
#: doc/rust.md:3214
msgid ""
"A task may transition to the *failing* state at any time, due being killed "
"by some external event or internally, from the evaluation of a `fail!()` "
"macro. Once *failing*, a task unwinds its stack and transitions to the "
"*dead* state. Unwinding the stack of a task is done by the task itself, on "
"its own control stack. If a value with a destructor is freed during "
"unwinding, the code for the destructor is run, also on the task's control "
"stack. Running the destructor code causes a temporary transition to a "
"*running* state, and allows the destructor code to cause any subsequent "
"state transitions. The original task of unwinding and failing thereby may "
"suspend temporarily, and may involve (recursive) unwinding of the stack of a "
"failed destructor. Nonetheless, the outermost unwinding activity will "
"continue until the stack is unwound and the task transitions to the *dead* "
"state. There is no way to \"recover\" from task failure. Once a task has "
"temporarily suspended its unwinding in the *failing* state, failure "
"occurring from within this destructor results in *hard* failure. The "
"unwinding procedure of hard failure frees resources but does not execute "
"destructors. The original (soft) failure is still resumed at the point "
"where it was temporarily suspended."
msgstr ""
#. type: Plain text
#: doc/rust.md:3218
msgid ""
"A task in the *dead* state cannot transition to other states; it exists only "
"to have its termination status inspected by other tasks, and/or to await "
"reclamation when the last reference to it drops."
msgstr ""
#. type: Plain text
#: doc/rust.md:3221
msgid "### Task scheduling"
msgstr ""
#. type: Plain text
#: doc/rust.md:3225
msgid ""
"The currently scheduled task is given a finite *time slice* in which to "
"execute, after which it is *descheduled* at a loop-edge or similar "
"preemption point, and another task within is scheduled, pseudo-randomly."
msgstr ""
#. type: Plain text
#: doc/rust.md:3229
msgid ""
"An executing task can yield control at any time, by making a library call to "
"`std::task::yield`, which deschedules it immediately. Entering any other non-"
"executing state (blocked, dead) similarly deschedules the task."
msgstr ""
#. type: Plain text
#: doc/rust.md:3232
msgid "# Runtime services, linkage and debugging"
msgstr ""
#. type: Plain text
#: doc/rust.md:3239
msgid ""
"The Rust _runtime_ is a relatively compact collection of C++ and Rust code "
"that provides fundamental services and datatypes to all Rust tasks at run-"
"time. It is smaller and simpler than many modern language runtimes. It is "
"tightly integrated into the language's execution model of memory, tasks, "
"communication and logging."
msgstr ""
#. type: Plain text
#: doc/rust.md:3241
msgid ""
"> **Note:** The runtime library will merge with the `std` library in future "
"versions of Rust."
msgstr ""
#. type: Plain text
#: doc/rust.md:3243
msgid "### Memory allocation"
msgstr ""
#. type: Plain text
#: doc/rust.md:3249
msgid ""
"The runtime memory-management system is based on a _service-provider "
"interface_, through which the runtime requests blocks of memory from its "
"environment and releases them back to its environment when they are no "
"longer needed. The default implementation of the service-provider interface "
"consists of the C runtime functions `malloc` and `free`."
msgstr ""
#. type: Plain text
#: doc/rust.md:3253
msgid ""
"The runtime memory-management system, in turn, supplies Rust tasks with "
"facilities for allocating, extending and releasing stacks, as well as "
"allocating and freeing heap data."
msgstr ""
#. type: Plain text
#: doc/rust.md:3255
msgid "### Built in types"
msgstr ""
#. type: Plain text
#: doc/rust.md:3259
msgid ""
"The runtime provides C and Rust code to assist with various built-in types, "
"such as vectors, strings, and the low level communication system (ports, "
"channels, tasks)."
msgstr ""
#. type: Plain text
#: doc/rust.md:3262
msgid ""
"Support for other built-in types such as simple types, tuples, records, and "
"enums is open-coded by the Rust compiler."
msgstr ""
#. type: Plain text
#: doc/rust.md:3266
msgid "### Task scheduling and communication"
msgstr ""
#. type: Plain text
#: doc/rust.md:3272
msgid ""
"The runtime provides code to manage inter-task communication. This includes "
"the system of task-lifecycle state transitions depending on the contents of "
"queues, as well as code to copy values between queues and their recipients "
"and to serialize values for transmission over operating-system inter-process "
"communication facilities."
msgstr ""
#. type: Plain text
#: doc/rust.md:3275
msgid "### Logging system"
msgstr ""
#. type: Plain text
#: doc/rust.md:3279
msgid ""
"The runtime contains a system for directing [logging expressions](#log-"
"expressions) to a logging console and/or internal logging buffers. Logging "
"can be enabled per module."
msgstr ""
#. type: Plain text
#: doc/rust.md:3286
msgid ""
"Logging output is enabled by setting the `RUST_LOG` environment variable. "
"`RUST_LOG` accepts a logging specification made up of a comma-separated list "
"of paths, with optional log levels. For each module containing log "
"expressions, if `RUST_LOG` contains the path to that module or a parent of "
"that module, then logs of the appropriate level will be output to the "
"console."
msgstr ""
#. type: Plain text
#: doc/rust.md:3294
msgid ""
"The path to a module consists of the crate name, any parent modules, then "
"the module itself, all separated by double colons (`::`). The optional log "
"level can be appended to the module path with an equals sign (`=`) followed "
"by the log level, from 1 to 4, inclusive. Level 1 is the error level, 2 is "
"warning, 3 info, and 4 debug. Any logs less than or equal to the specified "
"level will be output. If not specified then log level 4 is assumed."
msgstr ""
#. type: Plain text
#: doc/rust.md:3300
msgid ""
"As an example, to see all the logs generated by the compiler, you would set "
"`RUST_LOG` to `rustc`, which is the crate name (as specified in its `link` "
"[attribute](#attributes)). To narrow down the logs to just crate resolution, "
"you would set it to `rustc::metadata::creader`. To see just error logging "
"use `rustc=0`."
msgstr ""
#. type: Plain text
#: doc/rust.md:3305
msgid ""
"Note that when compiling source files that don't specify a crate name the "
"crate is given a default name that matches the source file, with the "
"extension removed. In that case, to turn on logging for a program compiled "
"from, e.g. `helloworld.rs`, `RUST_LOG` should be set to `helloworld`."
msgstr ""
#. type: Plain text
#: doc/rust.md:3309
msgid ""
"As a convenience, the logging spec can also be set to a special pseudo-"
"crate, `::help`. In this case, when the application starts, the runtime will "
"simply output a list of loaded modules containing log expressions, then exit."
msgstr ""
#. type: Plain text
#: doc/rust.md:3314
msgid ""
"The Rust runtime itself generates logging information. The runtime's logs "
"are generated for a number of artificial modules in the `::rt` pseudo-crate, "
"and can be enabled just like the logs for any standard module. The full list "
"of runtime logging modules follows."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::mem` Memory management"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::comm` Messaging and task communication"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::task` Task management"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::dom` Task scheduling"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::trace` Unused"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::cache` Type descriptor cache"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::upcall` Compiler-generated runtime calls"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::timer` The scheduler timer"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::gc` Garbage collection"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::stdlib` Functions used directly by the standard library"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::kern` The runtime kernel"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::backtrace` Log a backtrace on task failure"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3328
msgid "`::rt::callback` Unused"
msgstr ""
#. type: Plain text
#: doc/rust.md:3330
msgid "#### Logging Expressions"
msgstr ""
#. type: Plain text
#: doc/rust.md:3333
msgid ""
"Rust provides several macros to log information. Here's a simple Rust "
"program that demonstrates all four of them:"
msgstr ""
#. type: Plain text
#: doc/rust.md:3342
#, no-wrap
msgid ""
"```rust\n"
"fn main() {\n"
" error!(\"This is an error log\")\n"
" warn!(\"This is a warn log\")\n"
" info!(\"this is an info log\")\n"
" debug!(\"This is a debug log\")\n"
"}\n"
"```\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:3344
msgid ""
"These four log levels correspond to levels 1-4, as controlled by `RUST_LOG`:"
msgstr ""
#. type: Plain text
#: doc/rust.md:3351
msgid ""
"```bash $ RUST_LOG=rust=3 ./rust rust: ~\"\\\"This is an error log\\\"\" "
"rust: ~\"\\\"This is a warn log\\\"\" rust: ~\"\\\"this is an info log\\\"\" "
"```"
msgstr ""
#. type: Plain text
#: doc/rust.md:3353
msgid "# Appendix: Rationales and design tradeoffs"
msgstr ""
#. type: Plain text
#: doc/rust.md:3355
#, no-wrap
msgid "*TODO*.\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:3357
msgid "# Appendix: Influences and further references"
msgstr ""
#. type: Plain text
#: doc/rust.md:3359
msgid "## Influences"
msgstr ""
#. type: Plain text
#: doc/rust.md:3368
msgid ""
"> The essential problem that must be solved in making a fault-tolerant > "
"software system is therefore that of fault-isolation. Different programmers "
"> will write different modules, some modules will be correct, others will "
"have > errors. We do not want the errors in one module to adversely affect "
"the > behaviour of a module which does not have any errors. > > &mdash; Joe "
"Armstrong"
msgstr ""
#. type: Plain text
#: doc/rust.md:3380
msgid ""
"> In our approach, all data is private to some process, and processes can > "
"only communicate through communications channels. *Security*, as used > in "
"this paper, is the property which guarantees that processes in a system > "
"cannot affect each other except by explicit communication. > > When "
"security is absent, nothing which can be proven about a single module > in "
"isolation can be guaranteed to hold when that module is embedded in a > "
"system [...] > > &mdash; Robert Strom and Shaula Yemini"
msgstr ""
#. type: Plain text
#: doc/rust.md:3388
msgid ""
"> Concurrent and applicative programming complement each other. The > "
"ability to send messages on channels provides I/O without side effects, > "
"while the avoidance of shared data helps keep concurrent processes from > "
"colliding. > > &mdash; Rob Pike"
msgstr ""
#. type: Plain text
#: doc/rust.md:3395
msgid ""
"Rust is not a particularly original language. It may however appear unusual "
"by contemporary standards, as its design elements are drawn from a number of "
"\"historical\" languages that have, with a few exceptions, fallen out of "
"favour. Five prominent lineages contribute the most, though their influences "
"have come and gone during the course of Rust's development:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3399
msgid ""
"The NIL (1981) and Hermes (1990) family. These languages were developed by "
"Robert Strom, Shaula Yemini, David Bacon and others in their group at IBM "
"Watson Research Center (Yorktown Heights, NY, USA)."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3403
msgid ""
"The Erlang (1987) language, developed by Joe Armstrong, Robert Virding, "
"Claes Wikstr&ouml;m, Mike Williams and others in their group at the Ericsson "
"Computer Science Laboratory (&Auml;lvsj&ouml;, Stockholm, Sweden) ."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3408
msgid ""
"The Sather (1990) language, developed by Stephen Omohundro, Chu-Cheow Lim, "
"Heinz Schmidt and others in their group at The International Computer "
"Science Institute of the University of California, Berkeley (Berkeley, CA, "
"USA)."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3413
msgid ""
"The Newsqueak (1988), Alef (1995), and Limbo (1996) family. These languages "
"were developed by Rob Pike, Phil Winterbottom, Sean Dorward and others in "
"their group at Bell Labs Computing Sciences Research Center (Murray Hill, "
"NJ, USA)."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3417
msgid ""
"The Napier (1985) and Napier88 (1988) family. These languages were developed "
"by Malcolm Atkinson, Ron Morrison and others in their group at the "
"University of St. Andrews (St. Andrews, Fife, UK)."
msgstr ""
#. type: Plain text
#: doc/rust.md:3419
msgid ""
"Additional specific influences can be seen from the following languages:"
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The stack-growth implementation of Go."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The structural algebraic types and compilation manager of SML."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The attribute and assembly systems of C#."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The references and deterministic destructor system of C++."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The memory region systems of the ML Kit and Cyclone."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The typeclass system of Haskell."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The lexical identifier rule of Python."
msgstr ""
#. type: Bullet: '* '
#: doc/rust.md:3427
msgid "The block syntax of Ruby."
msgstr ""
doc/po/rustpkg.md.pot
-323
View File
@@ -1,323 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-07-30 07:07+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
msgid "# Introduction"
msgstr ""
#. type: Plain text
#: doc/rust.md:30 doc/rustpkg.md:8
msgid "## Disclaimer"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:2
msgid "% Rustpkg Reference Manual"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:6
msgid ""
"This document is the reference manual for the Rustpkg packaging and build "
"tool for the Rust programming language."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:12
msgid ""
"Rustpkg is a work in progress, as is this reference manual. If the actual "
"behavior of rustpkg differs from the behavior described in this reference, "
"that reflects either an incompleteness or a bug in rustpkg."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:14
msgid "# Package searching"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:17
msgid ""
"rustpkg searches for packages using the `RUST_PATH` environment variable, "
"which is a colon-separated list (semicolon-separated on Windows) of "
"directories."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:19
msgid "Each directory in this list is a *workspace* for rustpkg."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:30
msgid ""
"`RUST_PATH` implicitly contains an entry for `./.rust` (as well as `../."
"rust`, `../../.rust`, and so on for every parent of `.` up to the filesystem "
"root). That means that if `RUST_PATH` is not set, then rustpkg will still "
"search for workspaces in `./.rust` and so on. `RUST_PATH` also implicitly "
"contains an entry for the system path: `/usr/local` or the equivalent on "
"Windows. This entry comes after the implicit entries for `./.rust` and so "
"on. Finally, the last implicit entry in `RUST_PATH` is `~/.rust` or the "
"equivalent on Windows."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:32
msgid "Each workspace may contain one or more packages."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:38
msgid ""
"When building code that contains one or more directives of the form `extern "
"mod P`, rustpkg automatically searches for packages named `P` in the "
"`RUST_PATH` (as described above). It builds those dependencies if "
"necessary. Thus, when using rustpkg, there is no need for `-L` flags to "
"tell the linker where to find libraries for external crates."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:40
msgid "# Package structure"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:42
msgid "A valid workspace must contain each of the following subdirectories:"
msgstr ""
#. type: Bullet: '* '
#: doc/rustpkg.md:44
msgid ""
"'src/': contains one subdirectory per package. Each subdirectory contains "
"source files for a given package."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:49
#, no-wrap
msgid ""
" For example, if `foo` is a workspace containing the package `bar`,\n"
" then `foo/src/bar/main.rs` could be the `main` entry point for\n"
" building a `bar` executable.\n"
"* 'lib/': `rustpkg install` installs libraries into a target-specific subdirectory of this directory.\n"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:56
#, no-wrap
msgid ""
" For example, on a 64-bit machine running Mac OS X,\n"
" if `foo` is a workspace containing the package `bar`,\n"
" rustpkg will install libraries for bar to `foo/lib/x86_64-apple-darwin/`.\n"
" The libraries will have names of the form `foo/lib/x86_64-apple-darwin/libbar-[hash].dylib`,\n"
" where [hash] is a hash of the package ID.\n"
"* 'bin/': `rustpkg install` installs executable binaries into a target-specific subdirectory of this directory.\n"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:63
#, no-wrap
msgid ""
" For example, on a 64-bit machine running Mac OS X,\n"
" if `foo` is a workspace, containing the package `bar`,\n"
" rustpkg will install executables for `bar` to\n"
" `foo/bin/x86_64-apple-darwin/`.\n"
" The executables will have names of the form `foo/bin/x86_64-apple-darwin/bar`.\n"
"* 'build/': `rustpkg build` stores temporary build artifacts in a target-specific subdirectory of this directory.\n"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:67
#, no-wrap
msgid ""
" For example, on a 64-bit machine running Mac OS X,\n"
" if `foo` is a workspace containing the package `bar` and `foo/src/bar/main.rs` exists,\n"
" then `rustpkg build` will create `foo/build/x86_64-apple-darwin/bar/main.o`.\n"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:69
msgid "# Package identifiers"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:87
msgid ""
"A package identifier identifies a package uniquely. A package can be stored "
"in a workspace on the local file system, or on a remote Web server, in which "
"case the package ID resembles a URL. For example, `github.com/mozilla/rust` "
"is a package ID that would refer to the git repository browsable at `http://"
"github.com/mozilla/rust`. A package ID can also specify a version, like: "
"`github.com/mozilla/rust#0.3`. In this case, `rustpkg` will check that the "
"repository `github.com/mozilla/rust` has a tag named `0.3`, and report an "
"error otherwise. A package ID can also specify a particular revision of a "
"repository, like: `github.com/mozilla/rust#release-0.7`. When the refspec "
"(portion of the package ID after the `#`) can't be parsed as a decimal "
"number, rustpkg passes the refspec along to the version control system "
"without interpreting it. rustpkg also interprets any dependencies on such a "
"package ID literally (as opposed to versions, where a newer version "
"satisfies a dependency on an older version). Thus, `github.com/mozilla/"
"rust#5c4cd30f80` is also a valid package ID, since git can deduce that "
"5c4cd30f80 refers to a revision of the desired repository."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:89
msgid "## Source files"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:91
msgid ""
"rustpkg searches for four different fixed filenames in order to determine "
"the crates to build:"
msgstr ""
#. type: Bullet: '* '
#: doc/rustpkg.md:96
msgid "`main.rs`: Assumed to be a main entry point for building an executable."
msgstr ""
#. type: Bullet: '* '
#: doc/rustpkg.md:96
msgid "`lib.rs`: Assumed to be a library crate."
msgstr ""
#. type: Bullet: '* '
#: doc/rustpkg.md:96
msgid ""
"`test.rs`: Assumed to contain tests declared with the `#[test]` attribute."
msgstr ""
#. type: Bullet: '* '
#: doc/rustpkg.md:96
msgid ""
"`bench.rs`: Assumed to contain benchmarks declared with the `#[bench]` "
"attribute."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:98
msgid "## Versions"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:105
msgid ""
"`rustpkg` packages do not need to declare their versions with an attribute "
"inside one of the source files, because `rustpkg` infers it from the version "
"control system. When building a package that is in a `git` repository, "
"`rustpkg` assumes that the most recent tag specifies the current version. "
"When building a package that is not under version control, or that has no "
"tags, `rustpkg` assumes the intended version is 0.1."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:107
msgid "# Dependencies"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:111
msgid ""
"rustpkg infers dependencies from `extern mod` directives. Thus, there "
"should be no need to pass a `-L` flag to rustpkg to tell it where to find a "
"library. (In the future, it will also be possible to write an `extern mod` "
"directive referring to a remote package.)"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:113
msgid "# Custom build scripts"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:117
msgid ""
"A file called `pkg.rs` at the root level in a workspace is called a *package "
"script*. If a package script exists, rustpkg executes it to build the "
"package rather than inferring crates as described previously."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:121
msgid ""
"Inside `pkg.rs`, it's possible to call back into rustpkg to finish up the "
"build. `rustpkg::api` contains functions to build, install, or clean "
"libraries and executables in the way rustpkg normally would without custom "
"build logic."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:123
msgid "# Command reference"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:125
msgid "## build"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:131
msgid ""
"`rustpkg build foo` searches for a package with ID `foo` and builds it in "
"any workspace(s) where it finds one. Supposing such packages are found in "
"workspaces X, Y, and Z, the command leaves behind files in `X`'s, `Y`'s, and "
"`Z`'s `build` directories, but not in their `lib` or `bin` directories."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:133
msgid "## clean"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:135
msgid "`rustpkg clean foo` deletes the contents of `foo`'s `build` directory."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:137
msgid "## install"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:141
msgid ""
"`rustpkg install foo` builds the libraries and/or executables that are "
"targets for `foo`, and then installs them either into `foo`'s `lib` and "
"`bin` directories, or into the `lib` and `bin` subdirectories of the first "
"entry in `RUST_PATH`."
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:143
msgid "## test"
msgstr ""
#. type: Plain text
#: doc/rustpkg.md:145
msgid ""
"`rustpkg test foo` builds `foo`'s `test.rs` file if necessary, then runs the "
"resulting test executable."
msgstr ""
doc/po/tutorial-borrowed-ptr.md.pot
-1070
View File
@@ -1,1070 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-07-22 23:37+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
msgid "# Introduction"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1108 doc/tutorial-borrowed-ptr.md:72
msgid "Now we can call `compute_distance()` in various ways:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:2
msgid "% Rust Borrowed Pointers Tutorial"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:14
msgid ""
"Borrowed pointers are one of the more flexible and powerful tools available "
"in Rust. A borrowed pointer can point anywhere: into the managed or exchange "
"heap, into the stack, and even into the interior of another data structure. "
"A borrowed pointer is as flexible as a C pointer or C++ reference. However, "
"unlike C and C++ compilers, the Rust compiler includes special static checks "
"that ensure that programs use borrowed pointers safely. Another advantage of "
"borrowed pointers is that they are invisible to the garbage collector, so "
"working with borrowed pointers helps reduce the overhead of automatic memory "
"management."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:18
msgid ""
"Despite their complete safety, a borrowed pointer's representation at "
"runtime is the same as that of an ordinary pointer in a C program. They "
"introduce zero overhead. The compiler does all safety checks at compile time."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:24
msgid ""
"Although borrowed pointers have rather elaborate theoretical underpinnings "
"(region pointers), the core concepts will be familiar to anyone who has "
"worked with C or C++. Therefore, the best way to explain how they are used—"
"and their limitations—is probably just to work through several examples."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:26
msgid "# By example"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:31
msgid ""
"Borrowed pointers are called *borrowed* because they are only valid for a "
"limited duration. Borrowed pointers never claim any kind of ownership over "
"the data that they point to: instead, they are used for cases where you "
"would like to use data for a short time."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:33
msgid "As an example, consider a simple struct type `Point`:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:37
msgid "~~~ struct Point {x: float, y: float} ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:41
msgid ""
"We can use this simple definition to allocate points in many different ways. "
"For example, in this code, each of these three local variables contains a "
"point, but allocated in a different place:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:48
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"let on_the_stack : Point = Point {x: 3.0, y: 4.0};\n"
"let managed_box : @Point = @Point {x: 5.0, y: 1.0};\n"
"let owned_box : ~Point = ~Point {x: 7.0, y: 9.0};\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:60
msgid ""
"Suppose we wanted to write a procedure that computed the distance between "
"any two points, no matter where they were stored. For example, we might like "
"to compute the distance between `on_the_stack` and `managed_box`, or between "
"`managed_box` and `owned_box`. One option is to define a function that takes "
"two arguments of type `Point`—that is, it takes the points by value. But if "
"we define it this way, calling the function will cause the points to be "
"copied. For points, this is probably not so bad, but often copies are "
"expensive. Worse, if the data type contains mutable fields, copying can "
"change the semantics of your program in unexpected ways. So we'd like to "
"define a function that takes the points by pointer. We can use borrowed "
"pointers to do this:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:70
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"# fn sqrt(f: float) -> float { 0f }\n"
"fn compute_distance(p1: &Point, p2: &Point) -> float {\n"
" let x_d = p1.x - p2.x;\n"
" let y_d = p1.y - p2.y;\n"
" sqrt(x_d * x_d + y_d * y_d)\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:82
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"# let on_the_stack : Point = Point{x: 3.0, y: 4.0};\n"
"# let managed_box : @Point = @Point{x: 5.0, y: 1.0};\n"
"# let owned_box : ~Point = ~Point{x: 7.0, y: 9.0};\n"
"# fn compute_distance(p1: &Point, p2: &Point) -> float { 0f }\n"
"compute_distance(&on_the_stack, managed_box);\n"
"compute_distance(managed_box, owned_box);\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:89
msgid ""
"Here, the `&` operator takes the address of the variable `on_the_stack`; "
"this is because `on_the_stack` has the type `Point` (that is, a struct "
"value) and we have to take its address to get a value. We also call this "
"_borrowing_ the local variable `on_the_stack`, because we have created an "
"alias: that is, another name for the same data."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:95
msgid ""
"In contrast, we can pass the boxes `managed_box` and `owned_box` to "
"`compute_distance` directly. The compiler automatically converts a box like "
"`@Point` or `~Point` to a borrowed pointer like `&Point`. This is another "
"form of borrowing: in this case, the caller lends the contents of the "
"managed or owned box to the callee."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:105
msgid ""
"Whenever a caller lends data to a callee, there are some limitations on what "
"the caller can do with the original. For example, if the contents of a "
"variable have been lent out, you cannot send that variable to another task. "
"In addition, the compiler will reject any code that might cause the borrowed "
"value to be freed or overwrite its component fields with values of different "
"types (I'll get into what kinds of actions those are shortly). This rule "
"should make intuitive sense: you must wait for a borrower to return the "
"value that you lent it (that is, wait for the borrowed pointer to go out of "
"scope) before you can make full use of it again."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:107
msgid "# Other uses for the & operator"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:109
msgid "In the previous example, the value `on_the_stack` was defined like so:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:114
msgid ""
"~~~ # struct Point {x: float, y: float} let on_the_stack: Point = Point {x: "
"3.0, y: 4.0}; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:119
msgid ""
"This declaration means that code can only pass `Point` by value to other "
"functions. As a consequence, we had to explicitly take the address of "
"`on_the_stack` to get a borrowed pointer. Sometimes however it is more "
"convenient to move the & operator into the definition of `on_the_stack`:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:124
msgid ""
"~~~ # struct Point {x: float, y: float} let on_the_stack2: &Point = &Point "
"{x: 3.0, y: 4.0}; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:128
msgid ""
"Applying `&` to an rvalue (non-assignable location) is just a convenient "
"shorthand for creating a temporary and taking its address. A more verbose "
"way to write the same code is:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:134
msgid ""
"~~~ # struct Point {x: float, y: float} let tmp = Point {x: 3.0, y: 4.0}; "
"let on_the_stack2 : &Point = &tmp; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:136
msgid "# Taking the address of fields"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:141
msgid ""
"As in C, the `&` operator is not limited to taking the address of local "
"variables. It can also take the address of fields or individual array "
"elements. For example, consider this type definition for `rectangle`:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:147
msgid ""
"~~~ struct Point {x: float, y: float} // as before struct Size {w: float, h: "
"float} // as before struct Rectangle {origin: Point, size: Size} ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:149
msgid "Now, as before, we can define rectangles in a few different ways:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:161
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}\n"
"# struct Size {w: float, h: float} // as before\n"
"# struct Rectangle {origin: Point, size: Size}\n"
"let rect_stack = &Rectangle {origin: Point {x: 1f, y: 2f},\n"
" size: Size {w: 3f, h: 4f}};\n"
"let rect_managed = @Rectangle {origin: Point {x: 3f, y: 4f},\n"
" size: Size {w: 3f, h: 4f}};\n"
"let rect_owned = ~Rectangle {origin: Point {x: 5f, y: 6f},\n"
" size: Size {w: 3f, h: 4f}};\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:164
msgid ""
"In each case, we can extract out individual subcomponents with the `&` "
"operator. For example, I could write:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:175
msgid ""
"~~~ # struct Point {x: float, y: float} // as before # struct Size {w: "
"float, h: float} // as before # struct Rectangle {origin: Point, size: Size} "
"# let rect_stack = &Rectangle {origin: Point {x: 1f, y: 2f}, size: Size {w: "
"3f, h: 4f}}; # let rect_managed = @Rectangle {origin: Point {x: 3f, y: 4f}, "
"size: Size {w: 3f, h: 4f}}; # let rect_owned = ~Rectangle {origin: Point {x: "
"5f, y: 6f}, size: Size {w: 3f, h: 4f}}; # fn compute_distance(p1: &Point, "
"p2: &Point) -> float { 0f } compute_distance(&rect_stack.origin, "
"&rect_managed.origin); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:178
msgid ""
"which would borrow the field `origin` from the rectangle on the stack as "
"well as from the managed box, and then compute the distance between them."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:180
msgid "# Borrowing managed boxes and rooting"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:186
msgid ""
"We’ve seen a few examples so far of borrowing heap boxes, both managed and "
"owned. Up till this point, we’ve glossed over issues of safety. As stated in "
"the introduction, at runtime a borrowed pointer is simply a pointer, nothing "
"more. Therefore, avoiding C's problems with dangling pointers requires a "
"compile-time safety check."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:197
msgid ""
"The basis for the check is the notion of _lifetimes_. A lifetime is a static "
"approximation of the span of execution during which the pointer is valid: it "
"always corresponds to some expression or block within the program. Code "
"inside that expression can use the pointer without restrictions. But if the "
"pointer escapes from that expression (for example, if the expression "
"contains an assignment expression that assigns the pointer to a mutable "
"field of a data structure with a broader scope than the pointer itself), the "
"compiler reports an error. We'll be discussing lifetimes more in the "
"examples to come, and a more thorough introduction is also available."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:202
msgid ""
"When the `&` operator creates a borrowed pointer, the compiler must ensure "
"that the pointer remains valid for its entire lifetime. Sometimes this is "
"relatively easy, such as when taking the address of a local variable or a "
"field that is stored on the stack:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:211
#, no-wrap
msgid ""
"~~~\n"
"struct X { f: int }\n"
"fn example1() {\n"
" let mut x = X { f: 3 };\n"
" let y = &mut x.f; // -+ L\n"
" ... // |\n"
"} // -+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:216
msgid ""
"Here, the lifetime of the borrowed pointer `y` is simply L, the remainder of "
"the function body. The compiler need not do any other work to prove that "
"code will not free `x.f`. This is true even if the code mutates `x`."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:218
msgid "The situation gets more complex when borrowing data inside heap boxes:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:227
#, no-wrap
msgid ""
"~~~\n"
"# struct X { f: int }\n"
"fn example2() {\n"
" let mut x = @X { f: 3 };\n"
" let y = &x.f; // -+ L\n"
" ... // |\n"
"} // -+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:238
msgid ""
"In this example, the value `x` is a heap box, and `y` is therefore a pointer "
"into that heap box. Again the lifetime of `y` is L, the remainder of the "
"function body. But there is a crucial difference: suppose `x` were to be "
"reassigned during the lifetime L? If the compiler isn't careful, the managed "
"box could become *unrooted*, and would therefore be subject to garbage "
"collection. A heap box that is unrooted is one such that no pointer values "
"in the heap point to it. It would violate memory safety for the box that was "
"originally assigned to `x` to be garbage-collected, since a non-heap pointer "
"*`y`* still points into it."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:241
msgid ""
"> ***Note:*** Our current implementation implements the garbage collector > "
"using reference counting and cycle detection."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:247
msgid ""
"For this reason, whenever an `&` expression borrows the interior of a "
"managed box stored in a mutable location, the compiler inserts a temporary "
"that ensures that the managed box remains live for the entire lifetime. So, "
"the above example would be compiled as if it were written"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:257
#, no-wrap
msgid ""
"~~~\n"
"# struct X { f: int }\n"
"fn example2() {\n"
" let mut x = @X {f: 3};\n"
" let x1 = x;\n"
" let y = &x1.f; // -+ L\n"
" ... // |\n"
"} // -+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:260
msgid ""
"Now if `x` is reassigned, the pointer `y` will still remain valid. This "
"process is called *rooting*."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:262
msgid "# Borrowing owned boxes"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:268
msgid ""
"The previous example demonstrated *rooting*, the process by which the "
"compiler ensures that managed boxes remain live for the duration of a "
"borrow. Unfortunately, rooting does not work for borrows of owned boxes, "
"because it is not possible to have two references to a owned box."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:274
msgid ""
"For owned boxes, therefore, the compiler will only allow a borrow *if the "
"compiler can guarantee that the owned box will not be reassigned or moved "
"for the lifetime of the pointer*. This does not necessarily mean that the "
"owned box is stored in immutable memory. For example, the following function "
"is legal:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:289
#, no-wrap
msgid ""
"~~~\n"
"# fn some_condition() -> bool { true }\n"
"# struct Foo { f: int }\n"
"fn example3() -> int {\n"
" let mut x = ~Foo {f: 3};\n"
" if some_condition() {\n"
" let y = &x.f; // -+ L\n"
" return *y; // |\n"
" } // -+\n"
" x = ~Foo {f: 4};\n"
" ...\n"
"# return 0;\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:295
msgid ""
"Here, as before, the interior of the variable `x` is being borrowed and `x` "
"is declared as mutable. However, the compiler can prove that `x` is not "
"assigned anywhere in the lifetime L of the variable `y`. Therefore, it "
"accepts the function, even though `x` is mutable and in fact is mutated "
"later in the function."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:301
msgid ""
"It may not be clear why we are so concerned about mutating a borrowed "
"variable. The reason is that the runtime system frees any owned box _as soon "
"as its owning reference changes or goes out of scope_. Therefore, a program "
"like this is illegal (and would be rejected by the compiler):"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:310
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"fn example3() -> int {\n"
" let mut x = ~X {f: 3};\n"
" let y = &x.f;\n"
" x = ~X {f: 4}; // Error reported here.\n"
" *y\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:313
msgid ""
"To make this clearer, consider this diagram showing the state of memory "
"immediately before the re-assignment of `x`:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:316 doc/tutorial-borrowed-ptr.md:330
#, no-wrap
msgid ""
"~~~ {.notrust}\n"
" Stack Exchange Heap\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:325
#, no-wrap
msgid ""
" x +----------+\n"
" | ~{f:int} | ----+\n"
" y +----------+ |\n"
" | &int | ----+\n"
" +----------+ | +---------+\n"
" +--> | f: 3 |\n"
" +---------+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:327
msgid "Once the reassignment occurs, the memory will look like this:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:339
#, no-wrap
msgid ""
" x +----------+ +---------+\n"
" | ~{f:int} | -------> | f: 4 |\n"
" y +----------+ +---------+\n"
" | &int | ----+\n"
" +----------+ | +---------+\n"
" +--> | (freed) |\n"
" +---------+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:342
msgid ""
"Here you can see that the variable `y` still points at the old box, which "
"has been freed."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:348
msgid ""
"In fact, the compiler can apply the same kind of reasoning to any memory "
"that is _(uniquely) owned by the stack frame_. So we could modify the "
"previous example to introduce additional owned pointers and structs, and the "
"compiler will still be able to detect possible mutations:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:353
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"fn example3() -> int {\n"
" struct R { g: int }\n"
" struct S { f: ~R }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:361
#, no-wrap
msgid ""
" let mut x = ~S {f: ~R {g: 3}};\n"
" let y = &x.f.g;\n"
" x = ~S {f: ~R {g: 4}}; // Error reported here.\n"
" x.f = ~R {g: 5}; // Error reported here.\n"
" *y\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:365
msgid ""
"In this case, two errors are reported, one when the variable `x` is modified "
"and another when `x.f` is modified. Either modification would invalidate the "
"pointer `y`."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:367
msgid "# Borrowing and enums"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:373
msgid ""
"The previous example showed that the type system forbids any borrowing of "
"owned boxes found in aliasable, mutable memory. This restriction prevents "
"pointers from pointing into freed memory. There is one other case where the "
"compiler must be very careful to ensure that pointers remain valid: pointers "
"into the interior of an `enum`."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:376
msgid ""
"As an example, let’s look at the following `shape` type that can represent "
"both rectangles and circles:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:385
#, no-wrap
msgid ""
"~~~\n"
"struct Point {x: float, y: float}; // as before\n"
"struct Size {w: float, h: float}; // as before\n"
"enum Shape {\n"
" Circle(Point, float), // origin, radius\n"
" Rectangle(Point, Size) // upper-left, dimensions\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:389
msgid ""
"Now we might write a function to compute the area of a shape. This function "
"takes a borrowed pointer to a shape, to avoid the need for copying."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:405
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"# Circle(Point, float), // origin, radius\n"
"# Rectangle(Point, Size) // upper-left, dimensions\n"
"# }\n"
"# static tau: float = 6.28f;\n"
"fn compute_area(shape: &Shape) -> float {\n"
" match *shape {\n"
" Circle(_, radius) => 0.5 * tau * radius * radius,\n"
" Rectangle(_, ref size) => size.w * size.h\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:410
msgid ""
"The first case matches against circles. Here, the pattern extracts the "
"radius from the shape variant and the action uses it to compute the area of "
"the circle. (Like any up-to-date engineer, we use the [tau circle constant]"
"[tau] and not that dreadfully outdated notion of pi)."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:412
msgid "[tau]: http://www.math.utah.edu/~palais/pi.html"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:418
msgid ""
"The second match is more interesting. Here we match against a rectangle and "
"extract its size: but rather than copy the `size` struct, we use a by-"
"reference binding to create a pointer to it. In other words, a pattern "
"binding like `ref size` binds the name `size` to a pointer of type `&size` "
"into the _interior of the enum_."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:421
msgid ""
"To make this more clear, let's look at a diagram of memory layout in the "
"case where `shape` points at a rectangle:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:424 doc/tutorial-borrowed-ptr.md:449
#, no-wrap
msgid ""
"~~~ {.notrust}\n"
"Stack Memory\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:433
#, no-wrap
msgid ""
"+-------+ +---------------+\n"
"| shape | ------> | rectangle( |\n"
"+-------+ | {x: float, |\n"
"| size | -+ | y: float}, |\n"
"+-------+ +----> | {w: float, |\n"
" | h: float}) |\n"
" +---------------+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:440
msgid ""
"Here you can see that rectangular shapes are composed of five words of "
"memory. The first is a tag indicating which variant this enum is "
"(`rectangle`, in this case). The next two words are the `x` and `y` fields "
"for the point and the remaining two are the `w` and `h` fields for the size. "
"The binding `size` is then a pointer into the inside of the shape."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:446
msgid ""
"Perhaps you can see where the danger lies: if the shape were somehow to be "
"reassigned, perhaps to a circle, then although the memory used to store that "
"shape value would still be valid, _it would have a different type_! The "
"following diagram shows what memory would look like if code overwrote "
"`shape` with a circle:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:458
#, no-wrap
msgid ""
"+-------+ +---------------+\n"
"| shape | ------> | circle( |\n"
"+-------+ | {x: float, |\n"
"| size | -+ | y: float}, |\n"
"+-------+ +----> | float) |\n"
" | |\n"
" +---------------+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:463
msgid ""
"As you can see, the `size` pointer would be pointing at a `float` instead of "
"a struct. This is not good: dereferencing the second field of a `float` as "
"if it were a struct with two fields would be a memory safety violation."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:475
msgid ""
"So, in fact, for every `ref` binding, the compiler will impose the same "
"rules as the ones we saw for borrowing the interior of a owned box: it must "
"be able to guarantee that the `enum` will not be overwritten for the "
"duration of the borrow. In fact, the compiler would accept the example we "
"gave earlier. The example is safe because the shape pointer has type "
"`&Shape`, which means \"borrowed pointer to immutable memory containing a "
"`shape`\". If, however, the type of that pointer were `&mut Shape`, then the "
"ref binding would be ill-typed. Just as with owned boxes, the compiler will "
"permit `ref` bindings into data owned by the stack frame even if the data "
"are mutable, but otherwise it requires that the data reside in immutable "
"memory."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:477
msgid "# Returning borrowed pointers"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:483
msgid ""
"So far, all of the examples we have looked at, use borrowed pointers in a "
"“downward” direction. That is, a method or code block creates a borrowed "
"pointer, then uses it within the same scope. It is also possible to return "
"borrowed pointers as the result of a function, but as we'll see, doing so "
"requires some explicit annotation."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:485
msgid "For example, we could write a subroutine like this:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:490
msgid ""
"~~~ struct Point {x: float, y: float} fn get_x<'r>(p: &'r Point) -> &'r "
"float { &p.x } ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:498
msgid ""
"Here, the function `get_x()` returns a pointer into the structure it was "
"given. The type of the parameter (`&'r Point`) and return type (`&'r float`) "
"both use a new syntactic form that we have not seen so far. Here the "
"identifier `r` names the lifetime of the pointer explicitly. So in effect, "
"this function declares that it takes a pointer with lifetime `r` and returns "
"a pointer with that same lifetime."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:504
msgid ""
"In general, it is only possible to return borrowed pointers if they are "
"derived from a parameter to the procedure. In that case, the pointer result "
"will always have the same lifetime as one of the parameters; named lifetimes "
"indicate which parameter that is."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:510
msgid ""
"In the previous examples, function parameter types did not include a "
"lifetime name. In those examples, the compiler simply creates a fresh name "
"for the lifetime automatically: that is, the lifetime name is guaranteed to "
"refer to a distinct lifetime from the lifetimes of all other parameters."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:518
msgid ""
"Named lifetimes that appear in function signatures are conceptually the same "
"as the other lifetimes we have seen before, but they are a bit abstract: "
"they don’t refer to a specific expression within `get_x()`, but rather to "
"some expression within the *caller of `get_x()`*. The lifetime `r` is "
"actually a kind of *lifetime parameter*: it is defined by the caller to "
"`get_x()`, just as the value for the parameter `p` is defined by that caller."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:523
msgid ""
"In any case, whatever the lifetime of `r` is, the pointer produced by `&p.x` "
"always has the same lifetime as `p` itself: a pointer to a field of a struct "
"is valid as long as the struct is valid. Therefore, the compiler accepts the "
"function `get_x()`."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:526
msgid ""
"To emphasize this point, let’s look at a variation on the example, this time "
"one that does not compile:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:533
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"struct Point {x: float, y: float}\n"
"fn get_x_sh(p: @Point) -> &float {\n"
" &p.x // Error reported here\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:541
msgid ""
"Here, the function `get_x_sh()` takes a managed box as input and returns a "
"borrowed pointer. As before, the lifetime of the borrowed pointer that will "
"be returned is a parameter (specified by the caller). That means that "
"`get_x_sh()` promises to return a borrowed pointer that is valid for as long "
"as the caller would like: this is subtly different from the first example, "
"which promised to return a pointer that was valid for as long as its pointer "
"argument was valid."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:552
msgid ""
"Within `get_x_sh()`, we see the expression `&p.x` which takes the address of "
"a field of a managed box. The presence of this expression implies that the "
"compiler must guarantee that, so long as the resulting pointer is valid, the "
"managed box will not be reclaimed by the garbage collector. But recall that "
"`get_x_sh()` also promised to return a pointer that was valid for as long as "
"the caller wanted it to be. Clearly, `get_x_sh()` is not in a position to "
"make both of these guarantees; in fact, it cannot guarantee that the pointer "
"will remain valid at all once it returns, as the parameter `p` may or may "
"not be live in the caller. Therefore, the compiler will report an error here."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:559
msgid ""
"In general, if you borrow a managed (or owned) box to create a borrowed "
"pointer, the pointer will only be valid within the function and cannot be "
"returned. This is why the typical way to return borrowed pointers is to take "
"borrowed pointers as input (the only other case in which it can be legal to "
"return a borrowed pointer is if the pointer points at a static constant)."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:561
msgid "# Named lifetimes"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:565
msgid ""
"Let's look at named lifetimes in more detail. Named lifetimes allow for "
"grouping of parameters by lifetime. For example, consider this function:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:579
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"# Circle(Point, float), // origin, radius\n"
"# Rectangle(Point, Size) // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"fn select<'r, T>(shape: &'r Shape, threshold: float,\n"
" a: &'r T, b: &'r T) -> &'r T {\n"
" if compute_area(shape) > threshold {a} else {b}\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:585
msgid ""
"This function takes three borrowed pointers and assigns each the same "
"lifetime `r`. In practice, this means that, in the caller, the lifetime `r` "
"will be the *intersection of the lifetime of the three region parameters*. "
"This may be overly conservative, as in this example:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:607
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"# Circle(Point, float), // origin, radius\n"
"# Rectangle(Point, Size) // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"# fn select<'r, T>(shape: &Shape, threshold: float,\n"
"# a: &'r T, b: &'r T) -> &'r T {\n"
"# if compute_area(shape) > threshold {a} else {b}\n"
"# }\n"
" // -+ r\n"
"fn select_based_on_unit_circle<'r, T>( // |-+ B\n"
" threshold: float, a: &'r T, b: &'r T) -> &'r T { // | |\n"
" // | |\n"
" let shape = Circle(Point {x: 0., y: 0.}, 1.); // | |\n"
" select(&shape, threshold, a, b) // | |\n"
"} // |-+\n"
" // -+\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:617
msgid ""
"In this call to `select()`, the lifetime of the first parameter shape is B, "
"the function body. Both of the second two parameters `a` and `b` share the "
"same lifetime, `r`, which is a lifetime parameter of "
"`select_based_on_unit_circle()`. The caller will infer the intersection of "
"these two lifetimes as the lifetime of the returned value, and hence the "
"return value of `select()` will be assigned a lifetime of B. This will in "
"turn lead to a compilation error, because `select_based_on_unit_circle()` is "
"supposed to return a value with the lifetime `r`."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:622
msgid ""
"To address this, we can modify the definition of `select()` to distinguish "
"the lifetime of the first parameter from the lifetime of the latter two. "
"After all, the first parameter is not being returned. Here is how the new "
"`select()` might look:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:636
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"# Circle(Point, float), // origin, radius\n"
"# Rectangle(Point, Size) // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"fn select<'r, 'tmp, T>(shape: &'tmp Shape, threshold: float,\n"
" a: &'r T, b: &'r T) -> &'r T {\n"
" if compute_area(shape) > threshold {a} else {b}\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:641
msgid ""
"Here you can see that `shape`'s lifetime is now named `tmp`. The parameters "
"`a`, `b`, and the return value all have the lifetime `r`. However, since "
"the lifetime `tmp` is not returned, it would be more concise to just omit "
"the named lifetime for `shape` altogether:"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:655
#, no-wrap
msgid ""
"~~~\n"
"# struct Point {x: float, y: float}; // as before\n"
"# struct Size {w: float, h: float}; // as before\n"
"# enum Shape {\n"
"# Circle(Point, float), // origin, radius\n"
"# Rectangle(Point, Size) // upper-left, dimensions\n"
"# }\n"
"# fn compute_area(shape: &Shape) -> float { 0f }\n"
"fn select<'r, T>(shape: &Shape, threshold: float,\n"
" a: &'r T, b: &'r T) -> &'r T {\n"
" if compute_area(shape) > threshold {a} else {b}\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:657
msgid "This is equivalent to the previous definition."
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:659
msgid "# Conclusion"
msgstr ""
#. type: Plain text
#: doc/tutorial-borrowed-ptr.md:663
msgid ""
"So there you have it: a (relatively) brief tour of the borrowed pointer "
"system. For more details, we refer to the (yet to be written) reference "
"document on borrowed pointers, which will explain the full notation and give "
"more examples."
msgstr ""
doc/po/tutorial-container.md.pot
-673
View File
@@ -1,673 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-08-05 19:40+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/tutorial-container.md:2
msgid "% Containers and iterators"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:4
msgid "# Containers"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:6
msgid "The container traits are defined in the `std::container` module."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:8
msgid "## Unique and managed vectors"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:12
msgid ""
"Vectors have `O(1)` indexing and removal from the end, along with `O(1)` "
"amortized insertion. Vectors are the most common container in Rust, and are "
"flexible enough to fit many use cases."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:16
msgid ""
"Vectors can also be sorted and used as efficient lookup tables with the "
"`std::vec::bsearch` function, if all the elements are inserted at one time "
"and deletions are unnecessary."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:18
msgid "## Maps and sets"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:22
msgid ""
"Maps are collections of unique keys with corresponding values, and sets are "
"just unique keys without a corresponding value. The `Map` and `Set` traits "
"in `std::container` define the basic interface."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:24
msgid "The standard library provides three owned map/set types:"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-container.md:30
msgid ""
"`std::hashmap::HashMap` and `std::hashmap::HashSet`, requiring the keys to "
"implement `Eq` and `Hash`"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-container.md:30
msgid ""
"`std::trie::TrieMap` and `std::trie::TrieSet`, requiring the keys to be "
"`uint`"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-container.md:30
msgid ""
"`extra::treemap::TreeMap` and `extra::treemap::TreeSet`, requiring the keys "
"to implement `TotalOrd`"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:34
msgid ""
"These maps do not use managed pointers so they can be sent between tasks as "
"long as the key and value types are sendable. Neither the key or value type "
"has to be copyable."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:37
msgid ""
"The `TrieMap` and `TreeMap` maps are ordered, while `HashMap` uses an "
"arbitrary order."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:42
msgid ""
"Each `HashMap` instance has a random 128-bit key to use with a keyed hash, "
"making the order of a set of keys in a given hash table randomized. Rust "
"provides a [SipHash](https://131002.net/siphash/) implementation for any "
"type implementing the `IterBytes` trait."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:44
msgid "## Double-ended queues"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:49
msgid ""
"The `extra::deque` module implements a double-ended queue with `O(1)` "
"amortized inserts and removals from both ends of the container. It also has "
"`O(1)` indexing like a vector. The contained elements are not required to be "
"copyable, and the queue will be sendable if the contained type is sendable."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:51
msgid "## Priority queues"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:55
msgid ""
"The `extra::priority_queue` module implements a queue ordered by a key. The "
"contained elements are not required to be copyable, and the queue will be "
"sendable if the contained type is sendable."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:61
msgid ""
"Insertions have `O(log n)` time complexity and checking or popping the "
"largest element is `O(1)`. Converting a vector to a priority queue can be "
"done in-place, and has `O(n)` complexity. A priority queue can also be "
"converted to a sorted vector in-place, allowing it to be used for an `O(n "
"log n)` in-place heapsort."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:63
msgid "# Iterators"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:65
msgid "## Iteration protocol"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:69
msgid ""
"The iteration protocol is defined by the `Iterator` trait in the `std::"
"iterator` module. The minimal implementation of the trait is a `next` "
"method, yielding the next element from an iterator object:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:73
msgid "~~~ /// An infinite stream of zeroes struct ZeroStream;"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:80
#, no-wrap
msgid ""
"impl Iterator<int> for ZeroStream {\n"
" fn next(&mut self) -> Option<int> {\n"
" Some(0)\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:83
msgid ""
"Reaching the end of the iterator is signalled by returning `None` instead of "
"`Some(item)`:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:89 doc/tutorial-container.md:262
#, no-wrap
msgid ""
"~~~\n"
"/// A stream of N zeroes\n"
"struct ZeroStream {\n"
" priv remaining: uint\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:95
#, no-wrap
msgid ""
"impl ZeroStream {\n"
" fn new(n: uint) -> ZeroStream {\n"
" ZeroStream { remaining: n }\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:107 doc/tutorial-container.md:284
#, no-wrap
msgid ""
"impl Iterator<int> for ZeroStream {\n"
" fn next(&mut self) -> Option<int> {\n"
" if self.remaining == 0 {\n"
" None\n"
" } else {\n"
" self.remaining -= 1;\n"
" Some(0)\n"
" }\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:109
msgid "## Container iterators"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:112
msgid ""
"Containers implement iteration over the contained elements by returning an "
"iterator object. For example, vector slices several iterators available:"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-container.md:116
msgid "`iter()` and `rev_iter()`, for immutable references to the elements"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-container.md:116
msgid ""
"`mut_iter()` and `mut_rev_iter()`, for mutable references to the elements"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-container.md:116
msgid ""
"`consume_iter()` and `consume_rev_iter`, to move the elements out by-value"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:119
msgid ""
"A typical mutable container will implement at least `iter()`, `mut_iter()` "
"and `consume_iter()` along with the reverse variants if it maintains an "
"order."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:121
msgid "### Freezing"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:125
msgid ""
"Unlike most other languages with external iterators, Rust has no *iterator "
"invalidation*. As long an iterator is still in scope, the compiler will "
"prevent modification of the container through another handle."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:130
#, no-wrap
msgid ""
"~~~\n"
"let mut xs = [1, 2, 3];\n"
"{\n"
" let _it = xs.iter();\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:136
#, no-wrap
msgid ""
" // the vector is frozen for this scope, the compiler will statically\n"
" // prevent modification\n"
"}\n"
"// the vector becomes unfrozen again at the end of the scope\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:139
msgid ""
"These semantics are due to most container iterators being implemented with "
"`&` and `&mut`."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:141
msgid "## Iterator adaptors"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:145
msgid ""
"The `IteratorUtil` trait implements common algorithms as methods extending "
"every `Iterator` implementation. For example, the `fold` method will "
"accumulate the items yielded by an `Iterator` into a single value:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:151
msgid ""
"~~~ let xs = [1, 9, 2, 3, 14, 12]; let result = xs.iter().fold(0, |"
"accumulator, item| accumulator - *item); assert_eq!(result, -41); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:153
msgid ""
"Some adaptors return an adaptor object implementing the `Iterator` trait "
"itself:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:160
msgid ""
"~~~ let xs = [1, 9, 2, 3, 14, 12]; let ys = [5, 2, 1, 8]; let sum = xs."
"iter().chain_(ys.iter()).fold(0, |a, b| a + *b); assert_eq!(sum, 57); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:164
msgid ""
"Note that some adaptors like the `chain_` method above use a trailing "
"underscore to work around an issue with method resolve. The underscores will "
"be dropped when they become unnecessary."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:166
msgid "## For loops"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:168
msgid ""
"The `for` keyword can be used as sugar for iterating through any iterator:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:171
msgid "~~~ let xs = [2, 3, 5, 7, 11, 13, 17];"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:176
#, no-wrap
msgid ""
"// print out all the elements in the vector\n"
"for x in xs.iter() {\n"
" println(x.to_str())\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:182
#, no-wrap
msgid ""
"// print out all but the first 3 elements in the vector\n"
"for x in xs.iter().skip(3) {\n"
" println(x.to_str())\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:185
msgid ""
"For loops are *often* used with a temporary iterator object, as above. They "
"can also advance the state of an iterator in a mutable location:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:189
msgid ""
"~~~ let xs = [1, 2, 3, 4, 5]; let ys = [\"foo\", \"bar\", \"baz\", \"foobar"
"\"];"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:192
msgid ""
"// create an iterator yielding tuples of elements from both vectors let mut "
"it = xs.iter().zip(ys.iter());"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:196
#, no-wrap
msgid ""
"// print out the pairs of elements up to (&3, &\"baz\")\n"
"for (x, y) in it {\n"
" printfln!(\"%d %s\", *x, *y);\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:201
#, no-wrap
msgid ""
" if *x == 3 {\n"
" break;\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:204
msgid ""
"// yield and print the last pair from the iterator printfln!(\"last: %?\", "
"it.next());"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:208
msgid "// the iterator is now fully consumed assert!(it.next().is_none()); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:210
msgid "## Conversion"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:212
msgid ""
"Iterators offer generic conversion to containers with the `collect` adaptor:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:218
msgid ""
"~~~ let xs = [0, 1, 1, 2, 3, 5, 8]; let ys = xs.rev_iter().skip(1)."
"transform(|&x| x * 2).collect::<~[int]>(); assert_eq!(ys, ~[10, 6, 4, 2, 2, "
"0]); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:221
msgid ""
"The method requires a type hint for the container type, if the surrounding "
"code does not provide sufficient information."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:225
msgid ""
"Containers can provide conversion from iterators through `collect` by "
"implementing the `FromIterator` trait. For example, the implementation for "
"vectors is as follows:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:238
#, no-wrap
msgid ""
"~~~\n"
"impl<A> FromIterator<A> for ~[A] {\n"
" pub fn from_iterator<T: Iterator<A>>(iterator: &mut T) -> ~[A] {\n"
" let (lower, _) = iterator.size_hint();\n"
" let mut xs = with_capacity(lower);\n"
" for x in iterator {\n"
" xs.push(x);\n"
" }\n"
" xs\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:240
msgid "### Size hints"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:243
msgid ""
"The `Iterator` trait provides a `size_hint` default method, returning a "
"lower bound and optionally on upper bound on the length of the iterator:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:247
msgid "~~~ fn size_hint(&self) -> (uint, Option<uint>) { (0, None) } ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:251
msgid ""
"The vector implementation of `FromIterator` from above uses the lower bound "
"to pre-allocate enough space to hold the minimum number of elements the "
"iterator will yield."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:254
msgid ""
"The default implementation is always correct, but it should be overridden if "
"the iterator can provide better information."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:256
msgid ""
"The `ZeroStream` from earlier can provide an exact lower and upper bound:"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:267
#, no-wrap
msgid ""
"impl ZeroStream {\n"
" fn new(n: uint) -> ZeroStream {\n"
" ZeroStream { remaining: n }\n"
" }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:272
#, no-wrap
msgid ""
" fn size_hint(&self) -> (uint, Option<uint>) {\n"
" (self.remaining, Some(self.remaining))\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:286
msgid "## Double-ended iterators"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:290
msgid ""
"The `DoubleEndedIterator` trait represents an iterator able to yield "
"elements from either end of a range. It inherits from the `Iterator` trait "
"and extends it with the `next_back` function."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:293
msgid ""
"A `DoubleEndedIterator` can be flipped with the `invert` adaptor, returning "
"another `DoubleEndedIterator` with `next` and `next_back` exchanged."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:300
msgid ""
"~~~ let xs = [1, 2, 3, 4, 5, 6]; let mut it = xs.iter(); printfln!(\"%?\", "
"it.next()); // prints `Some(&1)` printfln!(\"%?\", it.next()); // prints "
"`Some(&2)` printfln!(\"%?\", it.next_back()); // prints `Some(&6)`"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:306
#, no-wrap
msgid ""
"// prints `5`, `4` and `3`\n"
"for &x in it.invert() {\n"
" printfln!(\"%?\", x)\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:309
msgid ""
"The `rev_iter` and `mut_rev_iter` methods on vectors just return an inverted "
"version of the standard immutable and mutable vector iterators."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:312
msgid ""
"The `chain_`, `transform`, `filter`, `filter_map` and `peek` adaptors are "
"`DoubleEndedIterator` implementations if the underlying iterators are."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:317
msgid ""
"~~~ let xs = [1, 2, 3, 4]; let ys = [5, 6, 7, 8]; let mut it = xs.iter()."
"chain_(ys.iter()).transform(|&x| x * 2);"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:319
msgid "printfln!(\"%?\", it.next()); // prints `Some(2)`"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:325
#, no-wrap
msgid ""
"// prints `16`, `14`, `12`, `10`, `8`, `6`, `4`\n"
"for x in it.invert() {\n"
" printfln!(\"%?\", x);\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:327
msgid "## Random-access iterators"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:331
msgid ""
"The `RandomAccessIterator` trait represents an iterator offering random "
"access to the whole range. The `indexable` method retrieves the number of "
"elements accessible with the `idx` method."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:334
msgid ""
"The `chain_` adaptor is an implementation of `RandomAccessIterator` if the "
"underlying iterators are."
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:343
msgid ""
"~~~ let xs = [1, 2, 3, 4, 5]; let ys = ~[7, 9, 11]; let mut it = xs.iter()."
"chain_(ys.iter()); printfln!(\"%?\", it.idx(0)); // prints `Some(&1)` "
"printfln!(\"%?\", it.idx(5)); // prints `Some(&7)` printfln!(\"%?\", it."
"idx(7)); // prints `Some(&11)` printfln!(\"%?\", it.idx(8)); // prints `None`"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:348
msgid ""
"// yield two elements from the beginning, and one from the end it.next(); it."
"next(); it.next_back();"
msgstr ""
#. type: Plain text
#: doc/tutorial-container.md:352
msgid ""
"printfln!(\"%?\", it.idx(0)); // prints `Some(&3)` printfln!(\"%?\", it."
"idx(4)); // prints `Some(&9)` printfln!(\"%?\", it.idx(6)); // prints `None` "
"~~~"
msgstr ""
doc/po/tutorial-ffi.md.pot
-602
View File
@@ -1,602 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-08-10 07:44+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
msgid "# Introduction"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:868 doc/tutorial-ffi.md:143
msgid "# Destructors"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:2
msgid "% Rust Foreign Function Interface Tutorial"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:10
msgid ""
"This tutorial will use the [snappy](https://code.google.com/p/snappy/) "
"compression/decompression library as an introduction to writing bindings for "
"foreign code. Rust is currently unable to call directly into a C++ library, "
"but snappy includes a C interface (documented in [`snappy-c.h`](https://code."
"google.com/p/snappy/source/browse/trunk/snappy-c.h))."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:13
msgid ""
"The following is a minimal example of calling a foreign function which will "
"compile if snappy is installed:"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:16
msgid "~~~~ {.xfail-test} use std::libc::size_t;"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:21
#, no-wrap
msgid ""
"#[link_args = \"-lsnappy\"]\n"
"extern {\n"
" fn snappy_max_compressed_length(source_length: size_t) -> size_t;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:27
#, no-wrap
msgid ""
"fn main() {\n"
" let x = unsafe { snappy_max_compressed_length(100) };\n"
" println(fmt!(\"max compressed length of a 100 byte buffer: %?\", x));\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:31
msgid ""
"The `extern` block is a list of function signatures in a foreign library, in "
"this case with the platform's C ABI. The `#[link_args]` attribute is used to "
"instruct the linker to link against the snappy library so the symbols are "
"resolved."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:37
msgid ""
"Foreign functions are assumed to be unsafe so calls to them need to be "
"wrapped with `unsafe {}` as a promise to the compiler that everything "
"contained within truly is safe. C libraries often expose interfaces that "
"aren't thread-safe, and almost any function that takes a pointer argument "
"isn't valid for all possible inputs since the pointer could be dangling, and "
"raw pointers fall outside of Rust's safe memory model."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:41
msgid ""
"When declaring the argument types to a foreign function, the Rust compiler "
"will not check if the declaration is correct, so specifying it correctly is "
"part of keeping the binding correct at runtime."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:43
msgid "The `extern` block can be extended to cover the entire snappy API:"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:46
msgid "~~~~ {.xfail-test} use std::libc::{c_int, size_t};"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:65
#, no-wrap
msgid ""
"#[link_args = \"-lsnappy\"]\n"
"extern {\n"
" fn snappy_compress(input: *u8,\n"
" input_length: size_t,\n"
" compressed: *mut u8,\n"
" compressed_length: *mut size_t) -> c_int;\n"
" fn snappy_uncompress(compressed: *u8,\n"
" compressed_length: size_t,\n"
" uncompressed: *mut u8,\n"
" uncompressed_length: *mut size_t) -> c_int;\n"
" fn snappy_max_compressed_length(source_length: size_t) -> size_t;\n"
" fn snappy_uncompressed_length(compressed: *u8,\n"
" compressed_length: size_t,\n"
" result: *mut size_t) -> c_int;\n"
" fn snappy_validate_compressed_buffer(compressed: *u8,\n"
" compressed_length: size_t) -> c_int;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:67
msgid "# Creating a safe interface"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:71
msgid ""
"The raw C API needs to be wrapped to provide memory safety and make use of "
"higher-level concepts like vectors. A library can choose to expose only the "
"safe, high-level interface and hide the unsafe internal details."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:76
msgid ""
"Wrapping the functions which expect buffers involves using the `vec::raw` "
"module to manipulate Rust vectors as pointers to memory. Rust's vectors are "
"guaranteed to be a contiguous block of memory. The length is number of "
"elements currently contained, and the capacity is the total size in elements "
"of the allocated memory. The length is less than or equal to the capacity."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:84
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"pub fn validate_compressed_buffer(src: &[u8]) -> bool {\n"
" unsafe {\n"
" snappy_validate_compressed_buffer(src.as_ptr(), src.len() as size_t) == 0\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:88
msgid ""
"The `validate_compressed_buffer` wrapper above makes use of an `unsafe` "
"block, but it makes the guarantee that calling it is safe for all inputs by "
"leaving off `unsafe` from the function signature."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:91
msgid ""
"The `snappy_compress` and `snappy_uncompress` functions are more complex, "
"since a buffer has to be allocated to hold the output too."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:96
msgid ""
"The `snappy_max_compressed_length` function can be used to allocate a vector "
"with the maximum required capacity to hold the compressed output. The vector "
"can then be passed to the `snappy_compress` function as an output parameter. "
"An output parameter is also passed to retrieve the true length after "
"compression for setting the length."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:102
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"pub fn compress(src: &[u8]) -> ~[u8] {\n"
" unsafe {\n"
" let srclen = src.len() as size_t;\n"
" let psrc = src.as_ptr();\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:106
#, no-wrap
msgid ""
" let mut dstlen = snappy_max_compressed_length(srclen);\n"
" let mut dst = vec::with_capacity(dstlen as uint);\n"
" let pdst = dst.as_mut_ptr();\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:113
#, no-wrap
msgid ""
" snappy_compress(psrc, srclen, pdst, &mut dstlen);\n"
" dst.set_len(dstlen as uint);\n"
" dst\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:116
msgid ""
"Decompression is similar, because snappy stores the uncompressed size as "
"part of the compression format and `snappy_uncompressed_length` will "
"retrieve the exact buffer size required."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:122
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"pub fn uncompress(src: &[u8]) -> Option<~[u8]> {\n"
" unsafe {\n"
" let srclen = src.len() as size_t;\n"
" let psrc = src.as_ptr();\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:125
#, no-wrap
msgid ""
" let mut dstlen: size_t = 0;\n"
" snappy_uncompressed_length(psrc, srclen, &mut dstlen);\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:128
#, no-wrap
msgid ""
" let mut dst = vec::with_capacity(dstlen as uint);\n"
" let pdst = dst.as_mut_ptr();\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:138
#, no-wrap
msgid ""
" if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 {\n"
" dst.set_len(dstlen as uint);\n"
" Some(dst)\n"
" } else {\n"
" None // SNAPPY_INVALID_INPUT\n"
" }\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:141
msgid ""
"For reference, the examples used here are also available as an [library on "
"GitHub](https://github.com/thestinger/rust-snappy)."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:147
msgid ""
"Foreign libraries often hand off ownership of resources to the calling code, "
"which should be wrapped in a destructor to provide safety and guarantee "
"their release."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:150
msgid ""
"A type with the same functionality as owned boxes can be implemented by "
"wrapping `malloc` and `free`:"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:156
msgid ""
"~~~~ use std::cast; use std::libc::{c_void, size_t, malloc, free}; use std::"
"ptr; use std::unstable::intrinsics;"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:161
#, no-wrap
msgid ""
"// a wrapper around the handle returned by the foreign code\n"
"pub struct Unique<T> {\n"
" priv ptr: *mut T\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:172
#, no-wrap
msgid ""
"impl<T: Send> Unique<T> {\n"
" pub fn new(value: T) -> Unique<T> {\n"
" unsafe {\n"
" let ptr = malloc(std::mem::size_of::<T>() as size_t) as *mut T;\n"
" assert!(!ptr::is_null(ptr));\n"
" // `*ptr` is uninitialized, and `*ptr = value` would attempt to destroy it\n"
" intrinsics::move_val_init(&mut *ptr, value);\n"
" Unique{ptr: ptr}\n"
" }\n"
" }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:177
#, no-wrap
msgid ""
" // the 'r lifetime results in the same semantics as `&*x` with ~T\n"
" pub fn borrow<'r>(&'r self) -> &'r T {\n"
" unsafe { cast::copy_lifetime(self, &*self.ptr) }\n"
" }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:183
#, no-wrap
msgid ""
" // the 'r lifetime results in the same semantics as `&mut *x` with ~T\n"
" pub fn borrow_mut<'r>(&'r mut self) -> &'r mut T {\n"
" unsafe { cast::copy_mut_lifetime(self, &mut *self.ptr) }\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:195
#, no-wrap
msgid ""
"#[unsafe_destructor]\n"
"impl<T: Send> Drop for Unique<T> {\n"
" fn drop(&self) {\n"
" unsafe {\n"
" let x = intrinsics::init(); // dummy value to swap in\n"
" // moving the object out is needed to call the destructor\n"
" ptr::replace_ptr(self.ptr, x);\n"
" free(self.ptr as *c_void)\n"
" }\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:202
#, no-wrap
msgid ""
"// A comparison between the built-in ~ and this reimplementation\n"
"fn main() {\n"
" {\n"
" let mut x = ~5;\n"
" *x = 10;\n"
" } // `x` is freed here\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:209
#, no-wrap
msgid ""
" {\n"
" let mut y = Unique::new(5);\n"
" *y.borrow_mut() = 10;\n"
" } // `y` is freed here\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:211
msgid "# Linking"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:215
msgid ""
"In addition to the `#[link_args]` attribute for explicitly passing arguments "
"to the linker, an `extern mod` block will pass `-lmodname` to the linker by "
"default unless it has a `#[nolink]` attribute applied."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:217
msgid "# Unsafe blocks"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:221
msgid ""
"Some operations, like dereferencing unsafe pointers or calling functions "
"that have been marked unsafe are only allowed inside unsafe blocks. Unsafe "
"blocks isolate unsafety and are a promise to the compiler that the unsafety "
"does not leak out of the block."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:224
msgid ""
"Unsafe functions, on the other hand, advertise it to the world. An unsafe "
"function is written like this:"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:228
msgid "~~~~ unsafe fn kaboom(ptr: *int) -> int { *ptr } ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:230
msgid ""
"This function can only be called from an `unsafe` block or another `unsafe` "
"function."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:232
msgid "# Accessing foreign globals"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:236
msgid ""
"Foreign APIs often export a global variable which could do something like "
"track global state. In order to access these variables, you declare them in "
"`extern` blocks with the `static` keyword:"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:239
msgid "~~~{.xfail-test} use std::libc;"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:244
#, no-wrap
msgid ""
"#[link_args = \"-lreadline\"]\n"
"extern {\n"
" static rl_readline_version: libc::c_int;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:250
#, no-wrap
msgid ""
"fn main() {\n"
" println(fmt!(\"You have readline version %d installed.\",\n"
" rl_readline_version as int));\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:254
msgid ""
"Alternatively, you may need to alter global state provided by a foreign "
"interface. To do this, statics can be declared with `mut` so rust can mutate "
"them."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:258
msgid "~~~{.xfail-test} use std::libc; use std::ptr;"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:263
#, no-wrap
msgid ""
"#[link_args = \"-lreadline\"]\n"
"extern {\n"
" static mut rl_prompt: *libc::c_char;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:272
#, no-wrap
msgid ""
"fn main() {\n"
" do \"[my-awesome-shell] $\".as_c_str |buf| {\n"
" unsafe { rl_prompt = buf; }\n"
" // get a line, process it\n"
" unsafe { rl_prompt = ptr::null(); }\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:274
msgid "# Foreign calling conventions"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:279
msgid ""
"Most foreign code exposes a C ABI, and Rust uses the platform's C calling "
"convention by default when calling foreign functions. Some foreign "
"functions, most notably the Windows API, use other calling conventions. Rust "
"provides the `abi` attribute as a way to hint to the compiler which calling "
"convention to use:"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:288
#, no-wrap
msgid ""
"~~~~\n"
"#[cfg(target_os = \"win32\")]\n"
"#[abi = \"stdcall\"]\n"
"#[link_name = \"kernel32\"]\n"
"extern {\n"
" fn SetEnvironmentVariableA(n: *u8, v: *u8) -> int;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:292
msgid ""
"The `abi` attribute applies to a foreign module (it cannot be applied to a "
"single function within a module), and must be either `\"cdecl\"` or `"
"\"stdcall\"`. The compiler may eventually support other calling conventions."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:294
msgid "# Interoperability with foreign code"
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:298
msgid ""
"Rust guarantees that the layout of a `struct` is compatible with the "
"platform's representation in C. A `#[packed]` attribute is available, which "
"will lay out the struct members without padding. However, there are "
"currently no guarantees about the layout of an `enum`."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:305
msgid ""
"Rust's owned and managed boxes use non-nullable pointers as handles which "
"point to the contained object. However, they should not be manually created "
"because they are managed by internal allocators. Borrowed pointers can "
"safely be assumed to be non-nullable pointers directly to the type. However, "
"breaking the borrow checking or mutability rules is not guaranteed to be "
"safe, so prefer using raw pointers (`*`) if that's needed because the "
"compiler can't make as many assumptions about them."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:310
msgid ""
"Vectors and strings share the same basic memory layout, and utilities are "
"available in the `vec` and `str` modules for working with C APIs. Strings "
"are terminated with `\\0` for interoperability with C, but it should not be "
"assumed because a slice will not always be nul-terminated. Instead, the "
"`str::as_c_str` function should be used."
msgstr ""
#. type: Plain text
#: doc/tutorial-ffi.md:312
msgid ""
"The standard library includes type aliases and function definitions for the "
"C standard library in the `libc` module, and Rust links against `libc` and "
"`libm` by default."
msgstr ""
doc/po/tutorial-macros.md.pot
-683
View File
@@ -1,683 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-07-22 23:37+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
msgid "# Introduction"
msgstr ""
#. type: Plain text
#: doc/rust.md:2136 doc/rust.md:2223 doc/tutorial-macros.md:323
msgid "~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:2
msgid "% Rust Macros Tutorial"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:12
msgid ""
"Functions are the primary tool that programmers can use to build "
"abstractions. Sometimes, however, programmers want to abstract over compile-"
"time syntax rather than run-time values. Macros provide syntactic "
"abstraction. For an example of how this can be useful, consider the "
"following two code fragments, which both pattern-match on their input and "
"both return early in one case, doing nothing otherwise:"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:30
#, no-wrap
msgid ""
"~~~~\n"
"# enum t { special_a(uint), special_b(uint) };\n"
"# fn f() -> uint {\n"
"# let input_1 = special_a(0);\n"
"# let input_2 = special_a(0);\n"
"match input_1 {\n"
" special_a(x) => { return x; }\n"
" _ => {}\n"
"}\n"
"// ...\n"
"match input_2 {\n"
" special_b(x) => { return x; }\n"
" _ => {}\n"
"}\n"
"# return 0u;\n"
"# }\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:38
msgid ""
"This code could become tiresome if repeated many times. However, no "
"function can capture its functionality to make it possible to abstract the "
"repetition away. Rust's macro system, however, can eliminate the "
"repetition. Macros are lightweight custom syntax extensions, themselves "
"defined using the `macro_rules!` syntax extension. The following "
"`early_return` macro captures the pattern in the above code:"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:59
#, no-wrap
msgid ""
"~~~~\n"
"# enum t { special_a(uint), special_b(uint) };\n"
"# fn f() -> uint {\n"
"# let input_1 = special_a(0);\n"
"# let input_2 = special_a(0);\n"
"macro_rules! early_return(\n"
" ($inp:expr $sp:ident) => ( // invoke it like `(input_5 special_e)`\n"
" match $inp {\n"
" $sp(x) => { return x; }\n"
" _ => {}\n"
" }\n"
" );\n"
")\n"
"// ...\n"
"early_return!(input_1 special_a);\n"
"// ...\n"
"early_return!(input_2 special_b);\n"
"# return 0;\n"
"# }\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:65
msgid ""
"Macros are defined in pattern-matching style: in the above example, the text "
"`($inp:expr $sp:ident)` that appears on the left-hand side of the `=>` is "
"the *macro invocation syntax*, a pattern denoting how to write a call to the "
"macro. The text on the right-hand side of the `=>`, beginning with `match "
"$inp`, is the *macro transcription syntax*: what the macro expands to."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:67
msgid "# Invocation syntax"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:71
msgid ""
"The macro invocation syntax specifies the syntax for the arguments to the "
"macro. It appears on the left-hand side of the `=>` in a macro definition. "
"It conforms to the following rules:"
msgstr ""
#. type: Bullet: '1. '
#: doc/tutorial-macros.md:76
msgid "It must be surrounded by parentheses."
msgstr ""
#. type: Bullet: '2. '
#: doc/tutorial-macros.md:76
msgid "`$` has special meaning (described below)."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:76
#, no-wrap
msgid ""
"3. The `()`s, `[]`s, and `{}`s it contains must balance. For example, `([)` is\n"
"forbidden.\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:78
msgid "Otherwise, the invocation syntax is free-form."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:83
#, no-wrap
msgid ""
"To take as an argument a fragment of Rust code, write `$` followed by a name\n"
" (for use on the right-hand side), followed by a `:`, followed by a *fragment\n"
" specifier*. The fragment specifier denotes the sort of fragment to match. The\n"
" most common fragment specifiers are:\n"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-macros.md:92
msgid ""
"`ident` (an identifier, referring to a variable or item. Examples: `f`, `x`, "
"`foo`.)"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-macros.md:92
msgid ""
"`expr` (an expression. Examples: `2 + 2`; `if true then { 1 } else { 2 }`; "
"`f(42)`.)"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-macros.md:92
msgid "`ty` (a type. Examples: `int`, `~[(char, ~str)]`, `&T`.)"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-macros.md:92
msgid ""
"`pat` (a pattern, usually appearing in a `match` or on the left-hand side of "
"a declaration. Examples: `Some(t)`; `(17, 'a')`; `_`.)"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-macros.md:92
msgid ""
"`block` (a sequence of actions. Example: `{ log(error, \"hi\"); return 12; }"
"`)"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:95
msgid ""
"The parser interprets any token that's not preceded by a `$` literally. "
"Rust's usual rules of tokenization apply,"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:98
msgid ""
"So `($x:ident -> (($e:expr)))`, though excessively fancy, would designate a "
"macro that could be invoked like: `my_macro!(i->(( 2+2 )))`."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:100
msgid "## Invocation location"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:105
msgid ""
"A macro invocation may take the place of (and therefore expand to) an "
"expression, an item, or a statement. The Rust parser will parse the macro "
"invocation as a \"placeholder\" for whichever of those three nonterminals is "
"appropriate for the location."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:112
msgid ""
"At expansion time, the output of the macro will be parsed as whichever of "
"the three nonterminals it stands in for. This means that a single macro "
"might, for example, expand to an item or an expression, depending on its "
"arguments (and cause a syntax error if it is called with the wrong argument "
"for its location). Although this behavior sounds excessively dynamic, it is "
"known to be useful under some circumstances."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:115
msgid "# Transcription syntax"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:119
msgid ""
"The right-hand side of the `=>` follows the same rules as the left-hand "
"side, except that a `$` need only be followed by the name of the syntactic "
"fragment to transcribe into the macro expansion; its type need not be "
"repeated."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:126
msgid ""
"The right-hand side must be enclosed by delimiters, which the transcriber "
"ignores. Therefore `() => ((1,2,3))` is a macro that expands to a tuple "
"expression, `() => (let $x=$val)` is a macro that expands to a statement, "
"and `() => (1,2,3)` is a macro that expands to a syntax error (since the "
"transcriber interprets the parentheses on the right-hand-size as delimiters, "
"and `1,2,3` is not a valid Rust expression on its own)."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:133
msgid ""
"Except for permissibility of `$name` (and `$(...)*`, discussed below), the "
"right-hand side of a macro definition is ordinary Rust syntax. In "
"particular, macro invocations (including invocations of the macro currently "
"being defined) are permitted in expression, statement, and item locations. "
"However, nothing else about the code is examined or executed by the macro "
"system; execution still has to wait until run-time."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:135
msgid "## Interpolation location"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:139
msgid ""
"The interpolation `$argument_name` may appear in any location consistent "
"with its fragment specifier (i.e., if it is specified as `ident`, it may be "
"used anywhere an identifier is permitted)."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:141
msgid "# Multiplicity"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:143
msgid "## Invocation"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:150
msgid ""
"Going back to the motivating example, recall that `early_return` expanded "
"into a `match` that would `return` if the `match`'s scrutinee matched the "
"\"special case\" identifier provided as the second argument to "
"`early_return`, and do nothing otherwise. Now suppose that we wanted to "
"write a version of `early_return` that could handle a variable number of "
"\"special\" cases."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:156
msgid ""
"The syntax `$(...)*` on the left-hand side of the `=>` in a macro definition "
"accepts zero or more occurrences of its contents. It works much like the `*` "
"operator in regular expressions. It also supports a separator token (a comma-"
"separated list could be written `$(...),*`), and `+` instead of `*` to mean "
"\"at least one\"."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:179
#, no-wrap
msgid ""
"~~~~\n"
"# enum t { special_a(uint),special_b(uint),special_c(uint),special_d(uint)};\n"
"# fn f() -> uint {\n"
"# let input_1 = special_a(0);\n"
"# let input_2 = special_a(0);\n"
"macro_rules! early_return(\n"
" ($inp:expr, [ $($sp:ident)|+ ]) => (\n"
" match $inp {\n"
" $(\n"
" $sp(x) => { return x; }\n"
" )+\n"
" _ => {}\n"
" }\n"
" );\n"
")\n"
"// ...\n"
"early_return!(input_1, [special_a|special_c|special_d]);\n"
"// ...\n"
"early_return!(input_2, [special_b]);\n"
"# return 0;\n"
"# }\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:181
msgid "### Transcription"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:191
msgid ""
"As the above example demonstrates, `$(...)*` is also valid on the right-hand "
"side of a macro definition. The behavior of `*` in transcription, especially "
"in cases where multiple `*`s are nested, and multiple different names are "
"involved, can seem somewhat magical and intuitive at first. The system that "
"interprets them is called \"Macro By Example\". The two rules to keep in "
"mind are (1) the behavior of `$(...)*` is to walk through one \"layer\" of "
"repetitions for all of the `$name`s it contains in lockstep, and (2) each `"
"$name` must be under at least as many `$(...)*`s as it was matched against. "
"If it is under more, it'll be repeated, as appropriate."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:193
msgid "## Parsing limitations"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:197
msgid ""
"For technical reasons, there are two limitations to the treatment of syntax "
"fragments by the macro parser:"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:210
#, no-wrap
msgid ""
"1. The parser will always parse as much as possible of a Rust syntactic\n"
"fragment. For example, if the comma were omitted from the syntax of\n"
"`early_return!` above, `input_1 [` would've been interpreted as the beginning\n"
"of an array index. In fact, invoking the macro would have been impossible.\n"
"2. The parser must have eliminated all ambiguity by the time it reaches a\n"
"`$name:fragment_specifier` declaration. This limitation can result in parse\n"
"errors when declarations occur at the beginning of, or immediately after,\n"
"a `$(...)*`. For example, the grammar `$($t:ty)* $e:expr` will always fail to\n"
"parse because the parser would be forced to choose between parsing `t` and\n"
"parsing `e`. Changing the invocation syntax to require a distinctive token in\n"
"front can solve the problem. In the above example, `$(T $t:ty)* E $e:exp`\n"
"solves the problem.\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:212
msgid "# Macro argument pattern matching"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:214
msgid "Now consider code like the following:"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:216
msgid "## Motivation"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:236
#, no-wrap
msgid ""
"~~~~\n"
"# enum t1 { good_1(t2, uint), bad_1 };\n"
"# pub struct t2 { body: t3 }\n"
"# enum t3 { good_2(uint), bad_2};\n"
"# fn f(x: t1) -> uint {\n"
"match x {\n"
" good_1(g1, val) => {\n"
" match g1.body {\n"
" good_2(result) => {\n"
" // complicated stuff goes here\n"
" return result + val;\n"
" },\n"
" _ => fail!(\"Didn't get good_2\")\n"
" }\n"
" }\n"
" _ => return 0 // default value\n"
"}\n"
"# }\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:241
msgid ""
"All the complicated stuff is deeply indented, and the error-handling code is "
"separated from matches that fail. We'd like to write a macro that performs a "
"match, but with a syntax that suits the problem better. The following macro "
"can solve the problem:"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:263
#, no-wrap
msgid ""
"~~~~\n"
"macro_rules! biased_match (\n"
" // special case: `let (x) = ...` is illegal, so use `let x = ...` instead\n"
" ( ($e:expr) ~ ($p:pat) else $err:stmt ;\n"
" binds $bind_res:ident\n"
" ) => (\n"
" let $bind_res = match $e {\n"
" $p => ( $bind_res ),\n"
" _ => { $err }\n"
" };\n"
" );\n"
" // more than one name; use a tuple\n"
" ( ($e:expr) ~ ($p:pat) else $err:stmt ;\n"
" binds $( $bind_res:ident ),*\n"
" ) => (\n"
" let ( $( $bind_res ),* ) = match $e {\n"
" $p => ( $( $bind_res ),* ),\n"
" _ => { $err }\n"
" };\n"
" )\n"
")\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:277
#, no-wrap
msgid ""
"# enum t1 { good_1(t2, uint), bad_1 };\n"
"# pub struct t2 { body: t3 }\n"
"# enum t3 { good_2(uint), bad_2};\n"
"# fn f(x: t1) -> uint {\n"
"biased_match!((x) ~ (good_1(g1, val)) else { return 0 };\n"
" binds g1, val )\n"
"biased_match!((g1.body) ~ (good_2(result) )\n"
" else { fail!(\"Didn't get good_2\") };\n"
" binds result )\n"
"// complicated stuff goes here\n"
"return result + val;\n"
"# }\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:288
#, no-wrap
msgid ""
"This solves the indentation problem. But if we have a lot of chained matches\n"
"like this, we might prefer to write a single macro invocation. The input\n"
"pattern we want is clear:\n"
"~~~~\n"
"# macro_rules! b(\n"
" ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )*\n"
" binds $( $bind_res:ident ),*\n"
" )\n"
"# => (0))\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:291
msgid ""
"However, it's not possible to directly expand to nested match statements. "
"But there is a solution."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:293
msgid "## The recursive approach to macro writing"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:297
msgid ""
"A macro may accept multiple different input grammars. The first one to "
"successfully match the actual argument to a macro invocation is the one that "
"\"wins\"."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:301
msgid ""
"In the case of the example above, we want to write a recursive macro to "
"process the semicolon-terminated lines, one-by-one. So, we want the "
"following input patterns:"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:308
#, no-wrap
msgid ""
"~~~~\n"
"# macro_rules! b(\n"
" ( binds $( $bind_res:ident ),* )\n"
"# => (0))\n"
"~~~~\n"
"...and:\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:317
#, no-wrap
msgid ""
"~~~~\n"
"# macro_rules! b(\n"
" ( ($e :expr) ~ ($p :pat) else $err :stmt ;\n"
" $( ($e_rest:expr) ~ ($p_rest:pat) else $err_rest:stmt ; )*\n"
" binds $( $bind_res:ident ),*\n"
" )\n"
"# => (0))\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:321
msgid ""
"The resulting macro looks like this. Note that the separation into "
"`biased_match!` and `biased_match_rec!` occurs only because we have an outer "
"piece of syntax (the `let`) which we only want to transcribe once."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:342
#, no-wrap
msgid ""
"macro_rules! biased_match_rec (\n"
" // Handle the first layer\n"
" ( ($e :expr) ~ ($p :pat) else $err :stmt ;\n"
" $( ($e_rest:expr) ~ ($p_rest:pat) else $err_rest:stmt ; )*\n"
" binds $( $bind_res:ident ),*\n"
" ) => (\n"
" match $e {\n"
" $p => {\n"
" // Recursively handle the next layer\n"
" biased_match_rec!($( ($e_rest) ~ ($p_rest) else $err_rest ; )*\n"
" binds $( $bind_res ),*\n"
" )\n"
" }\n"
" _ => { $err }\n"
" }\n"
" );\n"
" ( binds $( $bind_res:ident ),* ) => ( ($( $bind_res ),*) )\n"
")\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:364
#, no-wrap
msgid ""
"// Wrap the whole thing in a `let`.\n"
"macro_rules! biased_match (\n"
" // special case: `let (x) = ...` is illegal, so use `let x = ...` instead\n"
" ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )*\n"
" binds $bind_res:ident\n"
" ) => (\n"
" let ( $( $bind_res ),* ) = biased_match_rec!(\n"
" $( ($e) ~ ($p) else $err ; )*\n"
" binds $bind_res\n"
" );\n"
" );\n"
" // more than one name: use a tuple\n"
" ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )*\n"
" binds $( $bind_res:ident ),*\n"
" ) => (\n"
" let ( $( $bind_res ),* ) = biased_match_rec!(\n"
" $( ($e) ~ ($p) else $err ; )*\n"
" binds $( $bind_res ),*\n"
" );\n"
" )\n"
")\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:378
#, no-wrap
msgid ""
"# enum t1 { good_1(t2, uint), bad_1 };\n"
"# pub struct t2 { body: t3 }\n"
"# enum t3 { good_2(uint), bad_2};\n"
"# fn f(x: t1) -> uint {\n"
"biased_match!(\n"
" (x) ~ (good_1(g1, val)) else { return 0 };\n"
" (g1.body) ~ (good_2(result) ) else { fail!(\"Didn't get good_2\") };\n"
" binds val, result )\n"
"// complicated stuff goes here\n"
"return result + val;\n"
"# }\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:382
msgid ""
"This technique applies to many cases where transcribing a result all at once "
"is not possible. The resulting code resembles ordinary functional "
"programming in some respects, but has some important differences from "
"functional programming."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:390
msgid ""
"The first difference is important, but also easy to forget: the "
"transcription (right-hand) side of a `macro_rules!` rule is literal syntax, "
"which can only be executed at run-time. If a piece of transcription syntax "
"does not itself appear inside another macro invocation, it will become part "
"of the final program. If it is inside a macro invocation (for example, the "
"recursive invocation of `biased_match_rec!`), it does have the opportunity "
"to affect transcription, but only through the process of attempted pattern "
"matching."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:398
msgid ""
"The second, related, difference is that the evaluation order of macros feels "
"\"backwards\" compared to ordinary programming. Given an invocation `m1!(m2!"
"())`, the expander first expands `m1!`, giving it as input the literal "
"syntax `m2!()`. If it transcribes its argument unchanged into an appropriate "
"position (in particular, not as an argument to yet another macro "
"invocation), the expander will then proceed to evaluate `m2!()` (along with "
"any other macro invocations `m1!(m2!())` produced)."
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:400
msgid "# A final note"
msgstr ""
#. type: Plain text
#: doc/tutorial-macros.md:407
msgid ""
"Macros, as currently implemented, are not for the faint of heart. Even "
"ordinary syntax errors can be more difficult to debug when they occur inside "
"a macro, and errors caused by parse problems in generated code can be very "
"tricky. Invoking the `log_syntax!` macro can help elucidate intermediate "
"states, invoking `trace_macros!(true)` will automatically print those "
"intermediate states out, and passing the flag `--pretty expanded` as a "
"command-line argument to the compiler will show the result of expansion."
msgstr ""
doc/po/tutorial-tasks.md.pot
-1070
View File
@@ -1,1070 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-08-08 22:27+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
msgid "# Introduction"
msgstr ""
#. type: Plain text
#: doc/rust.md:1952 doc/tutorial-tasks.md:648
msgid "# } ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:2
msgid "% Rust Tasks and Communication Tutorial"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:10
msgid ""
"Rust provides safe concurrency through a combination of lightweight, memory-"
"isolated tasks and message passing. This tutorial will describe the "
"concurrency model in Rust, how it relates to the Rust type system, and "
"introduce the fundamental library abstractions for constructing concurrent "
"programs."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:19
msgid ""
"Rust tasks are not the same as traditional threads: rather, they are "
"considered _green threads_, lightweight units of execution that the Rust "
"runtime schedules cooperatively onto a small number of operating system "
"threads. On a multi-core system Rust tasks will be scheduled in parallel by "
"default. Because tasks are significantly cheaper to create than traditional "
"threads, Rust can create hundreds of thousands of concurrent tasks on a "
"typical 32-bit system. In general, all Rust code executes inside a task, "
"including the `main` function."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:26
msgid ""
"In order to make efficient use of memory Rust tasks have dynamically sized "
"stacks. A task begins its life with a small amount of stack space "
"(currently in the low thousands of bytes, depending on platform), and "
"acquires more stack as needed. Unlike in languages such as C, a Rust task "
"cannot accidentally write to memory beyond the end of the stack, causing "
"crashes or worse."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:32
msgid ""
"Tasks provide failure isolation and recovery. When a fatal error occurs in "
"Rust code as a result of an explicit call to `fail!()`, an assertion "
"failure, or another invalid operation, the runtime system destroys the "
"entire task. Unlike in languages such as Java and C++, there is no way to "
"`catch` an exception. Instead, tasks may monitor each other for failure."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:37
msgid ""
"Tasks use Rust's type system to provide strong memory safety guarantees. In "
"particular, the type system guarantees that tasks cannot share mutable state "
"with each other. Tasks communicate with each other by transferring _owned_ "
"data through the global _exchange heap_."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:39
msgid "## A note about the libraries"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:44
msgid ""
"While Rust's type system provides the building blocks needed for safe and "
"efficient tasks, all of the task functionality itself is implemented in the "
"standard and extra libraries, which are still under development and do not "
"always present a consistent or complete interface."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:47
msgid ""
"For your reference, these are the standard modules involved in Rust "
"concurrency at this writing:"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-tasks.md:56
msgid "[`std::task`] - All code relating to tasks and task scheduling,"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-tasks.md:56
msgid "[`std::comm`] - The message passing interface,"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-tasks.md:56
msgid "[`std::pipes`] - The underlying messaging infrastructure,"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-tasks.md:56
msgid "[`extra::comm`] - Additional messaging types based on `std::pipes`,"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-tasks.md:56
msgid "[`extra::sync`] - More exotic synchronization tools, including locks,"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-tasks.md:56
msgid ""
"[`extra::arc`] - The Arc (atomically reference counted) type, for safely "
"sharing immutable data,"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial-tasks.md:56
msgid ""
"[`extra::future`] - A type representing values that may be computed "
"concurrently and retrieved at a later time."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:64
msgid ""
"[`std::task`]: std/task.html [`std::comm`]: std/comm.html [`std::pipes`]: "
"std/pipes.html [`extra::comm`]: extra/comm.html [`extra::sync`]: extra/sync."
"html [`extra::arc`]: extra/arc.html [`extra::future`]: extra/future.html"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:66
msgid "# Basics"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:72
msgid ""
"The programming interface for creating and managing tasks lives in the "
"`task` module of the `std` library, and is thus available to all Rust code "
"by default. At its simplest, creating a task is a matter of calling the "
"`spawn` function with a closure argument. `spawn` executes the closure in "
"the new task."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:76
msgid "~~~~ # use std::io::println; # use std::task::spawn;"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:80
msgid ""
"// Print something profound in a different task using a named function fn "
"print_message() { println(\"I am running in a different task!\"); } "
"spawn(print_message);"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:83
msgid ""
"// Print something more profound in a different task using a lambda "
"expression spawn( || println(\"I am also running in a different task!\") );"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:89
#, no-wrap
msgid ""
"// The canonical way to spawn is using `do` notation\n"
"do spawn {\n"
" println(\"I too am running in a different task!\");\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:95
msgid ""
"In Rust, there is nothing special about creating tasks: a task is not a "
"concept that appears in the language semantics. Instead, Rust's type system "
"provides all the tools necessary to implement safe concurrency: "
"particularly, _owned types_. The language leaves the implementation details "
"to the standard library."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:102
msgid ""
"The `spawn` function has a very simple type signature: `fn spawn(f: proc())`. "
"Because it accepts only owned closures, and owned closures contain only "
"owned data, `spawn` can safely move the entire closure and all its "
"associated state into an entirely different task for execution. Like any "
"closure, the function passed to `spawn` may capture an environment that it "
"carries across tasks."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:109
msgid ""
"~~~ # use std::io::println; # use std::task::spawn; # fn "
"generate_task_number() -> int { 0 } // Generate some state locally let "
"child_task_number = generate_task_number();"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:115
#, no-wrap
msgid ""
"do spawn {\n"
" // Capture it in the remote task\n"
" println(fmt!(\"I am child number %d\", child_task_number));\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:119
msgid ""
"By default, the scheduler multiplexes tasks across the available cores, "
"running in parallel. Thus, on a multicore machine, running the following "
"code should interleave the output in vaguely random order."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:123
msgid "~~~ # use std::io::print; # use std::task::spawn;"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:130
#, no-wrap
msgid ""
"for child_task_number in range(0, 20) {\n"
" do spawn {\n"
" print(fmt!(\"I am child number %d\\n\", child_task_number));\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:132
msgid "## Communication"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:137
msgid ""
"Now that we have spawned a new task, it would be nice if we could "
"communicate with it. Recall that Rust does not have shared mutable state, so "
"one task may not manipulate variables owned by another task. Instead we use "
"*pipes*."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:142
msgid ""
"A pipe is simply a pair of endpoints: one for sending messages and another "
"for receiving messages. Pipes are low-level communication building-blocks "
"and so come in a variety of forms, each one appropriate for a different use "
"case. In what follows, we cover the most commonly used varieties."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:148
msgid ""
"The simplest way to create a pipe is to use the `pipes::stream` function to "
"create a `(Port, Chan)` pair. In Rust parlance, a *channel* is a sending "
"endpoint of a pipe, and a *port* is the receiving endpoint. Consider the "
"following example of calculating two results concurrently:"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:152
msgid "~~~~ # use std::task::spawn; # use std::comm::{stream, Port, Chan};"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:154
msgid "let (port, chan): (Port<int>, Chan<int>) = stream();"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:159
#, no-wrap
msgid ""
"do spawn || {\n"
" let result = some_expensive_computation();\n"
" chan.send(result);\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:165
msgid ""
"some_other_expensive_computation(); let result = port.recv(); # fn "
"some_expensive_computation() -> int { 42 } # fn "
"some_other_expensive_computation() {} ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:170
msgid ""
"Let's examine this example in detail. First, the `let` statement creates a "
"stream for sending and receiving integers (the left-hand side of the `let`, "
"`(chan, port)`, is an example of a *destructuring let*: the pattern "
"separates a tuple into its component parts)."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:175
msgid ""
"~~~~ # use std::comm::{stream, Chan, Port}; let (port, chan): (Port<int>, "
"Chan<int>) = stream(); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:179
msgid ""
"The child task will use the channel to send data to the parent task, which "
"will wait to receive the data on the port. The next statement spawns the "
"child task."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:190
#, no-wrap
msgid ""
"~~~~\n"
"# use std::task::spawn;\n"
"# use std::comm::stream;\n"
"# fn some_expensive_computation() -> int { 42 }\n"
"# let (port, chan) = stream();\n"
"do spawn || {\n"
" let result = some_expensive_computation();\n"
" chan.send(result);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:196
msgid ""
"Notice that the creation of the task closure transfers `chan` to the child "
"task implicitly: the closure captures `chan` in its environment. Both `Chan` "
"and `Port` are sendable types and may be captured into tasks or otherwise "
"transferred between them. In the example, the child task runs an expensive "
"computation, then sends the result over the captured channel."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:200
msgid ""
"Finally, the parent continues with some other expensive computation, then "
"waits for the child's result to arrive on the port:"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:209
msgid ""
"~~~~ # use std::comm::{stream}; # fn some_other_expensive_computation() {} # "
"let (port, chan) = stream::<int>(); # chan.send(0); "
"some_other_expensive_computation(); let result = port.recv(); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:215
msgid ""
"The `Port` and `Chan` pair created by `stream` enables efficient "
"communication between a single sender and a single receiver, but multiple "
"senders cannot use a single `Chan`, and multiple receivers cannot use a "
"single `Port`. What if our example needed to compute multiple results "
"across a number of tasks? The following program is ill-typed:"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:221
msgid ""
"~~~ {.xfail-test} # use std::task::{spawn}; # use std::comm::{stream, Port, "
"Chan}; # fn some_expensive_computation() -> int { 42 } let (port, chan) = "
"stream();"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:225
#, no-wrap
msgid ""
"do spawn {\n"
" chan.send(some_expensive_computation());\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:232
#, no-wrap
msgid ""
"// ERROR! The previous spawn statement already owns the channel,\n"
"// so the compiler will not allow it to be captured again\n"
"do spawn {\n"
" chan.send(some_expensive_computation());\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:235
msgid ""
"Instead we can use a `SharedChan`, a type that allows a single `Chan` to be "
"shared by multiple senders."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:239
msgid "~~~ # use std::task::spawn; # use std::comm::{stream, SharedChan};"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:242
msgid "let (port, chan) = stream(); let chan = SharedChan::new(chan);"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:250
#, no-wrap
msgid ""
"for init_val in range(0u, 3) {\n"
" // Create a new channel handle to distribute to the child task\n"
" let child_chan = chan.clone();\n"
" do spawn {\n"
" child_chan.send(some_expensive_computation(init_val));\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:254
msgid ""
"let result = port.recv() + port.recv() + port.recv(); # fn "
"some_expensive_computation(_i: uint) -> int { 42 } ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:263
msgid ""
"Here we transfer ownership of the channel into a new `SharedChan` value. "
"Like `Chan`, `SharedChan` is a non-copyable, owned type (sometimes also "
"referred to as an *affine* or *linear* type). Unlike with `Chan`, though, "
"the programmer may duplicate a `SharedChan`, with the `clone()` method. A "
"cloned `SharedChan` produces a new handle to the same channel, allowing "
"multiple tasks to send data to a single port. Between `spawn`, `stream` and "
"`SharedChan`, we have enough tools to implement many useful concurrency "
"patterns."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:268
msgid ""
"Note that the above `SharedChan` example is somewhat contrived since you "
"could also simply use three `stream` pairs, but it serves to illustrate the "
"point. For reference, written with multiple streams, it might look like the "
"example below."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:273
msgid "~~~ # use std::task::spawn; # use std::comm::stream; # use std::vec;"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:282
#, no-wrap
msgid ""
"// Create a vector of ports, one for each child task\n"
"let ports = do vec::from_fn(3) |init_val| {\n"
" let (port, chan) = stream();\n"
" do spawn {\n"
" chan.send(some_expensive_computation(init_val));\n"
" }\n"
" port\n"
"};\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:287
msgid ""
"// Wait on each port, accumulating the results let result = ports.iter()."
"fold(0, |accum, port| accum + port.recv() ); # fn "
"some_expensive_computation(_i: uint) -> int { 42 } ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:291
msgid ""
"## Backgrounding computations: Futures With `extra::future`, rust has a "
"mechanism for requesting a computation and getting the result later."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:299
#, no-wrap
msgid ""
"The basic example below illustrates this.\n"
"~~~\n"
"# fn make_a_sandwich() {};\n"
"fn fib(n: u64) -> u64 {\n"
" // lengthy computation returning an uint\n"
" 12586269025\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:304
msgid ""
"let mut delayed_fib = extra::future::spawn (|| fib(50) ); make_a_sandwich(); "
"println(fmt!(\"fib(50) = %?\", delayed_fib.get())) ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:310
msgid ""
"The call to `future::spawn` returns immediately a `future` object regardless "
"of how long it takes to run `fib(50)`. You can then make yourself a sandwich "
"while the computation of `fib` is running. The result of the execution of "
"the method is obtained by calling `get` on the future. This call will block "
"until the value is available (*i.e.* the computation is complete). Note that "
"the future needs to be mutable so that it can save the result for next time "
"`get` is called."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:322
#, no-wrap
msgid ""
"Here is another example showing how futures allow you to background computations. The workload will\n"
"be distributed on the available cores.\n"
"~~~\n"
"# use std::vec;\n"
"fn partial_sum(start: uint) -> f64 {\n"
" let mut local_sum = 0f64;\n"
" for num in range(start*100000, (start+1)*100000) {\n"
" local_sum += (num as f64 + 1.0).pow(&-2.0);\n"
" }\n"
" local_sum\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:325
#, no-wrap
msgid ""
"fn main() {\n"
" let mut futures = vec::from_fn(1000, |ind| do extra::future::spawn { partial_sum(ind) });\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:333
#, no-wrap
msgid ""
" let mut final_res = 0f64;\n"
" for ft in futures.mut_iter() {\n"
" final_res += ft.get();\n"
" }\n"
" println(fmt!(\"π^2/6 is not far from : %?\", final_res));\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:335
msgid "## Sharing immutable data without copy: Arc"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:340
msgid ""
"To share immutable data between tasks, a first approach would be to only use "
"pipes as we have seen previously. A copy of the data to share would then be "
"made for each task. In some cases, this would add up to a significant amount "
"of wasted memory and would require copying the same data more than necessary."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:344
msgid ""
"To tackle this issue, one can use an Atomically Reference Counted wrapper "
"(`Arc`) as implemented in the `extra` library of Rust. With an Arc, the data "
"will no longer be copied for each task. The Arc acts as a reference to the "
"shared data and only this reference is shared and cloned."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:351
msgid ""
"Here is a small example showing how to use Arcs. We wish to run concurrently "
"several computations on a single large vector of floats. Each task needs the "
"full vector to perform its duty. ~~~ # use std::vec; # use std::rand; use "
"extra::arc::Arc;"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:355
#, no-wrap
msgid ""
"fn pnorm(nums: &~[float], p: uint) -> float {\n"
" nums.iter().fold(0.0, |a,b| a+(*b).pow(&(p as float)) ).pow(&(1f / (p as float)))\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:359
#, no-wrap
msgid ""
"fn main() {\n"
" let numbers = vec::from_fn(1000000, |_| rand::random::<float>());\n"
" println(fmt!(\"Inf-norm = %?\", *numbers.iter().max().unwrap()));\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:361
#, no-wrap
msgid " let numbers_arc = Arc::new(numbers);\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:365
#, no-wrap
msgid ""
" for num in range(1u, 10) {\n"
" let (port, chan) = stream();\n"
" chan.send(numbers_arc.clone());\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:374
#, no-wrap
msgid ""
" do spawn {\n"
" let local_arc : Arc<~[float]> = port.recv();\n"
" let task_numbers = local_arc.get();\n"
" println(fmt!(\"%u-norm = %?\", num, pnorm(task_numbers, num)));\n"
" }\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:396
msgid ""
"The function `pnorm` performs a simple computation on the vector (it "
"computes the sum of its items at the power given as argument and takes the "
"inverse power of this value). The Arc on the vector is created by the line "
"~~~ # use extra::arc::Arc; # use std::vec; # use std::rand; # let numbers = "
"vec::from_fn(1000000, |_| rand::random::<float>()); let numbers_arc=Arc::"
"new(numbers); ~~~ and a clone of it is sent to each task ~~~ # use extra::"
"arc::Arc; # use std::vec; # use std::rand; # let numbers=vec::"
"from_fn(1000000, |_| rand::random::<float>()); # let numbers_arc = Arc::"
"new(numbers); # let (port, chan) = stream(); chan.send(numbers_arc."
"clone()); ~~~ copying only the wrapper and not its contents."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:410
msgid ""
"Each task recovers the underlying data by ~~~ # use extra::arc::Arc; # use "
"std::vec; # use std::rand; # let numbers=vec::from_fn(1000000, |_| rand::"
"random::<float>()); # let numbers_arc=Arc::new(numbers); # let (port, chan) "
"= stream(); # chan.send(numbers_arc.clone()); # let local_arc : "
"Arc<~[float]> = port.recv(); let task_numbers = local_arc.get(); ~~~ and can "
"use it as if it were local."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:412
msgid ""
"The `arc` module also implements Arcs around mutable data that are not "
"covered here."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:414
msgid "# Handling task failure"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:423
msgid ""
"Rust has a built-in mechanism for raising exceptions. The `fail!()` macro "
"(which can also be written with an error string as an argument: `fail!"
"( ~reason)`) and the `assert!` construct (which effectively calls `fail!()` "
"if a boolean expression is false) are both ways to raise exceptions. When a "
"task raises an exception the task unwinds its stack---running destructors "
"and freeing memory along the way---and then exits. Unlike exceptions in C++, "
"exceptions in Rust are unrecoverable within a single task: once a task "
"fails, there is no way to \"catch\" the exception."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:426
msgid ""
"All tasks are, by default, _linked_ to each other. That means that the fates "
"of all tasks are intertwined: if one fails, so do all the others."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:434
msgid ""
"~~~{.xfail-test .linked-failure} # use std::task::spawn; # use std::task; # "
"fn do_some_work() { loop { task::yield() } } # do task::try { // Create a "
"child task that fails do spawn { fail!() }"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:439
msgid ""
"// This will also fail because the task we spawned failed do_some_work(); "
"# }; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:449
msgid ""
"While it isn't possible for a task to recover from failure, tasks may notify "
"each other of failure. The simplest way of handling task failure is with the "
"`try` function, which is similar to `spawn`, but immediately blocks waiting "
"for the child task to finish. `try` returns a value of type `Result<int, "
"()>`. `Result` is an `enum` type with two variants: `Ok` and `Err`. In this "
"case, because the type arguments to `Result` are `int` and `()`, callers can "
"pattern-match on a result to check whether it's an `Ok` result with an `int` "
"field (representing a successful result) or an `Err` result (representing "
"termination with an error)."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:463
#, no-wrap
msgid ""
"~~~{.xfail-test .linked-failure}\n"
"# use std::task;\n"
"# fn some_condition() -> bool { false }\n"
"# fn calculate_result() -> int { 0 }\n"
"let result: Result<int, ()> = do task::try {\n"
" if some_condition() {\n"
" calculate_result()\n"
" } else {\n"
" fail!(\"oops!\");\n"
" }\n"
"};\n"
"assert!(result.is_err());\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:469
msgid ""
"Unlike `spawn`, the function spawned using `try` may return a value, which "
"`try` will dutifully propagate back to the caller in a [`Result`] enum. If "
"the child task terminates successfully, `try` will return an `Ok` result; if "
"the child task fails, `try` will return an `Error` result."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:471
msgid "[`Result`]: std/result.html"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:476
msgid ""
"> ***Note:*** A failed task does not currently produce a useful error > "
"value (`try` always returns `Err(())`). In the > future, it may be possible "
"for tasks to intercept the value passed to > `fail!()`."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:479
msgid ""
"TODO: Need discussion of `future_result` in order to make failure modes "
"useful."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:487
msgid ""
"But not all failures are created equal. In some cases you might need to "
"abort the entire program (perhaps you're writing an assert which, if it "
"trips, indicates an unrecoverable logic error); in other cases you might "
"want to contain the failure at a certain boundary (perhaps a small piece of "
"input from the outside world, which you happen to be processing in parallel, "
"is malformed and its processing task can't proceed). Hence, you will need "
"different _linked failure modes_."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:489
msgid "## Failure modes"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:492
msgid ""
"By default, task failure is _bidirectionally linked_, which means that if "
"either task fails, it kills the other one."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:507
#, no-wrap
msgid ""
"~~~{.xfail-test .linked-failure}\n"
"# use std::task;\n"
"# use std::comm::oneshot;\n"
"# fn sleep_forever() { loop { let (p, c) = oneshot::<()>(); p.recv(); } }\n"
"# do task::try {\n"
"do spawn {\n"
" do spawn {\n"
" fail!(); // All three tasks will fail.\n"
" }\n"
" sleep_forever(); // Will get woken up by force, then fail\n"
"}\n"
"sleep_forever(); // Will get woken up by force, then fail\n"
"# };\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:514
msgid ""
"If you want parent tasks to be able to kill their children, but do not want "
"a parent to fail automatically if one of its child task fails, you can call "
"`task::spawn_supervised` for _unidirectionally linked_ failure. The function "
"`task::try`, which we saw previously, uses `spawn_supervised` internally, "
"with additional logic to wait for the child task to finish before returning. "
"Hence:"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:536
#, no-wrap
msgid ""
"~~~{.xfail-test .linked-failure}\n"
"# use std::comm::{stream, Chan, Port};\n"
"# use std::comm::oneshot;\n"
"# use std::task::{spawn, try};\n"
"# use std::task;\n"
"# fn sleep_forever() { loop { let (p, c) = oneshot::<()>(); p.recv(); } }\n"
"# do task::try {\n"
"let (receiver, sender): (Port<int>, Chan<int>) = stream();\n"
"do spawn { // Bidirectionally linked\n"
" // Wait for the supervised child task to exist.\n"
" let message = receiver.recv();\n"
" // Kill both it and the parent task.\n"
" assert!(message != 42);\n"
"}\n"
"do try { // Unidirectionally linked\n"
" sender.send(42);\n"
" sleep_forever(); // Will get woken up by force\n"
"}\n"
"// Flow never reaches here -- parent task was killed too.\n"
"# };\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:542
msgid ""
"Supervised failure is useful in any situation where one task manages "
"multiple fallible child tasks, and the parent task can recover if any child "
"fails. On the other hand, if the _parent_ (supervisor) fails, then there is "
"nothing the children can do to recover, so they should also fail."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:545
msgid ""
"Supervised task failure propagates across multiple generations even if an "
"intermediate generation has already exited:"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:562
#, no-wrap
msgid ""
"~~~{.xfail-test .linked-failure}\n"
"# use std::task;\n"
"# use std::comm::oneshot;\n"
"# fn sleep_forever() { loop { let (p, c) = oneshot::<()>(); p.recv(); } }\n"
"# fn wait_for_a_while() { for _ in range(0, 1000u) { task::yield() } }\n"
"# do task::try::<int> {\n"
"do task::spawn_supervised {\n"
" do task::spawn_supervised {\n"
" sleep_forever(); // Will get woken up by force, then fail\n"
" }\n"
" // Intermediate task immediately exits\n"
"}\n"
"wait_for_a_while();\n"
"fail!(); // Will kill grandchild even if child has already exited\n"
"# };\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:565
msgid ""
"Finally, tasks can be configured to not propagate failure to each other at "
"all, using `task::spawn_unlinked` for _isolated failure_."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:581
#, no-wrap
msgid ""
"~~~{.xfail-test .linked-failure}\n"
"# use std::task;\n"
"# fn random() -> uint { 100 }\n"
"# fn sleep_for(i: uint) { for _ in range(0, i) { task::yield() } }\n"
"# do task::try::<()> {\n"
"let (time1, time2) = (random(), random());\n"
"do task::spawn_unlinked {\n"
" sleep_for(time2); // Won't get forced awake\n"
" fail!();\n"
"}\n"
"sleep_for(time1); // Won't get forced awake\n"
"fail!();\n"
"// It will take MAX(time1,time2) for the program to finish.\n"
"# };\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:583
msgid "## Creating a task with a bi-directional communication path"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:588
msgid ""
"A very common thing to do is to spawn a child task where the parent and "
"child both need to exchange messages with each other. The function `extra::"
"comm::DuplexStream()` supports this pattern. We'll look briefly at how to "
"use it."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:593
msgid ""
"To see how `DuplexStream()` works, we will create a child task that "
"repeatedly receives a `uint` message, converts it to a string, and sends the "
"string in response. The child terminates when it receives `0`. Here is the "
"function that implements the child task:"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:606
#, no-wrap
msgid ""
"~~~{.xfail-test .linked-failure}\n"
"# use extra::comm::DuplexStream;\n"
"# use std::uint;\n"
"fn stringifier(channel: &DuplexStream<~str, uint>) {\n"
" let mut value: uint;\n"
" loop {\n"
" value = channel.recv();\n"
" channel.send(uint::to_str(value));\n"
" if value == 0 { break; }\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:614
msgid ""
"The implementation of `DuplexStream` supports both sending and receiving. "
"The `stringifier` function takes a `DuplexStream` that can send strings (the "
"first type parameter) and receive `uint` messages (the second type "
"parameter). The body itself simply loops, reading from the channel and then "
"sending its response back. The actual response itself is simply the "
"stringified version of the received value, `uint::to_str(value)`."
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:616
msgid "Here is the code for the parent task:"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:630
#, no-wrap
msgid ""
"~~~{.xfail-test .linked-failure}\n"
"# use std::task::spawn;\n"
"# use std::uint;\n"
"# use extra::comm::DuplexStream;\n"
"# fn stringifier(channel: &DuplexStream<~str, uint>) {\n"
"# let mut value: uint;\n"
"# loop {\n"
"# value = channel.recv();\n"
"# channel.send(uint::to_str(value));\n"
"# if value == 0u { break; }\n"
"# }\n"
"# }\n"
"# fn main() {\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:632
msgid "let (from_child, to_child) = DuplexStream();"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:636
#, no-wrap
msgid ""
"do spawn {\n"
" stringifier(&to_child);\n"
"};\n"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:639
msgid "from_child.send(22); assert!(from_child.recv() == ~\"22\");"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:642
msgid "from_child.send(23); from_child.send(0);"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:645
msgid ""
"assert!(from_child.recv() == ~\"23\"); assert!(from_child.recv() == ~\"0\");"
msgstr ""
#. type: Plain text
#: doc/tutorial-tasks.md:652
msgid ""
"The parent task first calls `DuplexStream` to create a pair of bidirectional "
"endpoints. It then uses `task::spawn` to create the child task, which "
"captures one end of the communication channel. As a result, both parent and "
"child can send and receive data to and from the other."
msgstr ""
doc/po/tutorial.md.pot
-4352
View File
@@ -1,4352 +0,0 @@
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8\n"
"POT-Creation-Date: 2013-08-12 02:06+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. type: Plain text
#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4
#: doc/tutorial-borrowed-ptr.md:4 doc/tutorial-ffi.md:4
#: doc/tutorial-macros.md:4 doc/tutorial-tasks.md:4
msgid "# Introduction"
msgstr ""
#. type: Plain text
#: doc/rust.md:1277 doc/tutorial.md:2176
msgid ""
"In type-parameterized functions, methods of the supertrait may be called on "
"values of subtrait-bound type parameters. Refering to the previous example "
"of `trait Circle : Shape`:"
msgstr ""
#. type: Plain text
#: doc/rust.md:1286 doc/tutorial.md:2185
#, no-wrap
msgid ""
"~~~\n"
"# trait Shape { fn area(&self) -> f64; }\n"
"# trait Circle : Shape { fn radius(&self) -> f64; }\n"
"fn radius_times_area<T: Circle>(c: T) -> f64 {\n"
" // `c` is both a Circle and a Shape\n"
" c.radius() * c.area()\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/rust.md:1288 doc/tutorial.md:2187
msgid "Likewise, supertrait methods may also be called on trait objects."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2
msgid "% The Rust Language Tutorial"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:13
msgid ""
"Rust is a programming language with a focus on type safety, memory safety, "
"concurrency and performance. It is intended for writing large-scale, high-"
"performance software that is free from several classes of common errors. "
"Rust has a sophisticated memory model that encourages efficient data "
"structures and safe concurrency patterns, forbidding invalid memory accesses "
"that would otherwise cause segmentation faults. It is statically typed and "
"compiled ahead of time."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:17
msgid ""
"As a multi-paradigm language, Rust supports writing code in procedural, "
"functional and object-oriented styles. Some of its pleasant high-level "
"features include:"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:30
msgid ""
"**Type inference.** Type annotations on local variable declarations are "
"optional."
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:30
msgid ""
"**Safe task-based concurrency.** Rust's lightweight tasks do not share "
"memory, instead communicating through messages."
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:30
msgid ""
"**Higher-order functions.** Efficient and flexible closures provide "
"iteration and other control structures"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:30
msgid ""
"**Pattern matching and algebraic data types.** Pattern matching on Rust's "
"enumeration types (a more powerful version of C's enums, similar to "
"algebraic data types in functional languages) is a compact and expressive "
"way to encode program logic."
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:30
msgid ""
"**Polymorphism.** Rust has type-parametric functions and types, type classes "
"and OO-style interfaces."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:32
msgid "## Scope"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:38
msgid ""
"This is an introductory tutorial for the Rust programming language. It "
"covers the fundamentals of the language, including the syntax, the type "
"system and memory model, generics, and modules. [Additional tutorials](#what-"
"next) cover specific language features in greater depth."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:42
msgid ""
"This tutorial assumes that the reader is already familiar with one or more "
"languages in the C family. Understanding of pointers and general memory "
"management techniques will help."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:44
msgid "## Conventions"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:47
msgid ""
"Throughout the tutorial, language keywords and identifiers defined in "
"example code are displayed in `code font`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:53
msgid ""
"Code snippets are indented, and also shown in a monospaced font. Not all "
"snippets constitute whole programs. For brevity, we'll often show fragments "
"of programs that don't compile on their own. To try them out, you might have "
"to wrap them in `fn main() { ... }`, and make sure they don't contain "
"references to names that aren't actually defined."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:57
msgid ""
"> ***Warning:*** Rust is a language under ongoing development. Notes > about "
"potential changes to the language, implementation > deficiencies, and other "
"caveats appear offset in blockquotes."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:59
msgid "# Getting started"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:63
msgid ""
"The Rust compiler currently must be built from a [tarball], unless you are "
"on Windows, in which case using the [installer][win-exe] is recommended."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:69
msgid ""
"Since the Rust compiler is written in Rust, it must be built by a "
"precompiled \"snapshot\" version of itself (made in an earlier state of "
"development). As such, source builds require a connection to the Internet, "
"to fetch snapshots, and an OS that can execute the available snapshot "
"binaries."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:71
msgid "Snapshot binaries are currently built and tested on several platforms:"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:75
msgid "Windows (7, Server 2008 R2), x86 only"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:75
msgid "Linux (various distributions), x86 and x86-64"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:75
msgid "OSX 10.6 (\"Snow Leopard\") or greater, x86 and x86-64"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:78
msgid ""
"You may find that other platforms work, but these are our \"tier 1\" "
"supported build environments that are most likely to work."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:85
msgid ""
"> ***Note:*** Windows users should read the detailed > \"[getting started]"
"[wiki-start]\" notes on the wiki. Even when using > the binary installer, "
"the Windows build requires a MinGW installation, > the precise details of "
"which are not discussed here. Finally, `rustc` may > need to be [referred to "
"as `rustc.exe`][bug-3319]. It's a bummer, we > know."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:88
msgid ""
"[bug-3319]: https://github.com/mozilla/rust/issues/3319 [wiki-start]: "
"https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:91
msgid ""
"To build from source you will also need the following prerequisite packages:"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:97
msgid "g++ 4.4 or clang++ 3.x"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:97
msgid "python 2.6 or later (but not 3.x)"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:97
msgid "perl 5.0 or later"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:97
msgid "gnu make 3.81 or later"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:97
msgid "curl"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:100
msgid ""
"If you've fulfilled those prerequisites, something along these lines should "
"work."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:108
msgid ""
"~~~~ {.notrust} $ curl -O http://static.rust-lang.org/dist/rust-0.8.tar.gz $ "
"tar -xzf rust-0.8.tar.gz $ cd rust-0.8 $ ./configure $ make && make install "
"~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:114
msgid ""
"You may need to use `sudo make install` if you do not normally have "
"permission to modify the destination directory. The install locations can be "
"adjusted by passing a `--prefix` argument to `configure`. Various other "
"options are also supported: pass `--help` for more information on them."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:120
msgid ""
"When complete, `make install` will place several programs into `/usr/local/"
"bin`: `rustc`, the Rust compiler; `rustdoc`, the API-documentation tool; "
"and `rustpkg`, the Rust package manager."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:123
msgid ""
"[tarball]: http://static.rust-lang.org/dist/rust-0.8.tar.gz [win-exe]: "
"http://static.rust-lang.org/dist/rust-0.8-install.exe"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:125
msgid "## Compiling your first program"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:128
msgid ""
"Rust program files are, by convention, given the extension `.rs`. Say we "
"have a file `hello.rs` containing this program:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:134
#, no-wrap
msgid ""
"~~~~\n"
"fn main() {\n"
" println(\"hello?\");\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:138
msgid ""
"If the Rust compiler was installed successfully, running `rustc hello.rs` "
"will produce an executable called `hello` (or `hello.exe` on Windows) which, "
"upon running, will likely do exactly what you expect."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:143
msgid ""
"The Rust compiler tries to provide useful information when it encounters an "
"error. If you introduce an error into the program (for example, by changing "
"`println` to some nonexistent function), and then compile it, you'll see an "
"error message like this:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:149
#, no-wrap
msgid ""
"~~~~ {.notrust}\n"
"hello.rs:2:4: 2:16 error: unresolved name: print_with_unicorns\n"
"hello.rs:2 print_with_unicorns(\"hello?\");\n"
" ^~~~~~~~~~~~~~~~~~~~~~~\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:156
msgid ""
"In its simplest form, a Rust program is a `.rs` file with some types and "
"functions defined in it. If it has a `main` function, it can be compiled to "
"an executable. Rust does not allow code that's not a declaration to appear "
"at the top level of the file: all statements must live inside a function. "
"Rust programs can also be compiled as libraries, and included in other "
"programs."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:158
msgid "## Using the rust tool"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:163
msgid ""
"While using `rustc` directly to generate your executables, and then running "
"them manually is a perfectly valid way to test your code, for smaller "
"projects, prototypes, or if you're a beginner, it might be more convenient "
"to use the `rust` tool."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:169
msgid ""
"The `rust` tool provides central access to the other Rust tools, as well as "
"handy shortcuts for directly running source files. For example, if you have "
"a file `foo.rs` in your current directory, `rust run foo.rs` would attempt "
"to compile it and, if successful, directly run the resulting binary."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:172
msgid ""
"To get a list of all available commands, simply call `rust` without any "
"argument."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:174
msgid "## Editing Rust code"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:184
msgid ""
"There are vim highlighting and indentation scripts in the Rust source "
"distribution under `src/etc/vim/`. There is an emacs mode under `src/etc/"
"emacs/` called `rust-mode`, but do read the instructions included in that "
"directory. In particular, if you are running emacs 24, then using emacs's "
"internal package manager to install `rust-mode` is the easiest way to keep "
"it up to date. There is also a package for Sublime Text 2, available both "
"[standalone][sublime] and through [Sublime Package Control][sublime-pkg], "
"and support for Kate under `src/etc/kate`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:188
msgid ""
"There is ctags support via `src/etc/ctags.rust`, but many other tools and "
"editors are not yet supported. If you end up writing a Rust mode for your "
"favorite editor, let us know so that we can link to it."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:191
msgid ""
"[sublime]: http://github.com/dbp/sublime-rust [sublime-pkg]: http://wbond."
"net/sublime_packages/package_control"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:193
msgid "# Syntax basics"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:201
msgid ""
"Assuming you've programmed in any C-family language (C++, Java, JavaScript, "
"C#, or PHP), Rust will feel familiar. Code is arranged in blocks delineated "
"by curly braces; there are control structures for branching and looping, "
"like the familiar `if` and `while`; function calls are written `myfunc(arg1, "
"arg2)`; operators are written the same and mostly have the same precedence "
"as in C; comments are again like C; module names are separated with double-"
"colon (`::`) as with C++."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:206
msgid ""
"The main surface difference to be aware of is that the condition at the head "
"of control structures like `if` and `while` does not require parentheses, "
"while their bodies *must* be wrapped in braces. Single-statement, unbraced "
"bodies are not allowed."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:219
#, no-wrap
msgid ""
"~~~~\n"
"# mod universe { pub fn recalibrate() -> bool { true } }\n"
"fn main() {\n"
" /* A simple loop */\n"
" loop {\n"
" // A tricky calculation\n"
" if universe::recalibrate() {\n"
" return;\n"
" }\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:223
msgid ""
"The `let` keyword introduces a local variable. Variables are immutable by "
"default. To introduce a local variable that you can re-assign later, use "
"`let mut` instead."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:227
msgid "~~~~ let hi = \"hi\"; let mut count = 0;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:233
#, no-wrap
msgid ""
"while count < 10 {\n"
" println(fmt!(\"count: %?\", count));\n"
" count += 1;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:237
msgid ""
"Although Rust can almost always infer the types of local variables, you can "
"specify a variable's type by following it with a colon, then the type name. "
"Static items, on the other hand, always require a type annotation."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:243
msgid ""
"~~~~ static MONSTER_FACTOR: f64 = 57.8; let monster_size = MONSTER_FACTOR "
"* 10.0; let monster_size: int = 50; ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:252
msgid ""
"Local variables may shadow earlier declarations, as in the previous example: "
"`monster_size` was first declared as a `f64`, and then a second "
"`monster_size` was declared as an `int`. If you were to actually compile "
"this example, though, the compiler would determine that the first "
"`monster_size` is unused and issue a warning (because this situation is "
"likely to indicate a programmer error). For occasions where unused variables "
"are intentional, their names may be prefixed with an underscore to silence "
"the warning, like `let _monster_size = 50;`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:258
msgid ""
"Rust identifiers start with an alphabetic character or an underscore, and "
"after that may contain any sequence of alphabetic characters, numbers, or "
"underscores. The preferred style is to write function, variable, and module "
"names with lowercase letters, using underscores where they help readability, "
"while writing types in camel case."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:263
#, no-wrap
msgid ""
"~~~\n"
"let my_variable = 100;\n"
"type MyType = int; // primitive types are _not_ camel case\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:265
msgid "## Expressions and semicolons"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:271
msgid ""
"Though it isn't apparent in all code, there is a fundamental difference "
"between Rust's syntax and predecessors like C. Many constructs that are "
"statements in C are expressions in Rust, allowing code to be more concise. "
"For example, you might write a piece of code like this:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:283
#, no-wrap
msgid ""
"~~~~\n"
"# let item = \"salad\";\n"
"let price;\n"
"if item == \"salad\" {\n"
" price = 3.50;\n"
"} else if item == \"muffin\" {\n"
" price = 2.25;\n"
"} else {\n"
" price = 2.00;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:285
msgid "But, in Rust, you don't have to repeat the name `price`:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:297
#, no-wrap
msgid ""
"~~~~\n"
"# let item = \"salad\";\n"
"let price =\n"
" if item == \"salad\" {\n"
" 3.50\n"
" } else if item == \"muffin\" {\n"
" 2.25\n"
" } else {\n"
" 2.00\n"
" };\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:303
msgid ""
"Both pieces of code are exactly equivalent: they assign a value to `price` "
"depending on the condition that holds. Note that there are no semicolons in "
"the blocks of the second snippet. This is important: the lack of a semicolon "
"after the last statement in a braced block gives the whole block the value "
"of that last expression."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:309
msgid ""
"Put another way, the semicolon in Rust *ignores the value of an "
"expression*. Thus, if the branches of the `if` had looked like `{ 4; }`, "
"the above example would simply assign `()` (nil or void) to `price`. But "
"without the semicolon, each branch has a different value, and `price` gets "
"the value of the branch that was taken."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:314
msgid ""
"In short, everything that's not a declaration (declarations are `let` for "
"variables; `fn` for functions; and any top-level named items such as [traits]"
"(#traits), [enum types](#enums), and static items) is an expression, "
"including function bodies."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:322
#, no-wrap
msgid ""
"~~~~\n"
"fn is_four(x: int) -> bool {\n"
" // No need for a return statement. The result of the expression\n"
" // is used as the return value.\n"
" x == 4\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:324
msgid "## Primitive types and literals"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:331
msgid ""
"There are general signed and unsigned integer types, `int` and `uint`, as "
"well as 8-, 16-, 32-, and 64-bit variants, `i8`, `u16`, etc. Integers can "
"be written in decimal (`144`), hexadecimal (`0x90`), octal (`0o70`), or binary "
"(`0b10010000`) base. Each integral type has a corresponding literal suffix "
"that can be used to indicate the type of a literal: `i` for `int`, `u` for "
"`uint`, `i8` for the `i8` type."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:337
msgid ""
"In the absence of an integer literal suffix, Rust will infer the integer "
"type based on type annotations and function signatures in the surrounding "
"program. In the absence of any type information at all, Rust will assume "
"that an unsuffixed integer literal has type `int`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:344
#, no-wrap
msgid ""
"~~~~\n"
"let a = 1; // a is an int\n"
"let b = 10i; // b is an int, due to the 'i' suffix\n"
"let c = 100u; // c is a uint\n"
"let d = 1000i32; // d is an i32\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:349
msgid ""
"There are two floating-point types: `f32`, and `f64`. Floating-"
"point numbers are written `0.0`, `1e6`, or `2.1e-4`. Like integers, "
"floating-point literals are inferred to the correct type. Suffixes "
"`f32` and `f64` can be used to create literals of a specific type."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:351
msgid "The keywords `true` and `false` produce literals of type `bool`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:358
msgid ""
"Characters, the `char` type, are four-byte Unicode codepoints, whose "
"literals are written between single quotes, as in `'x'`. Just like C, Rust "
"understands a number of character escapes, using the backslash character, "
"such as `\\n`, `\\r`, and `\\t`. String literals, written between double "
"quotes, allow the same escape sequences. More on strings [later](#vectors-"
"and-strings)."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:360
msgid "The nil type, written `()`, has a single value, also written `()`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:362
msgid "## Operators"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:367
msgid ""
"Rust's set of operators contains very few surprises. Arithmetic is done with "
"`*`, `/`, `%`, `+`, and `-` (multiply, quotient, remainder, add, and "
"subtract). `-` is also a unary prefix operator that negates numbers. As in "
"C, the bitwise operators `>>`, `<<`, `&`, `|`, and `^` are also supported."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:370
msgid ""
"Note that, if applied to an integer value, `!` flips all the bits (like `~` "
"in C)."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:374
msgid ""
"The comparison operators are the traditional `==`, `!=`, `<`, `>`, `<=`, and "
"`>=`. Short-circuiting (lazy) boolean operators are written `&&` (and) and "
"`||` (or)."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:379
msgid ""
"For type casting, Rust uses the binary `as` operator. It takes an "
"expression on the left side and a type on the right side and will, if a "
"meaningful conversion exists, convert the result of the expression to the "
"given type."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:385
msgid ""
"~~~~ let x: f64 = 4.0; let y: uint = x as uint; assert!(y == 4u); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:387
msgid "## Syntax extensions"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:394
#, no-wrap
msgid ""
"*Syntax extensions* are special forms that are not built into the language,\n"
"but are instead provided by the libraries. To make it clear to the reader when\n"
"a name refers to a syntax extension, the names of all syntax extensions end\n"
"with `!`. The standard library defines a few syntax extensions, the most\n"
"useful of which is `fmt!`, a `sprintf`-style text formatter that you will\n"
"often see in examples.\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:398
msgid ""
"`fmt!` supports most of the directives that [printf][pf] supports, but "
"unlike printf, will give you a compile-time error when the types of the "
"directives don't match the types of the arguments."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:401
msgid "~~~~ # let mystery_object = ();"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:403
msgid "println(fmt!(\"%s is %d\", \"the answer\", 43));"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:407
msgid ""
"// %? will conveniently print any type println(fmt!(\"what is this thing: %?"
"\", mystery_object)); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:409
msgid "[pf]: http://en.cppreference.com/w/cpp/io/c/fprintf"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:411
msgid ""
"You can define your own syntax extensions with the macro system. For "
"details, see the [macro tutorial][macros]."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:413
msgid "# Control structures"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:415
msgid "## Conditionals"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:419
msgid ""
"We've seen `if` expressions a few times already. To recap, braces are "
"compulsory, an `if` can have an optional `else` clause, and multiple `if`/"
"`else` constructs can be chained together:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:429
#, no-wrap
msgid ""
"~~~~\n"
"if false {\n"
" println(\"that's odd\");\n"
"} else if true {\n"
" println(\"right\");\n"
"} else {\n"
" println(\"neither true nor false\");\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:434
msgid ""
"The condition given to an `if` construct *must* be of type `bool` (no "
"implicit conversion happens). If the arms are blocks that have a value, this "
"value must be of the same type for every arm in which control reaches the "
"end of the block:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:442
#, no-wrap
msgid ""
"~~~~\n"
"fn signum(x: int) -> int {\n"
" if x < 0 { -1 }\n"
" else if x > 0 { 1 }\n"
" else { return 0 }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:444
msgid "## Pattern matching"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:450
msgid ""
"Rust's `match` construct is a generalized, cleaned-up version of C's "
"`switch` construct. You provide it with a value and a number of *arms*, each "
"labelled with a pattern, and the code compares the value against each "
"pattern in order until one matches. The matching pattern executes its "
"corresponding arm."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:460
#, no-wrap
msgid ""
"~~~~\n"
"# let my_number = 1;\n"
"match my_number {\n"
" 0 => println(\"zero\"),\n"
" 1 | 2 => println(\"one or two\"),\n"
" 3..10 => println(\"three to ten\"),\n"
" _ => println(\"something else\")\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:464
msgid ""
"Unlike in C, there is no \"falling through\" between arms: only one arm "
"executes, and it doesn't have to explicitly `break` out of the construct "
"when it is finished."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:474
msgid ""
"A `match` arm consists of a *pattern*, then an arrow `=>`, followed by an "
"*action* (expression). Literals are valid patterns and match only their own "
"value. A single arm may match multiple different patterns by combining them "
"with the pipe operator (`|`), so long as every pattern binds the same set of "
"variables. Ranges of numeric literal patterns can be expressed with two "
"dots, as in `M..N`. The underscore (`_`) is a wildcard pattern that matches "
"any single value. The asterisk (`*`) is a different wildcard that can match "
"one or more fields in an `enum` variant."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:479
msgid ""
"The patterns in a match arm are followed by a fat arrow, `=>`, then an "
"expression to evaluate. Each case is separated by commas. It's often "
"convenient to use a block expression for each case, in which case the commas "
"are optional."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:487
#, no-wrap
msgid ""
"~~~\n"
"# let my_number = 1;\n"
"match my_number {\n"
" 0 => { println(\"zero\") }\n"
" _ => { println(\"something else\") }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:492
msgid ""
"`match` constructs must be *exhaustive*: they must have an arm covering "
"every possible case. For example, the typechecker would reject the previous "
"example if the arm with the wildcard pattern was omitted."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:496
msgid ""
"A powerful application of pattern matching is *destructuring*: matching in "
"order to bind names to the contents of data types."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:500
msgid ""
"> ***Note:*** The following code makes use of tuples (`(f64, f64)`) "
"which > are explained in section 5.3. For now you can think of tuples as a "
"list of > items."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:513
#, no-wrap
msgid ""
"~~~~\n"
"use std::f64;\n"
"use std::num::atan;\n"
"fn angle(vector: (f64, f64)) -> f64 {\n"
" let pi = f64::consts::pi;\n"
" match vector {\n"
" (0f, y) if y < 0f => 1.5 * pi,\n"
" (0f, y) => 0.5 * pi,\n"
" (x, y) => atan(y / x)\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:519
msgid ""
"A variable name in a pattern matches any value, *and* binds that name to the "
"value of the matched value inside of the arm's action. Thus, `(0f, y)` "
"matches any tuple whose first element is zero, and binds `y` to the second "
"element. `(x, y)` matches any two-element tuple, and binds both elements to "
"variables."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:526
msgid ""
"Any `match` arm can have a guard clause (written `if EXPR`), called a "
"*pattern guard*, which is an expression of type `bool` that determines, "
"after the pattern is found to match, whether the arm is taken or not. The "
"variables bound by the pattern are in scope in this guard expression. The "
"first arm in the `angle` example shows an example of a pattern guard."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:531
msgid ""
"You've already seen simple `let` bindings, but `let` is a little fancier "
"than you've been led to believe. It, too, supports destructuring patterns. "
"For example, you can write this to extract the fields from a tuple, "
"introducing two variables at once: `a` and `b`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:536
msgid ""
"~~~~ # fn get_tuple_of_two_ints() -> (int, int) { (1, 1) } let (a, b) = "
"get_tuple_of_two_ints(); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:540
msgid ""
"Let bindings only work with _irrefutable_ patterns: that is, patterns that "
"can never fail to match. This excludes `let` from matching literals and most "
"`enum` variants."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:542
msgid "## Loops"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:547
msgid ""
"`while` denotes a loop that iterates as long as its given condition (which "
"must have type `bool`) evaluates to `true`. Inside a loop, the keyword "
"`break` aborts the loop, and `loop` aborts the current iteration and "
"continues with the next."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:554
#, no-wrap
msgid ""
"~~~~\n"
"let mut cake_amount = 8;\n"
"while cake_amount > 0 {\n"
" cake_amount -= 1;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:556
msgid ""
"`loop` denotes an infinite loop, and is the preferred way of writing `while "
"true`:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:566
#, no-wrap
msgid ""
"~~~~\n"
"use std::int;\n"
"let mut x = 5;\n"
"loop {\n"
" x += x - 3;\n"
" if x % 5 == 0 { break; }\n"
" println(int::to_str(x));\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:569
msgid ""
"This code prints out a weird sequence of numbers and stops as soon as it "
"finds one that can be divided by five."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:571
msgid "# Data structures"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:573
msgid "## Structs"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:578
msgid ""
"Rust struct types must be declared before they are used using the `struct` "
"syntax: `struct Name { field1: T1, field2: T2 [, ...] }`, where `T1`, "
"`T2`, ... denote types. To construct a struct, use the same syntax, but "
"leave off the `struct`: for example: `Point { x: 1.0, y: 2.0 }`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:582
msgid ""
"Structs are quite similar to C structs and are even laid out the same way in "
"memory (so you can read from a Rust struct in C, and vice-versa). Use the "
"dot operator to access struct fields, as in `mypoint.x`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:589
#, no-wrap
msgid ""
"~~~~\n"
"struct Point {\n"
" x: f64,\n"
" y: f64\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:593
msgid ""
"Inherited mutability means that any field of a struct may be mutable, if the "
"struct is in a mutable slot (or a field of a struct in a mutable slot, and "
"so forth)."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:597
msgid ""
"With a value (say, `mypoint`) of such a type in a mutable location, you can "
"do `mypoint.y += 1.0`. But in an immutable location, such an assignment to a "
"struct without inherited mutability would result in a type error."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:602
msgid ""
"~~~~ {.xfail-test} # struct Point { x: f64, y: f64 } let mut mypoint = "
"Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:606
msgid ""
"mypoint.y += 1.0; // mypoint is mutable, and its fields as well origin.y += "
"1.0; // ERROR: assigning to immutable field ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:609
msgid ""
"`match` patterns destructure structs. The basic syntax is `Name { fieldname: "
"pattern, ... }`:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:618
#, no-wrap
msgid ""
"~~~~\n"
"# struct Point { x: f64, y: f64 }\n"
"# let mypoint = Point { x: 0.0, y: 0.0 };\n"
"match mypoint {\n"
" Point { x: 0.0, y: yy } => { println(yy.to_str()); }\n"
" Point { x: xx, y: yy } => { println(xx.to_str() + \" \" + yy.to_str()); }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:625
msgid ""
"In general, the field names of a struct do not have to appear in the same "
"order they appear in the type. When you are not interested in all the fields "
"of a struct, a struct pattern may end with `, _` (as in `Name { field1, _ }"
"`) to indicate that you're ignoring all other fields. Additionally, struct "
"fields have a shorthand matching form that simply reuses the field name as "
"the binding name."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:633
#, no-wrap
msgid ""
"~~~\n"
"# struct Point { x: f64, y: f64 }\n"
"# let mypoint = Point { x: 0.0, y: 0.0 };\n"
"match mypoint {\n"
" Point { x, _ } => { println(x.to_str()) }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:635
msgid "## Enums"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:638
msgid ""
"Enums are datatypes that have several alternate representations. For "
"example, consider the type shown earlier:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:646
#, no-wrap
msgid ""
"~~~~\n"
"# struct Point { x: f64, y: f64 }\n"
"enum Shape {\n"
" Circle(Point, f64),\n"
" Rectangle(Point, Point)\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:652
msgid ""
"A value of this type is either a `Circle`, in which case it contains a "
"`Point` struct and a `f64`, or a `Rectangle`, in which case it contains two "
"`Point` structs. The run-time representation of such a value includes an "
"identifier of the actual form that it holds, much like the \"tagged union\" "
"pattern in C, but with better static guarantees."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:658
msgid ""
"The above declaration will define a type `Shape` that can refer to such "
"shapes, and two functions, `Circle` and `Rectangle`, which can be used to "
"construct values of the type (taking arguments of the specified types). So "
"`Circle(Point { x: 0f, y: 0f }, 10f)` is the way to create a new circle."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:661
msgid ""
"Enum variants need not have parameters. This `enum` declaration, for "
"example, is equivalent to a C enum:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:670
#, no-wrap
msgid ""
"~~~~\n"
"enum Direction {\n"
" North,\n"
" East,\n"
" South,\n"
" West\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:673
msgid ""
"This declaration defines `North`, `East`, `South`, and `West` as constants, "
"all of which have type `Direction`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:677
msgid ""
"When an enum is C-like (that is, when none of the variants have parameters), "
"it is possible to explicitly set the discriminator values to a constant "
"value:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:685
#, no-wrap
msgid ""
"~~~~\n"
"enum Color {\n"
" Red = 0xff0000,\n"
" Green = 0x00ff00,\n"
" Blue = 0x0000ff\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:690
msgid ""
"If an explicit discriminator is not specified for a variant, the value "
"defaults to the value of the previous variant plus one. If the first variant "
"does not have a discriminator, it defaults to 0. For example, the value of "
"`North` is 0, `East` is 1, `South` is 2, and `West` is 3."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:693
msgid ""
"When an enum is C-like, you can apply the `as` cast operator to convert it "
"to its discriminator value as an `int`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:697
msgid ""
"For enum types with multiple variants, destructuring is the only way to get "
"at their contents. All variant constructors can be used as patterns, as in "
"this definition of `area`:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:709
#, no-wrap
msgid ""
"~~~~\n"
"use std::f64;\n"
"# struct Point {x: f64, y: f64}\n"
"# enum Shape { Circle(Point, f64), Rectangle(Point, Point) }\n"
"fn area(sh: Shape) -> f64 {\n"
" match sh {\n"
" Circle(_, size) => f64::consts::pi * size * size,\n"
" Rectangle(Point { x, y }, Point { x: x2, y: y2 }) => (x2 - x) * (y2 - y)\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:714
msgid ""
"You can write a lone `_` to ignore an individual field, and can ignore all "
"fields of a variant like: `Circle(*)`. As in their introduction form, "
"nullary enum patterns are written without parentheses."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:727
#, no-wrap
msgid ""
"~~~~\n"
"# struct Point { x: f64, y: f64 }\n"
"# enum Direction { North, East, South, West }\n"
"fn point_from_direction(dir: Direction) -> Point {\n"
" match dir {\n"
" North => Point { x: 0f, y: 1f },\n"
" East => Point { x: 1f, y: 0f },\n"
" South => Point { x: 0f, y: -1f },\n"
" West => Point { x: -1f, y: 0f }\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:729
msgid "Enum variants may also be structs. For example:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:747
#, no-wrap
msgid ""
"~~~~\n"
"use std::f64;\n"
"# struct Point { x: f64, y: f64 }\n"
"# fn square(x: f64) -> f64 { x * x }\n"
"enum Shape {\n"
" Circle { center: Point, radius: f64 },\n"
" Rectangle { top_left: Point, bottom_right: Point }\n"
"}\n"
"fn area(sh: Shape) -> f64 {\n"
" match sh {\n"
" Circle { radius: radius, _ } => f64::consts::pi * square(radius),\n"
" Rectangle { top_left: top_left, bottom_right: bottom_right } => {\n"
" (bottom_right.x - top_left.x) * (bottom_right.y - top_left.y)\n"
" }\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:749
msgid "## Tuples"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:754
msgid ""
"Tuples in Rust behave exactly like structs, except that their fields do not "
"have names. Thus, you cannot access their fields with dot notation. Tuples "
"can have any arity except for 0 (though you may consider unit, `()`, as the "
"empty tuple if you like)."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:761
#, no-wrap
msgid ""
"~~~~\n"
"let mytup: (int, int, f64) = (10, 20, 30.0);\n"
"match mytup {\n"
" (a, b, c) => info!(a + b + (c as int))\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:763
msgid "## Tuple structs"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:768
msgid ""
"Rust also has _tuple structs_, which behave like both structs and tuples, "
"except that, unlike tuples, tuple structs have names (so `Foo(1, 2)` has a "
"different type from `Bar(1, 2)`), and tuple structs' _fields_ do not have "
"names."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:777
#, no-wrap
msgid ""
"For example:\n"
"~~~~\n"
"struct MyTup(int, int, f64);\n"
"let mytup: MyTup = MyTup(10, 20, 30.0);\n"
"match mytup {\n"
" MyTup(a, b, c) => info!(a + b + (c as int))\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:779
msgid "<a name=\"newtype\"></a>"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:784
msgid ""
"There is a special case for tuple structs with a single field, which are "
"sometimes called \"newtypes\" (after Haskell's \"newtype\" feature). These "
"are used to define new types in such a way that the new name is not just a "
"synonym for an existing type but is rather its own distinct type."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:788
msgid "~~~~ struct GizmoId(int); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:791
msgid ""
"For convenience, you can extract the contents of such a struct with the "
"dereference (`*`) unary operator:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:797
msgid ""
"~~~~ # struct GizmoId(int); let my_gizmo_id: GizmoId = GizmoId(10); let "
"id_int: int = *my_gizmo_id; ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:800
msgid ""
"Types like this can be useful to differentiate between data that have the "
"same type but must be used in different ways."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:805
msgid "~~~~ struct Inches(int); struct Centimeters(int); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:808
msgid ""
"The above definitions allow for a simple way for programs to avoid confusing "
"numbers that correspond to different units."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:810
msgid "# Functions"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:818
msgid ""
"We've already seen several function definitions. Like all other static "
"declarations, such as `type`, functions can be declared both at the top "
"level and inside other functions (or in modules, which we'll come back to "
"[later](#modules-and-crates)). The `fn` keyword introduces a function. A "
"function has an argument list, which is a parenthesized list of `expr: type` "
"pairs separated by commas. An arrow `->` separates the argument list and the "
"function's return type."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:824
#, no-wrap
msgid ""
"~~~~\n"
"fn line(a: int, b: int, x: int) -> int {\n"
" return a * x + b;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:829
msgid ""
"The `return` keyword immediately returns from the body of a function. It is "
"optionally followed by an expression to return. A function can also return a "
"value by having its top-level block produce an expression."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:835
#, no-wrap
msgid ""
"~~~~\n"
"fn line(a: int, b: int, x: int) -> int {\n"
" a * x + b\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:842
msgid ""
"It's better Rust style to write a return value this way instead of writing "
"an explicit `return`. The utility of `return` comes in when returning early "
"from a function. Functions that do not return a value are said to return "
"nil, `()`, and both the return type and the return value may be omitted from "
"the definition. The following two functions are equivalent."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:845
msgid "~~~~ fn do_nothing_the_hard_way() -> () { return (); }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:848
msgid "fn do_nothing_the_easy_way() { } ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:850
msgid ""
"Ending the function with a semicolon like so is equivalent to returning `()`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:854
msgid ""
"~~~~ fn line(a: int, b: int, x: int) -> int { a * x + b } fn oops(a: int, b: "
"int, x: int) -> () { a * x + b; }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:858
msgid "assert!(8 == line(5, 3, 1)); assert!(() == oops(5, 3, 1)); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:862
msgid ""
"As with `match` expressions and `let` bindings, function arguments support "
"pattern destructuring. Like `let`, argument patterns must be irrefutable, as "
"in this example that unpacks the first value from a tuple and returns it."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:866
msgid "~~~ fn first((value, _): (int, f64)) -> int { value } ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:868 doc/tutorial-ffi.md:143
msgid "# Destructors"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:872
msgid ""
"A *destructor* is a function responsible for cleaning up the resources used "
"by an object when it is no longer accessible. Destructors can be defined to "
"handle the release of resources like files, sockets and heap memory."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:876
msgid ""
"Objects are never accessible after their destructor has been called, so "
"there are no dynamic failures from accessing freed resources. When a task "
"fails, the destructors of all objects in the task are called."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:878
msgid ""
"The `~` sigil represents a unique handle for a memory allocation on the heap:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:886
#, no-wrap
msgid ""
"~~~~\n"
"{\n"
" // an integer allocated on the heap\n"
" let y = ~10;\n"
"}\n"
"// the destructor frees the heap memory as soon as `y` goes out of scope\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:890
msgid ""
"Rust includes syntax for heap memory allocation in the language since it's "
"commonly used, but the same semantics can be implemented by a type with a "
"custom destructor."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:892
msgid "# Ownership"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:897
msgid ""
"Rust formalizes the concept of object ownership to delegate management of an "
"object's lifetime to either a variable or a task-local garbage collector. An "
"object's owner is responsible for managing the lifetime of the object by "
"calling the destructor, and the owner determines whether the object is "
"mutable."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:903
msgid ""
"Ownership is recursive, so mutability is inherited recursively and a "
"destructor destroys the contained tree of owned objects. Variables are top-"
"level owners and destroy the contained object when they go out of scope. A "
"box managed by the garbage collector starts a new ownership tree, and the "
"destructor is called when it is collected."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:907
msgid ""
"~~~~ // the struct owns the objects contained in the `x` and `y` fields "
"struct Foo { x: int, y: ~int }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:914
#, no-wrap
msgid ""
"{\n"
" // `a` is the owner of the struct, and thus the owner of the struct's fields\n"
" let a = Foo { x: 5, y: ~10 };\n"
"}\n"
"// when `a` goes out of scope, the destructor for the `~int` in the struct's\n"
"// field is called\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:919
msgid ""
"// `b` is mutable, and the mutability is inherited by the objects it owns "
"let mut b = Foo { x: 5, y: ~10 }; b.x = 10; ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:925
msgid ""
"If an object doesn't contain garbage-collected boxes, it consists of a "
"single ownership tree and is given the `Owned` trait which allows it to be "
"sent between tasks. Custom destructors can only be implemented directly on "
"types that are `Owned`, but garbage-collected boxes can still *contain* "
"types with custom destructors."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:927
msgid "# Boxes"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:934
msgid ""
"Many modern languages represent values as pointers to heap memory by "
"default. In contrast, Rust, like C and C++, represents such types directly. "
"Another way to say this is that aggregate data in Rust are *unboxed*. This "
"means that if you `let x = Point { x: 1f, y: 1f };`, you are creating a "
"struct on the stack. If you then copy it into a data structure, you copy the "
"entire struct, not just a pointer."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:939
msgid ""
"For small structs like `Point`, this is usually more efficient than "
"allocating memory and indirecting through a pointer. But for big structs, or "
"mutable state, it can be useful to have a single copy on the stack or on the "
"heap, and refer to that through a pointer."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:941
msgid "## Owned boxes"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:944
msgid ""
"An owned box (`~`) is a uniquely owned allocation on the heap. It inherits "
"the mutability and lifetime of the owner as it would if there was no box:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:949
msgid "~~~~ let x = 5; // immutable let mut y = 5; // mutable y += 2;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:954
msgid ""
"let x = ~5; // immutable let mut y = ~5; // mutable *y += 2; // the * "
"operator is needed to access the contained value ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:959
msgid ""
"The purpose of an owned box is to add a layer of indirection in order to "
"create recursive data structures or cheaply pass around an object larger "
"than a pointer. Since an owned box has a unique owner, it can only be used "
"to represent a tree data structure."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:962
msgid ""
"The following struct won't compile, because the lack of indirection would "
"mean it has an infinite size:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:968
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"struct Foo {\n"
" child: Option<Foo>\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:972
msgid ""
"> ***Note:*** The `Option` type is an enum that represents an *optional* "
"value. > It's comparable to a nullable pointer in many other languages, but "
"stores the > contained value unboxed."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:976
msgid ""
"Adding indirection with an owned pointer allocates the child outside of the "
"struct on the heap, which makes it a finite size and won't result in a "
"compile-time error:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:982
#, no-wrap
msgid ""
"~~~~\n"
"struct Foo {\n"
" child: Option<~Foo>\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:984
msgid "## Managed boxes"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:992
msgid ""
"A managed box (`@`) is a heap allocation with the lifetime managed by a task-"
"local garbage collector. It will be destroyed at some point after there are "
"no references left to the box, no later than the end of the task. Managed "
"boxes lack an owner, so they start a new ownership tree and don't inherit "
"mutability. They do own the contained object, and mutability is defined by "
"the type of the managed box (`@` or `@mut`). An object containing a managed "
"box is not `Owned`, and can't be sent between tasks."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:995
msgid "~~~~ let a = @5; // immutable"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:998
msgid "let mut b = @5; // mutable variable, immutable box b = @10;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1001
msgid "let c = @mut 5; // immutable variable, mutable box *c = 10;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1006
msgid ""
"let mut d = @mut 5; // mutable variable, mutable box *d += 5; d = @mut 15; "
"~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1011
msgid ""
"A mutable variable and an immutable variable can refer to the same box, "
"given that their types are compatible. Mutability of a box is a property of "
"its type, however, so for example a mutable handle to an immutable box "
"cannot be assigned a reference to a mutable box."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1015
#, no-wrap
msgid ""
"~~~~\n"
"let a = @1; // immutable box\n"
"let b = @mut 2; // mutable box\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1018
#, no-wrap
msgid ""
"let mut c : @int; // declare a variable with type managed immutable int\n"
"let mut d : @mut int; // and one of type managed mutable int\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1022
#, no-wrap
msgid ""
"c = a; // box type is the same, okay\n"
"d = b; // box type is the same, okay\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1027
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"// but b cannot be assigned to c, or a to d\n"
"c = b; // error\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1029
msgid "# Move semantics"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1035
msgid ""
"Rust uses a shallow copy for parameter passing, assignment and returning "
"values from functions. A shallow copy is considered a move of ownership if "
"the ownership tree of the copied value includes an owned box or a type with "
"a custom destructor. After a value has been moved, it can no longer be used "
"from the source location and will not be destroyed there."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1041
msgid ""
"~~~~ let x = ~5; let y = x.clone(); // y is a newly allocated box let z = "
"x; // no new memory allocated, x can no longer be used ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1044
msgid ""
"Since in owned boxes mutability is a property of the owner, not the box, "
"mutable boxes may become immutable when they are moved, and vice-versa."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1051
msgid ""
"~~~~ let r = ~13; let mut s = r; // box becomes mutable *s += 1; let t = "
"s; // box becomes immutable ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1053
msgid "# Borrowed pointers"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1059
msgid ""
"Rust's borrowed pointers are a general purpose reference type. In contrast "
"with owned boxes, where the holder of an owned box is the owner of the "
"pointed-to memory, borrowed pointers never imply ownership. A pointer can be "
"borrowed to any object, and the compiler verifies that it cannot outlive the "
"lifetime of the object."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1061
msgid "As an example, consider a simple struct type, `Point`:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1068
#, no-wrap
msgid ""
"~~~\n"
"struct Point {\n"
" x: f64,\n"
" y: f64\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1072
msgid ""
"We can use this simple definition to allocate points in many different ways. "
"For example, in this code, each of these three local variables contains a "
"point, but allocated in a different location:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1079
#, no-wrap
msgid ""
"~~~\n"
"# struct Point { x: f64, y: f64 }\n"
"let on_the_stack : Point = Point { x: 3.0, y: 4.0 };\n"
"let managed_box : @Point = @Point { x: 5.0, y: 1.0 };\n"
"let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1089
msgid ""
"Suppose we want to write a procedure that computes the distance between any "
"two points, no matter where they are stored. For example, we might like to "
"compute the distance between `on_the_stack` and `managed_box`, or between "
"`managed_box` and `owned_box`. One option is to define a function that takes "
"two arguments of type point—that is, it takes the points by value. But this "
"will cause the points to be copied when we call the function. For points, "
"this is probably not so bad, but often copies are expensive. So we’d like to "
"define a function that takes the points by pointer. We can use borrowed "
"pointers to do this:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1099
#, no-wrap
msgid ""
"~~~\n"
"# struct Point { x: f64, y: f64 }\n"
"# fn sqrt(f: f64) -> f64 { 0f }\n"
"fn compute_distance(p1: &Point, p2: &Point) -> f64 {\n"
" let x_d = p1.x - p2.x;\n"
" let y_d = p1.y - p2.y;\n"
" sqrt(x_d * x_d + y_d * y_d)\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1101 doc/tutorial-borrowed-ptr.md:72
msgid "Now we can call `compute_distance()` in various ways:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1111
#, no-wrap
msgid ""
"~~~\n"
"# struct Point{ x: f64, y: f64 };\n"
"# let on_the_stack : Point = Point { x: 3.0, y: 4.0 };\n"
"# let managed_box : @Point = @Point { x: 5.0, y: 1.0 };\n"
"# let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };\n"
"# fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0f }\n"
"compute_distance(&on_the_stack, managed_box);\n"
"compute_distance(managed_box, owned_box);\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1118
msgid ""
"Here the `&` operator is used to take the address of the variable "
"`on_the_stack`; this is because `on_the_stack` has the type `Point` (that "
"is, a struct value) and we have to take its address to get a value. We also "
"call this _borrowing_ the local variable `on_the_stack`, because we are "
"creating an alias: that is, another route to the same data."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1124
msgid ""
"In the case of the boxes `managed_box` and `owned_box`, however, no explicit "
"action is necessary. The compiler will automatically convert a box like "
"`@point` or `~point` to a borrowed pointer like `&point`. This is another "
"form of borrowing; in this case, the contents of the managed/owned box are "
"being lent out."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1133
msgid ""
"Whenever a value is borrowed, there are some limitations on what you can do "
"with the original. For example, if the contents of a variable have been lent "
"out, you cannot send that variable to another task, nor will you be "
"permitted to take actions that might cause the borrowed value to be freed or "
"to change its type. This rule should make intuitive sense: you must wait for "
"a borrowed value to be returned (that is, for the borrowed pointer to go out "
"of scope) before you can make full use of it again."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1136
msgid ""
"For a more in-depth explanation of borrowed pointers, read the [borrowed "
"pointer tutorial][borrowtut]."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1138
msgid "[borrowtut]: tutorial-borrowed-ptr.html"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1140
msgid "## Freezing"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1143
msgid ""
"Borrowing an immutable pointer to an object freezes it and prevents "
"mutation. `Owned` objects have freezing enforced statically at compile-time."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1152
#, no-wrap
msgid ""
"~~~~\n"
"let mut x = 5;\n"
"{\n"
" let y = &x; // x is now frozen, it cannot be modified\n"
"}\n"
"// x is now unfrozen again\n"
"# x = 3;\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1156
msgid ""
"Mutable managed boxes handle freezing dynamically when any of their contents "
"are borrowed, and the task will fail if an attempt to modify them is made "
"while they are frozen:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1166
#, no-wrap
msgid ""
"~~~~\n"
"let x = @mut 5;\n"
"let y = x;\n"
"{\n"
" let z = &*y; // the managed box is now frozen\n"
" // modifying it through x or y will cause a task failure\n"
"}\n"
"// the box is now unfrozen again\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1168
msgid "# Dereferencing pointers"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1171
msgid ""
"Rust uses the unary star operator (`*`) to access the contents of a box or "
"pointer, similarly to C."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1176
msgid "~~~ let managed = @10; let owned = ~20; let borrowed = &30;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1179
msgid "let sum = *managed + *owned + *borrowed; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1183
msgid ""
"Dereferenced mutable pointers may appear on the left hand side of "
"assignments. Such an assignment modifies the value that the pointer points "
"to."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1187
msgid "~~~ let managed = @mut 10; let mut owned = ~20;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1190
msgid "let mut value = 30; let borrowed = &mut value;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1195
#, no-wrap
msgid ""
"*managed = *owned + 10;\n"
"*owned = *borrowed + 100;\n"
"*borrowed = *managed + 1000;\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1199
msgid ""
"Pointers have high operator precedence, but lower precedence than the dot "
"operator used for field and method access. This precedence order can "
"sometimes make code awkward and parenthesis-filled."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1209
msgid ""
"~~~ # struct Point { x: f64, y: f64 } # enum Shape { Rectangle(Point, "
"Point) } # impl Shape { fn area(&self) -> int { 0 } } let start = @Point "
"{ x: 10f, y: 20f }; let end = ~Point { x: (*start).x + 100f, y: (*start).y + "
"100f }; let rect = &Rectangle(*start, *end); let area = (*rect).area(); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1213
msgid ""
"To combat this ugliness the dot operator applies _automatic pointer "
"dereferencing_ to the receiver (the value on the left-hand side of the dot), "
"so in most cases, explicitly dereferencing the receiver is not necessary."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1223
msgid ""
"~~~ # struct Point { x: f64, y: f64 } # enum Shape { Rectangle(Point, "
"Point) } # impl Shape { fn area(&self) -> int { 0 } } let start = @Point "
"{ x: 10f, y: 20f }; let end = ~Point { x: start.x + 100f, y: start.y + "
"100f }; let rect = &Rectangle(*start, *end); let area = rect.area(); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1227
msgid ""
"You can write an expression that dereferences any number of pointers "
"automatically. For example, if you feel inclined, you could write something "
"silly like"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1233
msgid ""
"~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: "
"20f }; println(fmt!(\"%f\", point.x)); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1235
msgid "The indexing operator (`[]`) also auto-dereferences."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1237
msgid "# Vectors and strings"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1242
msgid ""
"A vector is a contiguous section of memory containing zero or more values of "
"the same type. Like other types in Rust, vectors can be stored on the stack, "
"the local heap, or the exchange heap. Borrowed pointers to vectors are also "
"called 'slices'."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1252
#, no-wrap
msgid ""
"~~~\n"
"# enum Crayon {\n"
"# Almond, AntiqueBrass, Apricot,\n"
"# Aquamarine, Asparagus, AtomicTangerine,\n"
"# BananaMania, Beaver, Bittersweet,\n"
"# Black, BlizzardBlue, Blue\n"
"# }\n"
"// A fixed-size stack vector\n"
"let stack_crayons: [Crayon, ..3] = [Almond, AntiqueBrass, Apricot];\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1255
msgid ""
"// A borrowed pointer to stack-allocated vector let stack_crayons: &[Crayon] "
"= &[Aquamarine, Asparagus, AtomicTangerine];"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1258
msgid ""
"// A local heap (managed) vector of crayons let local_crayons: @[Crayon] = "
"@[BananaMania, Beaver, Bittersweet];"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1262
msgid ""
"// An exchange heap (owned) vector of crayons let exchange_crayons: "
"~[Crayon] = ~[Black, BlizzardBlue, Blue]; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1264
msgid "The `+` operator means concatenation when applied to vector types."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1274
#, no-wrap
msgid ""
"~~~~\n"
"# enum Crayon { Almond, AntiqueBrass, Apricot,\n"
"# Aquamarine, Asparagus, AtomicTangerine,\n"
"# BananaMania, Beaver, Bittersweet };\n"
"# impl Clone for Crayon {\n"
"# fn clone(&self) -> Crayon {\n"
"# *self\n"
"# }\n"
"# }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1277
msgid ""
"let my_crayons = ~[Almond, AntiqueBrass, Apricot]; let your_crayons = "
"~[BananaMania, Beaver, Bittersweet];"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1280
msgid ""
"// Add two vectors to create a new one let our_crayons = my_crayons + "
"your_crayons;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1285
msgid ""
"// .push_all() will append to a vector, provided it lives in a mutable slot "
"let mut my_crayons = my_crayons; my_crayons.push_all(your_crayons); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1290
msgid ""
"> ***Note:*** The above examples of vector addition use owned > vectors. "
"Some operations on slices and stack vectors are > not yet well-supported. "
"Owned vectors are often the most > usable."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1292
msgid "Square brackets denote indexing into a vector:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1304
#, no-wrap
msgid ""
"~~~~\n"
"# enum Crayon { Almond, AntiqueBrass, Apricot,\n"
"# Aquamarine, Asparagus, AtomicTangerine,\n"
"# BananaMania, Beaver, Bittersweet };\n"
"# fn draw_scene(c: Crayon) { }\n"
"let crayons: [Crayon, ..3] = [BananaMania, Beaver, Bittersweet];\n"
"match crayons[0] {\n"
" Bittersweet => draw_scene(crayons[0]),\n"
" _ => ()\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1306
msgid "A vector can be destructured using pattern matching:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1316
#, no-wrap
msgid ""
"~~~~\n"
"let numbers: &[int] = &[1, 2, 3];\n"
"let score = match numbers {\n"
" [] => 0,\n"
" [a] => a * 10,\n"
" [a, b] => a * 6 + b * 4,\n"
" [a, b, c, ..rest] => a * 5 + b * 3 + c * 2 + rest.len() as int\n"
"};\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1320
msgid ""
"The elements of a vector _inherit the mutability of the vector_, and as "
"such, individual elements may not be reassigned when the vector lives in an "
"immutable slot."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1326
#, no-wrap
msgid ""
"~~~ {.xfail-test}\n"
"# enum Crayon { Almond, AntiqueBrass, Apricot,\n"
"# Aquamarine, Asparagus, AtomicTangerine,\n"
"# BananaMania, Beaver, Bittersweet };\n"
"let crayons: ~[Crayon] = ~[BananaMania, Beaver, Bittersweet];\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1329
msgid "crayons[0] = Apricot; // ERROR: Can't assign to immutable vector ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1331
msgid "Moving it into a mutable slot makes the elements assignable."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1337
#, no-wrap
msgid ""
"~~~\n"
"# enum Crayon { Almond, AntiqueBrass, Apricot,\n"
"# Aquamarine, Asparagus, AtomicTangerine,\n"
"# BananaMania, Beaver, Bittersweet };\n"
"let crayons: ~[Crayon] = ~[BananaMania, Beaver, Bittersweet];\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1340
msgid ""
"// Put the vector into a mutable slot let mut mutable_crayons = crayons;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1344
msgid "// Now it's mutable to the bone mutable_crayons[0] = Apricot; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1347
msgid ""
"This is a simple example of Rust's _dual-mode data structures_, also "
"referred to as _freezing and thawing_."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1355
msgid ""
"Strings are implemented with vectors of `u8`, though they have a distinct "
"type. They support most of the same allocation options as vectors, though "
"the string literal without a storage sigil (for example, `\"foo\"`) is "
"treated differently than a comparable vector (`[foo]`). Whereas plain "
"vectors are stack-allocated fixed-length vectors, plain strings are borrowed "
"pointers to read-only (static) memory. All strings are immutable."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1359
msgid ""
"~~~ // A plain string is a slice to read-only (static) memory let "
"stack_crayons: &str = \"Almond, AntiqueBrass, Apricot\";"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1362
msgid ""
"// The same thing, but with the `&` let stack_crayons: &str = &\"Aquamarine, "
"Asparagus, AtomicTangerine\";"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1365
msgid ""
"// A local heap (managed) string let local_crayons: @str = @\"BananaMania, "
"Beaver, Bittersweet\";"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1369
msgid ""
"// An exchange heap (owned) string let exchange_crayons: ~str = ~\"Black, "
"BlizzardBlue, Blue\"; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1373
msgid ""
"Both vectors and strings support a number of useful [methods](#methods), "
"defined in [`std::vec`] and [`std::str`]. Here are some examples."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1376
msgid "[`std::vec`]: std/vec.html [`std::str`]: std/str.html"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1387
#, no-wrap
msgid ""
"~~~\n"
"# enum Crayon {\n"
"# Almond, AntiqueBrass, Apricot,\n"
"# Aquamarine, Asparagus, AtomicTangerine,\n"
"# BananaMania, Beaver, Bittersweet\n"
"# }\n"
"# fn unwrap_crayon(c: Crayon) -> int { 0 }\n"
"# fn eat_crayon_wax(i: int) { }\n"
"# fn store_crayon_in_nasal_cavity(i: uint, c: Crayon) { }\n"
"# fn crayon_to_str(c: Crayon) -> &str { \"\" }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1389
msgid "let crayons = [Almond, AntiqueBrass, Apricot];"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1393
msgid ""
"// Check the length of the vector assert!(crayons.len() == 3); assert!(!"
"crayons.is_empty());"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1400
#, no-wrap
msgid ""
"// Iterate over a vector, obtaining a pointer to each element\n"
"// (`for` is explained in the container/iterator tutorial)\n"
"for crayon in crayons.iter() {\n"
" let delicious_crayon_wax = unwrap_crayon(*crayon);\n"
" eat_crayon_wax(delicious_crayon_wax);\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1404
msgid ""
"// Map vector elements let crayon_names = crayons.map(|v| "
"crayon_to_str(*v)); let favorite_crayon_name = crayon_names[0];"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1407
msgid ""
"// Remove whitespace from before and after the string let "
"new_favorite_crayon_name = favorite_crayon_name.trim();"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1413
#, no-wrap
msgid ""
"if favorite_crayon_name.len() > 5 {\n"
" // Create a substring\n"
" println(favorite_crayon_name.slice_chars(0, 5));\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1415
msgid "# Closures"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1420
msgid ""
"Named functions, like those we've seen so far, may not refer to local "
"variables declared outside the function: they do not close over their "
"environment (sometimes referred to as \"capturing\" variables in their "
"environment). For example, you couldn't write the following:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1423
msgid "~~~~ {.ignore} let foo = 10;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1428
#, no-wrap
msgid ""
"fn bar() -> int {\n"
" return foo; // `bar` cannot refer to `foo`\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1431
msgid ""
"Rust also supports _closures_, functions that can access variables in the "
"enclosing scope."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1434
msgid "~~~~ fn call_closure_with_ten(b: |int|) { b(10); }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1437
msgid ""
"let captured_var = 20; let closure = |arg| println(fmt!(\"captured_var=%d, "
"arg=%d\", captured_var, arg));"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1440
msgid "call_closure_with_ten(closure); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1446
msgid ""
"Closures begin with the argument list between vertical bars and are followed "
"by a single expression. Remember that a block, `{ <expr1>; <expr2>; ... }`, "
"is considered a single expression: it evaluates to the result of the last "
"expression it contains if that expression is not followed by a semicolon, "
"otherwise the block evaluates to `()`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1451
msgid ""
"The types of the arguments are generally omitted, as is the return type, "
"because the compiler can almost always infer them. In the rare case where "
"the compiler needs assistance, though, the arguments and return types may be "
"annotated."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1455
msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1459
msgid ""
"There are several forms of closure, each with its own role. The most common, "
"called a _stack closure_, has type `||` and can directly access local "
"variables in the enclosing scope."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1464
msgid "~~~~ let mut max = 0; [1, 2, 3].map(|x| if *x > max { max = *x }); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1473
msgid ""
"Stack closures are very efficient because their environment is allocated on "
"the call stack and refers by pointer to captured locals. To ensure that "
"stack closures never outlive the local variables to which they refer, stack "
"closures are not first-class. That is, they can only be used in argument "
"position; they cannot be stored in data structures or returned from "
"functions. Despite these limitations, stack closures are used pervasively in "
"Rust code."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1475
msgid "## Managed closures"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1481
msgid ""
"When you need to store a closure in a data structure, a stack closure will "
"not do, since the compiler will refuse to let you store it. For this "
"purpose, Rust provides a type of closure that has an arbitrary lifetime, "
"written `@fn` (boxed closure, analogous to the `@` pointer type described "
"earlier). This type of closure *is* first-class."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1486
msgid ""
"A managed closure does not directly access its environment, but merely "
"copies out the values that it closes over into a private data structure. "
"This means that it can not assign to these variables, and cannot observe "
"updates to them."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1489
msgid ""
"This code creates a closure that adds a given string to its argument, "
"returns it from a function, and then calls it:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1495
#, no-wrap
msgid ""
"~~~~\n"
"fn mk_appender(suffix: ~str) -> @fn(~str) -> ~str {\n"
" // The compiler knows that we intend this closure to be of type @fn\n"
" return |s| s + suffix;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1501
#, no-wrap
msgid ""
"fn main() {\n"
" let shout = mk_appender(~\"!\");\n"
" println(shout(~\"hey ho, let's go\"));\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1503
msgid "## Owned closures"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1510
msgid ""
"Owned closures, written `proc`, hold on to "
"things that can safely be sent between processes. They copy the values they "
"close over, much like managed closures, but they also own them: that is, no "
"other code can access them. Owned closures are used in concurrent code, "
"particularly for spawning [tasks][tasks]."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1512
msgid "## Closure compatibility"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1519
msgid ""
"Rust closures have a convenient subtyping property: you can pass any kind of "
"closure (as long as the arguments and return types match) to functions that "
"expect a `||`. Thus, when writing a higher-order function that only calls "
"its function argument, and does nothing else with it, you should almost "
"always declare the type of that argument as `||`. That way, callers may "
"pass any kind of closure."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1527
msgid ""
"~~~~ fn call_twice(f: ||) { f(); f(); } let closure = || { \"I'm a "
"closure, and it doesn't matter what type I am\"; }; fn function() { \"I'm a "
"normal function\"; } call_twice(closure); call_twice(function); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1531
msgid ""
"> ***Note:*** Both the syntax and the semantics will be changing > in small "
"ways. At the moment they can be unsound in some > scenarios, particularly "
"with non-copyable types."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1533
msgid "## Do syntax"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1536
msgid ""
"The `do` expression provides a way to treat higher-order functions "
"(functions that take closures as arguments) as control structures."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1539
msgid ""
"Consider this function that iterates over a vector of integers, passing in a "
"pointer to each integer in the vector:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1549
#, no-wrap
msgid ""
"~~~~\n"
"fn each(v: &[int], op: |v: &int|) {\n"
" let mut n = 0;\n"
" while n < v.len() {\n"
" op(&v[n]);\n"
" n += 1;\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1553
msgid ""
"As a caller, if we use a closure to provide the final operator argument, we "
"can write it in a way that has a pleasant, block-like structure."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1561
#, no-wrap
msgid ""
"~~~~\n"
"# fn each(v: &[int], op: |v: &int|) { }\n"
"# fn do_some_work(i: &int) { }\n"
"each([1, 2, 3], |n| {\n"
" do_some_work(n);\n"
"});\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1564
msgid ""
"This is such a useful pattern that Rust has a special form of function call "
"that can be written more like a built-in control structure:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1572
#, no-wrap
msgid ""
"~~~~\n"
"# fn each(v: &[int], op: |v: &int|) { }\n"
"# fn do_some_work(i: &int) { }\n"
"do each([1, 2, 3]) |n| {\n"
" do_some_work(n);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1577
msgid ""
"The call is prefixed with the keyword `do` and, instead of writing the final "
"closure inside the argument list, it appears outside of the parentheses, "
"where it looks more like a typical block of code."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1582
msgid ""
"`do` is a convenient way to create tasks with the `task::spawn` function. "
"`spawn` has the signature `spawn(fn: proc())`. In other words, it is a "
"function that takes an owned closure that takes no arguments."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1585 doc/tutorial.md:1597
msgid "~~~~ use std::task::spawn;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1590
#, no-wrap
msgid ""
"do spawn() || {\n"
" debug!(\"I'm a task, whatever\");\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1594
msgid ""
"Look at all those bars and parentheses -- that's two empty argument lists "
"back to back. Since that is so unsightly, empty argument lists may be "
"omitted from `do` expressions."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1602
#, no-wrap
msgid ""
"do spawn {\n"
" debug!(\"Kablam!\");\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1605
msgid ""
"If you want to see the output of `debug!` statements, you will need to turn "
"on `debug!` logging. To enable `debug!` logging, set the RUST_LOG "
"environment variable to the name of your crate, which, for a file named `foo."
"rs`, will be `foo` (e.g., with bash, `export RUST_LOG=foo`)."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1607
msgid "# Methods"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1613
msgid ""
"Methods are like functions except that they always begin with a special "
"argument, called `self`, which has the type of the method's receiver. The "
"`self` argument is like `this` in C++ and many other languages. Methods are "
"called with dot notation, as in `my_vec.len()`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1617
msgid ""
"_Implementations_, written with the `impl` keyword, can define methods on "
"most Rust types, including structs and enums. As an example, let's define a "
"`draw` method on our `Shape` enum."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1625
#, no-wrap
msgid ""
"~~~\n"
"# fn draw_circle(p: Point, f: f64) { }\n"
"# fn draw_rectangle(p: Point, p: Point) { }\n"
"struct Point {\n"
" x: f64,\n"
" y: f64\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1630
#, no-wrap
msgid ""
"enum Shape {\n"
" Circle(Point, f64),\n"
" Rectangle(Point, Point)\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1639
#, no-wrap
msgid ""
"impl Shape {\n"
" fn draw(&self) {\n"
" match *self {\n"
" Circle(p, f) => draw_circle(p, f),\n"
" Rectangle(p1, p2) => draw_rectangle(p1, p2)\n"
" }\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1643
msgid "let s = Circle(Point { x: 1f, y: 2f }, 3f); s.draw(); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1647
msgid ""
"This defines an _implementation_ for `Shape` containing a single method, "
"`draw`. In most respects the `draw` method is defined like any other "
"function, except for the name `self`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1652
msgid ""
"The type of `self` is the type on which the method is implemented, or a "
"pointer thereof. As an argument it is written either `self`, `&self`, "
"`@self`, or `~self`. A caller must in turn have a compatible pointer type "
"to call the method."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1667
#, no-wrap
msgid ""
"~~~\n"
"# fn draw_circle(p: Point, f: f64) { }\n"
"# fn draw_rectangle(p: Point, p: Point) { }\n"
"# struct Point { x: f64, y: f64 }\n"
"# enum Shape {\n"
"# Circle(Point, f64),\n"
"# Rectangle(Point, Point)\n"
"# }\n"
"impl Shape {\n"
" fn draw_borrowed(&self) { ... }\n"
" fn draw_managed(@self) { ... }\n"
" fn draw_owned(~self) { ... }\n"
" fn draw_value(self) { ... }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1669
msgid "let s = Circle(Point { x: 1f, y: 2f }, 3f);"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1675
msgid ""
"(@s).draw_managed(); (~s).draw_owned(); (&s).draw_borrowed(); s."
"draw_value(); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1679
msgid ""
"Methods typically take a borrowed pointer self type, so the compiler will go "
"to great lengths to convert a callee to a borrowed pointer."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1697
#, no-wrap
msgid ""
"~~~\n"
"# fn draw_circle(p: Point, f: f64) { }\n"
"# fn draw_rectangle(p: Point, p: Point) { }\n"
"# struct Point { x: f64, y: f64 }\n"
"# enum Shape {\n"
"# Circle(Point, f64),\n"
"# Rectangle(Point, Point)\n"
"# }\n"
"# impl Shape {\n"
"# fn draw_borrowed(&self) { ... }\n"
"# fn draw_managed(@self) { ... }\n"
"# fn draw_owned(~self) { ... }\n"
"# fn draw_value(self) { ... }\n"
"# }\n"
"# let s = Circle(Point { x: 1f, y: 2f }, 3f);\n"
"// As with typical function arguments, managed and owned pointers\n"
"// are automatically converted to borrowed pointers\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1700
msgid "(@s).draw_borrowed(); (~s).draw_borrowed();"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1704
msgid ""
"// Unlike typical function arguments, the self value will // automatically "
"be referenced ... s.draw_borrowed();"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1707
msgid "// ... and dereferenced (& &s).draw_borrowed();"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1711
msgid "// ... and dereferenced and borrowed (&@~s).draw_borrowed(); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1715
msgid ""
"Implementations may also define standalone (sometimes called \"static\") "
"methods. The absence of a `self` parameter distinguishes such methods. "
"These methods are the preferred way to define constructor functions."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1722
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"impl Circle {\n"
" fn area(&self) -> f64 { ... }\n"
" fn new(area: f64) -> Circle { ... }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1724
msgid ""
"To call such a method, just prefix it with the type name and a double colon:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1733
#, no-wrap
msgid ""
"~~~~\n"
"use std::f64::consts::pi;\n"
"struct Circle { radius: f64 }\n"
"impl Circle {\n"
" fn new(area: f64) -> Circle { Circle { radius: (area / pi).sqrt() } }\n"
"}\n"
"let c = Circle::new(42.5);\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1735
msgid "# Generics"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1743
msgid ""
"Throughout this tutorial, we've been defining functions that act only on "
"specific data types. With type parameters we can also define functions whose "
"arguments have generic types, and which can be invoked with a variety of "
"types. Consider a generic `map` function, which takes a function `function` "
"and a vector `vector` and returns a new vector consisting of the result of "
"applying `function` to each element of `vector`:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1753
#, no-wrap
msgid ""
"~~~~\n"
"fn map<T, U>(vector: &[T], function: |v: &T| -> U) -> ~[U] {\n"
" let mut accumulator = ~[];\n"
" for element in vector.iter() {\n"
" accumulator.push(function(element));\n"
" }\n"
" return accumulator;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1758
msgid ""
"When defined with type parameters, as denoted by `<T, U>`, this function can "
"be applied to any type of vector, as long as the type of `function`'s "
"argument and the type of the vector's contents agree with each other."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1768
msgid ""
"Inside a generic function, the names of the type parameters (capitalized by "
"convention) stand for opaque types. All you can do with instances of these "
"types is pass them around: you can't apply any operations to them or pattern-"
"match on them. Note that instances of generic types are often passed by "
"pointer. For example, the parameter `function()` is supplied with a pointer "
"to a value of type `T` and not a value of type `T` itself. This ensures that "
"the function works with the broadest set of types possible, since some types "
"are expensive or illegal to copy and pass by value."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1770
msgid ""
"Generic `type`, `struct`, and `enum` declarations follow the same pattern:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1774
msgid "~~~~ use std::hashmap::HashMap; type Set<T> = HashMap<T, ()>;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1778
#, no-wrap
msgid ""
"struct Stack<T> {\n"
" elements: ~[T]\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1784
#, no-wrap
msgid ""
"enum Option<T> {\n"
" Some(T),\n"
" None\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1787
msgid ""
"These declarations can be instantiated to valid types like `Set<int>`, "
"`Stack<int>`, and `Option<int>`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1793
msgid ""
"The last type in that example, `Option`, appears frequently in Rust code. "
"Because Rust does not have null pointers (except in unsafe code), we need "
"another way to write a function whose result isn't defined on every possible "
"combination of arguments of the appropriate types. The usual way is to write "
"a function that returns `Option<T>` instead of `T`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1804
#, no-wrap
msgid ""
"~~~~\n"
"# struct Point { x: f64, y: f64 }\n"
"# enum Shape { Circle(Point, f64), Rectangle(Point, Point) }\n"
"fn radius(shape: Shape) -> Option<f64> {\n"
" match shape {\n"
" Circle(_, radius) => Some(radius),\n"
" Rectangle(*) => None\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1812
msgid ""
"The Rust compiler compiles generic functions very efficiently by "
"*monomorphizing* them. *Monomorphization* is a fancy name for a simple idea: "
"generate a separate copy of each generic function at each call site, a copy "
"that is specialized to the argument types and can thus be optimized "
"specifically for them. In this respect, Rust's generics have similar "
"performance characteristics to C++ templates."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1814
msgid "## Traits"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1824
msgid ""
"Within a generic function the operations available on generic types are very "
"limited. After all, since the function doesn't know what types it is "
"operating on, it can't safely modify or query their values. This is where "
"_traits_ come into play. Traits are Rust's most powerful tool for writing "
"polymorphic code. Java developers will see them as similar to Java "
"interfaces, and Haskellers will notice their similarities to type classes. "
"Rust's traits are a form of *bounded polymorphism*: a trait is a way of "
"limiting the set of possible types that a type parameter could refer to."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1832
msgid ""
"As motivation, let us consider copying in Rust. The `clone` method is not "
"defined for all Rust types. One reason is user-defined destructors: copying "
"a type that has a destructor could result in the destructor running multiple "
"times. Therefore, types with destructors cannot be copied unless you "
"explicitly implement `Clone` for them."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1837
msgid ""
"This complicates handling of generic functions. If you have a type "
"parameter `T`, can you copy values of that type? In Rust, you can't, and if "
"you try to run the following code the compiler will complain."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1844
#, no-wrap
msgid ""
"~~~~ {.xfail-test}\n"
"// This does not compile\n"
"fn head_bad<T>(v: &[T]) -> T {\n"
" v[0] // error: copying a non-copyable value\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1851
msgid ""
"However, we can tell the compiler that the `head` function is only for "
"copyable types: that is, those that implement the `Clone` trait. In that "
"case, we can explicitly create a second copy of the value we are returning "
"using the `clone` keyword:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1858
#, no-wrap
msgid ""
"~~~~\n"
"// This does\n"
"fn head<T: Clone>(v: &[T]) -> T {\n"
" v[0].clone()\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1866
msgid ""
"This says that we can call `head` on any type `T` as long as that type "
"implements the `Clone` trait. When instantiating a generic function, you "
"can only instantiate it with types that implement the correct trait, so you "
"could not apply `head` to a type that does not implement `Clone`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1871
msgid ""
"While most traits can be defined and implemented by user code, two traits "
"are automatically derived and implemented for all applicable types by the "
"compiler, and may not be overridden:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1875
#, no-wrap
msgid ""
"* `Send` - Sendable types.\n"
"Types are sendable\n"
"unless they contain managed boxes, managed closures, or borrowed pointers.\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1880
#, no-wrap
msgid ""
"* `Freeze` - Constant (immutable) types.\n"
"These are types that do not contain anything intrinsically mutable.\n"
"Intrinsically mutable values include `@mut`\n"
"and `Cell` in the standard library.\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1883
msgid ""
"> ***Note:*** These two traits were referred to as 'kinds' in earlier > "
"iterations of the language, and often still are."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1889
msgid ""
"Additionally, the `Drop` trait is used to define destructors. This trait "
"defines one method called `drop`, which is automatically called when a value "
"of the type that implements this trait is destroyed, either because the "
"value went out of scope or because the garbage collector reclaimed it."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1894
#, no-wrap
msgid ""
"~~~\n"
"struct TimeBomb {\n"
" explosivity: uint\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1903
#, no-wrap
msgid ""
"impl Drop for TimeBomb {\n"
" fn drop(&self) {\n"
" for _ in range(0, self.explosivity) {\n"
" println(\"blam!\");\n"
" }\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1906
msgid ""
"It is illegal to call `drop` directly. Only code inserted by the compiler "
"may call it."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1908
msgid "## Declaring and implementing traits"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1914
msgid ""
"A trait consists of a set of methods without bodies, or may be empty, as is "
"the case with `Send` and `Freeze`. For example, we could declare the trait "
"`Printable` for things that can be printed to the console, with a single "
"method:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1920
#, no-wrap
msgid ""
"~~~~\n"
"trait Printable {\n"
" fn print(&self);\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1925
msgid ""
"Traits may be implemented for specific types with [impls]. An impl that "
"implements a trait includes the name of the trait at the start of the "
"definition, as in the following impls of `Printable` for `int` and `~str`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1927
msgid "[impls]: #methods"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1933
#, no-wrap
msgid ""
"~~~~\n"
"# trait Printable { fn print(&self); }\n"
"impl Printable for int {\n"
" fn print(&self) { println(fmt!(\"%d\", *self)) }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1937
#, no-wrap
msgid ""
"impl Printable for ~str {\n"
" fn print(&self) { println(*self) }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1941
msgid "# 1.print(); # (~\"foo\").print(); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1946
msgid ""
"Methods defined in an implementation of a trait may be called just like any "
"other method, using dot notation, as in `1.print()`. Traits may themselves "
"contain type parameters. A trait for generalized sequence types might look "
"like the following:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1951
#, no-wrap
msgid ""
"~~~~\n"
"trait Seq<T> {\n"
" fn length(&self) -> uint;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1956
#, no-wrap
msgid ""
"impl<T> Seq<T> for ~[T] {\n"
" fn length(&self) -> uint { self.len() }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1963
msgid ""
"The implementation has to explicitly declare the type parameter that it "
"binds, `T`, before using it to specify its trait type. Rust requires this "
"declaration because the `impl` could also, for example, specify an "
"implementation of `Seq<int>`. The trait type (appearing between `impl` and "
"`for`) *refers* to a type, rather than defining one."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1968
msgid ""
"The type parameters bound by a trait are in scope in each of the method "
"declarations. So, re-declaring the type parameter `T` as an explicit type "
"parameter for `len`, in either the trait or the impl, would be a compile-"
"time error."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1973
msgid ""
"Within a trait definition, `Self` is a special type that you can think of as "
"a type parameter. An implementation of the trait for any given type `T` "
"replaces the `Self` type parameter with `T`. The following trait describes "
"types that support an equality operation:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1980
#, no-wrap
msgid ""
"~~~~\n"
"// In a trait, `self` refers to the self argument.\n"
"// `Self` refers to the type implementing the trait.\n"
"trait Eq {\n"
" fn equals(&self, other: &Self) -> bool;\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1986
#, no-wrap
msgid ""
"// In an impl, `self` refers just to the value of the receiver\n"
"impl Eq for int {\n"
" fn equals(&self, other: &int) -> bool { *other == *self }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1991
msgid ""
"Notice that in the trait definition, `equals` takes a second parameter of "
"type `Self`. In contrast, in the `impl`, `equals` takes a second parameter "
"of type `int`, only using `self` as the name of the receiver."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:1996
msgid ""
"Just as in type implementations, traits can define standalone (static) "
"methods. These methods are called by prefixing the method name with the "
"trait name and a double colon. The compiler uses type inference to decide "
"which implementation to use."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2002
msgid ""
"~~~~ use std::f64::consts::pi; trait Shape { fn new(area: f64) -> "
"Self; } struct Circle { radius: f64 } struct Square { length: f64 }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2009
#, no-wrap
msgid ""
"impl Shape for Circle {\n"
" fn new(area: f64) -> Circle { Circle { radius: (area / pi).sqrt() } }\n"
"}\n"
"impl Shape for Square {\n"
" fn new(area: f64) -> Square { Square { length: (area).sqrt() } }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2014
msgid ""
"let area = 42.5; let c: Circle = Shape::new(area); let s: Square = Shape::"
"new(area); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2016
msgid "## Bounded type parameters and static method dispatch"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2021
msgid ""
"Traits give us a language for defining predicates on types, or abstract "
"properties that types can have. We can use this language to define _bounds_ "
"on type parameters, so that we can then operate on generic types."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2030
#, no-wrap
msgid ""
"~~~~\n"
"# trait Printable { fn print(&self); }\n"
"fn print_all<T: Printable>(printable_things: ~[T]) {\n"
" for thing in printable_things.iter() {\n"
" thing.print();\n"
" }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2036
msgid ""
"Declaring `T` as conforming to the `Printable` trait (as we earlier did with "
"`Clone`) makes it possible to call methods from that trait on values of type "
"`T` inside the function. It will also cause a compile-time error when anyone "
"tries to call `print_all` on an array whose element type does not have a "
"`Printable` implementation."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2039
msgid ""
"Type parameters can have multiple bounds by separating them with `+`, as in "
"this version of `print_all` that copies elements."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2051
#, no-wrap
msgid ""
"~~~\n"
"# trait Printable { fn print(&self); }\n"
"fn print_all<T: Printable + Clone>(printable_things: ~[T]) {\n"
" let mut i = 0;\n"
" while i < printable_things.len() {\n"
" let copy_of_thing = printable_things[i].clone();\n"
" copy_of_thing.print();\n"
" i += 1;\n"
" }\n"
"}\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2055
msgid ""
"Method calls to bounded type parameters are _statically dispatched_, "
"imposing no more overhead than normal function invocation, so are the "
"preferred way to use traits polymorphically."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2057
msgid "This usage of traits is similar to Haskell type classes."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2059
msgid "## Trait objects and dynamic method dispatch"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2063
msgid ""
"The above allows us to define functions that polymorphically act on values "
"of a single unknown type that conforms to a given trait. However, consider "
"this function:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2069
msgid ""
"~~~~ # type Circle = int; type Rectangle = int; # impl Drawable for int { fn "
"draw(&self) {} } # fn new_circle() -> int { 1 } trait Drawable { fn "
"draw(&self); }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2076
#, no-wrap
msgid ""
"fn draw_all<T: Drawable>(shapes: ~[T]) {\n"
" for shape in shapes.iter() { shape.draw(); }\n"
"}\n"
"# let c: Circle = new_circle();\n"
"# draw_all(~[c]);\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2082
msgid ""
"You can call that on an array of circles, or an array of rectangles "
"(assuming those have suitable `Drawable` traits defined), but not on an "
"array containing both circles and rectangles. When such behavior is needed, "
"a trait name can alternately be used as a type, called an _object_."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2089
#, no-wrap
msgid ""
"~~~~\n"
"# trait Drawable { fn draw(&self); }\n"
"fn draw_all(shapes: &[@Drawable]) {\n"
" for shape in shapes.iter() { shape.draw(); }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2094
msgid ""
"In this example, there is no type parameter. Instead, the `@Drawable` type "
"denotes any managed box value that implements the `Drawable` trait. To "
"construct such a value, you use the `as` operator to cast a value to an "
"object:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2101
msgid ""
"~~~~ # type Circle = int; type Rectangle = bool; # trait Drawable { fn "
"draw(&self); } # fn new_circle() -> Circle { 1 } # fn new_rectangle() -> "
"Rectangle { true } # fn draw_all(shapes: &[@Drawable]) {}"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2104
msgid ""
"impl Drawable for Circle { fn draw(&self) { ... } } impl Drawable for "
"Rectangle { fn draw(&self) { ... } }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2109
msgid ""
"let c: @Circle = @new_circle(); let r: @Rectangle = @new_rectangle(); "
"draw_all([c as @Drawable, r as @Drawable]); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2117
msgid ""
"We omit the code for `new_circle` and `new_rectangle`; imagine that these "
"just return `Circle`s and `Rectangle`s with a default size. Note that, like "
"strings and vectors, objects have dynamic size and may only be referred to "
"via one of the pointer types. Other pointer types work as well. Casts to "
"traits may only be done with compatible pointers so, for example, an "
"`@Circle` may not be cast to an `~Drawable`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2131
msgid ""
"~~~ # type Circle = int; type Rectangle = int; # trait Drawable { fn "
"draw(&self); } # impl Drawable for int { fn draw(&self) {} } # fn "
"new_circle() -> int { 1 } # fn new_rectangle() -> int { 2 } // A managed "
"object let boxy: @Drawable = @new_circle() as @Drawable; // An owned object "
"let owny: ~Drawable = ~new_circle() as ~Drawable; // A borrowed object let "
"stacky: &Drawable = &new_circle() as &Drawable; ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2136
msgid ""
"Method calls to trait types are _dynamically dispatched_. Since the compiler "
"doesn't know specifically which functions to call at compile time, it uses a "
"lookup table (also known as a vtable or dictionary) to select the method to "
"call at runtime."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2138
msgid "This usage of traits is similar to Java interfaces."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2140
msgid "## Trait inheritance"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2145
msgid ""
"We can write a trait declaration that _inherits_ from other traits, called "
"_supertraits_. Types that implement a trait must also implement its "
"supertraits. For example, we can define a `Circle` trait that inherits from "
"`Shape`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2150
msgid ""
"~~~~ trait Shape { fn area(&self) -> f64; } trait Circle : Shape { fn "
"radius(&self) -> f64; } ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2152
msgid ""
"Now, we can implement `Circle` on a type only if we also implement `Shape`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2167
#, no-wrap
msgid ""
"~~~~\n"
"use std::f64::consts::pi;\n"
"# trait Shape { fn area(&self) -> f64; }\n"
"# trait Circle : Shape { fn radius(&self) -> f64; }\n"
"# struct Point { x: f64, y: f64 }\n"
"# fn square(x: f64) -> f64 { x * x }\n"
"struct CircleStruct { center: Point, radius: f64 }\n"
"impl Circle for CircleStruct {\n"
" fn radius(&self) -> f64 { (self.area() / pi).sqrt() }\n"
"}\n"
"impl Shape for CircleStruct {\n"
" fn area(&self) -> f64 { pi * square(self.radius) }\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2172
msgid ""
"Notice that methods of `Circle` can call methods on `Shape`, as our `radius` "
"implementation calls the `area` method. This is a silly way to compute the "
"radius of a circle (since we could just return the `radius` field), but you "
"get the idea."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2196
msgid ""
"~~~ {.xfail-test} use std::f64::consts::pi; # trait Shape { fn area(&self) "
"-> f64; } # trait Circle : Shape { fn radius(&self) -> f64; } # struct "
"Point { x: f64, y: f64 } # struct CircleStruct { center: Point, radius: "
"f64 } # impl Circle for CircleStruct { fn radius(&self) -> f64 { (self."
"area() / pi).sqrt() } } # impl Shape for CircleStruct { fn area(&self) -> "
"f64 { pi * square(self.radius) } }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2201
msgid ""
"let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f}; let "
"mycircle: @Circle = concrete as @Circle; let nonsense = mycircle.radius() * "
"mycircle.area(); ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2203
msgid "> ***Note:*** Trait inheritance does not actually work with objects yet"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2205
msgid "## Deriving implementations for traits"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2212
msgid ""
"A small number of traits in `std` and `extra` can have implementations that "
"can be automatically derived. These instances are specified by placing the "
"`deriving` attribute on a data type declaration. For example, the following "
"will mean that `Circle` has an implementation for `Eq` and can be used with "
"the equality operators, and that a value of type `ABC` can be randomly "
"generated and converted to a string:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2216
msgid "~~~ #[deriving(Eq)] struct Circle { radius: f64 }"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2220
msgid "#[deriving(Rand, ToStr)] enum ABC { A, B, C } ~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2224
msgid ""
"The full list of derivable traits is `Eq`, `TotalEq`, `Ord`, `TotalOrd`, "
"`Encodable` `Decodable`, `Clone`, `DeepClone`, `IterBytes`, `Rand`, `Zero`, "
"and `ToStr`."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2226
msgid "# Modules and crates"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2230
msgid ""
"The Rust namespace is arranged in a hierarchy of modules. Each source (.rs) "
"file represents a single module and may in turn contain additional modules."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2236
#, no-wrap
msgid ""
"~~~~\n"
"mod farm {\n"
" pub fn chicken() -> &str { \"cluck cluck\" }\n"
" pub fn cow() -> &str { \"mooo\" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2241
#, no-wrap
msgid ""
"fn main() {\n"
" println(farm::chicken());\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2246
msgid ""
"The contents of modules can be imported into the current scope with the "
"`use` keyword, optionally giving it an alias. `use` may appear at the "
"beginning of crates, `mod`s, `fn`s, and other blocks."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2252
msgid ""
"~~~ # mod farm { pub fn chicken() { } } # fn main() { // Bring `chicken` "
"into scope use farm::chicken;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2262
#, no-wrap
msgid ""
"fn chicken_farmer() {\n"
" // The same, but name it `my_chicken`\n"
" use my_chicken = farm::chicken;\n"
" ...\n"
"# my_chicken();\n"
"}\n"
"# chicken();\n"
"# }\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2269
msgid ""
"These farm animal functions have a new keyword, `pub`, attached to them. The "
"`pub` keyword modifies an item's visibility, making it visible outside its "
"containing module. An expression with `::`, like `farm::chicken`, can name "
"an item outside of its containing module. Items, such as those declared with "
"`fn`, `struct`, `enum`, `type`, or `static`, are module-private by default."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2276
msgid ""
"Visibility restrictions in Rust exist only at module boundaries. This is "
"quite different from most object-oriented languages that also enforce "
"restrictions on objects themselves. That's not to say that Rust doesn't "
"support encapsulation: both struct fields and methods can be private. But "
"this encapsulation is at the module level, not the struct level. Note that "
"fields and methods are _public_ by default."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2289
#, no-wrap
msgid ""
"~~~\n"
"pub mod farm {\n"
"# pub type Chicken = int;\n"
"# type Cow = int;\n"
"# struct Human(int);\n"
"# impl Human { fn rest(&self) { } }\n"
"# pub fn make_me_a_farm() -> Farm { Farm { chickens: ~[], cows: ~[], farmer: Human(0) } }\n"
" pub struct Farm {\n"
" priv chickens: ~[Chicken],\n"
" priv cows: ~[Cow],\n"
" farmer: Human\n"
" }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2295
#, no-wrap
msgid ""
" impl Farm {\n"
" fn feed_chickens(&self) { ... }\n"
" fn feed_cows(&self) { ... }\n"
" pub fn add_chicken(&self, c: Chicken) { ... }\n"
" }\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2301
#, no-wrap
msgid ""
" pub fn feed_animals(farm: &Farm) {\n"
" farm.feed_chickens();\n"
" farm.feed_cows();\n"
" }\n"
"}\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2311
#, no-wrap
msgid ""
"fn main() {\n"
" let f = make_me_a_farm();\n"
" f.add_chicken(make_me_a_chicken());\n"
" farm::feed_animals(&f);\n"
" f.farmer.rest();\n"
"}\n"
"# fn make_me_a_farm() -> farm::Farm { farm::make_me_a_farm() }\n"
"# fn make_me_a_chicken() -> farm::Chicken { 0 }\n"
"~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2313
msgid "## Crates"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2317
msgid ""
"The unit of independent compilation in Rust is the crate: rustc compiles a "
"single crate at a time, from which it produces either a library or an "
"executable."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2322
msgid ""
"When compiling a single `.rs` source file, the file acts as the whole "
"crate. You can compile it with the `--lib` compiler switch to create a "
"shared library, or without, provided that your file contains a `fn main` "
"somewhere, to create an executable."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2327
msgid ""
"Larger crates typically span multiple files and are, by convention, compiled "
"from a source file with the `.rc` extension, called a *crate file*. The "
"crate file extension distinguishes source files that represent crates from "
"those that do not, but otherwise source files and crate files are identical."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2336
msgid ""
"A typical crate file declares attributes associated with the crate that may "
"affect how the compiler processes the source. Crate attributes specify "
"metadata used for locating and linking crates, the type of crate (library or "
"executable), and control warning and error behavior, among other things. "
"Crate files additionally declare the external crates they depend on as well "
"as any modules loaded from other files."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2340
msgid ""
"~~~~ { .xfail-test } // Crate linkage metadata #[link(name = \"farm\", vers "
"= \"2.5\", author = \"mjh\")];"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2343
msgid "// Make a library (\"bin\" is the default) #[crate_type = \"lib\"];"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2346
msgid "// Turn on a warning #[warn(non_camel_case_types)]"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2349
msgid "// Link to the standard library extern mod std;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2354
msgid "// Load some modules from other files mod cow; mod chicken; mod horse;"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2359
#, no-wrap
msgid ""
"fn main() {\n"
" ...\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2366
msgid ""
"Compiling this file will cause `rustc` to look for files named `cow.rs`, "
"`chicken.rs`, and `horse.rs` in the same directory as the `.rc` file, "
"compile them all together, and, based on the presence of the `crate_type = "
"\"lib\"` attribute, output a shared library or an executable. (If the line "
"`#[crate_type = \"lib\"];` was omitted, `rustc` would create an executable.)"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2370
msgid ""
"The `#[link(...)]` attribute provides meta information about the module, "
"which other crates can use to load the right module. More about that later."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2373
msgid ""
"To have a nested directory structure for your source files, you can nest "
"mods:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2380
#, no-wrap
msgid ""
"~~~~ {.ignore}\n"
"mod poultry {\n"
" mod chicken;\n"
" mod turkey;\n"
"}\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2385
msgid ""
"The compiler will now look for `poultry/chicken.rs` and `poultry/turkey.rs`, "
"and export their content in `poultry::chicken` and `poultry::turkey`. You "
"can also provide a `poultry.rs` to add content to the `poultry` module "
"itself."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2387
msgid "## Using other crates"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2395
msgid ""
"The `extern mod` directive lets you use a crate (once it's been compiled "
"into a library) from inside another crate. `extern mod` can appear at the "
"top of a crate file or at the top of modules. It will cause the compiler to "
"look in the library search path (which you can extend with the `-L` switch) "
"for a compiled Rust library with the right name, then add a module with that "
"crate's name into the local scope."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2397
msgid "For example, `extern mod std` links the [standard library]."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2399
msgid "[standard library]: std/index.html"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2406
msgid ""
"When a comma-separated list of name/value pairs appears after `extern mod`, "
"the compiler front-end matches these pairs against the attributes provided "
"in the `link` attribute of the crate file. The front-end will only select "
"this crate for use if the actual pairs match the declared attributes. You "
"can provide a `name` value to override the name used to search for the crate."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2408
msgid "Our example crate declared this set of `link` attributes:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2412
msgid "~~~~ #[link(name = \"farm\", vers = \"2.5\", author = \"mjh\")]; ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2414
msgid "Which you can then link with any (or all) of the following:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2420
msgid ""
"~~~~ {.xfail-test} extern mod farm; extern mod my_farm (name = \"farm\", "
"vers = \"2.5\"); extern mod my_auxiliary_farm (name = \"farm\", author = "
"\"mjh\"); ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2423
msgid ""
"If any of the requested metadata do not match, then the crate will not be "
"compiled successfully."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2425
msgid "## A minimal example"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2428
msgid ""
"Now for something that you can actually compile yourself, we have these two "
"files:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2434
msgid ""
"~~~~ // world.rs #[link(name = \"world\", vers = \"1.0\")]; pub fn explore() "
"-> &str { \"world\" } ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2440
msgid ""
"~~~~ {.xfail-test} // main.rs extern mod world; fn main() { println(~\"hello "
"\" + world::explore()); } ~~~~"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2442
msgid "Now compile and run like this (adjust to your platform if necessary):"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2449
#, no-wrap
msgid ""
"~~~~ {.notrust}\n"
"> rustc --lib world.rs # compiles libworld-94839cbfe144198-1.0.so\n"
"> rustc main.rs -L . # compiles main\n"
"> ./main\n"
"\"hello world\"\n"
"~~~~\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2454
msgid ""
"Notice that the library produced contains the version in the filename as "
"well as an inscrutable string of alphanumerics. These are both part of "
"Rust's library versioning scheme. The alphanumerics are a hash representing "
"the crate metadata."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2456
msgid "## The standard library"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2461
msgid ""
"The Rust standard library provides runtime features required by the "
"language, including the task scheduler and memory allocators, as well as "
"library support for Rust built-in types, platform abstractions, and other "
"commonly used features."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2472
msgid ""
"[`std`] includes modules corresponding to each of the integer types, each of "
"the floating point types, the [`bool`] type, [tuples], [characters], "
"[strings], [vectors], [managed boxes], [owned boxes], and unsafe and "
"borrowed [pointers]. Additionally, `std` provides some pervasive types "
"([`option`] and [`result`]), [task] creation and [communication] primitives, "
"platform abstractions ([`os`] and [`path`]), basic I/O abstractions "
"([`io`]), [containers] like [`hashmap`], common traits ([`kinds`], [`ops`], "
"[`cmp`], [`num`], [`to_str`], [`clone`]), and complete bindings to the C "
"standard library ([`libc`])."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2474
msgid "### Standard Library injection and the Rust prelude"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2477
msgid ""
"`std` is imported at the topmost level of every crate by default, as if the "
"first line of each crate was"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2479
#, no-wrap
msgid " extern mod std;\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2483
msgid ""
"This means that the contents of std can be accessed from from any context "
"with the `std::` path prefix, as in `use std::vec`, `use std::task::spawn`, "
"etc."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2488
msgid ""
"Additionally, `std` contains a `prelude` module that reexports many of the "
"most common standard modules, types and traits. The contents of the prelude "
"are imported into every *module* by default. Implicitly, all modules behave "
"as if they contained the following prologue:"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2490
#, no-wrap
msgid " use std::prelude::*;\n"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2516
msgid ""
"[`std`]: std/index.html [`bool`]: std/bool.html [tuples]: std/tuple.html "
"[characters]: std/char.html [strings]: std/str.html [vectors]: std/vec.html "
"[managed boxes]: std/managed.html [owned boxes]: std/owned.html [pointers]: "
"std/ptr.html [`option`]: std/option.html [`result`]: std/result.html [task]: "
"std/task.html [communication]: std/comm.html [`os`]: std/os.html [`path`]: "
"std/path.html [`io`]: std/io.html [containers]: std/container.html "
"[`hashmap`]: std/hashmap.html [`kinds`]: std/kinds.html [`ops`]: std/ops."
"html [`cmp`]: std/cmp.html [`num`]: std/num.html [`to_str`]: std/to_str.html "
"[`clone`]: std/clone.html [`libc`]: std/libc.html"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2518
msgid "# What next?"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2521
msgid ""
"Now that you know the essentials, check out any of the additional tutorials "
"on individual topics."
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:2527
msgid "[Borrowed pointers][borrow]"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:2527
msgid "[Tasks and communication][tasks]"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:2527
msgid "[Macros][macros]"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:2527
msgid "[The foreign function interface][ffi]"
msgstr ""
#. type: Bullet: '* '
#: doc/tutorial.md:2527
msgid "[Containers and iterators](tutorial-container.html)"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2529
msgid "There is further documentation on the [wiki]."
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2534
msgid ""
"[borrow]: tutorial-borrowed-ptr.html [tasks]: tutorial-tasks.html [macros]: "
"tutorial-macros.html [ffi]: tutorial-ffi.html"
msgstr ""
#. type: Plain text
#: doc/tutorial.md:2536
msgid "[wiki]: https://github.com/mozilla/rust/wiki/Docs"
msgstr ""