From b2cac497e8989fb6d26c1f20441e8354950bbcc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20T=C3=A9tar?= Date: Fri, 17 Jan 2014 19:38:48 +0100 Subject: [PATCH 1/4] doc: fix version stamp for TeX files This fixes a regression introduced in 3d57b240ab1fd038b3a41fe2042dc9a0544ea53e. --- mk/docs.mk | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/mk/docs.mk b/mk/docs.mk index 71ea4ba44d177..bacf39e1307db 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -17,16 +17,16 @@ CDOCS := DOCS_L10N := HTML_DEPS := -BASE_DOC_OPTS := --include-before-body=doc/version_info.html --standalone \ - --toc --number-sections -HTML_OPTS = $(BASE_DOC_OPTS) --to=html5 --section-divs --css=rust.css \ - --include-in-header=doc/favicon.inc -TEX_OPTS = $(BASE_DOC_OPTS) --to=latex +BASE_DOC_OPTS := --standalone --toc --number-sections +HTML_OPTS = $(BASE_DOC_OPTS) --to=html5 --section-divs --css=rust.css \ + --include-before-body=doc/version_info.html --include-in-header=doc/favicon.inc +TEX_OPTS = $(BASE_DOC_OPTS) --include-before-body=doc/version.md --to=latex EPUB_OPTS = $(BASE_DOC_OPTS) --to=epub ###################################################################### # Rust version ###################################################################### + doc/version.md: $(MKFILE_DEPS) $(wildcard $(S)doc/*.*) @$(call E, version-stamp: $@) $(Q)echo "$(CFG_VERSION)" >$@ @@ -84,7 +84,7 @@ doc/rust.tex: rust.md doc/version.md $(CFG_PANDOC) $(TEX_OPTS) --output=$@ DOCS += doc/rust.epub -doc/rust.epub: rust.md doc/version_info.html doc/rust.css +doc/rust.epub: rust.md @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(EPUB_OPTS) --output=$@ @@ -114,7 +114,7 @@ doc/tutorial.tex: tutorial.md doc/version.md $(CFG_PANDOC) $(TEX_OPTS) --output=$@ DOCS += doc/tutorial.epub -doc/tutorial.epub: tutorial.md doc/version_info.html doc/rust.css +doc/tutorial.epub: tutorial.md @$(call E, pandoc: $@) $(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \ $(CFG_PANDOC) $(EPUB_OPTS) --output=$@ @@ -265,6 +265,7 @@ endif # No pandoc / node ###################################################################### # LLnextgen (grammar analysis from refman) ###################################################################### + ifeq ($(CFG_LLNEXTGEN),) $(info cfg: no llnextgen found, omitting grammar-verification) else From e33b1dabd35685e586f85f3e53783e31871bc5b7 Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Mon, 9 Dec 2013 22:14:43 -0800 Subject: [PATCH 2/4] Elaborate manual on matching (dereference patterns, lvalue/rvalue matching) Signed-off-by: Edward Z. Yang --- doc/rust.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index ad93964d6aa87..f955cbda9b83a 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -2893,12 +2893,21 @@ tail value of `~Nil`. The second pattern matches _any_ list constructed with `Co ignoring the values of its arguments. The difference between `_` and `*` is that the pattern `C(_)` is only type-correct if `C` has exactly one argument, while the pattern `C(..)` is type-correct for any enum variant `C`, regardless of how many arguments `C` has. -To execute an `match` expression, first the head expression is evaluated, then -its value is sequentially compared to the patterns in the arms until a match +A `match` behaves differently depending on whether or not the head expression +is an [lvalue or an rvalue](#lvalues-rvalues-and-temporaries). +If the head expression is an rvalue, it is +first evaluated into a temporary location, and the resulting value +is sequentially compared to the patterns in the arms until a match is found. The first arm with a matching pattern is chosen as the branch target of the `match`, any variables bound by the pattern are assigned to local variables in the arm's block, and control enters the block. +When the head expression is an lvalue, the match does not allocate a +temporary location (however, a by-value binding may copy or move from +the lvalue). When possible, it is preferable to match on lvalues, as the +lifetime of these matches inherits the lifetime of the lvalue, rather +than being restricted to the inside of the match. + An example of an `match` expression: ~~~~ @@ -2932,6 +2941,15 @@ This can be changed to bind to a reference by using the ```ref``` keyword, or to a mutable reference using ```ref mut```. +Patterns can also dereference pointers by using the ``&``, +``~`` or ``@`` symbols, as appropriate. For example, these two matches +on ``x: &int`` are equivalent: + +~~~~ +match *x { 0 => "zero", _ => "some" } +match x { &0 => "zero", _ => "some" } +~~~~ + A pattern that's just an identifier, like `Nil` in the previous answer, could either refer to an enum variant that's in scope, From 2c19f51d52b596987d27f9c1b3fb8b79424296d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20T=C3=A9tar?= Date: Fri, 17 Jan 2014 19:55:08 +0100 Subject: [PATCH 3/4] doc: fix rust.md fallout --- doc/rust.md | 46 +++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index f955cbda9b83a..ad85275105e92 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -2890,8 +2890,9 @@ match x { The first pattern matches lists constructed by applying `Cons` to any head value, and a tail value of `~Nil`. The second pattern matches _any_ list constructed with `Cons`, -ignoring the values of its arguments. The difference between `_` and `*` is that the pattern `C(_)` is only type-correct if -`C` has exactly one argument, while the pattern `C(..)` is type-correct for any enum variant `C`, regardless of how many arguments `C` has. +ignoring the values of its arguments. The difference between `_` and `*` is that the pattern +`C(_)` is only type-correct if `C` has exactly one argument, while the pattern `C(..)` is +type-correct for any enum variant `C`, regardless of how many arguments `C` has. A `match` behaves differently depending on whether or not the head expression is an [lvalue or an rvalue](#lvalues-rvalues-and-temporaries). @@ -2904,11 +2905,11 @@ variables in the arm's block, and control enters the block. When the head expression is an lvalue, the match does not allocate a temporary location (however, a by-value binding may copy or move from -the lvalue). When possible, it is preferable to match on lvalues, as the +the lvalue). When possible, it is preferable to match on lvalues, as the lifetime of these matches inherits the lifetime of the lvalue, rather than being restricted to the inside of the match. -An example of an `match` expression: +An example of a `match` expression: ~~~~ # fn process_pair(a: int, b: int) { } @@ -2938,28 +2939,31 @@ Patterns that bind variables default to binding to a copy or move of the matched value (depending on the matched value's type). This can be changed to bind to a reference by -using the ```ref``` keyword, -or to a mutable reference using ```ref mut```. +using the `ref` keyword, +or to a mutable reference using `ref mut`. -Patterns can also dereference pointers by using the ``&``, -``~`` or ``@`` symbols, as appropriate. For example, these two matches -on ``x: &int`` are equivalent: +Patterns can also dereference pointers by using the `&`, +`~` or `@` symbols, as appropriate. For example, these two matches +on `x: &int` are equivalent: ~~~~ -match *x { 0 => "zero", _ => "some" } -match x { &0 => "zero", _ => "some" } +# let x = &3; +let y = match *x { 0 => "zero", _ => "some" }; +let z = match x { &0 => "zero", _ => "some" }; + +assert_eq!(y, z); ~~~~ -A pattern that's just an identifier, -like `Nil` in the previous answer, -could either refer to an enum variant that's in scope, -or bind a new variable. -The compiler resolves this ambiguity by forbidding variable bindings that occur in ```match``` patterns from shadowing names of variants that are in scope. -For example, wherever ```List``` is in scope, -a ```match``` pattern would not be able to bind ```Nil``` as a new name. -The compiler interprets a variable pattern `x` as a binding _only_ if there is no variant named `x` in scope. -A convention you can use to avoid conflicts is simply to name variants with upper-case letters, -and local variables with lower-case letters. +A pattern that's just an identifier, like `Nil` in the previous answer, +could either refer to an enum variant that's in scope, or bind a new variable. +The compiler resolves this ambiguity by forbidding variable bindings that occur +in `match` patterns from shadowing names of variants that are in scope. +For example, wherever `List` is in scope, +a `match` pattern would not be able to bind `Nil` as a new name. +The compiler interprets a variable pattern `x` as a binding _only_ if there is +no variant named `x` in scope. +A convention you can use to avoid conflicts is simply to name variants with +upper-case letters, and local variables with lower-case letters. Multiple match patterns may be joined with the `|` operator. A range of values may be specified with `..`. From 14f605df21237d1a08d05dac2c964f08e8d21486 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20T=C3=A9tar?= Date: Fri, 17 Jan 2014 20:13:02 +0100 Subject: [PATCH 4/4] doc: fix dangling links in rust.md Fixes #11559 (not that the manual couldn't use a review). --- doc/rust.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index ad85275105e92..bf0e9dd090ae4 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -2211,12 +2211,9 @@ dereferences (`*expr`), [indexing expressions](#index-expressions) (`expr[expr]`), and [field references](#field-expressions) (`expr.f`). All other expressions are rvalues. -The left operand of an [assignment](#assignment-expressions), -[binary move](#binary-move-expressions) or +The left operand of an [assignment](#assignment-expressions) or [compound-assignment](#compound-assignment-expressions) expression is an lvalue context, -as is the single operand of a unary [borrow](#unary-operator-expressions), -or [move](#unary-move-expressions) expression, -and _both_ operands of a [swap](#swap-expressions) expression. +as is the single operand of a unary [borrow](#unary-operator-expressions). All other expression contexts are rvalue contexts. When an lvalue is evaluated in an _lvalue context_, it denotes a memory location; @@ -2229,9 +2226,8 @@ A temporary's lifetime equals the largest lifetime of any reference that points When a [local variable](#memory-slots) is used as an [rvalue](#lvalues-rvalues-and-temporaries) -the variable will either be [moved](#move-expressions) or copied, -depending on its type. -For types that contain [owning pointers](#owning-pointers) +the variable will either be moved or copied, depending on its type. +For types that contain [owning pointers](#pointer-types) or values that implement the special trait `Drop`, the variable is moved. All other types are copied. @@ -3144,19 +3140,20 @@ A `struct` *type* is a heterogeneous product of other types, called the *fields* the *record* types of the ML family, or the *structure* types of the Lisp family.] -New instances of a `struct` can be constructed with a [struct expression](#struct-expressions). +New instances of a `struct` can be constructed with a [struct expression](#structure-expressions). The memory order of fields in a `struct` is given by the item defining it. Fields may be given in any order in a corresponding struct *expression*; the resulting `struct` value will always be laid out in memory in the order specified by the corresponding *item*. -The fields of a `struct` may be qualified by [visibility modifiers](#visibility-modifiers), +The fields of a `struct` may be qualified by [visibility modifiers](#re-exporting-and-visibility), to restrict access to implementation-private data in a structure. A _tuple struct_ type is just like a structure type, except that the fields are anonymous. A _unit-like struct_ type is like a structure type, except that it has no fields. -The one value constructed by the associated [structure expression](#structure-expression) is the only value that inhabits such a type. +The one value constructed by the associated [structure expression](#structure-expressions) +is the only value that inhabits such a type. ### Enumerated types @@ -3827,7 +3824,7 @@ over the output format of a Rust crate. ### Logging system The runtime contains a system for directing [logging -expressions](#log-expressions) to a logging console and/or internal logging +expressions](#logging-expressions) to a logging console and/or internal logging buffers. Logging can be enabled per module. Logging output is enabled by setting the `RUST_LOG` environment