diff --git a/src/doc/guide-lifetimes.md b/src/doc/guide-lifetimes.md index 69596b6e304..eb16f73c3a9 100644 --- a/src/doc/guide-lifetimes.md +++ b/src/doc/guide-lifetimes.md @@ -559,9 +559,14 @@ points at a static constant). # Named lifetimes -Let's look at named lifetimes in more detail. Named lifetimes allow -for grouping of parameters by lifetime. For example, consider this -function: +Lifetimes can be named and referenced. For example, the special lifetime +`'static`, which does not go out of scope, can be used to create global +variables and communicate between tasks (see the manual for usecases). + +## Parameter Lifetimes + +Named lifetimes allow for grouping of parameters by lifetime. +For example, consider this function: ~~~ # struct Point {x: f64, y: f64}; // as before @@ -655,6 +660,25 @@ fn select<'r, T>(shape: &Shape, threshold: f64, This is equivalent to the previous definition. +## Labeled Control Structures + +Named lifetime notation can also be used to control the flow of execution: + +~~~ +'h: for i in range(0,10) { + 'g: loop { + if i % 2 == 0 { continue 'h; } + if i == 9 { break 'h; } + break 'g; + } +} +~~~ + +> ***Note:*** Labelled breaks are not currently supported within `while` loops. + +Named labels are hygienic and can be used safely within macros. +See the macros guide section on hygiene for more details. + # Conclusion So there you have it: a (relatively) brief tour of the lifetime diff --git a/src/doc/guide-macros.md b/src/doc/guide-macros.md index 527777a0eba..23510997f24 100644 --- a/src/doc/guide-macros.md +++ b/src/doc/guide-macros.md @@ -398,6 +398,38 @@ position (in particular, not as an argument to yet another macro invocation), the expander will then proceed to evaluate `m2!()` (along with any other macro invocations `m1!(m2!())` produced). +# Hygiene + +To prevent clashes, rust implements +[hygienic macros](http://en.wikipedia.org/wiki/Hygienic_macro). + +As an example, `loop` and `for-loop` labels (discussed in the lifetimes guide) +will not clash. The following code will print "Hello!" only once: + +~~~ +#[feature(macro_rules)]; + +macro_rules! loop_x ( + ($e: expr) => ( + // $e will not interact with this 'x + 'x: loop { + println!("Hello!"); + $e + } + ); +) + +fn main() { + 'x: loop { + loop_x!(break 'x); + println!("I am never printed."); + } +} +~~~ + +The two `'x` names did not clash, which would have caused the loop +to print "I am never printed" and to run forever. + # A final note Macros, as currently implemented, are not for the faint of heart. Even diff --git a/src/doc/tutorial.md b/src/doc/tutorial.md index bfa1a3a2a29..09539e6d59d 100644 --- a/src/doc/tutorial.md +++ b/src/doc/tutorial.md @@ -2103,7 +2103,8 @@ a `&T` pointer. `MutexArc` is an example of a *sharable* type with internal muta These are types that do not contain any data whose lifetime is bound to a particular stack frame. These are types that do not contain any references, or types where the only contained references -have the `'static` lifetime. +have the `'static` lifetime. (For more on named lifetimes and their uses, +see the [references and lifetimes guide][lifetimes].) > ***Note:*** These two traits were referred to as 'kinds' in earlier > iterations of the language, and often still are.