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/css/manual.inc b/doc/css/manual.inc
new file mode 100644
index 0000000000000..783679d0ea5fd
--- /dev/null
+++ b/doc/css/manual.inc
@@ -0,0 +1,7 @@
+
\ No newline at end of file
diff --git a/doc/css/rust.css b/doc/css/rust.css
new file mode 100644
index 0000000000000..69aeb397074dc
--- /dev/null
+++ b/doc/css/rust.css
@@ -0,0 +1,311 @@
+/**
+ * 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 {
+ 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;
+}
+@media (min-width: 768px) {
+ body {
+ max-width: 750px;
+ }
+}
+@media (min-width: 992px) {
+ body {
+ max-width: 970px;
+ }
+}
+@media (min-width: 1200px) {
+ body {
+ max-width: 1170px;
+ }
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: black;
+ font-weight: 500;
+ line-height: 1.1;
+}
+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: 18px;
+}
+h5 {
+ font-size: 16px;
+}
+h6 {
+ font-size: 14px;
+}
+
+p {
+ margin: 0 0 10px;
+}
+
+/* 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, 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;}
+.cm-s-default span.cm-atom {color: #219;}
+.cm-s-default span.cm-number {color: #164;}
+.cm-s-default span.cm-def {color: #00f;}
+.cm-s-default span.cm-variable {color: black;}
+.cm-s-default span.cm-variable-2 {color: #05a;}
+.cm-s-default span.cm-variable-3 {color: #085;}
+.cm-s-default span.cm-property {color: black;}
+.cm-s-default span.cm-operator {color: black;}
+.cm-s-default span.cm-comment {color: #a50;}
+.cm-s-default span.cm-string {color: #a11;}
+.cm-s-default span.cm-string-2 {color: #f50;}
+.cm-s-default span.cm-meta {color: #555;}
+.cm-s-default span.cm-error {color: #f00;}
+.cm-s-default span.cm-qualifier {color: #555;}
+.cm-s-default span.cm-builtin {color: #30a;}
+.cm-s-default span.cm-bracket {color: #cc7;}
+.cm-s-default span.cm-tag {color: #170;}
+.cm-s-default span.cm-attribute {color: #00c;}
+
+/* The rest
+ ========================================================================== */
+#versioninfo {
+ text-align: center;
+ margin: 0.5em;
+ font-size: 1.1em;
+}
+@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: 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;
+}
+blockquote small {
+ display: block;
+ line-height: 1.428571429;
+ color: #999;
+}
+
+/* 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;
+}
+/* Also for the benefit of the type table */
+td {
+ padding-right: 1em;
+}
+
+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-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;
+}
+
+div.section.level3 {
+ margin-left: 1em;
+}
+
+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/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/rust.css b/doc/rust.css
deleted file mode 100644
index ed9ea446aa87e..0000000000000
--- a/doc/rust.css
+++ /dev/null
@@ -1,156 +0,0 @@
-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;
-}
-
-h1 {
- font-size: 24pt;
- margin-top: 1.6em;
- padding-left: 0.4em;
- line-height: 1.6em;
- background-color:#FFF2CE;
- border-radius: 0.2em;
-}
-
-h2 {
- font-size: 16pt;
- margin-top: 1.6em;
- padding: 0.2em 0.5em;
- background-color:#FFF2CE;
- border-radius: 0.4em;
-}
-
-h2 code {
- color: #097334;
- font-size: 16pt;
-}
-
-h3 {
- font-size: 14pt;
- color: black;
- background-color:#D9E7FF;
- border-radius: 0.4em;
- padding: 0.2em 0.5em;
-}
-
-h3 code {
- color: #541800;
- font-size: 14pt;
- font-style: italic;
-}
-
-h4 {
- font-size: 11pt;
- margin-top: 0em;
- margin-bottom: 0em;
-}
-
-code {
- font-size: 11pt;
-}
-
-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);
-}
-
-pre.rust {
- background-color: #F3F6FF;
-}
-
-a, a:visited, a:link {
- text-decoration: none;
- color: rgb(0, 105, 214);
-}
-
-h1 a:link, h1 a:visited, h2 a:link, h2 a:visited,
-h3 a:link, h3 a:visited { color: black; }
-
-/* Code highlighting */
-.cm-s-default span.cm-keyword {color: #708;}
-.cm-s-default span.cm-atom {color: #219;}
-.cm-s-default span.cm-number {color: #164;}
-.cm-s-default span.cm-def {color: #00f;}
-.cm-s-default span.cm-variable {color: black;}
-.cm-s-default span.cm-variable-2 {color: #05a;}
-.cm-s-default span.cm-variable-3 {color: #085;}
-.cm-s-default span.cm-property {color: black;}
-.cm-s-default span.cm-operator {color: black;}
-.cm-s-default span.cm-comment {color: #a50;}
-.cm-s-default span.cm-string {color: #a11;}
-.cm-s-default span.cm-string-2 {color: #f50;}
-.cm-s-default span.cm-meta {color: #555;}
-.cm-s-default span.cm-error {color: #f00;}
-.cm-s-default span.cm-qualifier {color: #555;}
-.cm-s-default span.cm-builtin {color: #30a;}
-.cm-s-default span.cm-bracket {color: #cc7;}
-.cm-s-default span.cm-tag {color: #170;}
-.cm-s-default span.cm-attribute {color: #00c;}
-
-#versioninfo {
- position: fixed;
- bottom: 0px;
- right: 0px;
-
- background-color: white;
- padding: 0.5em;
-}
-
-a.lessimportant {
- color: gray;
- font-size: 60%;
-}
-
-blockquote {
- color: black;
- border-left: solid 1px silver;
- margin: 1em;
- padding: 0.5em 1em 0.5em 1em;
-}
-
-/* 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;
-}
-/* Also for the benefit of the type table */
-td {
- padding-right: 1em;
-}
-
-/* Only display one level of hierarchy in the TOC */
-#TOC ul ul {
- display: none;
-}
-
-#TOC ul {
- list-style: none;
- padding-left: 0px;
-}
-
-/* Adjust list alignment so rustdoc indexes don't align with blockquotes */
-div.index ul {
- padding-left: 1em;
-}
-
-ul {
- margin-top: 0em
-}
-
-div.section.level3 {
- margin-left: 1.0em;
-}
diff --git a/doc/rust.md b/doc/rust.md
index 621bf927e39fe..4a4a465e39920 100644
--- a/doc/rust.md
+++ b/doc/rust.md
@@ -61,7 +61,6 @@ dialect of EBNF supported by common automated LL(k) parsing tools such as
defined self-referentially as follows:
~~~~~~~~ {.ebnf .notation}
-
grammar : rule + ;
rule : nonterminal ':' productionrule ';' ;
productionrule : production [ '|' production ] * ;
@@ -69,7 +68,6 @@ production : term * ;
term : element repeats ;
element : LITERAL | IDENTIFIER | '[' productionrule ']' ;
repeats : [ '*' | '+' ] NUMBER ? | NUMBER ? | '?' ;
-
~~~~~~~~
Where:
@@ -305,7 +303,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,12 +312,11 @@ r##"foo #"# bar"##; // foo #"# bar
"\x52"; "R"; r"R"; // R
"\\x52"; r"\x52"; // \x52
-~~~
+~~~~~~~~
#### Number literals
~~~~~~~~ {.ebnf .gram}
-
num_lit : nonzero_dec [ dec_digit | '_' ] * num_suffix ?
| '0' [ [ dec_digit | '_' ] + num_suffix ?
| 'b' [ '1' | '0' | '_' ] + int_suffix ?
@@ -429,7 +426,6 @@ operators](#binary-operator-expressions), or [keywords](#keywords).
## Paths
~~~~~~~~ {.ebnf .gram}
-
expr_path : ident [ "::" expr_path_tail ] + ;
expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'
| expr_path ;
@@ -437,7 +433,6 @@ 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
@@ -496,7 +491,6 @@ with values. `proto!` is an item, defining a new name.
## Macros
~~~~~~~~ {.ebnf .gram}
-
expr_macro_rules : "macro_rules" '!' ident '(' macro_rule * ')'
macro_rule : '(' matcher * ')' "=>" '(' transcriber * ')' ';'
matcher : '(' matcher * ')' | '[' matcher * ']'
@@ -507,7 +501,6 @@ transcriber : '(' transcriber * ')' | '[' transcriber * ']'
| '{' transcriber * '}' | '$' ident
| '$' '(' transcriber * ')' sep_token? [ '*' | '+' ]
| non_special_token
-
~~~~~~~~
User-defined syntax extensions are called "macros",
@@ -839,7 +832,7 @@ Use declarations support a number of convenient shortcuts:
An example of `use` declarations:
-~~~~
+~~~~~~~~
use std::num::sin;
use std::option::{Some, None};
@@ -852,7 +845,7 @@ fn main() {
// Equivalent to 'foo(~[std::option::Some(1.0), std::option::None]);'
foo(~[Some(1.0), None]);
}
-~~~~
+~~~~~~~~
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.
@@ -863,7 +856,7 @@ If a sequence of such redirections form a cycle or cannot be resolved unambiguou
they represent a compile-time error.
An example of re-exporting:
-~~~~
+~~~~~~~~
# fn main() { }
mod quux {
pub use quux::foo::*;
@@ -873,7 +866,7 @@ mod quux {
pub fn baz() { }
}
}
-~~~~
+~~~~~~~~
In this example, the module `quux` re-exports all of the public names defined in `foo`.
@@ -886,7 +879,7 @@ All rules regarding accessing declared modules in `use` declarations applies to
and `extern mod` declarations.
An example of what will and will not work for `use` items:
-~~~~
+~~~~~~~~
# #[allow(unused_imports)];
use foo::extra; // good: foo is at the root of the crate
use foo::baz::foobaz; // good: foo is at the root of the crate
@@ -910,7 +903,7 @@ mod foo {
}
fn main() {}
-~~~~
+~~~~~~~~
### Functions
@@ -931,18 +924,18 @@ final-expression.
An example of a function:
-~~~~
+~~~~~~~~
fn add(x: int, y: int) -> int {
return x + y;
}
-~~~~
+~~~~~~~~
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
@@ -952,7 +945,7 @@ appear in its signature. Each type parameter must be explicitly
declared, in an angle-bracket-enclosed, comma-separated list following
the function name.
-~~~~ {.xfail-test}
+~~~~~~~~ {.xfail-test}
fn iter(seq: &[T], f: &fn(T)) {
for elt in seq.iter() { f(elt); }
}
@@ -961,7 +954,7 @@ fn map(seq: &[T], f: &fn(T) -> U) -> ~[U] {
for elt in seq.iter() { acc.push(f(elt)); }
acc
}
-~~~~
+~~~~~~~~
Inside the function signature and body, the name of the type parameter
can be used as a type name.
@@ -981,9 +974,9 @@ 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.
-~~~~
+~~~~~~~~
fn id(x: T) -> T { x }
-~~~~
+~~~~~~~~
Similarly, [trait](#traits) bounds can be specified for type
parameters to allow methods with that trait to be called on values
@@ -1066,12 +1059,12 @@ This is a list of behaviour not considered *unsafe* in Rust terms, but that may
A special kind of function can be declared with a `!` character where the
output slot type would normally be. For example:
-~~~~
+~~~~~~~~
fn my_err(s: &str) -> ! {
info2!("{}", s);
fail2!();
}
-~~~~
+~~~~~~~~
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
@@ -1086,7 +1079,7 @@ with a [`return`](#return-expressions) or diverging expression. So, if `my_err`
were declared without the `!` annotation, the following code would not
typecheck:
-~~~~
+~~~~~~~~
# fn my_err(s: &str) -> ! { fail2!() }
fn f(i: int) -> int {
@@ -1097,7 +1090,7 @@ fn f(i: int) -> int {
my_err("Bad number!");
}
}
-~~~~
+~~~~~~~~
This will not compile without the `!` annotation on `my_err`,
since the `else` branch of the conditional in `f` does not return an `int`,
@@ -1117,22 +1110,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
@@ -1159,29 +1152,29 @@ A _structure_ is a nominal [structure type](#structure-types) defined with the k
An example of a `struct` item and its use:
-~~~~
+~~~~~~~~
struct Point {x: int, y: int}
let p = Point {x: 10, y: 11};
let px: int = p.x;
-~~~~
+~~~~~~~~
A _tuple structure_ is a nominal [tuple type](#tuple-types), also defined with the keyword `struct`.
For example:
-~~~~
+~~~~~~~~
struct Point(int, int);
let p = Point(10, 11);
let px: int = match p { Point(x, _) => x };
-~~~~
+~~~~~~~~
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:
-~~~~
+~~~~~~~~
struct Cookie;
let c = [Cookie, Cookie, Cookie, Cookie];
-~~~~
+~~~~~~~~
### Enumerations
@@ -1192,7 +1185,7 @@ Enumerations are declared with the keyword `enum`.
An example of an `enum` item and its use:
-~~~~
+~~~~~~~~
enum Animal {
Dog,
Cat
@@ -1200,10 +1193,10 @@ enum Animal {
let mut a: Animal = Dog;
a = Cat;
-~~~~
+~~~~~~~~
Enumeration constructors can have either named or unnamed fields:
-~~~~
+~~~~~~~~
enum Animal {
Dog (~str, f64),
Cat { name: ~str, weight: f64 }
@@ -1211,7 +1204,7 @@ enum Animal {
let mut a: Animal = Dog(~"Cocoa", 37.2);
a = Cat{ name: ~"Spotty", weight: 2.7 };
-~~~~
+~~~~~~~~
In this example, `Cat` is a _struct-like enum variant_,
whereas `Dog` is simply called an enum variant.
@@ -1234,7 +1227,7 @@ The type may be ```bool```, ```char```, a number, or a type derived from those p
The derived types are borrowed pointers with the `'static` lifetime,
fixed-size arrays, tuples, and structs.
-~~~~
+~~~~~~~~
static BIT1: uint = 1 << 0;
static BIT2: uint = 1 << 1;
@@ -1250,7 +1243,7 @@ static bits_n_strings: BitsNStrings<'static> = BitsNStrings {
mybits: BITS,
mystring: STRING
};
-~~~~
+~~~~~~~~
#### Mutable statics
@@ -1265,13 +1258,13 @@ 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;
// This violates the idea of no shared state, and this doesn't internally
-// protect against races, so this function is `unsafe`
+// protect against races, so this function is `unsafe`.
unsafe fn bump_levels_unsafe1() -> uint {
let ret = LEVELS;
LEVELS += 1;
@@ -1280,12 +1273,11 @@ unsafe fn bump_levels_unsafe1() -> uint {
// Assuming that we have an atomic_add function which returns the old value,
// this function is "safe" but the meaning of the return value may not be what
-// callers expect, so it's still marked as `unsafe`
+// callers expect, so it's still marked as `unsafe`.
unsafe fn bump_levels_unsafe2() -> uint {
return atomic_add(&mut LEVELS, 1);
}
-
-~~~
+~~~~~~~~
### Traits
@@ -1298,7 +1290,7 @@ or constrained by some other trait.
Traits are implemented for specific types through separate [implementations](#implementations).
-~~~~
+~~~~~~~~
# type Surface = int;
# type BoundingBox = int;
@@ -1306,7 +1298,7 @@ trait Shape {
fn draw(&self, Surface);
fn bounding_box(&self) -> BoundingBox;
}
-~~~~
+~~~~~~~~
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,
@@ -1315,13 +1307,13 @@ using `value.bounding_box()` [syntax](#method-call-expressions).
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).
-~~~~
+~~~~~~~~
trait Seq {
fn len(&self) -> uint;
fn elt_at(&self, n: uint) -> T;
fn iter(&self, &fn(T));
}
-~~~~
+~~~~~~~~
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,
@@ -1329,7 +1321,7 @@ and within the generic function,
the methods of the trait can be called on values that have the parameter's type.
For example:
-~~~~
+~~~~~~~~
# type Surface = int;
# trait Shape { fn draw(&self, Surface); }
@@ -1337,20 +1329,20 @@ fn draw_twice(surface: Surface, sh: T) {
sh.draw(surface);
sh.draw(surface);
}
-~~~~
+~~~~~~~~
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.
-~~~~
+~~~~~~~~
# trait Shape { }
# impl Shape for int { }
# let mycircle = 0;
let myshape: @Shape = @mycircle as @Shape;
-~~~~
+~~~~~~~~
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.
@@ -1366,7 +1358,7 @@ The way to refer to the name of a static method is to qualify it with the trait
treating the trait name like a module.
For example:
-~~~~
+~~~~~~~~
trait Num {
fn from_int(n: int) -> Self;
}
@@ -1374,14 +1366,14 @@ impl Num for f64 {
fn from_int(n: int) -> f64 { n as f64 }
}
let x: f64 = Num::from_int(42);
-~~~~
+~~~~~~~~
Traits may inherit from other traits. For example, in
-~~~~
+~~~~~~~~
trait Shape { fn area() -> f64; }
trait Circle : Shape { fn radius() -> f64; }
-~~~~
+~~~~~~~~
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 { }`.
@@ -1392,18 +1384,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 +1404,7 @@ Likewise, supertrait methods may also be called on trait objects.
let mycircle: Circle = @mycircle as @Circle;
let nonsense = mycircle.radius() * mycircle.area();
-~~~
+~~~~~~~~
### Implementations
@@ -1420,7 +1412,7 @@ An _implementation_ is an item that implements a [trait](#traits) for a specific
Implementations are defined with the keyword `impl`.
-~~~~
+~~~~~~~~
# struct Point {x: f64, y: f64};
# type Surface = int;
# struct BoundingBox {x: f64, y: f64, width: f64, height: f64};
@@ -1440,7 +1432,7 @@ impl Shape for Circle {
width: 2.0 * r, height: 2.0 * r}
}
}
-~~~~
+~~~~~~~~
It is possible to define an implementation without referring to a trait.
The methods in such an implementation can only be used
@@ -1457,7 +1449,7 @@ 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.
-~~~~
+~~~~~~~~
# trait Seq { }
impl Seq for ~[T] {
@@ -1466,14 +1458,14 @@ impl Seq for ~[T] {
impl Seq for u32 {
/* Treat the integer as a sequence of bits */
}
-~~~~
+~~~~~~~~
### 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 +1476,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 +1497,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 +1545,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 +1559,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:
@@ -1606,13 +1598,13 @@ would mean that it is invoked.
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.
mod crate_helper_module {
- // This function can be used by anything in the current crate
+ // This function can be used by anything in the current crate.
pub fn crate_helper() {}
// This function *cannot* be used by anything else in the crate. It is not
@@ -1637,7 +1629,7 @@ pub mod submodule {
}
// This function is hidden to any module which is not a descendant of
- // `submodule`
+ // `submodule`.
fn my_implementation() {}
#[cfg(test)]
@@ -1654,7 +1646,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,
@@ -1667,7 +1659,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 {
@@ -1675,7 +1667,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.
@@ -1696,7 +1688,7 @@ 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
@@ -1718,7 +1710,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"];
@@ -1776,7 +1768,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)]
@@ -1790,12 +1782,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)]
@@ -1812,12 +1804,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
@@ -1825,7 +1817,7 @@ mod m3 {
/// Returns 2.
pub fn undocumented_too() -> int { 2 }
}
-~~~
+~~~~~~~~
### Language items
@@ -1835,12 +1827,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
@@ -1932,17 +1924,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 {
@@ -1953,7 +1945,7 @@ impl Eq for Foo {
self.a != other.a || self.b != other.b
}
}
-~~~
+~~~~~~~~
Supported traits for `deriving` are:
@@ -1996,7 +1988,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`"]
@@ -2020,7 +2012,7 @@ fn main() {
best(); // no warning
}
-~~~
+~~~~~~~~
> **Note:** Currently these are only checked when applied to
> individual functions, structs, methods and enum variants, *not* to
@@ -2035,9 +2027,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,7 +2115,7 @@ declaring a function-local item.
#### Slot declarations
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
let_decl : "let" pat [':' type ] ? [ init ] ? ';' ;
init : [ '=' ] expr ;
~~~~~~~~
@@ -2224,7 +2216,7 @@ values.
### Structure expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
struct_expr : expr_path '{' ident ':' expr
[ ',' ident ':' expr ] *
[ ".." expr ] '}' |
@@ -2249,7 +2241,7 @@ A _unit-like structure expression_ consists only of the [path](#paths) of a [str
The following are examples of structure expressions:
-~~~~
+~~~~~~~~
# struct Point { x: f64, y: f64 }
# struct TuplePoint(f64, f64);
# mod game { pub struct User<'self> { name: &'self str, age: uint, score: uint } }
@@ -2258,7 +2250,7 @@ Point {x: 10.0, y: 20.0};
TuplePoint(10.0, 20.0);
let u = game::User {name: "Joe", age: 35, score: 100_000};
some_fn::(Cookie);
-~~~~
+~~~~~~~~
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.
@@ -2270,15 +2262,15 @@ The entire expression denotes the result of allocating a new structure
with the given values for the fields that were explicitly specified
and the values in the base record for all other fields.
-~~~~
+~~~~~~~~
# struct Point3d { x: int, y: int, z: int }
let base = Point3d {x: 1, y: 2, z: 3};
Point3d {y: 0, z: 10, .. base};
-~~~~
+~~~~~~~~
### Record expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
rec_expr : '{' ident ':' expr
[ ',' ident ':' expr ] *
[ ".." expr ] '}'
@@ -2286,7 +2278,7 @@ rec_expr : '{' ident ':' expr
### Method-call expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
method_call_expr : expr '.' ident paren_expr_list ;
~~~~~~~~
@@ -2298,7 +2290,7 @@ or dynamically dispatching if the left-hand-side expression is an indirect [obje
### Field expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
field_expr : expr '.' ident
~~~~~~~~
@@ -2320,7 +2312,7 @@ 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]
@@ -2342,7 +2334,7 @@ as a [literal](#literals) or a [static item](#static-items).
### Index expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
idx_expr : expr '[' expr ']'
~~~~~~~~
@@ -2355,7 +2347,7 @@ 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_.
-~~~~
+~~~~~~~~
# use std::task;
# do task::spawn_unlinked {
@@ -2363,7 +2355,7 @@ task in a _failing state_.
(["a", "b"])[10]; // fails
# }
-~~~~
+~~~~~~~~
### Unary operator expressions
@@ -2392,7 +2384,7 @@ before the expression they apply to.
### Binary operator expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
binop_expr : expr binop expr ;
~~~~~~~~
@@ -2495,7 +2487,7 @@ Any other cast is unsupported and will fail to compile.
An example of an `as` expression:
-~~~~
+~~~~~~~~
# fn sum(v: &[f64]) -> f64 { 0.0 }
# fn len(v: &[f64]) -> int { 0 }
@@ -2504,7 +2496,7 @@ fn avg(v: &[f64]) -> f64 {
let sz: f64 = len(v) as f64;
return sum / sz;
}
-~~~~
+~~~~~~~~
#### Assignment expressions
@@ -2513,12 +2505,12 @@ equals sign (`=`) and an [rvalue](#lvalues-rvalues-and-temporaries) expression.
Evaluating an assignment expression [either copies or moves](#moved-and-copied-types) its right-hand operand to its left-hand operand.
-~~~~
+~~~~~~~~
# let mut x = 0;
# let y = 0;
x = y;
-~~~~
+~~~~~~~~
#### Compound assignment expressions
@@ -2534,7 +2526,7 @@ Any such expression always has the [`unit`](#primitive-types) type.
The precedence of Rust binary operators is ordered as follows, going
from strong to weak:
-~~~~ {.precedence}
+~~~~~~~~ {.precedence}
* / %
as
+ -
@@ -2547,7 +2539,7 @@ as
&&
||
=
-~~~~
+~~~~~~~~
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'.
@@ -2558,15 +2550,15 @@ 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:
-~~~~
+~~~~~~~~
let x = (2 + 3) * 4;
-~~~~
+~~~~~~~~
### Call expressions
@@ -2584,13 +2576,13 @@ then the expression completes.
Some examples of call expressions:
-~~~~
+~~~~~~~~
# use std::from_str::FromStr;
# fn add(x: int, y: int) -> int { 0 }
let x: int = add(1, 2);
let pi: Option = FromStr::from_str("3.14");
-~~~~
+~~~~~~~~
### Lambda expressions
@@ -2623,7 +2615,7 @@ from the environment into the lambda expression's captured environment.
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.
-~~~~
+~~~~~~~~
fn ten_times(f: &fn(int)) {
let mut i = 0;
while i < 10 {
@@ -2633,12 +2625,11 @@ fn ten_times(f: &fn(int)) {
}
ten_times(|j| println!("hello, {}", j));
-
-~~~~
+~~~~~~~~
### While loops
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
while_expr : "while" expr '{' block '}' ;
~~~~~~~~
@@ -2649,14 +2640,14 @@ conditional expression evaluates to `false`, the `while` expression completes.
An example:
-~~~~
+~~~~~~~~
let mut i = 0;
while i < 10 {
println("hello\n");
i = i + 1;
}
-~~~~
+~~~~~~~~
### Infinite loops
@@ -2664,7 +2655,7 @@ 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 '}';
~~~~~~~~
@@ -2675,7 +2666,7 @@ See [Break expressions](#break-expressions).
### Break expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
break_expr : "break" [ lifetime ];
~~~~~~~~
@@ -2688,7 +2679,7 @@ but must enclose it.
### Continue expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
continue_expr : "loop" [ lifetime ];
~~~~~~~~
@@ -2708,7 +2699,7 @@ 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 '}' ;
~~~~~~~~
@@ -2734,7 +2725,7 @@ If the `expr` is a [field expression](#field-expressions), it is parsed as thoug
In this example, both calls to `f` are equivalent:
-~~~~
+~~~~~~~~
# fn f(f: &fn(int)) { }
# fn g(i: int) { }
@@ -2743,11 +2734,11 @@ f(|j| g(j));
do f |j| {
g(j);
}
-~~~~
+~~~~~~~~
In this example, both calls to the (binary) function `k` are equivalent:
-~~~~
+~~~~~~~~
# fn k(x:int, f: &fn(int)) { }
# fn l(i: int) { }
@@ -2756,12 +2747,12 @@ k(3, |j| l(j));
do k(3) |j| {
l(j);
}
-~~~~
+~~~~~~~~
### For expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
for_expr : "for" pat "in" expr '{' block '}' ;
~~~~~~~~
@@ -2771,7 +2762,7 @@ over elements provided by an implementation of
An example of a for loop over the contents of a vector:
-~~~~
+~~~~~~~~
# type foo = int;
# fn bar(f: foo) { }
# let a = 0;
@@ -2783,20 +2774,20 @@ let v: &[foo] = &[a, b, c];
for e in v.iter() {
bar(*e);
}
-~~~~
+~~~~~~~~
An example of a for loop over a series of integers:
-~~~~
+~~~~~~~~
# fn bar(b:uint) { }
for i in range(0u, 256) {
bar(i);
}
-~~~~
+~~~~~~~~
### If expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
if_expr : "if" expr '{' block '}'
else_tail ? ;
@@ -2818,7 +2809,7 @@ 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 '}' ] ;
@@ -2838,7 +2829,7 @@ In a pattern whose head expression has an `enum` type, a placeholder (`_`) stand
*single* data field, whereas a wildcard `*` stands for *all* the fields of a particular
variant. For example:
-~~~~
+~~~~~~~~
enum List { Nil, Cons(X, @List) }
let x: List = Cons(10, @Cons(11, @Nil));
@@ -2848,7 +2839,7 @@ match x {
Cons(*) => return,
Nil => fail2!("empty list")
}
-~~~~
+~~~~~~~~
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`,
@@ -2863,8 +2854,7 @@ 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() { }
@@ -2886,7 +2876,7 @@ match x {
fail2!();
}
}
-~~~~
+~~~~~~~~
Patterns that bind variables
default to binding to a copy or move of the matched value
@@ -2910,7 +2900,7 @@ Multiple match patterns may be joined with the `|` operator.
A range of values may be specified with `..`.
For example:
-~~~~
+~~~~~~~~
# let x = 2;
let message = match x {
@@ -2918,7 +2908,7 @@ let message = match x {
2 .. 9 => "a few",
_ => "lots"
};
-~~~~
+~~~~~~~~
Range patterns only work on scalar types
(like integers and characters; not like vectors and structs, which have sub-components).
@@ -2929,7 +2919,7 @@ 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.
-~~~~
+~~~~~~~~
# let maybe_digit = Some(0);
# fn process_digit(i: int) { }
# fn process_other(i: int) { }
@@ -2939,11 +2929,11 @@ let message = match maybe_digit {
Some(x) => process_other(x),
None => fail2!()
};
-~~~~
+~~~~~~~~
### Return expressions
-~~~~~~~~{.ebnf .gram}
+~~~~~~~~ {.ebnf .gram}
return_expr : "return" expr ? ;
~~~~~~~~
@@ -2954,15 +2944,14 @@ control to the caller frame.
An example of a `return` expression:
-~~~~
+~~~~~~~~
fn max(a: int, b: int) -> int {
if a > b {
return a;
}
return b;
}
-~~~~
-
+~~~~~~~~
# Type system
@@ -2989,7 +2978,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.
@@ -3014,7 +3002,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.
@@ -3028,7 +3015,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
@@ -3046,13 +3032,12 @@ order specified by the tuple type.
An example of a tuple type and its use:
-~~~~
+~~~~~~~~
type Pair<'self> = (int,&'self str);
let p: Pair<'static> = (10,"hello");
let (a, b) = p;
assert!(b != "world");
-~~~~
-
+~~~~~~~~
### Vector types
@@ -3075,16 +3060,15 @@ definite-sized vector contents into a distinct vector of indefinite size.
An example of a vector type and its use:
-~~~~
+~~~~~~~~
let v: &[int] = &[7, 5, 3];
let i: int = v[2];
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.
@@ -3143,15 +3127,14 @@ Such recursion has restrictions:
An example of a *recursive* type and its use:
-~~~~
+~~~~~~~~
enum List {
Nil,
Cons(T, @List)
}
let a: List = Cons(7, @Cons(13, @Nil));
-~~~~
-
+~~~~~~~~
### Pointer types
@@ -3201,7 +3184,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.
@@ -3263,7 +3245,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 ~[];
@@ -3272,7 +3254,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`.
@@ -3371,7 +3353,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
@@ -3414,7 +3395,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.
@@ -3441,7 +3421,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
@@ -3526,7 +3505,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,
@@ -3546,7 +3524,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
@@ -3590,7 +3567,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
@@ -3601,10 +3577,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
@@ -3634,8 +3608,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
@@ -3644,7 +3616,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
@@ -3707,14 +3678,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`:
@@ -3733,15 +3704,13 @@ 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
> 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
-
+> — Joe Armstrong
> In our approach, all data is private to some process, and processes can
> only communicate through communications channels. *Security*, as used
@@ -3752,16 +3721,14 @@ 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,
> while the avoidance of shared data helps keep concurrent processes from
> colliding.
>
-> — Rob Pike
-
+> — 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
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 @@
-
