| | Example | `#` sets | Characters | Escapes |
|----------------------------------------------|-----------------|------------|-------------|---------------------|
-| [Character](#character-literals) | `'H'` | `N/A` | All Unicode | `\'` & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
-| [String](#string-literals) | `"hello"` | `N/A` | All Unicode | `\"` & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
+| [Character](#character-literals) | `'H'` | `N/A` | All Unicode | [Quote](#quote-escapes) & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
+| [String](#string-literals) | `"hello"` | `N/A` | All Unicode | [Quote](#quote-escapes) & [Byte](#byte-escapes) & [Unicode](#unicode-escapes) |
| [Raw](#raw-string-literals) | `r#"hello"#` | `0...` | All Unicode | `N/A` |
-| [Byte](#byte-literals) | `b'H'` | `N/A` | All ASCII | `\'` & [Byte](#byte-escapes) |
-| [Byte string](#byte-string-literals) | `b"hello"` | `N/A` | All ASCII | `\"` & [Byte](#byte-escapes) |
+| [Byte](#byte-literals) | `b'H'` | `N/A` | All ASCII | [Quote](#quote-escapes) & [Byte](#byte-escapes) |
+| [Byte string](#byte-string-literals) | `b"hello"` | `N/A` | All ASCII | [Quote](#quote-escapes) & [Byte](#byte-escapes) |
| [Raw byte string](#raw-byte-string-literals) | `br#"hello"#` | `0...` | All ASCII | `N/A` |
##### Byte escapes
| `\r` | Carriage return |
| `\t` | Tab |
| `\\` | Backslash |
+| `\0` | Null |
##### Unicode escapes
| | Name |
|---|------|
| `\u{7FFF}` | 24-bit Unicode character code (up to 6 digits) |
+##### Quote escapes
+| | Name |
+|---|------|
+| `\'` | Single quote |
+| `\"` | Double quote |
+
##### Numbers
| [Number literals](#number-literals)`*` | Example | Exponentiation | Suffixes |
> **Note**: there is no implicit capture of the function's dynamic environment when
> declaring a function-local item.
-#### Variable declarations
+#### `let` statements
-A _variable declaration_ introduces a new set of variable, given by a pattern. The
+A _`let` statement_ introduces a new set of variables, given by a pattern. The
pattern may be followed by a type annotation, and/or an initializer expression.
When no type annotation is given, the compiler will infer the type, or signal
an error if insufficient type information is available for definite inference.
### `if let` expressions
-An `if let` expression is semantically identical to an `if` expression but in place
-of a condition expression it expects a refutable let statement. If the value of the
-expression on the right hand side of the let statement matches the pattern, the corresponding
-block will execute, otherwise flow proceeds to the first `else` block that follows.
+An `if let` expression is semantically identical to an `if` expression but in
+place of a condition expression it expects a `let` statement with a refutable
+pattern. If the value of the expression on the right hand side of the `let`
+statement matches the pattern, the corresponding block will execute, otherwise
+flow proceeds to the first `else` block that follows.
```
let dish = ("Ham", "Eggs");
### `while let` loops
-A `while let` loop is semantically identical to a `while` loop but in place of a
-condition expression it expects a refutable let statement. If the value of the
-expression on the right hand side of the let statement matches the pattern, the
-loop body block executes and control returns to the pattern matching statement.
-Otherwise, the while expression completes.
+A `while let` loop is semantically identical to a `while` loop but in place of
+a condition expression it expects `let` statement with a refutable pattern. If
+the value of the expression on the right hand side of the `let` statement
+matches the pattern, the loop body block executes and control returns to the
+pattern matching statement. Otherwise, the while expression completes.
### `return` expressions
}
/// Conversion from an `Iterator`.
+///
+/// By implementing `FromIterator` for a type, you define how it will be
+/// created from an iterator. This is common for types which describe a
+/// collection of some kind.
+///
+/// `FromIterator`'s [`from_iter()`] is rarely called explicitly, and is instead
+/// used through [`Iterator`]'s [`collect()`] method. See [`collect()`]'s
+/// documentation for more examples.
+///
+/// [`from_iter()`]: #tymethod.from_iter
+/// [`Iterator`]: trait.Iterator.html
+/// [`collect()`]: trait.Iterator.html#method.collect
+///
+/// See also: [`IntoIterator`].
+///
+/// [`IntoIterator`]: trait.IntoIterator.html
+///
+/// # Examples
+///
+/// Basic usage:
+///
+/// ```
+/// use std::iter::FromIterator;
+///
+/// let five_fives = std::iter::repeat(5).take(5);
+///
+/// let v = Vec::from_iter(five_fives);
+///
+/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
+/// ```
+///
+/// Using [`collect()`] to implicitly use `FromIterator`:
+///
+/// ```
+/// let five_fives = std::iter::repeat(5).take(5);
+///
+/// let v: Vec<i32> = five_fives.collect();
+///
+/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
+/// ```
+///
+/// Implementing `FromIterator` for your type:
+///
+/// ```
+/// use std::iter::FromIterator;
+///
+/// // A sample collection, that's just a wrapper over Vec<T>
+/// #[derive(Debug)]
+/// struct MyCollection(Vec<i32>);
+///
+/// // Let's give it some methods so we can create one and add things
+/// // to it.
+/// impl MyCollection {
+/// fn new() -> MyCollection {
+/// MyCollection(Vec::new())
+/// }
+///
+/// fn add(&mut self, elem: i32) {
+/// self.0.push(elem);
+/// }
+/// }
+///
+/// // and we'll implement FromIterator
+/// impl FromIterator<i32> for MyCollection {
+/// fn from_iter<I: IntoIterator<Item=i32>>(iterator: I) -> Self {
+/// let mut c = MyCollection::new();
+///
+/// for i in iterator {
+/// c.add(i);
+/// }
+///
+/// c
+/// }
+/// }
+///
+/// // Now we can make a new iterator...
+/// let iter = (0..5).into_iter();
+///
+/// // ... and make a MyCollection out of it
+/// let c = MyCollection::from_iter(iter);
+///
+/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
+///
+/// // collect works too!
+///
+/// let iter = (0..5).into_iter();
+/// let c: MyCollection = iter.collect();
+///
+/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
+/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_on_unimplemented="a collection of type `{Self}` cannot be \
built from an iterator over elements of type `{A}`"]
pub trait FromIterator<A>: Sized {
- /// Builds a container with elements from something iterable.
+ /// Creates a value from an iterator.
+ ///
+ /// See the [module-level documentation] for more.
+ ///
+ /// [module-level documentation]: trait.FromIterator.html
///
/// # Examples
///
- /// ```
- /// use std::collections::HashSet;
- /// use std::iter::FromIterator;
+ /// Basic usage:
///
- /// let colors_vec = vec!["red", "red", "yellow", "blue"];
- /// let colors_set = HashSet::<&str>::from_iter(colors_vec);
- /// assert_eq!(colors_set.len(), 3);
/// ```
+ /// use std::iter::FromIterator;
///
- /// `FromIterator` is more commonly used implicitly via the
- /// `Iterator::collect` method:
+ /// let five_fives = std::iter::repeat(5).take(5);
///
- /// ```
- /// use std::collections::HashSet;
+ /// let v = Vec::from_iter(five_fives);
///
- /// let colors_vec = vec!["red", "red", "yellow", "blue"];
- /// let colors_set = colors_vec.into_iter().collect::<HashSet<&str>>();
- /// assert_eq!(colors_set.len(), 3);
+ /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn from_iter<T: IntoIterator<Item=A>>(iterator: T) -> Self;
/// One benefit of implementing `IntoIterator` is that your type will [work
/// with Rust's `for` loop syntax](index.html#for-loops-and-intoiterator).
///
+/// See also: [`FromIterator`].
+///
+/// [`FromIterator`]: trait.FromIterator.html
+///
/// # Examples
///
-/// Vectors implement `IntoIterator`:
+/// Basic usage:
///
/// ```
/// let v = vec![1, 2, 3];
#[stable(feature = "rust1", since = "1.0.0")]
type IntoIter: Iterator<Item=Self::Item>;
- /// Consumes `Self` and returns an iterator over it.
+ /// Creates an iterator from a value.
+ ///
+ /// See the [module-level documentation] for more.
+ ///
+ /// [module-level documentation]: trait.IntoIterator.html
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// let v = vec![1, 2, 3];
+ ///
+ /// let mut iter = v.into_iter();
+ ///
+ /// let n = iter.next();
+ /// assert_eq!(Some(1), n);
+ ///
+ /// let n = iter.next();
+ /// assert_eq!(Some(2), n);
+ ///
+ /// let n = iter.next();
+ /// assert_eq!(Some(3), n);
+ ///
+ /// let n = iter.next();
+ /// assert_eq!(None, n);
+ /// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn into_iter(self) -> Self::IntoIter;
}
projects / rust.git / commitdiff