mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #37627 - GuillaumeGomez:missing_urls_bis, r=frewsxcv

Browse Source 
Add missing urls and few local rewrites

r? @steveklabnik
This commit is contained in:
Eduard-Mihai Burtescu 2016-11-09 20:51:18 +02:00 committed by GitHub
commit e0894cafd5
1 changed files with 92 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
src/libcore/iter/iterator.rs
View File

@ -35,11 +35,14 @@ pub trait Iterator {
/// Advances the iterator and returns the next value.
///
/// Returns `None` when iteration is finished. Individual iterator
/// Returns [`None`] when iteration is finished. Individual iterator
/// implementations may choose to resume iteration, and so calling `next()`
/// again may or may not eventually start returning `Some(Item)` again at some
/// again may or may not eventually start returning [`Some(Item)`] again at some
/// point.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`Some(Item)`]: ../../std/option/enum.Option.html#variant.Some
///
/// # Examples
///
/// Basic usage:
@ -69,9 +72,9 @@ pub trait Iterator {
/// Specifically, `size_hint()` returns a tuple where the first element
/// is the lower bound, and the second element is the upper bound.
///
/// The second half of the tuple that is returned is an `Option<usize>`. A
/// `None` here means that either there is no known upper bound, or the
/// upper bound is larger than `usize`.
/// The second half of the tuple that is returned is an [`Option`]`<`[`usize`]`>`.
/// A [`None`] here means that either there is no known upper bound, or the
/// upper bound is larger than [`usize`].
///
/// # Implementation notes
///
@ -91,6 +94,10 @@ pub trait Iterator {
/// The default implementation returns `(0, None)` which is correct for any
/// iterator.
///
/// [`usize`]: ../../std/primitive.usize.html
/// [`Option`]: ../../std/option/enum.Option.html
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
@ -134,23 +141,26 @@ fn size_hint(&self) -> (usize, Option<usize>) { (0, None) }
/// Consumes the iterator, counting the number of iterations and returning it.
///
/// This method will evaluate the iterator until its [`next()`] returns
/// `None`. Once `None` is encountered, `count()` returns the number of
/// [`None`]. Once [`None`] is encountered, `count()` returns the number of
/// times it called [`next()`].
///
/// [`next()`]: #tymethod.next
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Overflow Behavior
///
/// The method does no guarding against overflows, so counting elements of
/// an iterator with more than `usize::MAX` elements either produces the
/// an iterator with more than [`usize::MAX`] elements either produces the
/// wrong result or panics. If debug assertions are enabled, a panic is
/// guaranteed.
///
/// # Panics
///
/// This function might panic if the iterator has more than `usize::MAX`
/// This function might panic if the iterator has more than [`usize::MAX`]
/// elements.
///
/// [`usize::MAX`]: ../../std/isize/constant.MAX.html
///
/// # Examples
///
/// Basic usage:
@ -172,10 +182,12 @@ fn count(self) -> usize where Self: Sized {
/// Consumes the iterator, returning the last element.
///
/// This method will evaluate the iterator until it returns `None`. While
/// doing so, it keeps track of the current element. After `None` is
/// This method will evaluate the iterator until it returns [`None`]. While
/// doing so, it keeps track of the current element. After [`None`] is
/// returned, `last()` will then return the last element it saw.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
@ -202,9 +214,11 @@ fn last(self) -> Option<Self::Item> where Self: Sized {
/// Like most indexing operations, the count starts from zero, so `nth(0)`
/// returns the first value, `nth(1)` the second, and so on.
///
/// `nth()` will return `None` if `n` is greater than or equal to the length of the
/// `nth()` will return [`None`] if `n` is greater than or equal to the length of the
/// iterator.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
@ -306,8 +320,8 @@ fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter> where
///
/// In other words, it zips two iterators together, into a single one.
///
/// When either iterator returns `None`, all further calls to `next()`
/// will return `None`.
/// When either iterator returns [`None`], all further calls to [`next()`]
/// will return [`None`].
///
/// # Examples
///
@ -346,7 +360,7 @@ fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter> where
/// ```
///
/// `zip()` is often used to zip an infinite iterator to a finite one.
/// This works because the finite iterator will eventually return `None`,
/// This works because the finite iterator will eventually return [`None`],
/// ending the zipper. Zipping with `(0..)` can look a lot like [`enumerate()`]:
///
/// ```
@ -365,6 +379,8 @@ fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter> where
/// ```
///
/// [`enumerate()`]: trait.Iterator.html#method.enumerate
/// [`next()`]: ../../std/iter/trait.Iterator.html#tymethod.next
/// [`None`]: ../../std/option/enum.Option.html#variant.None
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter> where
@ -501,11 +517,9 @@ fn filter<P>(self, predicate: P) -> Filter<Self, P> where
///
/// The closure must return an [`Option<T>`]. `filter_map()` creates an
/// iterator which calls this closure on each element. If the closure
/// returns `Some(element)`, then that element is returned. If the
/// closure returns `None`, it will try again, and call the closure on the
/// next element, seeing if it will return `Some`.
///
/// [`Option<T>`]: ../../std/option/enum.Option.html
/// returns [`Some(element)`][`Some`], then that element is returned. If the
/// closure returns [`None`], it will try again, and call the closure on the
/// next element, seeing if it will return [`Some`].
///
/// Why `filter_map()` and not just [`filter()`].[`map()`]? The key is in this
/// part:
@ -513,11 +527,11 @@ fn filter<P>(self, predicate: P) -> Filter<Self, P> where
/// [`filter()`]: #method.filter
/// [`map()`]: #method.map
///
/// > If the closure returns `Some(element)`, then that element is returned.
/// > If the closure returns [`Some(element)`][`Some`], then that element is returned.
///
/// In other words, it removes the [`Option<T>`] layer automatically. If your
/// mapping is already returning an [`Option<T>`] and you want to skip over
/// `None`s, then `filter_map()` is much, much nicer to use.
/// [`None`]s, then `filter_map()` is much, much nicer to use.
///
/// # Examples
///
@ -547,7 +561,11 @@ fn filter<P>(self, predicate: P) -> Filter<Self, P> where
/// assert_eq!(iter.next(), None);
/// ```
///
/// There's an extra layer of `Some` in there.
/// There's an extra layer of [`Some`] in there.
///
/// [`Option<T>`]: ../../std/option/enum.Option.html
/// [`Some`]: ../../std/option/enum.Option.html#variant.Some
/// [`None`]: ../../std/option/enum.Option.html#variant.None
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> where
@ -567,21 +585,20 @@ fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> where
/// different sized integer, the [`zip()`] function provides similar
/// functionality.
///
/// [`usize`]: ../../std/primitive.usize.html
/// [`zip()`]: #method.zip
///
/// # Overflow Behavior
///
/// The method does no guarding against overflows, so enumerating more than
/// [`usize::MAX`] elements either produces the wrong result or panics. If
/// debug assertions are enabled, a panic is guaranteed.
///
/// [`usize::MAX`]: ../../std/usize/constant.MAX.html
///
/// # Panics
///
/// The returned iterator might panic if the to-be-returned index would
/// overflow a `usize`.
/// overflow a [`usize`].
///
/// [`usize::MAX`]: ../../std/usize/constant.MAX.html
/// [`usize`]: ../../std/primitive.usize.html
/// [`zip()`]: #method.zip
///
/// # Examples
///
@ -607,12 +624,13 @@ fn enumerate(self) -> Enumerate<Self> where Self: Sized {
/// Adds a [`peek()`] method to an iterator. See its documentation for
/// more information.
///
/// Note that the underlying iterator is still advanced when `peek` is
/// Note that the underlying iterator is still advanced when [`peek()`] is
/// called for the first time: In order to retrieve the next element,
/// `next` is called on the underlying iterator, hence any side effects of
/// the `next` method will occur.
/// [`next()`] is called on the underlying iterator, hence any side effects of
/// the [`next()`] method will occur.
///
/// [`peek()`]: struct.Peekable.html#method.peek
/// [`next()`]: ../../std/iter/trait.Iterator.html#tymethod.next
///
/// # Examples
///
@ -894,12 +912,12 @@ fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F>
/// an extra layer of indirection. `flat_map()` will remove this extra layer
/// on its own.
///
/// [`map()`]: #method.map
///
/// Another way of thinking about `flat_map()`: [`map()`]'s closure returns
/// one item for each element, and `flat_map()`'s closure returns an
/// iterator for each element.
///
/// [`map()`]: #method.map
///
/// # Examples
///
/// Basic usage:
@ -921,11 +939,14 @@ fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F>
FlatMap{iter: self, f: f, frontiter: None, backiter: None }
}
/// Creates an iterator which ends after the first `None`.
/// Creates an iterator which ends after the first [`None`].
///
/// After an iterator returns `None`, future calls may or may not yield
/// `Some(T)` again. `fuse()` adapts an iterator, ensuring that after a
/// `None` is given, it will always return `None` forever.
/// After an iterator returns [`None`], future calls may or may not yield
/// [`Some(T)`] again. `fuse()` adapts an iterator, ensuring that after a
/// [`None`] is given, it will always return [`None`] forever.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`Some(T)`]: ../../std/option/enum.Option.html#variant.Some
///
/// # Examples
///
@ -1082,19 +1103,15 @@ fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
/// library, used in a variety of contexts.
///
/// The most basic pattern in which `collect()` is used is to turn one
/// collection into another. You take a collection, call `iter()` on it,
/// collection into another. You take a collection, call [`iter()`] on it,
/// do a bunch of transformations, and then `collect()` at the end.
///
/// One of the keys to `collect()`'s power is that many things you might
/// not think of as 'collections' actually are. For example, a [`String`]
/// is a collection of [`char`]s. And a collection of [`Result<T, E>`] can
/// be thought of as single `Result<Collection<T>, E>`. See the examples
/// be thought of as single [`Result`]`<Collection<T>, E>`. See the examples
/// below for more.
///
/// [`String`]: ../../std/string/struct.String.html
/// [`Result<T, E>`]: ../../std/result/enum.Result.html
/// [`char`]: ../../std/primitive.char.html
///
/// Because `collect()` is so general, it can cause problems with type
/// inference. As such, `collect()` is one of the few times you'll see
/// the syntax affectionately known as the 'turbofish': `::<>`. This
@ -1172,7 +1189,7 @@ fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
/// assert_eq!("hello", hello);
/// ```
///
/// If you have a list of [`Result<T, E>`]s, you can use `collect()` to
/// If you have a list of [`Result<T, E>`][`Result`]s, you can use `collect()` to
/// see if any of them failed:
///
/// ```
@ -1190,6 +1207,11 @@ fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
/// // gives us the list of answers
/// assert_eq!(Ok(vec![1, 3]), result);
/// ```
///
/// [`iter()`]: ../../std/iter/trait.Iterator.html#tymethod.next
/// [`String`]: ../../std/string/struct.String.html
/// [`char`]: ../../std/primitive.char.html
/// [`Result`]: ../../std/result/enum.Result.html
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
fn collect<B: FromIterator<Self::Item>>(self) -> B where Self: Sized {
@ -1281,6 +1303,8 @@ fn partition<B, F>(self, mut f: F) -> (B, B) where
/// use a `for` loop with a list of things to build up a result. Those
/// can be turned into `fold()`s:
///
/// [`for`]: ../../book/loops.html#for
///
/// ```
/// let numbers = [1, 2, 3, 4, 5];
///
@ -1414,8 +1438,8 @@ fn any<F>(&mut self, mut f: F) -> bool where
///
/// `find()` takes a closure that returns `true` or `false`. It applies
/// this closure to each element of the iterator, and if any of them return
/// `true`, then `find()` returns `Some(element)`. If they all return
/// `false`, it returns `None`.
/// `true`, then `find()` returns [`Some(element)`]. If they all return
/// `false`, it returns [`None`].
///
/// `find()` is short-circuiting; in other words, it will stop processing
/// as soon as the closure returns `true`.
@ -1425,6 +1449,9 @@ fn any<F>(&mut self, mut f: F) -> bool where
/// argument is a double reference. You can see this effect in the
/// examples below, with `&&x`.
///
/// [`Some(element)`]: ../../std/option/enum.Option.html#variant.Some
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
@ -1465,8 +1492,8 @@ fn find<P>(&mut self, mut predicate: P) -> Option<Self::Item> where
///
/// `position()` takes a closure that returns `true` or `false`. It applies
/// this closure to each element of the iterator, and if one of them
/// returns `true`, then `position()` returns `Some(index)`. If all of
/// them return `false`, it returns `None`.
/// returns `true`, then `position()` returns [`Some(index)`]. If all of
/// them return `false`, it returns [`None`].
///
/// `position()` is short-circuiting; in other words, it will stop
/// processing as soon as it finds a `true`.
@ -1474,7 +1501,7 @@ fn find<P>(&mut self, mut predicate: P) -> Option<Self::Item> where
/// # Overflow Behavior
///
/// The method does no guarding against overflows, so if there are more
/// than `usize::MAX` non-matching elements, it either produces the wrong
/// than [`usize::MAX`] non-matching elements, it either produces the wrong
/// result or panics. If debug assertions are enabled, a panic is
/// guaranteed.
///
@ -1483,6 +1510,10 @@ fn find<P>(&mut self, mut predicate: P) -> Option<Self::Item> where
/// This function might panic if the iterator has more than `usize::MAX`
/// non-matching elements.
///
/// [`Some(index)`]: ../../std/option/enum.Option.html#variant.Some
/// [`None`]: ../../std/option/enum.Option.html#variant.None
/// [`usize::MAX`]: ../../std/usize/constant.MAX.html
///
/// # Examples
///
/// Basic usage:
@ -1528,11 +1559,14 @@ fn position<P>(&mut self, mut predicate: P) -> Option<usize> where
/// `rposition()` takes a closure that returns `true` or `false`. It applies
/// this closure to each element of the iterator, starting from the end,
/// and if one of them returns `true`, then `rposition()` returns
/// `Some(index)`. If all of them return `false`, it returns `None`.
/// [`Some(index)`]. If all of them return `false`, it returns [`None`].
///
/// `rposition()` is short-circuiting; in other words, it will stop
/// processing as soon as it finds a `true`.
///
/// [`Some(index)`]: ../../std/option/enum.Option.html#variant.Some
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
@ -1798,11 +1832,13 @@ fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB) where
(ts, us)
}
/// Creates an iterator which `clone()`s all of its elements.
/// Creates an iterator which [`clone()`]s all of its elements.
///
/// This is useful when you have an iterator over `&T`, but you need an
/// iterator over `T`.
///
/// [`clone()`]: ../../std/clone/trait.Clone.html#tymethod.clone
///
/// # Examples
///
/// Basic usage:
@ -1827,10 +1863,12 @@ fn cloned<'a, T: 'a>(self) -> Cloned<Self>
/// Repeats an iterator endlessly.
///
/// Instead of stopping at `None`, the iterator will instead start again,
/// Instead of stopping at [`None`], the iterator will instead start again,
/// from the beginning. After iterating again, it will start at the
/// beginning again. And again. And again. Forever.
///
/// [`None`]: ../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// Basic usage:
@ -1862,7 +1900,7 @@ fn cycle(self) -> Cycle<Self> where Self: Sized + Clone {
///
/// # Panics
///
/// When calling `sum` and a primitive integer type is being returned, this
/// When calling `sum()` and a primitive integer type is being returned, this
/// method will panic if the computation overflows and debug assertions are
/// enabled.
///
@ -1890,7 +1928,7 @@ fn sum<S>(self) -> S
///
/// # Panics
///
/// When calling `product` and a primitive integer type is being returned,
/// When calling `product()` and a primitive integer type is being returned,
/// method will panic if the computation overflows and debug assertions are
/// enabled.
///