From 532ee3c6d6907bd683c643756c1842446ed62faa Mon Sep 17 00:00:00 2001 From: Andrew Paseltiner Date: Tue, 29 Sep 2015 18:35:33 -0400 Subject: [PATCH 01/13] Derive `Clone` for `Peekable` --- src/libcore/iter.rs | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index 97dcb2475a3cf..b493745fc2c77 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -1862,6 +1862,7 @@ impl DoubleEndedIterator for Enumerate where } /// An iterator with a `peek()` that returns an optional reference to the next element. +#[derive(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[stable(feature = "rust1", since = "1.0.0")] pub struct Peekable { @@ -1869,15 +1870,6 @@ pub struct Peekable { peeked: Option, } -impl Clone for Peekable where I::Item: Clone { - fn clone(&self) -> Peekable { - Peekable { - iter: self.iter.clone(), - peeked: self.peeked.clone(), - } - } -} - #[stable(feature = "rust1", since = "1.0.0")] impl Iterator for Peekable { type Item = I::Item; From ff2bc7785d2d735f39bd6eb733893aceaef269cd Mon Sep 17 00:00:00 2001 From: Jan Likar Date: Wed, 30 Sep 2015 02:42:52 +0200 Subject: [PATCH 02/13] Improve "Variable bindings" chapter - Expand the first paragraph - Improve readability by partitioning the chapter into the following sections: "Patterns", "Type annotations", "Mutability", and "Initializing bindings" - Add "Scope and shadowing" section (fix #28177) --- src/doc/trpl/variable-bindings.md | 99 ++++++++++++++++++++++++++++--- 1 file changed, 91 insertions(+), 8 deletions(-) diff --git a/src/doc/trpl/variable-bindings.md b/src/doc/trpl/variable-bindings.md index 2166c046897f0..3521c970e72c8 100644 --- a/src/doc/trpl/variable-bindings.md +++ b/src/doc/trpl/variable-bindings.md @@ -1,7 +1,8 @@ % Variable Bindings Virtually every non-'Hello World’ Rust program uses *variable bindings*. They -look like this: +bind some value to a name, so it can be used later. `let` is +used to introduce a binding, just like this: ```rust fn main() { @@ -13,10 +14,12 @@ Putting `fn main() {` in each example is a bit tedious, so we’ll leave that ou in the future. If you’re following along, make sure to edit your `main()` function, rather than leaving it off. Otherwise, you’ll get an error. -In many languages, this is called a *variable*, but Rust’s variable bindings -have a few tricks up their sleeves. For example the left-hand side of a `let` -expression is a ‘[pattern][pattern]’, not just a variable name. This means we -can do things like: +# Patterns + +In many languages, a variable binding would be called a *variable*, but Rust’s +variable bindings have a few tricks up their sleeves. For example the +left-hand side of a `let` expression is a ‘[pattern][pattern]’, not just a +variable name. This means we can do things like: ```rust let (x, y) = (1, 2); @@ -29,6 +32,8 @@ of our minds as we go forward. [pattern]: patterns.html +# Type annotations + Rust is a statically typed language, which means that we specify our types up front, and they’re checked at compile time. So why does our first example compile? Well, Rust has this thing called ‘type inference’. If it can figure @@ -63,6 +68,8 @@ Note the similarities between this annotation and the syntax you use with occasionally include them to help you understand what the types that Rust infers are. +# Mutability + By default, bindings are *immutable*. This code will not compile: ```rust,ignore @@ -97,9 +104,11 @@ out of the scope of this guide. In general, you can often avoid explicit mutation, and so it is preferable in Rust. That said, sometimes, mutation is what you need, so it’s not verboten. -Let’s get back to bindings. Rust variable bindings have one more aspect that -differs from other languages: bindings are required to be initialized with a -value before you're allowed to use them. +# Initializing bindings + +Rust variable bindings have one more aspect that differs from other languages: +bindings are required to be initialized with a value before you're allowed to +use them. Let’s try it out. Change your `src/main.rs` file to look like this: @@ -167,3 +176,77 @@ For now, we'll just stick to the default: integers aren't very complicated to print. [format]: ../std/fmt/index.html + +# Scope and shadowing + +Let’s get back to bindings. Variable bindings have a scope - they are +constrained to live in a block they were defined in. A block is a collection +of statements enclosed by `{` and `}`. Function definitions are also blocks! +In the following example we define two variable bindings, `x` and `y`, which +live in different blocks. `x` can be accessed from inside the `fn main() {}` +block, while `y` can be accessed only from inside the inner block: + +```rust,ignore +fn main() { + let x: i32 = 17; + { + let y: i32 = 3; + println!("The value of x is {} and value of y is {}", x, y); + } + println!("The value of x is {} and value of y is {}", x, y); // This won't work +} +``` + +The first `println!` would print "The value of x is 17 and the value of y is +3", but this example cannot be compiled successfully, because the second +`println!` cannot access the value of `y`, since it is not in scope anymore. +Instead we get this error: + +```bash +$ cargo build + Compiling hello v0.1.0 (file:///home/you/projects/hello_world) +main.rs:7:62: 7:63 error: unresolved name `y`. Did you mean `x`? [E0425] +main.rs:7 println!("The value of x is {} and value of y is {}", x, y); // This won't work + ^ +note: in expansion of format_args! +:2:25: 2:56 note: expansion site +:1:1: 2:62 note: in expansion of print! +:3:1: 3:54 note: expansion site +:1:1: 3:58 note: in expansion of println! +main.rs:7:5: 7:65 note: expansion site +main.rs:7:62: 7:63 help: run `rustc --explain E0425` to see a detailed explanation +error: aborting due to previous error +Could not compile `hello`. + +To learn more, run the command again with --verbose. +``` + +Additionaly, variable bindings can be shadowed. This means that a later +variable binding with the same name as another binding, that's currently in +scope, will override the previous binding. + +```rust +let x: i32 = 8; +{ + println!("{}", x); // Prints "8" + let x = 12; + println!("{}", x); // Prints "12" +} +println!("{}", x); // Prints "8" +let x = 42; +println!("{}", x); // Prints "42" +``` + +Shadowing and mutable bindings may appear as two sides of the same coin, but +they are two distinct concepts that can't always be used interchangeably. For +one, shadowing enables us to rebind a name to a value of a different type. It +is also possible to change the mutability of a binding. + +```rust +let mut x: i32 = 1; +x = 7; +let x = x; // x is now immutable and is bound to 7 + +let y = 4; +let y = "I can also be bound to text!"; // y is now of a different type +``` From 7914d1b8b7d45965c1cefffb6d250ed463e9a78e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dato=20Sim=C3=B3?= Date: Wed, 30 Sep 2015 01:18:23 -0300 Subject: [PATCH 03/13] Fix typo in docs: usize is unsigned, not signed. --- src/libstd/primitive_docs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index f2ae168e560bd..7d62d477a0a52 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -411,7 +411,7 @@ mod prim_isize { } #[doc(primitive = "usize")] // -/// The pointer-sized signed integer type. +/// The pointer-sized unsigned integer type. /// /// *[See also the `std::usize` module](usize/index.html).* /// From c6b8deef7dad7b93b8939b0cd994eadfac546ed1 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 30 Sep 2015 08:39:02 +0200 Subject: [PATCH 04/13] doc: fix typo --- src/libstd/path.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 8eb5d1f2726d6..ed70c2bd7b4ac 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1292,7 +1292,7 @@ impl Path { /// use std::path::Path; /// /// let path_str = Path::new("foo.txt").to_str(); - //// assert_eq!(path_str, Some("foo.txt")); + /// assert_eq!(path_str, Some("foo.txt")); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn to_str(&self) -> Option<&str> { From ffab1b405c4008d935e05f2f3eebd3b97bdb0863 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 30 Sep 2015 12:00:02 +0200 Subject: [PATCH 05/13] path: remove a line of code that is not useful --- src/libstd/path.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 8eb5d1f2726d6..01588a681b868 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -351,7 +351,6 @@ impl<'a> Prefix<'a> { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn is_separator(c: char) -> bool { - use ascii::*; c.is_ascii() && is_sep_byte(c as u8) } From 73bd0ba91efe68b3d2932d7a2abbdde7308d0738 Mon Sep 17 00:00:00 2001 From: Ted Mielczarek Date: Wed, 30 Sep 2015 12:33:38 -0400 Subject: [PATCH 06/13] Fix module links in std::fmt and the Rust book's documentation chapter. The links in the rustdoc for several places in fmt were trying to link to the std::fmt module but actually linking to std, which was confusing. While trying to figure out why I noticed that the documentation chapter of the Rust book has examples that show this same bug (although it doesn't seem widespread in practice). --- src/doc/trpl/documentation.md | 4 ++-- src/libcore/fmt/mod.rs | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index 0a471beb43914..5afb9b7f868c8 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -45,7 +45,7 @@ Rust keeps track of these comments, and uses them when generating documentation. This is important when documenting things like enums: ```rust -/// The `Option` type. See [the module level documentation](../) for more. +/// The `Option` type. See [the module level documentation](index.html) for more. enum Option { /// No value None, @@ -57,7 +57,7 @@ enum Option { The above works, but this does not: ```rust,ignore -/// The `Option` type. See [the module level documentation](../) for more. +/// The `Option` type. See [the module level documentation](index.html) for more. enum Option { None, /// No value Some(T), /// Some value `T` diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs index 8c596eb3e997b..65206f42b3933 100644 --- a/src/libcore/fmt/mod.rs +++ b/src/libcore/fmt/mod.rs @@ -298,7 +298,7 @@ impl<'a> Display for Arguments<'a> { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -393,7 +393,7 @@ pub trait Debug { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -435,7 +435,7 @@ pub trait Display { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -482,7 +482,7 @@ pub trait Octal { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -530,7 +530,7 @@ pub trait Binary { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -578,7 +578,7 @@ pub trait LowerHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -624,7 +624,7 @@ pub trait UpperHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -668,7 +668,7 @@ pub trait Pointer { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -711,7 +711,7 @@ pub trait LowerExp { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// From 9c70d5160bbd76ed428499d8a54b7a47361b2007 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 12:39:37 -0400 Subject: [PATCH 07/13] Improve wording in error handling guide The original blog post referred to examples by their file names, and now that it's in guide form, there is no file name. So edit the text so that it makes a bit more sense. Fixes #28428 --- src/doc/trpl/error-handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index a54ba91da2e9f..7fb1a79dcf1df 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -182,7 +182,7 @@ analysis is the only way to get at the value stored inside an `Option`. This means that you, as the programmer, must handle the case when an `Option` is `None` instead of `Some(t)`. -But wait, what about `unwrap` used in [`unwrap-double`](#code-unwrap-double)? +But wait, what about `unwrap`,which we used [`previously`](#code-unwrap-double)? There was no case analysis there! Instead, the case analysis was put inside the `unwrap` method for you. You could define it yourself if you want: @@ -211,7 +211,7 @@ that makes `unwrap` ergonomic to use. Unfortunately, that `panic!` means that ### Composing `Option` values -In [`option-ex-string-find`](#code-option-ex-string-find) +In an [example from before](#code-option-ex-string-find), we saw how to use `find` to discover the extension in a file name. Of course, not all file names have a `.` in them, so it's possible that the file name has no extension. This *possibility of absence* is encoded into the types using From d310ad95479369c75bfcd4f126f0b6accc1aaee6 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 12:42:47 -0400 Subject: [PATCH 08/13] Format panic docs for split_at Fixes #28384 --- src/libcollections/slice.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index 76bdd6dbea122..dabfd168c89ac 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -455,6 +455,8 @@ impl [T] { /// the index `mid` itself) and the second will contain all /// indices from `[mid, len)` (excluding the index `len` itself). /// + /// # Panics + /// /// Panics if `mid > len`. /// /// # Examples From bc0440a63146085fc42a7defbf6f944900f0be3d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:21:02 -0400 Subject: [PATCH 09/13] Call out slicing syntax more explicitly Fixes #28359 --- src/doc/trpl/primitive-types.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/doc/trpl/primitive-types.md b/src/doc/trpl/primitive-types.md index 027909dd05876..a8c7a7d41573e 100644 --- a/src/doc/trpl/primitive-types.md +++ b/src/doc/trpl/primitive-types.md @@ -162,13 +162,18 @@ A ‘slice’ is a reference to (or “view” into) another data structure. The useful for allowing safe, efficient access to a portion of an array without copying. For example, you might want to reference just one line of a file read into memory. By nature, a slice is not created directly, but from an existing -variable. Slices have a length, can be mutable or not, and in many ways behave -like arrays: +variable binding. Slices have a defined length, can be mutable or immutable. + +## Slicing syntax + +You can use a combo of `&` and `[]` to create a slice from various things. The +`&` indicates that slices are similar to references, and the `[]`s, with a +range, let you define the length of the slice: ```rust let a = [0, 1, 2, 3, 4]; -let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3 let complete = &a[..]; // A slice containing all of the elements in a +let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3 ``` Slices have type `&[T]`. We’ll talk about that `T` when we cover From 49fa11c5a5fef15b49abf0a22b0991f1b6ed114b Mon Sep 17 00:00:00 2001 From: Ted Mielczarek Date: Wed, 30 Sep 2015 13:24:39 -0400 Subject: [PATCH 10/13] Fix module links from core::fmt::* to go to std::fmt --- src/libcore/fmt/mod.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs index 65206f42b3933..69fa0fa1609e3 100644 --- a/src/libcore/fmt/mod.rs +++ b/src/libcore/fmt/mod.rs @@ -298,7 +298,7 @@ impl<'a> Display for Arguments<'a> { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -393,7 +393,7 @@ pub trait Debug { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -435,7 +435,7 @@ pub trait Display { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -482,7 +482,7 @@ pub trait Octal { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -530,7 +530,7 @@ pub trait Binary { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -578,7 +578,7 @@ pub trait LowerHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -624,7 +624,7 @@ pub trait UpperHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -668,7 +668,7 @@ pub trait Pointer { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -711,7 +711,7 @@ pub trait LowerExp { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// From 201384c1077493e84aaeb3a2370d041678e5aa6d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:30:43 -0400 Subject: [PATCH 11/13] Cross-reference doc chapter from testing chapter We don't completely cover documentation tests in the testing chapter, since we cover them in the documentation chapter. So make sure people know that. Fixes #28082 --- src/doc/trpl/testing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/doc/trpl/testing.md b/src/doc/trpl/testing.md index 587f60343c344..452dc13c6968d 100644 --- a/src/doc/trpl/testing.md +++ b/src/doc/trpl/testing.md @@ -502,3 +502,5 @@ documentation tests: the `_0` is generated for the module test, and `add_two_0` for the function test. These will auto increment with names like `add_two_1` as you add more examples. +We haven’t covered all of the details with writing documentation tests. For more, +please see the [Documentation chapter](documentation.html) From 367f46d7931db1871c7eb5f6bece64c1f2467b18 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:35:33 -0400 Subject: [PATCH 12/13] Make note of performance implications of Read Fixes #28073 --- src/libstd/io/mod.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 54869807cacef..a76755dadd35b 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -370,6 +370,13 @@ fn read_to_end(r: &mut R, buf: &mut Vec) -> Result /// throughout `std::io` take and provide types which implement the `Read` /// trait. /// +/// Please note that each call to `read` may involve a system call, and +/// therefore, using something that implements [`BufRead`][bufread], such as +/// [`BufReader`][bufreader], will be more efficient. +/// +/// [bufread]: trait.BufRead.html +/// [bufreader]: struct.BufReader.html +/// /// # Examples /// /// [`File`][file]s implement `Read`: From 9812eb0ef4f1dedd6f25a2c63f755b683b6ce787 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:39:59 -0400 Subject: [PATCH 13/13] Elaborate on the io prelude in the book Fixes #27917 --- src/doc/trpl/guessing-game.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/trpl/guessing-game.md b/src/doc/trpl/guessing-game.md index 94280aa4a3317..db484a28cb02c 100644 --- a/src/doc/trpl/guessing-game.md +++ b/src/doc/trpl/guessing-game.md @@ -99,9 +99,12 @@ use std::io; We’ll need to take user input, and then print the result as output. As such, we need the `io` library from the standard library. Rust only imports a few things by default into every program, [the ‘prelude’][prelude]. If it’s not in the -prelude, you’ll have to `use` it directly. +prelude, you’ll have to `use` it directly. There is also a second ‘prelude’, the +[`io` prelude][ioprelude], which serves a similar function: you import it, and it +imports a number of useful, `io`-related things. [prelude]: ../std/prelude/index.html +[ioprelude]: ../std/io/prelude/index.html ```rust,ignore fn main() {