From 1d7d0192d264aa03358fab1d683b984ed6eef2d7 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 17 Apr 2015 12:58:55 +0200 Subject: [PATCH 1/9] Add backquotes to have better looking rust code --- src/librustc/diagnostics.rs | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index 306d2cd102fdb..055129b35df9e 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -75,11 +75,13 @@ the following is invalid as it requires the entire Option to be moved into a variable called `op_string` while simultaneously requiring the inner String to be moved into a variable called `s`. +``` let x = Some("s".to_string()); match x { op_string @ Some(s) => ... None => ... } +``` See also Error 303. "##, @@ -90,10 +92,12 @@ name is bound by move in a pattern, it should also be moved to wherever it is referenced in the pattern guard code. Doing so however would prevent the name from being available in the body of the match arm. Consider the following: +``` match Some("hi".to_string()) { Some(s) if s.len() == 0 => // use s. ... } +``` The variable `s` has type String, and its use in the guard is as a variable of type String. The guard code effectively executes in a separate scope to the body @@ -102,11 +106,13 @@ become unavailable in the body of the arm. Although this example seems innocuous, the problem is most clear when considering functions that take their argument by value. +``` match Some("hi".to_string()) { Some(s) if { drop(s); false } => (), Some(s) => // use s. ... } +``` The value would be dropped in the guard then become unavailable not only in the body of that arm but also in all subsequent arms! The solution is to bind by @@ -218,6 +224,7 @@ An if-let pattern attempts to match the pattern, and enters the body if the match was succesful. If the match is irrefutable (when it cannot fail to match), use a regular `let`-binding instead. For instance: +``` struct Irrefutable(i32); let irr = Irrefutable(0); @@ -230,6 +237,7 @@ if let Irrefutable(x) = irr { // Try this instead: let Irrefutable(x) = irr; foo(x); +``` "##, E0165: r##" @@ -237,6 +245,7 @@ A while-let pattern attempts to match the pattern, and enters the body if the match was succesful. If the match is irrefutable (when it cannot fail to match), use a regular `let`-binding inside a `loop` instead. For instance: +``` struct Irrefutable(i32); let irr = Irrefutable(0); @@ -250,6 +259,7 @@ loop { let Irrefutable(x) = irr; ... } +``` "##, E0170: r##" @@ -304,6 +314,7 @@ that a name will be extracted in all cases. Instead of pattern matching the loop variable, consider using a `match` or `if let` inside the loop body. For instance: +``` // This fails because `None` is not covered. for Some(x) in xs { ... @@ -323,6 +334,7 @@ for item in xs { ... } } +``` "##, E0301: r##" @@ -332,11 +344,13 @@ on which the match depends in such a way, that the match would not be exhaustive. For instance, the following would not match any arm if mutable borrows were allowed: +``` match Some(()) { None => { }, option if option.take().is_none() => { /* impossible, option is `Some` */ }, Some(_) => { } // When the previous match failed, the option became `None`. } +``` "##, E0302: r##" @@ -346,11 +360,13 @@ on which the match depends in such a way, that the match would not be exhaustive. For instance, the following would not match any arm if assignments were allowed: +``` match Some(()) { None => { }, option if { option = None; false } { }, Some(_) => { } // When the previous match failed, the option became `None`. } +``` "##, E0303: r##" @@ -358,9 +374,10 @@ In certain cases it is possible for sub-bindings to violate memory safety. Updates to the borrow checker in a future version of Rust may remove this restriction, but for now patterns must be rewritten without sub-bindings. -// Before. -match Some("hi".to_string()) { - ref op_string_ref @ Some(ref s) => ... +``` +// Code like this... +match Some(5) { + ref op_num @ Some(num) => ... None => ... } @@ -372,6 +389,7 @@ match Some("hi".to_string()) { } None => ... } +``` The `op_string_ref` binding has type &Option<&String> in both cases. From a9bc39c536b7ef2080e5b60bb4e68722394c3bae Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 22 Apr 2015 16:41:22 -0400 Subject: [PATCH 2/9] remove debug and display chapter this is too small for its own thing, I think. --- src/doc/trpl/SUMMARY.md | 1 - src/doc/trpl/debug-and-display.md | 3 --- 2 files changed, 4 deletions(-) delete mode 100644 src/doc/trpl/debug-and-display.md diff --git a/src/doc/trpl/SUMMARY.md b/src/doc/trpl/SUMMARY.md index e3c636df2e45f..b0ee8e1fa9308 100644 --- a/src/doc/trpl/SUMMARY.md +++ b/src/doc/trpl/SUMMARY.md @@ -7,7 +7,6 @@ * [Learn Rust](learn-rust.md) * [Effective Rust](effective-rust.md) * [The Stack and the Heap](the-stack-and-the-heap.md) - * [Debug and Display](debug-and-display.md) * [Testing](testing.md) * [Documentation](documentation.md) * [Iterators](iterators.md) diff --git a/src/doc/trpl/debug-and-display.md b/src/doc/trpl/debug-and-display.md deleted file mode 100644 index 918f4c440ac32..0000000000000 --- a/src/doc/trpl/debug-and-display.md +++ /dev/null @@ -1,3 +0,0 @@ -% Debug and Display - -Coming soon! From b4a6f895caf3d49ad00a0982ef28485385e78d17 Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Wed, 22 Apr 2015 13:57:08 -0700 Subject: [PATCH 3/9] Explain how to create a Stdin or Stdout --- src/libstd/io/stdio.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index cd6af77daa906..42fad701533b2 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -95,6 +95,8 @@ impl Write for StderrRaw { /// /// This handle implements the `Read` trait, but beware that concurrent reads /// of `Stdin` must be executed with care. +/// +/// Created by the function `io::stdin()`. #[stable(feature = "rust1", since = "1.0.0")] pub struct Stdin { inner: Arc>>, @@ -206,6 +208,8 @@ const OUT_MAX: usize = ::usize::MAX; /// Each handle shares a global buffer of data to be written to the standard /// output stream. Access is also synchronized via a lock and explicit control /// over locking is available via the `lock` method. +/// +/// Created by the function `io::stdout()`. #[stable(feature = "rust1", since = "1.0.0")] pub struct Stdout { // FIXME: this should be LineWriter or BufWriter depending on the state of From b3a7837eab3384876144621dedbeab88a1e44738 Mon Sep 17 00:00:00 2001 From: Robin Kruppe Date: Wed, 22 Apr 2015 23:06:32 +0200 Subject: [PATCH 4/9] Fix a tiny typo in core::raw --- src/libcore/raw.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/raw.rs b/src/libcore/raw.rs index 685b3e5c546dd..ec84ef7986a43 100644 --- a/src/libcore/raw.rs +++ b/src/libcore/raw.rs @@ -80,7 +80,7 @@ impl Clone for Slice { /// `TraitObject` is guaranteed to match layouts, but it is not the /// type of trait objects (e.g. the fields are not directly accessible /// on a `&SomeTrait`) nor does it control that layout (changing the -/// definition will not change the layout of a `&SometTrait`). It is +/// definition will not change the layout of a `&SomeTrait`). It is /// only designed to be used by unsafe code that needs to manipulate /// the low-level details. /// From 4047a7c29f5e4481ba6056cadf4a1157e9d16c8f Mon Sep 17 00:00:00 2001 From: Tamir Duberstein Date: Wed, 22 Apr 2015 15:57:24 -0700 Subject: [PATCH 5/9] Remove stale comment `ToCStr` was removed with `old_io` and the current method `as_os_str` is inherent to `Path`, meaning there is no suitable trait bound that could be used here. --- src/libstd/dynamic_lib.rs | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/libstd/dynamic_lib.rs b/src/libstd/dynamic_lib.rs index 8ca462f5a3870..d0f990eaf782a 100644 --- a/src/libstd/dynamic_lib.rs +++ b/src/libstd/dynamic_lib.rs @@ -40,14 +40,6 @@ impl Drop for DynamicLibrary { } impl DynamicLibrary { - // FIXME (#12938): Until DST lands, we cannot decompose &str into - // & and str, so we cannot usefully take ToCStr arguments by - // reference (without forcing an additional & around &str). So we - // are instead temporarily adding an instance for &Path, so that - // we can take ToCStr as owned. When DST lands, the &Path instance - // should be removed, and arguments bound by ToCStr should be - // passed by reference. (Here: in the `open` method.) - /// Lazily open a dynamic library. When passed None it gives a /// handle to the calling process pub fn open(filename: Option<&Path>) -> Result { From 76a590d0ef15506ed805a943b3a19ce65651903f Mon Sep 17 00:00:00 2001 From: Liigo Zhuang Date: Thu, 23 Apr 2015 01:32:59 +0800 Subject: [PATCH 6/9] rustdoc: add back [-]/[+] toggle links for unstable-methods --- src/librustdoc/html/static/main.js | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/librustdoc/html/static/main.js b/src/librustdoc/html/static/main.js index 0379c04be4d29..7e0b6813bc040 100644 --- a/src/librustdoc/html/static/main.js +++ b/src/librustdoc/html/static/main.js @@ -823,6 +823,9 @@ $(document).on("click", ".collapse-toggle", function() { var toggle = $(this); var relatedDoc = toggle.parent().next(); + if (relatedDoc.is(".stability")) { + relatedDoc = relatedDoc.next(); + } if (relatedDoc.is(".docblock")) { if (relatedDoc.is(":visible")) { relatedDoc.slideUp({duration:'fast', easing:'linear'}); @@ -843,9 +846,10 @@ .html("[-]"); $(".method").each(function() { - if ($(this).next().is(".docblock")) { - $(this).children().first().after(toggle.clone()); - } + if ($(this).next().is(".docblock") || + ($(this).next().is(".stability") && $(this).next().next().is(".docblock"))) { + $(this).children().first().after(toggle.clone()); + } }); var mainToggle = From 5efdbecdf9472bb7ca2c8ae7a89b8c4966d567ce Mon Sep 17 00:00:00 2001 From: Andrzej Janik Date: Thu, 23 Apr 2015 16:39:18 +0200 Subject: [PATCH 7/9] Stop mentioning obsolete integer suffixes `us` and `is` were replaced with `usize` and `isize` some time ago. --- src/doc/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index d918a320e63a9..d1bc676f6ad0e 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -268,7 +268,7 @@ cases mentioned in [Number literals](#number-literals) below. ##### Suffixes | Integer | Floating-point | |---------|----------------| -| `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `u64`, `i64`, `is` (`isize`), `us` (`usize`) | `f32`, `f64` | +| `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `u64`, `i64`, `isize`, `usize` | `f32`, `f64` | #### Character and string literals From 2ddc8f5eb53a1966f17991a3920295e080b09097 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 21 Apr 2015 11:51:49 +0200 Subject: [PATCH 8/9] Update diagnostics.rs --- src/librustc/diagnostics.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index 055129b35df9e..73abac5abbb16 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -187,8 +187,10 @@ them yourself. You can build a free-standing crate by adding `#![no_std]` to the crate attributes: +``` #![feature(no_std)] #![no_std] +``` See also https://doc.rust-lang.org/book/no-stdlib.html "##, @@ -204,11 +206,13 @@ mutex can be declared `static` as well. If you want to match against a `static`, consider using a guard instead: +``` static FORTY_TWO: i32 = 42; match Some(42) { Some(x) if x == FORTY_TWO => ... ... } +``` "##, E0161: r##" @@ -265,17 +269,21 @@ loop { E0170: r##" Enum variants are qualified by default. For example, given this type: +``` enum Method { GET, POST } +``` you would match it using: +``` match m { Method::GET => ... Method::POST => ... } +``` If you don't qualify the names, the code will bind new variables named "GET" and "POST" instead. This behavior is likely not what you want, so rustc warns when @@ -284,8 +292,10 @@ that happens. Qualified names are good practice, and most code works well with them. But if you prefer them unqualified, you can import the variants into scope: +``` use Method::*; enum Method { GET, POST } +``` "##, E0267: r##" @@ -305,7 +315,9 @@ E0296: r##" This error indicates that the given recursion limit could not be parsed. Ensure that the value provided is a positive integer between quotes, like so: +``` #![recursion_limit="1000"] +``` "##, E0297: r##" From e9f298082e84a4c7a355d777fce2b4e3347b16e3 Mon Sep 17 00:00:00 2001 From: Robin Kruppe Date: Thu, 23 Apr 2015 19:06:09 +0200 Subject: [PATCH 9/9] Reference audit: section 5 (Crates and source files) --- src/doc/reference.md | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index d918a320e63a9..2f7ec6a999e1d 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -735,15 +735,26 @@ Rust syntax is restricted in two ways: # Crates and source files -Rust is a *compiled* language. Its semantics obey a *phase distinction* between -compile-time and run-time. Those semantic rules that have a *static +Although Rust, like any other language, can be implemented by an interpreter as +well as a compiler, the only existing implementation is a compiler — +from now on referred to as *the* Rust compiler — and the language has +always been designed to be compiled. For these reasons, this section assumes a +compiler. + +Rust's semantics obey a *phase distinction* between compile-time and +run-time.[^phase-distinction] Those semantic rules that have a *static interpretation* govern the success or failure of compilation. Those semantics that have a *dynamic interpretation* govern the behavior of the program at run-time. +[^phase-distinction]: This distinction would also exist in an interpreter. + Static checks like syntactic analysis, type checking, and lints should + happen before the program is executed regardless of when it is executed. + The compilation model centers on artifacts called _crates_. Each compilation processes a single crate in source form, and if successful, produces a single -crate in binary form: either an executable or a library.[^cratesourcefile] +crate in binary form: either an executable or some sort of +library.[^cratesourcefile] [^cratesourcefile]: A crate is somewhat analogous to an *assembly* in the ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit* @@ -764,21 +775,25 @@ extension `.rs`. A Rust source file describes a module, the name and location of which — in the module tree of the current crate — are defined from outside the source file: either by an explicit `mod_item` in a referencing source file, or -by the name of the crate itself. +by the name of the crate itself. Every source file is a module, but not every +module needs its own source file: [module definitions](#modules) can be nested +within one file. Each source file contains a sequence of zero or more `item` definitions, and -may optionally begin with any number of `attributes` that apply to the -containing module. Attributes on the anonymous crate module define important -metadata that influences the behavior of the compiler. +may optionally begin with any number of [attributes](#Items and attributes) +that apply to the containing module, most of which influence the behavior of +the compiler. The anonymous crate module can have additional attributes that +apply to the crate as a whole. ```no_run -// Crate name +// Specify the crate name. #![crate_name = "projx"] -// Specify the output type +// Specify the type of output artifact. #![crate_type = "lib"] -// Turn on a warning +// Turn on a warning. +// This can be done in any module, not just the anonymous crate module. #![warn(non_camel_case_types)] ```