From 5b10f4e117479afbf1cd69e471e4a63995187db5 Mon Sep 17 00:00:00 2001 From: "Felix S. Klock II" Date: Mon, 25 Mar 2013 15:21:02 +0100 Subject: [PATCH 1/5] Miscellaneous documentation additions. Added notes explaining how [expr, ..expr] form is used, targeted at individuals like me who thought it was more general and handled dynamic repeat expressions. (I left a TODO for this section in a comment, but perhaps that is bad form for the manual...) Added example of `do` syntax with a function of arity > 1; yes, one should be able to derive this from the text above it, but it is still a useful detail to compare and contrast against the arity == 1 case. Added example of using for expression over a uint range, since someone who is most used to write `for(int i; i < lim; i++) { ... }` will likely want to know how to translate that form (regardless of whether it happens to be good style or not for their use-case). Added note about the semi-strange meaning of "fixed size" of vectors in the vector type section. --- doc/rust.md | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/doc/rust.md b/doc/rust.md index 60a83662b0e4c..3dca649807f42 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -1671,6 +1671,12 @@ 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. +In the `[expr ',' ".." expr]` form, the expression after the `".."` +must be an expression form that can be evaluated at compile time, such +as a [literal](#literals) or a [constant](#constants). + + + ~~~~ [1, 2, 3, 4]; ["a", "b", "c", "d"]; @@ -2156,6 +2162,19 @@ do f |j| { } ~~~~ +In this example, both calls to the (binary) function `k` are equivalent: + +~~~~ +# fn k(x:int, f: &fn(int)) { } +# fn l(i: int) { } + +k(3, |j| l(j)); + +do k(3) |j| { + l(j); +} +~~~~ + ### For expressions @@ -2184,7 +2203,7 @@ and early boolean-valued returns from the `block` function, such that the meaning of `break` and `loop` is preserved in a primitive loop when rewritten as a `for` loop controlled by a higher order function. -An example a for loop: +An example of a for loop over the contents of a vector: ~~~~ # type foo = int; @@ -2198,6 +2217,14 @@ for v.each |e| { } ~~~~ +An example of a for loop over a series of integers: + +~~~~ +# fn bar(b:uint) { } +for uint::range(0, 256) |i| { + bar(i); +} +~~~~ ### If expressions @@ -2474,6 +2501,7 @@ fail_unless!(b != "world"); The vector type constructor represents a homogeneous array of values of a given type. A vector has a fixed size. +(Operations like `vec::push` operate solely on owned vectors.) A vector type can be annotated with a _definite_ size, written with a trailing asterisk and integer literal, such as `[int * 10]`. Such a definite-sized vector type is a first-class type, since its size is known statically. @@ -2484,6 +2512,10 @@ such as `&[T]`, `@[T]` or `~[T]`. The kind of a vector type depends on the kind of its element type, as with other simple structural types. +Expressions producing vectors of definite size cannot be evaluated in a +context expecting a vector of indefinite size; one must copy the +definite-sized vector contents into a distinct vector of indefinite size. + An example of a vector type and its use: ~~~~ From a266bda393ecbea53a040763eb94afe57a259a7c Mon Sep 17 00:00:00 2001 From: "Felix S. Klock II" Date: Mon, 25 Mar 2013 15:22:19 +0100 Subject: [PATCH 2/5] Fixes mozilla/rust#3612. --- src/libcore/iter.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index f94c62d23ece3..58a514dc0eeeb 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -284,7 +284,8 @@ pub fn build_sized_opt>(size: Option, // Functions that combine iteration and building -/// Applies a function to each element of an iterable and returns the results. +/// Applies a function to each element of an iterable and returns the results +/// in a sequence built via `BU`. See also `map_to_vec`. #[inline(always)] pub fn map,U,BU: Buildable>(v: &IT, f: &fn(&T) -> U) -> BU { From afaa48cfb5e7d5bb5de706de44bf8ce4106af322 Mon Sep 17 00:00:00 2001 From: "Felix S. Klock II" Date: Mon, 25 Mar 2013 23:34:15 +0100 Subject: [PATCH 3/5] Spelling fixes; replaced `size` with `capacity` in few places. --- src/libcore/vec.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libcore/vec.rs b/src/libcore/vec.rs index 9def28fd3aa78..5c976756d137d 100644 --- a/src/libcore/vec.rs +++ b/src/libcore/vec.rs @@ -172,12 +172,12 @@ pub fn with_capacity(capacity: uint) -> ~[T] { /** * Builds a vector by calling a provided function with an argument * function that pushes an element to the back of a vector. - * This version takes an initial size for the vector. + * This version takes an initial capacity for the vector. * * # Arguments * * * size - An initial size of the vector to reserve - * * builder - A function that will construct the vector. It recieves + * * builder - A function that will construct the vector. It receives * as an argument a function that will push an element * onto the vector being constructed. */ @@ -194,7 +194,7 @@ pub fn build_sized(size: uint, builder: &fn(push: &fn(v: A))) -> ~[A] { * * # Arguments * - * * builder - A function that will construct the vector. It recieves + * * builder - A function that will construct the vector. It receives * as an argument a function that will push an element * onto the vector being constructed. */ From 7b6e90630e7c0a606c84d556556e2572a9137617 Mon Sep 17 00:00:00 2001 From: "Felix S. Klock II" Date: Mon, 11 Feb 2013 09:31:40 +0100 Subject: [PATCH 4/5] Cleanup wording around the awkward "and so on is . ." in the README.txt. --- src/librustc/README.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/librustc/README.txt b/src/librustc/README.txt index e61714c0dd277..9ac35aa444877 100644 --- a/src/librustc/README.txt +++ b/src/librustc/README.txt @@ -32,8 +32,8 @@ lib/ - bindings to LLVM The files concerned purely with syntax -- that is, the AST, parser, pretty-printer, lexer, macro expander, and utilities for traversing ASTs -- are in a separate crate called "syntax", whose files are in -./../libsyntax if the parent directory of front/, middle/, back/, and -so on is . . +./../libsyntax, where . is the current directory (that is, the parent +directory of front/, middle/, back/, and so on). The entry-point for the compiler is main() in driver/rustc.rs, and this file sequences the various parts together. From e1dccf9a7362d0537b92f6c642a00e3c716c7b60 Mon Sep 17 00:00:00 2001 From: "Felix S. Klock II" Date: Tue, 26 Mar 2013 14:36:01 +0100 Subject: [PATCH 5/5] Updated to reflect alpha-rename of constant/static items section. --- doc/rust.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/rust.md b/doc/rust.md index 3dca649807f42..3847b0b975583 100644 --- a/doc/rust.md +++ b/doc/rust.md @@ -1672,10 +1672,8 @@ A [_vector_](#vector-types) _expression_ is written by enclosing zero or more comma-separated expressions of uniform type in square brackets. In the `[expr ',' ".." expr]` form, the expression after the `".."` -must be an expression form that can be evaluated at compile time, such -as a [literal](#literals) or a [constant](#constants). - - +must be a constant expression that can be evaluated at compile time, such +as a [literal](#literals) or a [static item](#static-items). ~~~~ [1, 2, 3, 4];