6491 lines
179 KiB
Plaintext
6491 lines
179 KiB
Plaintext
# 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: &fn(T)) {\n"
|
|
" for elt in seq.iter() { f(elt); }\n"
|
|
"}\n"
|
|
"fn map<T, U>(seq: &[T], f: &fn(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, &fn(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 "
|
|
"```&fn() { }``` 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: &fn(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: &fn(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: &fn(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 fn(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: &fn(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. > > — 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 [...] > > — 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. > > — 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öm, Mike Williams and others in their group at the Ericsson "
|
|
"Computer Science Laboratory (Älvsjö, 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 ""
|