Commit c4e17347 authored by bors's avatar bors

Auto merge of #74017 - poliorcetics:where-keyword, r=jyn514

Document the where keyword

Partial fix of #34601 (and last PR for it 馃帀).

This documents the `where` keyword.

@rustbot modify labels: T-doc,C-enhancement
parents 1e55f584 6af60d3e
......@@ -1870,9 +1870,100 @@ mod use_keyword {}
//
/// Add constraints that must be upheld to use an item.
///
/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
/// `where` allows specifying constraints on lifetime and generic parameters.
/// The [RFC] introducing `where` contains detailed informations about the
/// keyword.
///
/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
/// # Examples
///
/// `where` can be used for constraints with traits:
///
/// ```rust
/// fn new<T: Default>() -> T {
/// T::default()
/// }
///
/// fn new_where<T>() -> T
/// where
/// T: Default,
/// {
/// T::default()
/// }
///
/// assert_eq!(0.0, new());
/// assert_eq!(0.0, new_where());
///
/// assert_eq!(0, new());
/// assert_eq!(0, new_where());
/// ```
///
/// `where` can also be used for lifetimes.
///
/// This compiles because `longer` outlives `shorter`, thus the constraint is
/// respected:
///
/// ```rust
/// fn select<'short, 'long>(s1: &'short str, s2: &'long str, second: bool) -> &'short str
/// where
/// 'long: 'short,
/// {
/// if second { s2 } else { s1 }
/// }
///
/// let outer = String::from("Long living ref");
/// let longer = &outer;
/// {
/// let inner = String::from("Short living ref");
/// let shorter = &inner;
///
/// assert_eq!(select(shorter, longer, false), shorter);
/// assert_eq!(select(shorter, longer, true), longer);
/// }
/// ```
///
/// On the other hand, this will not compile because the `where 'b: 'a` clause
/// is missing: the `'b` lifetime is not known to live at least as long as `'a`
/// which means this function cannot ensure it always returns a valid reference:
///
/// ```rust,compile_fail,E0623
/// fn select<'a, 'b>(s1: &'a str, s2: &'b str, second: bool) -> &'a str
/// {
/// if second { s2 } else { s1 }
/// }
/// ```
///
/// `where` can also be used to express more complicated constraints that cannot
/// be written with the `<T: Trait>` syntax:
///
/// ```rust
/// fn first_or_default<I>(mut i: I) -> I::Item
/// where
/// I: Iterator,
/// I::Item: Default,
/// {
/// i.next().unwrap_or_else(I::Item::default)
/// }
///
/// assert_eq!(first_or_default(vec![1, 2, 3].into_iter()), 1);
/// assert_eq!(first_or_default(Vec::<i32>::new().into_iter()), 0);
/// ```
///
/// `where` is available anywhere generic and lifetime parameters are available,
/// as can be seen with the [`Cow`](crate::borrow::Cow) type from the standard
/// library:
///
/// ```rust
/// # #![allow(dead_code)]
/// pub enum Cow<'a, B>
/// where
/// B: 'a + ToOwned + ?Sized,
/// {
/// Borrowed(&'a B),
/// Owned(<B as ToOwned>::Owned),
/// }
/// ```
///
/// [RFC]: https://github.com/rust-lang/rfcs/blob/master/text/0135-where.md
mod where_keyword {}
// 2018 Edition keywords
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment