Skip to content

Commit 277416e

Browse files
committed
Auto merge of #29900 - steveklabnik:rollup, r=steveklabnik
- Successful merges: #29612, #29888, #29889, #29890, #29891, #29892 - Failed merges:
2 parents 841e36e + 5c99fb7 commit 277416e

File tree

5 files changed

+178
-33
lines changed

5 files changed

+178
-33
lines changed

src/doc/reference.md

+23-15
Original file line numberDiff line numberDiff line change
@@ -147,11 +147,11 @@ a form of constant expression, so is evaluated (primarily) at compile time.
147147

148148
| | Example | `#` sets | Characters | Escapes |
149149
|----------------------------------------------|-----------------|------------|-------------|---------------------|
150-
| [Character](#character-literals) | `'H'` | `N/A` | All Unicode | `\'` & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
151-
| [String](#string-literals) | `"hello"` | `N/A` | All Unicode | `\"` & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
150+
| [Character](#character-literals) | `'H'` | `N/A` | All Unicode | [Quote](#quote-escapes) & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
151+
| [String](#string-literals) | `"hello"` | `N/A` | All Unicode | [Quote](#quote-escapes) & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
152152
| [Raw](#raw-string-literals) | `r#"hello"#` | `0...` | All Unicode | `N/A` |
153-
| [Byte](#byte-literals) | `b'H'` | `N/A` | All ASCII | `\'` & [Byte](#byte-escapes) |
154-
| [Byte string](#byte-string-literals) | `b"hello"` | `N/A` | All ASCII | `\"` & [Byte](#byte-escapes) |
153+
| [Byte](#byte-literals) | `b'H'` | `N/A` | All ASCII | [Quote](#quote-escapes) & [Byte](#byte-escapes) |
154+
| [Byte string](#byte-string-literals) | `b"hello"` | `N/A` | All ASCII | [Quote](#quote-escapes) & [Byte](#byte-escapes) |
155155
| [Raw byte string](#raw-byte-string-literals) | `br#"hello"#` | `0...` | All ASCII | `N/A` |
156156

157157
##### Byte escapes
@@ -163,12 +163,19 @@ a form of constant expression, so is evaluated (primarily) at compile time.
163163
| `\r` | Carriage return |
164164
| `\t` | Tab |
165165
| `\\` | Backslash |
166+
| `\0` | Null |
166167

167168
##### Unicode escapes
168169
| | Name |
169170
|---|------|
170171
| `\u{7FFF}` | 24-bit Unicode character code (up to 6 digits) |
171172

173+
##### Quote escapes
174+
| | Name |
175+
|---|------|
176+
| `\'` | Single quote |
177+
| `\"` | Double quote |
178+
172179
##### Numbers
173180

174181
| [Number literals](#number-literals)`*` | Example | Exponentiation | Suffixes |
@@ -2415,9 +2422,9 @@ in meaning to declaring the item outside the statement block.
24152422
> **Note**: there is no implicit capture of the function's dynamic environment when
24162423
> declaring a function-local item.
24172424
2418-
#### Variable declarations
2425+
#### `let` statements
24192426

2420-
A _variable declaration_ introduces a new set of variable, given by a pattern. The
2427+
A _`let` statement_ introduces a new set of variables, given by a pattern. The
24212428
pattern may be followed by a type annotation, and/or an initializer expression.
24222429
When no type annotation is given, the compiler will infer the type, or signal
24232430
an error if insufficient type information is available for definite inference.
@@ -3190,10 +3197,11 @@ let message = match maybe_digit {
31903197

31913198
### `if let` expressions
31923199

3193-
An `if let` expression is semantically identical to an `if` expression but in place
3194-
of a condition expression it expects a refutable let statement. If the value of the
3195-
expression on the right hand side of the let statement matches the pattern, the corresponding
3196-
block will execute, otherwise flow proceeds to the first `else` block that follows.
3200+
An `if let` expression is semantically identical to an `if` expression but in
3201+
place of a condition expression it expects a `let` statement with a refutable
3202+
pattern. If the value of the expression on the right hand side of the `let`
3203+
statement matches the pattern, the corresponding block will execute, otherwise
3204+
flow proceeds to the first `else` block that follows.
31973205

31983206
```
31993207
let dish = ("Ham", "Eggs");
@@ -3211,11 +3219,11 @@ if let ("Ham", b) = dish {
32113219

32123220
### `while let` loops
32133221

3214-
A `while let` loop is semantically identical to a `while` loop but in place of a
3215-
condition expression it expects a refutable let statement. If the value of the
3216-
expression on the right hand side of the let statement matches the pattern, the
3217-
loop body block executes and control returns to the pattern matching statement.
3218-
Otherwise, the while expression completes.
3222+
A `while let` loop is semantically identical to a `while` loop but in place of
3223+
a condition expression it expects `let` statement with a refutable pattern. If
3224+
the value of the expression on the right hand side of the `let` statement
3225+
matches the pattern, the loop body block executes and control returns to the
3226+
pattern matching statement. Otherwise, the while expression completes.
32193227

32203228
### `return` expressions
32213229

src/doc/trpl/ffi.md

+17
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,23 @@ foreign code. Rust is currently unable to call directly into a C++ library, but
88
snappy includes a C interface (documented in
99
[`snappy-c.h`](https://github.com/google/snappy/blob/master/snappy-c.h)).
1010

11+
## A note about libc
12+
13+
Many of these examples use [the `libc` crate][libc], which provides various
14+
type definitions for C types, among other things. If you’re trying these
15+
examples yourself, you’ll need to add `libc` to your `Cargo.toml`:
16+
17+
```toml
18+
[dependencies]
19+
libc = "0.2.0"
20+
```
21+
22+
[libc]: https://crates.io/crates/libc
23+
24+
and add `extern crate libc;` to your crate root.
25+
26+
## Calling foreign functions
27+
1128
The following is a minimal example of calling a foreign function which will
1229
compile if snappy is installed:
1330

src/doc/trpl/lifetimes.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,8 @@ reference to an `i32` with the lifetime `'a`’.
116116

117117
# In `struct`s
118118

119-
You’ll also need explicit lifetimes when working with [`struct`][structs]s:
119+
You’ll also need explicit lifetimes when working with [`struct`][structs]s that
120+
contain references:
120121

121122
```rust
122123
struct Foo<'a> {

src/libcore/iter.rs

+132-16
Original file line numberDiff line numberDiff line change
@@ -2375,32 +2375,118 @@ impl<'a, I: Iterator + ?Sized> Iterator for &'a mut I {
23752375
}
23762376

23772377
/// Conversion from an `Iterator`.
2378+
///
2379+
/// By implementing `FromIterator` for a type, you define how it will be
2380+
/// created from an iterator. This is common for types which describe a
2381+
/// collection of some kind.
2382+
///
2383+
/// `FromIterator`'s [`from_iter()`] is rarely called explicitly, and is instead
2384+
/// used through [`Iterator`]'s [`collect()`] method. See [`collect()`]'s
2385+
/// documentation for more examples.
2386+
///
2387+
/// [`from_iter()`]: #tymethod.from_iter
2388+
/// [`Iterator`]: trait.Iterator.html
2389+
/// [`collect()`]: trait.Iterator.html#method.collect
2390+
///
2391+
/// See also: [`IntoIterator`].
2392+
///
2393+
/// [`IntoIterator`]: trait.IntoIterator.html
2394+
///
2395+
/// # Examples
2396+
///
2397+
/// Basic usage:
2398+
///
2399+
/// ```
2400+
/// use std::iter::FromIterator;
2401+
///
2402+
/// let five_fives = std::iter::repeat(5).take(5);
2403+
///
2404+
/// let v = Vec::from_iter(five_fives);
2405+
///
2406+
/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
2407+
/// ```
2408+
///
2409+
/// Using [`collect()`] to implicitly use `FromIterator`:
2410+
///
2411+
/// ```
2412+
/// let five_fives = std::iter::repeat(5).take(5);
2413+
///
2414+
/// let v: Vec<i32> = five_fives.collect();
2415+
///
2416+
/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
2417+
/// ```
2418+
///
2419+
/// Implementing `FromIterator` for your type:
2420+
///
2421+
/// ```
2422+
/// use std::iter::FromIterator;
2423+
///
2424+
/// // A sample collection, that's just a wrapper over Vec<T>
2425+
/// #[derive(Debug)]
2426+
/// struct MyCollection(Vec<i32>);
2427+
///
2428+
/// // Let's give it some methods so we can create one and add things
2429+
/// // to it.
2430+
/// impl MyCollection {
2431+
/// fn new() -> MyCollection {
2432+
/// MyCollection(Vec::new())
2433+
/// }
2434+
///
2435+
/// fn add(&mut self, elem: i32) {
2436+
/// self.0.push(elem);
2437+
/// }
2438+
/// }
2439+
///
2440+
/// // and we'll implement FromIterator
2441+
/// impl FromIterator<i32> for MyCollection {
2442+
/// fn from_iter<I: IntoIterator<Item=i32>>(iterator: I) -> Self {
2443+
/// let mut c = MyCollection::new();
2444+
///
2445+
/// for i in iterator {
2446+
/// c.add(i);
2447+
/// }
2448+
///
2449+
/// c
2450+
/// }
2451+
/// }
2452+
///
2453+
/// // Now we can make a new iterator...
2454+
/// let iter = (0..5).into_iter();
2455+
///
2456+
/// // ... and make a MyCollection out of it
2457+
/// let c = MyCollection::from_iter(iter);
2458+
///
2459+
/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
2460+
///
2461+
/// // collect works too!
2462+
///
2463+
/// let iter = (0..5).into_iter();
2464+
/// let c: MyCollection = iter.collect();
2465+
///
2466+
/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
2467+
/// ```
23782468
#[stable(feature = "rust1", since = "1.0.0")]
23792469
#[rustc_on_unimplemented="a collection of type `{Self}` cannot be \
23802470
built from an iterator over elements of type `{A}`"]
23812471
pub trait FromIterator<A>: Sized {
2382-
/// Builds a container with elements from something iterable.
2472+
/// Creates a value from an iterator.
2473+
///
2474+
/// See the [module-level documentation] for more.
2475+
///
2476+
/// [module-level documentation]: trait.FromIterator.html
23832477
///
23842478
/// # Examples
23852479
///
2386-
/// ```
2387-
/// use std::collections::HashSet;
2388-
/// use std::iter::FromIterator;
2480+
/// Basic usage:
23892481
///
2390-
/// let colors_vec = vec!["red", "red", "yellow", "blue"];
2391-
/// let colors_set = HashSet::<&str>::from_iter(colors_vec);
2392-
/// assert_eq!(colors_set.len(), 3);
23932482
/// ```
2483+
/// use std::iter::FromIterator;
23942484
///
2395-
/// `FromIterator` is more commonly used implicitly via the
2396-
/// `Iterator::collect` method:
2485+
/// let five_fives = std::iter::repeat(5).take(5);
23972486
///
2398-
/// ```
2399-
/// use std::collections::HashSet;
2487+
/// let v = Vec::from_iter(five_fives);
24002488
///
2401-
/// let colors_vec = vec!["red", "red", "yellow", "blue"];
2402-
/// let colors_set = colors_vec.into_iter().collect::<HashSet<&str>>();
2403-
/// assert_eq!(colors_set.len(), 3);
2489+
/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
24042490
/// ```
24052491
#[stable(feature = "rust1", since = "1.0.0")]
24062492
fn from_iter<T: IntoIterator<Item=A>>(iterator: T) -> Self;
@@ -2415,9 +2501,13 @@ pub trait FromIterator<A>: Sized {
24152501
/// One benefit of implementing `IntoIterator` is that your type will [work
24162502
/// with Rust's `for` loop syntax](index.html#for-loops-and-intoiterator).
24172503
///
2504+
/// See also: [`FromIterator`].
2505+
///
2506+
/// [`FromIterator`]: trait.FromIterator.html
2507+
///
24182508
/// # Examples
24192509
///
2420-
/// Vectors implement `IntoIterator`:
2510+
/// Basic usage:
24212511
///
24222512
/// ```
24232513
/// let v = vec![1, 2, 3];
@@ -2489,7 +2579,33 @@ pub trait IntoIterator {
24892579
#[stable(feature = "rust1", since = "1.0.0")]
24902580
type IntoIter: Iterator<Item=Self::Item>;
24912581

2492-
/// Consumes `Self` and returns an iterator over it.
2582+
/// Creates an iterator from a value.
2583+
///
2584+
/// See the [module-level documentation] for more.
2585+
///
2586+
/// [module-level documentation]: trait.IntoIterator.html
2587+
///
2588+
/// # Examples
2589+
///
2590+
/// Basic usage:
2591+
///
2592+
/// ```
2593+
/// let v = vec![1, 2, 3];
2594+
///
2595+
/// let mut iter = v.into_iter();
2596+
///
2597+
/// let n = iter.next();
2598+
/// assert_eq!(Some(1), n);
2599+
///
2600+
/// let n = iter.next();
2601+
/// assert_eq!(Some(2), n);
2602+
///
2603+
/// let n = iter.next();
2604+
/// assert_eq!(Some(3), n);
2605+
///
2606+
/// let n = iter.next();
2607+
/// assert_eq!(None, n);
2608+
/// ```
24932609
#[stable(feature = "rust1", since = "1.0.0")]
24942610
fn into_iter(self) -> Self::IntoIter;
24952611
}

src/libcore/lib.rs

+4-1
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,15 @@
1010

1111
//! # The Rust Core Library
1212
//!
13-
//! The Rust Core Library is the dependency-free foundation of [The
13+
//! The Rust Core Library is the dependency-free[^free] foundation of [The
1414
//! Rust Standard Library](../std/index.html). It is the portable glue
1515
//! between the language and its libraries, defining the intrinsic and
1616
//! primitive building blocks of all Rust code. It links to no
1717
//! upstream libraries, no system libraries, and no libc.
1818
//!
19+
//! [^free]: Strictly speaking, there are some symbols which are needed but
20+
//! they aren't always neccesary.
21+
//!
1922
//! The core library is *minimal*: it isn't even aware of heap allocation,
2023
//! nor does it provide concurrency or I/O. These things require
2124
//! platform integration, and this library is platform-agnostic.

0 commit comments

Comments
 (0)