From 8b57cb90e50b600824c967470483462aeb663e50 Mon Sep 17 00:00:00 2001 From: Marijn Haverbeke Date: Tue, 1 Nov 2011 09:42:24 +0100 Subject: [PATCH] Clarify tutorial based on feedback, fix some Markdown errors --- doc/tutorial/control.md | 23 +++++++++++++++++++++-- doc/tutorial/data.md | 2 ++ doc/tutorial/setup.md | 4 +++- doc/tutorial/syntax.md | 23 +++++++++++++++-------- 4 files changed, 41 insertions(+), 11 deletions(-) diff --git a/doc/tutorial/control.md b/doc/tutorial/control.md index 9172cb7303f..9d6dd358fc4 100644 --- a/doc/tutorial/control.md +++ b/doc/tutorial/control.md @@ -94,8 +94,9 @@ extract the fields from a tuple: This will introduce two new variables, `a` and `b`, bound to the content of the tuple. -You may only use irrevocable patterns in let bindings, though. Things -like literals, which only match a specific value, are not allowed. +You may only use irrevocable patterns—patterns that can never fail to +match—in let bindings, though. Things like literals, which only match +a specific value, are not allowed. ## Loops @@ -114,6 +115,13 @@ to abort the current iteration and continue with the next. This code prints out a weird sequence of numbers and stops as soon as it finds one that can be divided by five. +There's also `while`'s ugly cousin, `do`/`while`, which does not check +its condition on the first iteration, using traditional syntax: + + do { + eat_cake(); + } while any_cake_left(); + When iterating over a vector, use `for` instead. for elt in ["red", "green", "blue"] { @@ -167,3 +175,14 @@ leave them in. For interactive debugging, you often want unconditional logging. For this, use `log_err` instead of `log` [FIXME better name]. + +## Assertions + +The keyword `assert`, followed by an expression with boolean type, +will check that the given expression results in `true`, and cause a +failure otherwise. It is typically used to double-check things that +*should* hold at a certain point in a program. + + let x = 100; + while (x > 10) { x -= 10; } + assert x == 10; diff --git a/doc/tutorial/data.md b/doc/tutorial/data.md index 25135787f4d..d09359f198d 100644 --- a/doc/tutorial/data.md +++ b/doc/tutorial/data.md @@ -33,7 +33,9 @@ error. To 'update' an immutable record, you use functional record update syntax, by ending a record literal with the keyword `with`: + let oldpoint = {x: 10f, y: 20f}; let newpoint = {x: 0f with oldpoint}; + assert newpoint == {x: 0f, y: 20f}; This will create a new struct, copying all the fields from `oldpoint` into it, except for the ones that are explicitly set in the literal. diff --git a/doc/tutorial/setup.md b/doc/tutorial/setup.md index ffa3a976629..ec1e27a0af9 100644 --- a/doc/tutorial/setup.md +++ b/doc/tutorial/setup.md @@ -36,7 +36,9 @@ FIXME say something about libs, main, modules, use There are Vim highlighting and indentation scrips in the Rust source distribution under `src/etc/vim/`. An Emacs mode can be found at -`[https://github.com/marijnh/rust-mode](https://github.com/marijnh/rust-mode)`. +[https://github.com/marijnh/rust-mode][rust-mode]. + +[rust-mode]: https://github.com/marijnh/rust-mode Other editors are not provided for yet. If you end up writing a Rust mode for your favorite editor, let us know so that we can link to it. diff --git a/doc/tutorial/syntax.md b/doc/tutorial/syntax.md index 19e9c4aa8ef..2b284ecafa4 100644 --- a/doc/tutorial/syntax.md +++ b/doc/tutorial/syntax.md @@ -37,9 +37,9 @@ like `if` and `while` are available: Though it isn't apparent in most everyday code, there is a fundamental difference between Rust's syntax and the predecessors in this family -of languages. Almost everything in rust is an expression, even things -that are statements in other languages. This allows for useless things -like this (which passes nil—the void type—to a function): +of languages. A lot of thing that are statements in C are expressions +in Rust. This allows for useless things like this (which passes +nil—the void type—to a function): a_function(while false {}); @@ -62,11 +62,14 @@ This also works for function bodies. This function returns a boolean: fn is_four(x: int) -> bool { x == 4 } -If everything is an expression, you might conclude that you have to -add a terminating semicolon after *every* statement, even ones that +In short, everything that's not a declaration (`let` for variables, +`fn` for functions, etcetera) is an expression. + +If all those things are expressions, you might conclude that you have +to add a terminating semicolon after *every* statement, even ones that are not traditionally terminated with a semicolon in C (like `while`). -That is not the case, though. Statements that end in a block only need -a semicolon if that block contains a trailing expression. `while` +That is not the case, though. Expressions that end in a block only +need a semicolon if that block contains a trailing expression. `while` loops do not allow trailing expressions, and `if` statements tend to only have a trailing expression when you want to use their value for something—in which case you'll have embedded it in a bigger statement, @@ -166,7 +169,7 @@ Integers can be written in decimal (`144`), hexadecimal (`0x90`), and binary (`0b10010000`) base. Without suffix, an integer literal is considered to be of type `int`. Add a `u` (`144u`) to make it a `uint` instead. Literals of the fixed-size integer types can be created by -the literal with the type name (`i8`, `u64`, etc). +the literal with the type name (`255u8`, `50i64`, etc). Note that, in Rust, no implicit conversion between integer types happens. If you are adding one to a variable of type `uint`, you must @@ -188,12 +191,16 @@ character escapes, using the backslash character: `\n` : A newline (unicode character 32). + `\r` : A carriage return (13). + `\t` : A tab character (9). + `\\`, `\'`, `\"` : Simply escapes the following character. + `\xHH`, `\uHHHH`, `\UHHHHHHHH` : Unicode escapes, where the `H` characters are the hexadecimal digits that form the character code.