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/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 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() { 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 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) 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 +``` 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 diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs index 8c596eb3e997b..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 /// diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index d0590fdb72af1..abf50250dc2ef 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; 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`: diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 8eb5d1f2726d6..43c2766782e58 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) } @@ -1292,7 +1291,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> { 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).* ///