fedb775fbb
Not included in the build by default, since it's fragile and kludgy. Do
something like this to run it:
cd doc/tutorial
RUSTC=../../build/stage2/bin/rustc bash test.sh
Closes #1143
193 lines
6.9 KiB
Markdown
193 lines
6.9 KiB
Markdown
# Control structures
|
|
|
|
## Conditionals
|
|
|
|
We've seen `if` pass by a few times already. To recap, braces are
|
|
compulsory, an optional `else` clause can be appended, and multiple
|
|
`if`/`else` constructs can be chained together:
|
|
|
|
if false {
|
|
std::io::println("that's odd");
|
|
} else if true {
|
|
std::io::println("right");
|
|
} else {
|
|
std::io::println("neither true nor false");
|
|
}
|
|
|
|
The condition given to an `if` construct *must* be of type boolean (no
|
|
implicit conversion happens). If the arms return a value, this value
|
|
must be of the same type for every arm in which control reaches the
|
|
end of the block:
|
|
|
|
fn signum(x: int) -> int {
|
|
if x < 0 { -1 }
|
|
else if x > 0 { 1 }
|
|
else { ret 0; }
|
|
}
|
|
|
|
The `ret` (return) and its semicolon could have been left out without
|
|
changing the meaning of this function, but it illustrates that you
|
|
will not get a type error in this case, although the last arm doesn't
|
|
have type `int`, because control doesn't reach the end of that arm
|
|
(`ret` is jumping out of the function).
|
|
|
|
## Pattern matching
|
|
|
|
Rust's `alt` construct is a generalized, cleaned-up version of C's
|
|
`switch` construct. You provide it with a value and a number of arms,
|
|
each labelled with a pattern, and it will execute the arm that matches
|
|
the value.
|
|
|
|
# let my_number = 1;
|
|
alt my_number {
|
|
0 { std::io::println("zero"); }
|
|
1 | 2 { std::io::println("one or two"); }
|
|
3 to 10 { std::io::println("three to ten"); }
|
|
_ { std::io::println("something else"); }
|
|
}
|
|
|
|
There is no 'falling through' between arms, as in C—only one arm is
|
|
executed, and it doesn't have to explicitly `break` out of the
|
|
construct when it is finished.
|
|
|
|
The part to the left of each arm is called the pattern. Literals are
|
|
valid patterns, and will match only their own value. The pipe operator
|
|
(`|`) can be used to assign multiple patterns to a single arm. Ranges
|
|
of numeric literal patterns can be expressed with `to`. The underscore
|
|
(`_`) is a wildcard pattern that matches everything.
|
|
|
|
If the arm with the wildcard pattern was left off in the above
|
|
example, running it on a number greater than ten (or negative) would
|
|
cause a run-time failure. When no arm matches, `alt` constructs do not
|
|
silently fall through—they blow up instead.
|
|
|
|
A powerful application of pattern matching is *destructuring*, where
|
|
you use the matching to get at the contents of data types. Remember
|
|
that `(float, float)` is a tuple of two floats:
|
|
|
|
fn angle(vec: (float, float)) -> float {
|
|
alt vec {
|
|
(0f, y) when y < 0f { 1.5 * std::math::pi }
|
|
(0f, y) { 0.5 * std::math::pi }
|
|
(x, y) { std::math::atan(y / x) }
|
|
}
|
|
}
|
|
|
|
A variable name in a pattern matches everything, *and* binds that name
|
|
to the value of the matched thing inside of the arm block. Thus, `(0f,
|
|
y)` matches any tuple whose first element is zero, and binds `y` to
|
|
the second element. `(x, y)` matches any tuple, and binds both
|
|
elements to a variable.
|
|
|
|
Any `alt` arm can have a guard clause (written `when EXPR`), which is
|
|
an expression of type `bool` that determines, after the pattern is
|
|
found to match, whether the arm is taken or not. The variables bound
|
|
by the pattern are available in this guard expression.
|
|
|
|
## Destructuring let
|
|
|
|
To a limited extent, it is possible to use destructuring patterns when
|
|
declaring a variable with `let`. For example, you can say this to
|
|
extract the fields from a tuple:
|
|
|
|
# fn get_tuple_of_two_ints() -> (int, int) { (1, 1) }
|
|
let (a, b) = get_tuple_of_two_ints();
|
|
|
|
This will introduce two new variables, `a` and `b`, bound to the
|
|
content of the tuple.
|
|
|
|
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
|
|
|
|
`while` produces a loop that runs as long as its given condition
|
|
(which must have type `bool`) evaluates to true. Inside a loop, the
|
|
keyword `break` can be used to abort the loop, and `cont` can be used
|
|
to abort the current iteration and continue with the next.
|
|
|
|
let x = 5;
|
|
while true {
|
|
x += x - 3;
|
|
if x % 5 == 0 { break; }
|
|
std::io::println(std::int::str(x));
|
|
}
|
|
|
|
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:
|
|
|
|
# fn eat_cake() {}
|
|
# fn any_cake_left() -> bool { false }
|
|
do {
|
|
eat_cake();
|
|
} while any_cake_left();
|
|
|
|
When iterating over a vector, use `for` instead.
|
|
|
|
for elt in ["red", "green", "blue"] {
|
|
std::io::println(elt);
|
|
}
|
|
|
|
This will go over each element in the given vector (a three-element
|
|
vector of strings, in this case), and repeatedly execute the body with
|
|
`elt` bound to the current element. You may add an optional type
|
|
declaration (`elt: str`) for the iteration variable if you want.
|
|
|
|
For more involved iteration, such as going over the elements of a hash
|
|
table, Rust uses higher-order functions. We'll come back to those in a
|
|
moment.
|
|
|
|
## Failure
|
|
|
|
The `fail` keyword causes the current [task][tasks] to fail. You use
|
|
it to indicate unexpected failure, much like you'd use `exit(1)` in a
|
|
C program, except that in Rust, it is possible for other tasks to
|
|
handle the failure, allowing the program to continue running.
|
|
|
|
`fail` takes an optional argument, which must have type `str`. Trying
|
|
to access a vector out of bounds, or running a pattern match with no
|
|
matching clauses, both result in the equivalent of a `fail`.
|
|
|
|
[tasks]: task.html
|
|
|
|
## Logging
|
|
|
|
Rust has a built-in logging mechanism, using the `log` statement.
|
|
Logging is polymorphic—any type of value can be logged, and the
|
|
runtime will do its best to output a textual representation of the
|
|
value.
|
|
|
|
log "hi";
|
|
log (1, [2.5, -1.8]);
|
|
|
|
By default, you *will not* see the output of your log statements. The
|
|
environment variable `RUST_LOG` controls which log statements actually
|
|
get output. It can contain a comma-separated list of paths for modules
|
|
that should be logged. For example, running `rustc` with
|
|
`RUST_LOG=rustc::front::attr` will turn on logging in its attribute
|
|
parser. If you compile a program `foo.rs`, you can set `RUST_LOG` to
|
|
`foo` to enable its logging.
|
|
|
|
Turned-off `log` statements impose minimal overhead on the code that
|
|
contains them, so except in code that needs to be really, really fast,
|
|
you should feel free to scatter around debug logging statements, and
|
|
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;
|