diff --git a/.gitignore b/.gitignore
index eef182a12233d..4eff4c540588f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -77,7 +77,7 @@ src/.DS_Store
/nd/
/llvm/
version.md
-rust.tex
+*.tex
keywords.md
x86_64-apple-darwin/
x86_64-unknown-linux-gnu/
diff --git a/doc/README b/doc/README
index bb6ab77a80213..d7578987e2b15 100644
--- a/doc/README
+++ b/doc/README
@@ -19,7 +19,7 @@ To generate HTML documentation from one source file/crate, do something like:
To generate an HTML version of a doc from Markdown, without having Node.js
installed, do something like:
- pandoc --from=markdown --to=html --number-sections -o rust.html rust.md
+ pandoc --from=markdown --to=html5 --number-sections -o rust.html rust.md
The syntax for pandoc flavored markdown can be found at:
http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
diff --git a/doc/lib.css b/doc/lib.css
deleted file mode 100644
index 443f118058405..0000000000000
--- a/doc/lib.css
+++ /dev/null
@@ -1,8 +0,0 @@
-/*
-Custom styles for the library docs generated by naturaldocs
-*/
-
-p {
- text-indent: 0;
- margin-bottom: 1em;
- }
diff --git a/doc/manual.css b/doc/manual.css
deleted file mode 100644
index 883dfab3f7982..0000000000000
--- a/doc/manual.css
+++ /dev/null
@@ -1,6 +0,0 @@
-/* Display the full TOC */
-
-#TOC ul ul {
- display: block;
- padding-left: 2em;
-}
diff --git a/doc/manual.inc b/doc/manual.inc
new file mode 100644
index 0000000000000..783679d0ea5fd
--- /dev/null
+++ b/doc/manual.inc
@@ -0,0 +1,7 @@
+
\ No newline at end of file
diff --git a/doc/rust.css b/doc/rust.css
index ed9ea446aa87e..26135edd8bead 100644
--- a/doc/rust.css
+++ b/doc/rust.css
@@ -1,82 +1,148 @@
+/**
+ * Copyright 2013 The Rust Project Developers. See the COPYRIGHT
+ * file at the top-level directory of this distribution and at
+ * http://rust-lang.org/COPYRIGHT.
+ * With elements taken from Bootstrap v3.0.0 (Apache v2.0 licensed).
+ *
+ * Licensed under the Apache License, Version 2.0 or the MIT license
+ * , at your
+ * option. This file may not be copied, modified, or distributed
+ * except according to those terms.
+ */
+/* Global page semantics
+ ========================================================================== */
body {
- padding: 1em 6em;
- margin: 0;
- margin-bottom: 4em;
- font-family: "Helvetica Neue", Helvetica, sans-serif;
- font-size: 12pt;
- background-color: white;
- color: black;
- line-height: 1.6em;
- min-width: 45em;
- max-width: 60em;
+ background-color: #fff;
+ margin: 0 auto;
+ padding: 0 15px;
+ margin-bottom: 4em;
+ font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+ font-size: 14px;
+ color: #333;
+ line-height: 1.428571429;
}
-
-h1 {
- font-size: 24pt;
- margin-top: 1.6em;
- padding-left: 0.4em;
- line-height: 1.6em;
- background-color:#FFF2CE;
- border-radius: 0.2em;
+@media (min-width: 768px) {
+ body {
+ max-width: 750px;
+ }
}
-
-h2 {
- font-size: 16pt;
- margin-top: 1.6em;
- padding: 0.2em 0.5em;
- background-color:#FFF2CE;
- border-radius: 0.4em;
+@media (min-width: 992px) {
+ body {
+ max-width: 970px;
+ }
}
-
-h2 code {
- color: #097334;
- font-size: 16pt;
+@media (min-width: 1200px) {
+ body {
+ max-width: 1170px;
+ }
}
-h3 {
- font-size: 14pt;
- color: black;
- background-color:#D9E7FF;
- border-radius: 0.4em;
- padding: 0.2em 0.5em;
+h1, h2, h3, h4, h5, h6 {
+ color: black;
+ font-weight: 500;
+ line-height: 1.1;
}
-
-h3 code {
- color: #541800;
- font-size: 14pt;
- font-style: italic;
+h1, h2, h3 {
+ margin-top: 20px;
+ margin-bottom: 10px;
+}
+h4, h5, h6 {
+ margin-top: 12px;
+ margin-bottom: 10px;
}
+h1 {
+ font-size: 36px;
+ padding: .1em .4em;
+ margin: 0.67em 0;
+ background-color: #E9E9E9;
+ border-radius: .2em;
+}
+h1.title {
+ line-height: 1.5em;
+}
+h2 {
+ font-size: 30px;
+ padding: .2em .5em;
+ background-color: #E9E9E9;
+ border-radius: .3em;
+}
+h3 {
+ font-size: 24px;
+ padding: .2em .5em;
+ background-color: #DDE8FC;
+ border-radius: .4em;
+}
h4 {
- font-size: 11pt;
- margin-top: 0em;
- margin-bottom: 0em;
+ font-size: 18px;
}
-
-code {
- font-size: 11pt;
+h5 {
+ font-size: 16px;
}
-
-pre {
- margin-left: 1.1em;
- padding: .4em .4em .4em .8em;
- font-size: 10pt;
- background-color: #F5F5F5;
- border-radius: 0.5em;
- border: 1px solid rgba(0, 0, 0, 0.15);
+h6 {
+ font-size: 14px;
}
-pre.rust {
- background-color: #F3F6FF;
+p {
+ margin: 0 0 10px;
}
-a, a:visited, a:link {
- text-decoration: none;
- color: rgb(0, 105, 214);
+/* Links layout
+ ========================================================================== */
+a {
+ text-decoration: none;
+ color: #428BCA;
+}
+a:hover, a:focus {
+ color: #2A6496;
+ text-decoration: underline;
+}
+a:focus {
+ outline: thin dotted #333;
+ outline: 5px auto -webkit-focus-ring-color;
+ outline-offset: -2px;
+}
+a:hover, a:active {
+ outline: 0;
}
h1 a:link, h1 a:visited, h2 a:link, h2 a:visited,
-h3 a:link, h3 a:visited { color: black; }
+h3 a:link, h3 a:visited, h4 a:link, h4 a:visited,
+h5 a:link, h5 a:visited {color: black;}
+
+/* Code
+ ========================================================================== */
+pre, code {
+ font-family: Monaco, Menlo, Consolas, "Courier New", monospace;
+ border-radius: 4px;
+}
+pre {
+ background-color: #F5F5F5;
+ border: 1px solid #CCC;
+ border-radius: 0.5em;
+ white-space: pre-wrap;
+ padding: 9.5px;
+ margin: 10px 0;
+ font-size: 13px;
+ word-break: break-all;
+ word-wrap: break-word;
+}
+code {
+ padding: 2px 4px;
+ font-size: 90%;
+ color: #C7254E;
+ background-color: #F9F2F4;
+ white-space: nowrap;
+}
+pre code {
+ padding: 0;
+ font-size: inherit;
+ color: inherit;
+ white-space: pre-wrap;
+ background-color: transparent;
+ border: 0;
+}
/* Code highlighting */
.cm-s-default span.cm-keyword {color: #708;}
@@ -99,58 +165,142 @@ h3 a:link, h3 a:visited { color: black; }
.cm-s-default span.cm-tag {color: #170;}
.cm-s-default span.cm-attribute {color: #00c;}
+/* The rest
+ ========================================================================== */
#versioninfo {
- position: fixed;
- bottom: 0px;
- right: 0px;
-
- background-color: white;
- padding: 0.5em;
+ text-align: center;
+ margin: 0.5em;
+ font-size: 1.1em;
}
-
-a.lessimportant {
- color: gray;
- font-size: 60%;
+@media (min-width: 768px) {
+ #versioninfo {
+ position: fixed;
+ bottom: 0px;
+ right: 0px;
+ }
+ .white-sticker {
+ background-color: #fff;
+ margin: 2px;
+ padding: 0 2px;
+ border-radius: .3em;
+ }
+}
+#versioninfo a.hash {
+ color: gray;
+ font-size: 60%;
}
blockquote {
- color: black;
- border-left: solid 1px silver;
- margin: 1em;
- padding: 0.5em 1em 0.5em 1em;
+ color: black;
+ border-left: 5px solid #eee;
+ margin: 0 0 20px;
+ padding: 10px 20px;
+}
+blockquote p {
+ font-size: 17px;
+ font-weight: 300;
+ line-height: 1.25;
+}
+blockquote p:last-child {
+ margin-bottom: 0;
}
/* Make the table under the tutorial's 'Types' section look nicer */
table {
- border-top: 1px solid silver;
- border-bottom: 1px solid silver;
- padding: 0.8em;
- font-size: smaller;
+ border-top: 1px solid silver;
+ border-bottom: 1px solid silver;
+ padding: 0.8em;
+ font-size: smaller;
}
/* Also for the benefit of the type table */
td {
- padding-right: 1em;
+ padding-right: 1em;
}
-/* Only display one level of hierarchy in the TOC */
-#TOC ul ul {
- display: none;
+ul,
+ol {
+ margin-top: 0;
+ margin-bottom: 10px;
+}
+ul ul,
+ol ul,
+ul ol,
+ol ol {
+ margin-bottom: 0;
+}
+dl {
+ margin-bottom: 20px;
+}
+dd {
+ margin-left: 0;
}
#TOC ul {
- list-style: none;
- padding-left: 0px;
+ list-style-type: none;
+ padding-left: 0px;
+}
+/* Only display one level of hierarchy in the TOC */
+#TOC ul ul {
+ display: none;
}
/* Adjust list alignment so rustdoc indexes don't align with blockquotes */
div.index ul {
- padding-left: 1em;
+ padding-left: 1em;
}
-ul {
- margin-top: 0em
+div.section.level3 {
+ margin-left: 1em;
}
-div.section.level3 {
- margin-left: 1.0em;
+sub,
+sup {
+ font-size: 75%;
+ line-height: 0;
+ position: relative;
}
+
+hr {
+ margin-top: 20px;
+ margin-bottom: 20px;
+ border: 0;
+ border-top: 1px solid #eeeeee;
+}
+
+@media print {
+ * {
+ text-shadow: none !important;
+ color: #000 !important;
+ background: transparent !important;
+ box-shadow: none !important;
+ }
+ a, a:visited {
+ text-decoration: underline;
+ }
+ a[href]:after {
+ content: " (" attr(href) ")";
+ }
+ a[href^="javascript:"]:after, a[href^="#"]:after {
+ content: "";
+ }
+ pre, blockquote {
+ border: 1px solid #999;
+ page-break-inside: avoid;
+ }
+ @page {
+ margin: 2cm .5cm;
+ }
+ p, h2, h3 {
+ orphans: 3;
+ widows: 3;
+ }
+ h2, h3 {
+ page-break-after: avoid;
+ }
+ table {
+ border-collapse: collapse !important;
+ }
+ table td, table th {
+ background-color: #fff !important;
+ }
+}
\ No newline at end of file
diff --git a/doc/rust.md b/doc/rust.md
index bf35ada5d79e6..e17f8ed890b28 100644
--- a/doc/rust.md
+++ b/doc/rust.md
@@ -60,8 +60,7 @@ 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:
-~~~~~~~~ {.ebnf .notation}
-
+~~~~ {.ebnf .notation}
grammar : rule + ;
rule : nonterminal ':' productionrule ';' ;
productionrule : production [ '|' production ] * ;
@@ -69,8 +68,7 @@ production : term * ;
term : element repeats ;
element : LITERAL | IDENTIFIER | '[' productionrule ']' ;
repeats : [ '*' | '+' ] NUMBER ? | NUMBER ? | '?' ;
-
-~~~~~~~~
+~~~~
Where:
@@ -111,7 +109,6 @@ 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.
-
# Lexical structure
## Input format
@@ -153,12 +150,12 @@ Some productions are defined by exclusion of particular Unicode characters:
## Comments
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.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 * ;
-~~~~~~~~
+~~~~
Comments in Rust code follow the general C++ style of line and block-comment forms,
with no nesting of block-comment delimiters.
@@ -172,10 +169,10 @@ Non-doc comments are interpreted as a form of whitespace.
## Whitespace
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
whitespace_char : '\x20' | '\x09' | '\x0a' | '\x0d' ;
whitespace : [ whitespace_char | comment ] + ;
-~~~~~~~~
+~~~~
The `whitespace_char` production is any nonempty Unicode string consisting of any
of the following Unicode characters: `U+0020` (space, `' '`), `U+0009` (tab,
@@ -189,10 +186,10 @@ with any other legal whitespace element, such as a single space character.
## Tokens
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
simple_token : keyword | unop | binop ;
token : simple_token | ident | literal | symbol | whitespace token ;
-~~~~~~~~
+~~~~
Tokens are primitive productions in the grammar defined by regular
(non-recursive) languages. "Simple" tokens are given in [string table
@@ -203,7 +200,7 @@ grammar as double-quoted strings. Other tokens have exact rules given.
The keywords are the following strings:
-~~~~~~~~ {.keyword}
+~~~~ {.keyword}
as
break
do
@@ -218,7 +215,7 @@ self static struct super
true trait type
unsafe use
while
-~~~~~~~~
+~~~~
Each of these keywords has special meaning in its grammar,
and all of them are excluded from the `ident` rule.
@@ -231,13 +228,13 @@ 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.
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
literal : string_lit | char_lit | num_lit ;
-~~~~~~~~
+~~~~
#### Character and string literals
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
char_lit : '\x27' char_body '\x27' ;
string_lit : '"' string_body * '"' | 'r' raw_string ;
@@ -260,7 +257,7 @@ hex_digit : 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
dec_digit : '0' | nonzero_dec ;
nonzero_dec: '1' | '2' | '3' | '4'
| '5' | '6' | '7' | '8' | '9' ;
-~~~~~~~~
+~~~~
A _character literal_ is a single Unicode character enclosed within two
`U+0027` (single-quote) characters, with the exception of `U+0027` itself,
@@ -305,7 +302,7 @@ many `U+0023` (`#`) characters as were used to start the raw string literal) or
Examples for string literals:
-~~~
+~~~~
"foo"; r"foo"; // foo
"\"foo\""; r#""foo""#; // "foo"
@@ -314,11 +311,11 @@ r##"foo #"# bar"##; // foo #"# bar
"\x52"; "R"; r"R"; // R
"\\x52"; r"\x52"; // \x52
-~~~
+~~~~
#### Number literals
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
num_lit : nonzero_dec [ dec_digit | '_' ] * num_suffix ?
| '0' [ [ dec_digit | '_' ] + num_suffix ?
@@ -335,7 +332,7 @@ 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 | '_' ] + ;
-~~~~~~~~
+~~~~
A _number literal_ is either an _integer literal_ or a _floating-point
literal_. The grammar for recognizing the two kinds of literals is mixed,
@@ -413,11 +410,11 @@ The two values of the boolean type are written `true` and `false`.
### Symbols
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
symbol : "::" "->"
| '#' | '[' | ']' | '(' | ')' | '{' | '}'
| ',' | ';' ;
-~~~~~~~~
+~~~~
Symbols are a general class of printable [token](#tokens) that play structural
roles in a variety of grammar productions. They are catalogued here for
@@ -428,8 +425,7 @@ operators](#binary-operator-expressions), or [keywords](#keywords).
## Paths
-~~~~~~~~ {.ebnf .gram}
-
+~~~~ {.ebnf .gram}
expr_path : ident [ "::" expr_path_tail ] + ;
expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'
| expr_path ;
@@ -437,8 +433,7 @@ expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'
type_path : ident [ type_path_tail ] + ;
type_path_tail : '<' type_expr [ ',' type_expr ] + '>'
| "::" type_path ;
-
-~~~~~~~~
+~~~~
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
@@ -451,7 +446,7 @@ across crates; an item's canonical path merely identifies it within the crate.
Two examples of simple paths consisting of only identifier components:
-~~~~{.ignore}
+~~~~ {.ignore}
x;
x::y::z;
~~~~
@@ -495,8 +490,7 @@ with values. `proto!` is an item, defining a new name.
## Macros
-~~~~~~~~ {.ebnf .gram}
-
+~~~~ {.ebnf .gram}
expr_macro_rules : "macro_rules" '!' ident '(' macro_rule * ')'
macro_rule : '(' matcher * ')' "=>" '(' transcriber * ')' ';'
matcher : '(' matcher * ')' | '[' matcher * ']'
@@ -507,8 +501,7 @@ transcriber : '(' transcriber * ')' | '[' transcriber * ']'
| '{' transcriber * '}' | '$' ident
| '$' '(' transcriber * ')' sep_token? [ '*' | '+' ]
| non_special_token
-
-~~~~~~~~
+~~~~
User-defined syntax extensions are called "macros",
and the `macro_rules` syntax extension defines them.
@@ -570,7 +563,6 @@ index operation and fail. Adding a separator can solve this problem.
2. The parser must have eliminated all ambiguity by the time it reaches a `$` _name_ `:` _designator_.
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.
-
## Syntax extensions useful for the macro author
* `log_syntax!` : print out the arguments at compile time
@@ -611,7 +603,7 @@ and may optionally begin with any number of `attributes` that apply to the conta
Attributes on the anonymous crate module define important metadata that influences
the behavior of the compiler.
-~~~~~~~~
+~~~~
// Linkage attributes
#[ link(name = "projx",
vers = "2.5",
@@ -627,12 +619,11 @@ the behavior of the compiler.
// Turn on a warning
#[ warn(non_camel_case_types) ];
-~~~~~~~~
+~~~~
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.
-
# Items and attributes
Crates contain [items](#items),
@@ -640,10 +631,10 @@ each of which may have some number of [attributes](#attributes) attached to it.
## Items
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
item : mod_item | fn_item | type_item | struct_item | enum_item
| static_item | trait_item | impl_item | extern_block ;
-~~~~~~~~
+~~~~
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
@@ -688,10 +679,10 @@ That is, Rust has no notion of type abstraction: there are no first-class "foral
### Modules
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
mod_item : "mod" ident ( ';' | '{' mod '}' );
mod : [ view_item | item ] * ;
-~~~~~~~~
+~~~~
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
@@ -704,7 +695,7 @@ of modules making up a crate. Modules can nest arbitrarily.
An example of a module:
-~~~~~~~~
+~~~~
mod math {
type complex = (f64, f64);
fn sin(f: f64) -> f64 {
@@ -720,7 +711,7 @@ mod math {
# fail2!();
}
}
-~~~~~~~~
+~~~~
Modules and types share the same namespace.
Declaring a named type that has the same name as a module in scope is forbidden:
@@ -732,7 +723,7 @@ 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.
-~~~ {.xfail-test}
+~~~~ {.xfail-test}
// Load the `vec` module from `vec.rs`
mod vec;
@@ -740,25 +731,25 @@ mod task {
// Load the `local_data` module from `task/local_data.rs`
mod local_data;
}
-~~~
+~~~~
The directories and files used for loading external file modules can be influenced
with the `path` attribute.
-~~~ {.xfail-test}
+~~~~ {.xfail-test}
#[path = "task_files"]
mod task {
// Load the `local_data` module from `task_files/tls.rs`
#[path = "tls.rs"]
mod local_data;
}
-~~~
+~~~~
#### View items
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
view_item : extern_mod_decl | use_decl ;
-~~~~~~~~
+~~~~
A view item manages the namespace of a module.
View items do not define new items, but rather, simply change other items' visibility.
@@ -769,11 +760,11 @@ There are several kinds of view item:
##### Extern mod declarations
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
extern_mod_decl : "extern" "mod" ident [ '(' link_attrs ')' ] ? [ '=' string_lit ] ? ;
link_attrs : link_attr [ ',' link_attrs ] + ;
link_attr : ident '=' literal ;
-~~~~~~~~
+~~~~
An _`extern mod` declaration_ specifies a dependency on an external crate.
The external crate is then bound into the declaring scope
@@ -801,7 +792,7 @@ is that the name `a` should be taken as a reference to the crate whose absolute
Four examples of `extern mod` declarations:
-~~~~~~~~{.xfail-test}
+~~~~ {.xfail-test}
extern mod pcre (uuid = "54aba0f8-a7b1-4beb-92f1-4cf625264841");
extern mod extra; // equivalent to: extern mod extra ( name = "extra" );
@@ -809,18 +800,18 @@ extern mod extra; // equivalent to: extern mod extra ( name = "extra" );
extern mod rustextra (name = "extra"); // linking to 'extra' under another name
extern mod complicated_mod = "some-file/in/the-rust/path";
-~~~~~~~~
+~~~~
##### Use declarations
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
use_decl : "pub" ? "use" ident [ '=' path
| "::" path_glob ] ;
path_glob : ident [ "::" path_glob ] ?
| '*'
| '{' ident [ ',' ident ] * '}'
-~~~~~~~~
+~~~~
A _use declaration_ creates one or more local name bindings synonymous
with some other [path](#paths).
@@ -940,9 +931,9 @@ fn add(x: int, y: int) -> int {
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.
-~~~
+~~~~
fn first((value, _): (int, int)) -> int { value }
-~~~
+~~~~
#### Generic functions
@@ -1117,22 +1108,22 @@ 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.
-~~~
+~~~~
// Declares an extern fn, the ABI defaults to "C"
extern fn new_vec() -> ~[int] { ~[] }
// Declares an extern fn with "stdcall" ABI
extern "stdcall" fn new_vec_stdcall() -> ~[int] { ~[] }
-~~~
+~~~~
Unlike normal functions, extern fns have an `extern "ABI" fn()`.
This is the same type as the functions declared in an extern
block.
-~~~
+~~~~
# extern fn new_vec() -> ~[int] { ~[] }
let fptr: extern "C" fn() -> ~[int] = new_vec;
-~~~
+~~~~
Extern functions may be called from Rust code, but
caution must be taken with respect to the size of the stack
@@ -1218,9 +1209,9 @@ whereas `Dog` is simply called an enum variant.
### Static items
-~~~~~~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
static_item : "static" ident ':' type '=' expr ';' ;
-~~~~~~~~
+~~~~
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.
@@ -1265,7 +1256,7 @@ running in the same process.
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).
-~~~
+~~~~
# fn atomic_add(_: &mut uint, _: uint) -> uint { 2 }
static mut LEVELS: uint = 0;
@@ -1284,8 +1275,7 @@ unsafe fn bump_levels_unsafe1() -> uint {
unsafe fn bump_levels_unsafe2() -> uint {
return atomic_add(&mut LEVELS, 1);
}
-
-~~~
+~~~~
### Traits
@@ -1392,18 +1382,18 @@ In type-parameterized functions,
methods of the supertrait may be called on values of subtrait-bound type parameters.
Referring to the previous example of `trait Circle : Shape`:
-~~~
+~~~~
# trait Shape { fn area(&self) -> f64; }
# trait Circle : Shape { fn radius(&self) -> f64; }
fn radius_times_area(c: T) -> f64 {
// `c` is both a Circle and a Shape
c.radius() * c.area()
}
-~~~
+~~~~
Likewise, supertrait methods may also be called on trait objects.
-~~~ {.xfail-test}
+~~~~ {.xfail-test}
# trait Shape { fn area(&self) -> f64; }
# trait Circle : Shape { fn radius(&self) -> f64; }
# impl Shape for int { fn area(&self) -> f64 { 0.0 } }
@@ -1412,7 +1402,7 @@ Likewise, supertrait methods may also be called on trait objects.
let mycircle: Circle = @mycircle as @Circle;
let nonsense = mycircle.radius() * mycircle.area();
-~~~
+~~~~
### Implementations
@@ -1470,10 +1460,10 @@ impl Seq for u32 {
### External blocks
-~~~ {.ebnf .gram}
+~~~~ {.ebnf .gram}
extern_block_item : "extern" '{' extern_block '} ;
extern_block : [ foreign_fn ] * ;
-~~~
+~~~~
External blocks form the basis for Rust's foreign function interface.
Declarations in an external block describe symbols
@@ -1484,14 +1474,14 @@ 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.
-~~~
+~~~~
# use std::libc::{c_char, FILE};
# #[nolink]
extern {
fn fopen(filename: *c_char, mode: *c_char) -> *FILE;
}
-~~~
+~~~~
Functions within external blocks may be called by Rust code,
just like functions defined in Rust.
@@ -1505,17 +1495,17 @@ By default external blocks assume that the library they are calling
uses the standard C "cdecl" ABI. Other ABIs may be specified using
an `abi` string, as shown here:
-~~~{.xfail-test}
+~~~~ {.xfail-test}
// Interface to the Windows API
extern "stdcall" { }
-~~~
+~~~~
The `link_name` attribute allows the name of the library to be specified.
-~~~{.xfail-test}
+~~~~ {.xfail-test}
#[link_name = "crypto"]
extern { }
-~~~
+~~~~
The `nolink` attribute tells the Rust compiler
not to do any linking for the external block.
@@ -1553,7 +1543,7 @@ allowed to alter this default visibility with the `pub` keyword (or `priv`
keyword for struct fields and enum variants). When an item is declared as `pub`,
it can be thought of as being accessible to the outside world. For example:
-~~~
+~~~~
// Declare a private struct
struct Foo;
@@ -1567,7 +1557,7 @@ pub enum State {
PubliclyAccessibleState,
priv PrivatelyAccessibleState
}
-~~~
+~~~~
With the notion of an item being either public or private, Rust allows item
accesses in two cases:
@@ -1609,7 +1599,7 @@ scope.
Here's an example of a program which exemplifies the three cases outlined above.
-~~~
+~~~~
// This module is private, meaning that no external crate can access this
// module. Because it is private at the root of this current crate, however, any
// module in the crate may access any publicly visible item in this module.
@@ -1657,7 +1647,7 @@ pub mod submodule {
}
# fn main() {}
-~~~
+~~~~
For a rust program to pass the privacy checking pass, all paths must be valid
accesses given the two rules above. This includes all use statements,
@@ -1670,7 +1660,7 @@ this is a public directive, this allows the item to be used in the current
module through the rules above. It essentially allows public access into the
re-exported item. For example, this program is valid:
-~~~
+~~~~
pub use api = self::implementation;
mod implementation {
@@ -1678,7 +1668,7 @@ mod implementation {
}
# fn main() {}
-~~~
+~~~~
This means that any external crate referencing `implementation::f` would receive
a privacy violation, while the path `api::f` would be allowed.
@@ -1699,12 +1689,12 @@ import public items from their destination, not private items.
## Attributes
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
attribute : '#' '[' attr_list ']' ;
attr_list : attr [ ',' attr_list ]*
attr : ident [ '=' literal
| '(' attr_list ')' ] ? ;
-~~~~~~~~
+~~~~
Static entities in Rust -- crates, modules and items -- may have _attributes_
applied to them. ^[Attributes in Rust are modeled on Attributes in ECMA-335,
@@ -1721,7 +1711,7 @@ within. Attributes that are not terminated by a semi-colon apply to the next ent
An example of attributes:
-~~~~~~~~{.xfail-test}
+~~~~ {.xfail-test}
// General metadata applied to the enclosing module or crate.
#[license = "BSD"];
@@ -1740,7 +1730,7 @@ mod bar {
// A lint attribute used to suppress a warning/error
#[allow(non_camel_case_types)]
pub type int8_t = i8;
-~~~~~~~~
+~~~~
> **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.
@@ -1779,7 +1769,7 @@ For any lint check `C`:
The lint checks supported by the compiler can be found via `rustc -W help`,
along with their default settings.
-~~~{.xfail-test}
+~~~~ {.xfail-test}
mod m1 {
// Missing documentation is ignored here
#[allow(missing_doc)]
@@ -1793,12 +1783,12 @@ mod m1 {
#[deny(missing_doc)]
pub fn undocumented_end() -> int { 3 }
}
-~~~
+~~~~
This example shows how one can use `allow` and `warn` to toggle
a particular check on and off.
-~~~{.xfail-test}
+~~~~ {.xfail-test}
#[warn(missing_doc)]
mod m2{
#[allow(missing_doc)]
@@ -1815,12 +1805,12 @@ mod m2{
// Missing documentation signals a warning here
pub fn undocumented_too() -> int { 3 }
}
-~~~
+~~~~
This example shows how one can use `forbid` to disallow uses
of `allow` for that lint check.
-~~~{.xfail-test}
+~~~~ {.xfail-test}
#[forbid(missing_doc)]
mod m3 {
// Attempting to toggle warning signals an error here
@@ -1828,7 +1818,7 @@ mod m3 {
/// Returns 2.
pub fn undocumented_too() -> int { 2 }
}
-~~~
+~~~~
### Language items
@@ -1838,12 +1828,12 @@ 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:
-~~~ {.xfail-test}
+~~~~ {.xfail-test}
#[lang="str_eq"]
pub fn eq_slice(a: &str, b: &str) -> bool {
// details elided
}
-~~~
+~~~~
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
@@ -1935,17 +1925,17 @@ 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`:
-~~~
+~~~~
#[deriving(Eq, Clone)]
struct Foo {
a: int,
b: T
}
-~~~
+~~~~
The generated `impl` for `Eq` is equivalent to
-~~~
+~~~~
# struct Foo { a: int, b: T }
impl Eq for Foo {
fn eq(&self, other: &Foo) -> bool {
@@ -1956,7 +1946,7 @@ impl Eq for Foo {
self.a != other.a || self.b != other.b
}
}
-~~~
+~~~~
Supported traits for `deriving` are:
@@ -1999,7 +1989,7 @@ by default. Items with not marked with a stability are considered to
be unstable for the purposes of the lint. One can give an optional
string that will be displayed when the lint flags the use of an item.
-~~~ {.xfail-test}
+~~~~ {.xfail-test}
#[warn(unstable)];
#[deprecated="replaced by `best`"]
@@ -2023,7 +2013,7 @@ fn main() {
best(); // no warning
}
-~~~
+~~~~
> **Note:** Currently these are only checked when applied to
> individual functions, structs, methods and enum variants, *not* to
@@ -2038,9 +2028,9 @@ considered a full-fleged language feature.
For this reason, rust recognizes a special crate-level attribute of the form:
-~~~ {.xfail-test}
+~~~~ {.xfail-test}
#[feature(feature1, feature2, feature3)]
-~~~
+~~~~
This directive informs the compiler that the feature list: `feature1`,
`feature2`, and `feature3` should all be enabled. This is only recognized at a
@@ -2123,13 +2113,12 @@ declaring the item outside the statement block.
Note: there is no implicit capture of the function's dynamic environment when
declaring a function-local item.
-
#### Slot declarations
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
init : [ '=' ] expr ;
-~~~~~~~~
+~~~~
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.
@@ -2194,19 +2183,18 @@ or values that implement the special trait `Drop`,
the variable is moved.
All other types are copied.
-
### Literal expressions
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.
-~~~~~~~~ {.literals}
+~~~~ {.literals}
(); // unit type
"hello"; // string type
'5'; // character type
5; // integer type
-~~~~~~~~
+~~~~
### Path expressions
@@ -2219,22 +2207,22 @@ Tuples are written by enclosing one or more comma-separated
expressions in parentheses. They are used to create [tuple-typed](#tuple-types)
values.
-~~~~~~~~ {.tuple}
+~~~~ {.tuple}
(0,);
(0.0, 4.5);
("a", 4u, true);
-~~~~~~~~
+~~~~
### Structure expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
struct_expr : expr_path '{' ident ':' expr
[ ',' ident ':' expr ] *
[ ".." expr ] '}' |
expr_path '(' expr
[ ',' expr ] * ')' |
expr_path
-~~~~~~~~
+~~~~
There are several forms of structure expressions.
A _structure expression_ consists of the [path](#paths) of a [structure item](#structures),
@@ -2281,38 +2269,37 @@ Point3d {y: 0, z: 10, .. base};
### Record expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
rec_expr : '{' ident ':' expr
[ ',' ident ':' expr ] *
[ ".." expr ] '}'
-~~~~~~~~
+~~~~
### Method-call expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
method_call_expr : expr '.' ident paren_expr_list ;
-~~~~~~~~
+~~~~
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).
-
### Field expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
field_expr : expr '.' ident
-~~~~~~~~
+~~~~
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).
-~~~~~~~~ {.field}
+~~~~ {.field}
myrecord.myfield;
{a: 10, b: 20}.a;
-~~~~~~~~
+~~~~
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.
@@ -2320,14 +2307,13 @@ When the field is mutable, it can be [assigned](#assignment-expressions) to.
When the type of the expression to the left of the dot is a pointer to a record or structure,
it is automatically dereferenced to make the field access possible.
-
### Vector expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
vec_expr : '[' "mut" ? vec_elems? ']'
vec_elems : [expr [',' expr]*] | [expr ',' ".." expr]
-~~~~~~~~
+~~~~
A [_vector_](#vector-types) _expression_ is written by enclosing zero or
more comma-separated expressions of uniform type in square brackets.
@@ -2345,10 +2331,9 @@ as a [literal](#literals) or a [static item](#static-items).
### Index expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
idx_expr : expr '[' expr ']'
-~~~~~~~~
-
+~~~~
[Vector](#vector-types)-typed expressions can be indexed by writing a
square-bracket-enclosed expression (the index) after them. When the
@@ -2395,9 +2380,9 @@ before the expression they apply to.
### Binary operator expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
binop_expr : expr binop expr ;
-~~~~~~~~
+~~~~
Binary operators expressions are given in terms of
[operator precedence](#operator-precedence).
@@ -2484,7 +2469,6 @@ The default meaning of the operators on standard types is given here.
: Greater than or equal.
Calls the `ge` method on the `std::cmp::Ord` trait.
-
#### Type cast expressions
A type cast expression is denoted with the binary operator `as`.
@@ -2561,9 +2545,9 @@ 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.
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
paren_expr : '(' expr ')' ;
-~~~~~~~~
+~~~~
An example of a parenthesized expression:
@@ -2574,11 +2558,11 @@ let x = (2 + 3) * 4;
### Call expressions
-~~~~~~~~ {.abnf .gram}
+~~~~ {.abnf .gram}
expr_list : [ expr [ ',' expr ]* ] ? ;
paren_expr_list : '(' expr_list ')' ;
call_expr : expr paren_expr_list ;
-~~~~~~~~
+~~~~
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
@@ -2597,10 +2581,10 @@ let pi: Option = FromStr::from_str("3.14");
### Lambda expressions
-~~~~~~~~ {.abnf .gram}
+~~~~ {.abnf .gram}
ident_list : [ ident [ ',' ident ]* ] ? ;
lambda_expr : '|' ident_list '|' expr ;
-~~~~~~~~
+~~~~
A _lambda expression_ (sometimes called an "anonymous function expression") defines a function and denotes it as a value,
in a single expression.
@@ -2636,14 +2620,13 @@ fn ten_times(f: &fn(int)) {
}
ten_times(|j| println!("hello, {}", j));
-
~~~~
### While loops
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
while_expr : "while" expr '{' block '}' ;
-~~~~~~~~
+~~~~
A `while` loop begins by evaluating the boolean loop conditional expression.
If the loop conditional expression evaluates to `true`, the loop body block
@@ -2667,9 +2650,9 @@ The keyword `loop` in Rust appears both in _loop expressions_ and in _continue e
A loop expression denotes an infinite loop;
see [Continue expressions](#continue-expressions) for continue expressions.
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
loop_expr : [ lifetime ':' ] "loop" '{' block '}';
-~~~~~~~~
+~~~~
A `loop` expression may optionally have a _label_.
If a label is present,
@@ -2678,9 +2661,9 @@ See [Break expressions](#break-expressions).
### Break expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
break_expr : "break" [ lifetime ];
-~~~~~~~~
+~~~~
A `break` expression has an optional `label`.
If the label is absent, then executing a `break` expression immediately terminates the innermost loop enclosing it.
@@ -2691,9 +2674,9 @@ but must enclose it.
### Continue expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
continue_expr : "loop" [ lifetime ];
-~~~~~~~~
+~~~~
A continue expression, written `loop`, also has an optional `label`.
If the label is absent,
@@ -2708,12 +2691,11 @@ but must enclose it.
A `loop` expression is only permitted in the body of a loop.
-
### Do expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
do_expr : "do" expr [ '|' ident_list '|' ] ? '{' block '}' ;
-~~~~~~~~
+~~~~
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.
@@ -2761,12 +2743,11 @@ do k(3) |j| {
}
~~~~
-
### For expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
for_expr : "for" pat "in" expr '{' block '}' ;
-~~~~~~~~
+~~~~
A `for` expression is a syntactic construct for looping
over elements provided by an implementation of
@@ -2799,13 +2780,13 @@ for i in range(0u, 256) {
### If expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
if_expr : "if" expr '{' block '}'
else_tail ? ;
else_tail : "else" [ if_expr
| '{' block '}' ] ;
-~~~~~~~~
+~~~~
An `if` expression is a conditional branch in program control. The form of
an `if` expression is a condition expression, followed by a consequent
@@ -2818,17 +2799,15 @@ 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.
-
### Match expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
match_expr : "match" expr '{' match_arm [ '|' match_arm ] * '}' ;
match_arm : match_pat '=>' [ expr "," | '{' block '}' ] ;
match_pat : pat [ ".." pat ] ? [ "if" expr ] ;
-~~~~~~~~
-
+~~~~
A `match` expression branches on a *pattern*. The exact form of matching that
occurs depends on the pattern. Patterns consist of some combination of
@@ -2866,7 +2845,6 @@ variables in the arm's block, and control enters the block.
An example of an `match` expression:
-
~~~~
# fn process_pair(a: int, b: int) { }
# fn process_ten() { }
@@ -2946,9 +2924,9 @@ let message = match maybe_digit {
### Return expressions
-~~~~~~~~{.ebnf .gram}
+~~~~ {.ebnf .gram}
return_expr : "return" expr ? ;
-~~~~~~~~
+~~~~
Return expressions are denoted with the keyword `return`. Evaluating a `return`
expression moves its argument into the output slot of the current
@@ -2966,7 +2944,6 @@ fn max(a: int, b: int) -> int {
}
~~~~
-
# Type system
## Types
@@ -2992,7 +2969,6 @@ The primitive types are the following:
The machine types are the following:
-
* 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.
@@ -3017,7 +2993,6 @@ 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.
-
### Textual types
The types `char` and `str` hold textual data.
@@ -3031,7 +3006,6 @@ 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`.
-
### Tuple types
The tuple type-constructor forms a new heterogeneous product of values similar
@@ -3056,7 +3030,6 @@ let (a, b) = p;
assert!(b != "world");
~~~~
-
### Vector types
The vector type constructor represents a homogeneous array of values of a given type.
@@ -3087,7 +3060,6 @@ assert!(i == 3);
All in-bounds elements of a vector are always initialized,
and access to a vector is always bounds-checked.
-
### Structure types
A `struct` *type* is a heterogeneous product of other types, called the *fields* of the type.
@@ -3127,7 +3099,6 @@ Any `enum` value consumes as much memory as the largest variant constructor for
Enum types cannot be denoted *structurally* as types,
but must be denoted by named reference to an [`enum` item](#enumerations).
-
### Recursive types
Nominal types -- [enumerations](#enumerated-types) and [structures](#structure-types) -- may be recursive.
@@ -3155,7 +3126,6 @@ enum List {
let a: List = Cons(7, @Cons(13, @Nil));
~~~~
-
### Pointer types
All pointers in Rust are explicit first-class values.
@@ -3204,7 +3174,6 @@ Raw pointers (`*`)
they exist to support interoperability with foreign code,
and writing performance-critical or low-level functions.
-
### Function types
The function type constructor `fn` forms new function types.
@@ -3213,7 +3182,7 @@ A function type consists of a possibly-empty set of function-type modifiers
An example of a `fn` type:
-~~~~~~~~
+~~~~
fn add(x: int, y: int) -> int {
return x + y;
}
@@ -3223,7 +3192,7 @@ let mut x = add(5,7);
type Binop<'self> = &'self fn(int,int) -> int;
let bo: Binop = add;
x = bo(5,7);
-~~~~~~~~
+~~~~
### Object types
@@ -3241,7 +3210,7 @@ the vtable pointer for the `T` implementation of `R`, and the pointer value of `
An example of an object type:
-~~~~~~~~
+~~~~
trait Printable {
fn to_string(&self) -> ~str;
}
@@ -3257,7 +3226,7 @@ fn print(a: @Printable) {
fn main() {
print(@10 as @Printable);
}
-~~~~~~~~
+~~~~
In this example, the trait `Printable` occurs as an object type in both the type signature of `print`,
and the cast expression in `main`.
@@ -3266,7 +3235,7 @@ and the cast expression in `main`.
Within the body of an item that has type parameter declarations, the names of its type parameters are types:
-~~~~~~~
+~~~~
fn map(f: &fn(A) -> B, xs: &[A]) -> ~[B] {
if xs.len() == 0 {
return ~[];
@@ -3275,7 +3244,7 @@ fn map(f: &fn(A) -> B, xs: &[A]) -> ~[B] {
let rest: ~[B] = map(f, xs.slice(1, xs.len()));
return ~[first] + rest;
}
-~~~~~~~
+~~~~
Here, `first` has type `B`, referring to `map`'s `B` type parameter;
and `rest` has type `~[B]`, a vector type with element type `B`.
@@ -3286,7 +3255,7 @@ 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:
-~~~~~~~~
+~~~~
trait Printable {
fn make_string(&self) -> ~str;
}
@@ -3296,7 +3265,7 @@ impl Printable for ~str {
(*self).clone()
}
}
-~~~~~~~~
+~~~~
`self` refers to the value of type `~str` that is the receiver for a
call to the method `make_string`.
@@ -3374,7 +3343,6 @@ the heap may be shared between tasks, mutable portions may not.
Allocations in the stack consist of *slots*, and allocations in the heap
consist of *boxes*.
-
### Memory allocation and lifetime
The _items_ of a program are those functions, modules and types
@@ -3417,7 +3385,6 @@ unmanaged kinds of data.
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.
-
### Memory slots
A task's stack contains slots.
@@ -3444,7 +3411,6 @@ 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.
-
### Memory boxes
A _box_ is a reference to a heap allocation holding another value. There
@@ -3464,19 +3430,19 @@ Owned box values exist in 1:1 correspondence with their heap allocation.
An example of constructing one managed box type and value, and one owned box
type and value:
-~~~~~~~~
+~~~~
let x: @int = @10;
let x: ~int = ~10;
-~~~~~~~~
+~~~~
Some operations (such as field selection) implicitly dereference boxes. An
example of an _implicit dereference_ operation performed on box values:
-~~~~~~~~
+~~~~
struct Foo { y: int }
let x = @Foo{y: 10};
assert!(x.y == 10);
-~~~~~~~~
+~~~~
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
@@ -3487,10 +3453,9 @@ operations are:
* copying box values (`x = y`)
* passing box values to functions (`f(x,y)`)
-
An example of an explicit-dereference operation performed on box values:
-~~~~~~~~
+~~~~
fn takes_boxed(b: @int) {
}
@@ -3502,7 +3467,7 @@ fn main() {
takes_boxed(x);
takes_unboxed(*x);
}
-~~~~~~~~
+~~~~
## Tasks
@@ -3529,7 +3494,6 @@ 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.]
-
### Communication between tasks
Rust tasks are isolated and generally unable to interfere with one another's memory directly,
@@ -3549,7 +3513,6 @@ Restricting communication interfaces to this kind ensures that no borrowed or ma
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.
-
### Task lifecycle
The _lifecycle_ of a task consists of a finite set of states and events
@@ -3593,7 +3556,6 @@ 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.
-
### Task scheduling
The currently scheduled task is given a finite *time slice* in which to
@@ -3604,10 +3566,8 @@ 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.
-
# Runtime services, linkage and debugging
-
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
@@ -3637,8 +3597,6 @@ channels, tasks).
Support for other built-in types such as simple types, tuples, records, and
enums is open-coded by the Rust compiler.
-
-
### Task scheduling and communication
The runtime provides code to manage inter-task communication. This includes
@@ -3647,7 +3605,6 @@ 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.
-
### Logging system
The runtime contains a system for directing [logging
@@ -3710,14 +3667,14 @@ of runtime logging modules follows.
Rust provides several macros to log information. Here's a simple Rust program
that demonstrates all four of them:
-```rust
+~~~~
fn main() {
error2!("This is an error log")
warn2!("This is a warn log")
info2!("this is an info log")
debug2!("This is a debug log")
}
-```
+~~~~
These four log levels correspond to levels 1-4, as controlled by `RUST_LOG`:
@@ -3736,7 +3693,6 @@ this is an info log
## Influences
-
> 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
@@ -3745,7 +3701,6 @@ this is an info log
>
> — Joe Armstrong
-
> 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
@@ -3755,8 +3710,7 @@ this is an info log
> in isolation can be guaranteed to hold when that module is embedded in a
> system [...]
>
-> — Robert Strom and Shaula Yemini
-
+> — Robert Strom and Shaula Yemini
> Concurrent and applicative programming complement each other. The
> ability to send messages on channels provides I/O without side effects,
@@ -3765,7 +3719,6 @@ this is an info log
>
> — Rob Pike
-
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
diff --git a/doc/tutorial-tasks.md b/doc/tutorial-tasks.md
index dedbc8ae5931c..767f712a8d8c1 100644
--- a/doc/tutorial-tasks.md
+++ b/doc/tutorial-tasks.md
@@ -53,12 +53,12 @@ concurrency at this writing:
for safely sharing immutable data,
* [`extra::future`] - A type representing values that may be computed concurrently and retrieved at a later time.
-[`std::task`]: std/task.html
-[`std::comm`]: std/comm.html
-[`extra::comm`]: extra/comm.html
-[`extra::sync`]: extra/sync.html
-[`extra::arc`]: extra/arc.html
-[`extra::future`]: extra/future.html
+[`std::task`]: std/task/index.html
+[`std::comm`]: std/comm/index.html
+[`extra::comm`]: extra/comm/index.html
+[`extra::sync`]: extra/sync/index.html
+[`extra::arc`]: extra/arc/index.html
+[`extra::future`]: extra/future/index.html
# Basics
@@ -449,7 +449,7 @@ enum. If the child task terminates successfully, `try` will
return an `Ok` result; if the child task fails, `try` will return
an `Error` result.
-[`Result`]: std/result.html
+[`Result`]: std/result/index.html
> ***Note:*** A failed task does not currently produce a useful error
> value (`try` always returns `Err(())`). In the
diff --git a/doc/tutorial.md b/doc/tutorial.md
index 241e0367fefa4..51a2e6eb38420 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -1391,8 +1391,8 @@ Both vectors and strings support a number of useful
[methods](#methods), defined in [`std::vec`]
and [`std::str`]. Here are some examples.
-[`std::vec`]: std/vec.html
-[`std::str`]: std/str.html
+[`std::vec`]: std/vec/index.html
+[`std::str`]: std/str/index.html
~~~
# enum Crayon {
@@ -2966,30 +2966,30 @@ The full documentation for `std` can be found here: [standard library].
[standard library]: std/index.html
[`std`]: std/index.html
-[`bool`]: std/bool.html
-[tuples]: std/tuple.html
-[characters]: std/char.html
-[strings]: std/str.html
-[vectors]: std/vec.html
-[managed boxes]: std/managed.html
-[owned boxes]: std/owned.html
-[pointers]: std/ptr.html
-[`option`]: std/option.html
-[`result`]: std/result.html
-[task]: std/task.html
-[communication]: std/comm.html
-[`os`]: std/os.html
-[`path`]: std/path.html
-[`io`]: std/io.html
-[containers]: std/container.html
-[`hashmap`]: std/hashmap.html
-[`kinds`]: std/kinds.html
-[`ops`]: std/ops.html
-[`cmp`]: std/cmp.html
-[`num`]: std/num.html
-[`to_str`]: std/to_str.html
-[`clone`]: std/clone.html
-[`libc`]: std/libc.html
+[`bool`]: std/bool/index.html
+[tuples]: std/tuple/index.html
+[characters]: std/char/index.html
+[strings]: std/str/index.html
+[vectors]: std/vec/index.html
+[managed boxes]: std/managed/index.html
+[owned boxes]: std/owned/index.html
+[pointers]: std/ptr/index.html
+[`option`]: std/option/index.html
+[`result`]: std/result/index.html
+[task]: std/task/index.html
+[communication]: std/comm/index.html
+[`os`]: std/os/index.html
+[`path`]: std/path/index.html
+[`io`]: std/io/index.html
+[containers]: std/container/index.html
+[`hashmap`]: std/hashmap/index.html
+[`kinds`]: std/kinds/index.html
+[`ops`]: std/ops/index.html
+[`cmp`]: std/cmp/index.html
+[`num`]: std/num/index.html
+[`to_str`]: std/to_str/index.html
+[`clone`]: std/clone/index.html
+[`libc`]: std/libc/index.html
## The extra library
@@ -3012,8 +3012,8 @@ tutorials on individual topics.
* [Tasks and communication][tasks]
* [Macros][macros]
* [The foreign function interface][ffi]
-* [Containers and iterators](tutorial-container.html)
-* [Error-handling and Conditions](tutorial-conditions.html)
+* [Containers and iterators][container]
+* [Error-handling and Conditions][conditions]
* [Packaging up Rust code][rustpkg]
There is further documentation on the [wiki], however those tend to be even more out of date as this document.
@@ -3022,6 +3022,8 @@ There is further documentation on the [wiki], however those tend to be even more
[tasks]: tutorial-tasks.html
[macros]: tutorial-macros.html
[ffi]: tutorial-ffi.html
+[container]: tutorial-container.html
+[conditions]: tutorial-conditions.html
[rustpkg]: tutorial-rustpkg.html
[wiki]: https://github.com/mozilla/rust/wiki/Docs
diff --git a/doc/version_info.html.template b/doc/version_info.html.template
index aa44097a337e9..858e5a35f8741 100644
--- a/doc/version_info.html.template
+++ b/doc/version_info.html.template
@@ -1,9 +1,6 @@
-
