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

Rollup merge of #76867 - poliorcetics:intra-doc-core-iter, r=jyn514

Browse Source 
Use intra-doc links in core/src/iter when possible

Helps with #75080.

I also updated lots of links to use `fn()` instead of `fn` when possible.

@rustbot modify labels: T-doc A-intra-doc-links

r? @jyn514
This commit is contained in:
Ralf Jung 2020-09-21 10:40:32 +02:00 committed by GitHub
commit 5031242606
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 93 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
library/core/src/iter/sources.rs
View File

@ -5,9 +5,7 @@ use super::{FusedIterator, TrustedLen};
/// An iterator that repeats an element endlessly.
///
/// This `struct` is created by the [`repeat`] function. See its documentation for more.
///
/// [`repeat`]: fn.repeat.html
/// This `struct` is created by the [`repeat()`] function. See its documentation for more.
#[derive(Clone, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct Repeat<A> {
@ -47,15 +45,11 @@ unsafe impl<A: Clone> TrustedLen for Repeat<A> {}
/// The `repeat()` function repeats a single value over and over again.
///
/// Infinite iterators like `repeat()` are often used with adapters like
/// [`take`], in order to make them finite.
///
/// [`take`]: trait.Iterator.html#method.take
/// [`Iterator::take()`], in order to make them finite.
///
/// If the element type of the iterator you need does not implement `Clone`,
/// or if you do not want to keep the repeated element in memory, you can
/// instead use the [`repeat_with`] function.
///
/// [`repeat_with`]: fn.repeat_with.html
/// instead use the [`repeat_with()`] function.
///
/// # Examples
///
@ -77,7 +71,7 @@ unsafe impl<A: Clone> TrustedLen for Repeat<A> {}
/// assert_eq!(Some(4), fours.next());
/// ```
///
/// Going finite with [`take`]:
/// Going finite with [`Iterator::take()`]:
///
/// ```
/// use std::iter;
@ -102,10 +96,8 @@ pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
/// An iterator that repeats elements of type `A` endlessly by
/// applying the provided closure `F: FnMut() -> A`.
///
/// This `struct` is created by the [`repeat_with`] function.
/// This `struct` is created by the [`repeat_with()`] function.
/// See its documentation for more.
///
/// [`repeat_with`]: fn.repeat_with.html
#[derive(Copy, Clone, Debug)]
#[stable(feature = "iterator_repeat_with", since = "1.28.0")]
pub struct RepeatWith<F> {
@ -139,20 +131,18 @@ unsafe impl<A, F: FnMut() -> A> TrustedLen for RepeatWith<F> {}
/// The `repeat_with()` function calls the repeater over and over again.
///
/// Infinite iterators like `repeat_with()` are often used with adapters like
/// [`take`], in order to make them finite.
/// [`Iterator::take()`], in order to make them finite.
///
/// [`take`]: trait.Iterator.html#method.take
///
/// If the element type of the iterator you need implements `Clone`, and
/// If the element type of the iterator you need implements [`Clone`], and
/// it is OK to keep the source element in memory, you should instead use
/// the [`repeat`] function.
/// the [`repeat()`] function.
///
/// [`repeat`]: fn.repeat.html
///
/// An iterator produced by `repeat_with()` is not a `DoubleEndedIterator`.
/// If you need `repeat_with()` to return a `DoubleEndedIterator`,
/// An iterator produced by `repeat_with()` is not a [`DoubleEndedIterator`].
/// If you need `repeat_with()` to return a [`DoubleEndedIterator`],
/// please open a GitHub issue explaining your use case.
///
/// [`DoubleEndedIterator`]: crate::iter::DoubleEndedIterator
///
/// # Examples
///
/// Basic usage:
@ -201,9 +191,7 @@ pub fn repeat_with<A, F: FnMut() -> A>(repeater: F) -> RepeatWith<F> {
/// An iterator that yields nothing.
///
/// This `struct` is created by the [`empty`] function. See its documentation for more.
///
/// [`empty`]: fn.empty.html
/// This `struct` is created by the [`empty()`] function. See its documentation for more.
#[stable(feature = "iter_empty", since = "1.2.0")]
pub struct Empty<T>(marker::PhantomData<T>);
@ -292,9 +280,7 @@ pub const fn empty<T>() -> Empty<T> {
/// An iterator that yields an element exactly once.
///
/// This `struct` is created by the [`once`] function. See its documentation for more.
///
/// [`once`]: fn.once.html
/// This `struct` is created by the [`once()`] function. See its documentation for more.
#[derive(Clone, Debug)]
#[stable(feature = "iter_once", since = "1.2.0")]
pub struct Once<T> {
@ -336,12 +322,12 @@ impl<T> FusedIterator for Once<T> {}
/// Creates an iterator that yields an element exactly once.
///
/// This is commonly used to adapt a single value into a [`chain`] of other
/// This is commonly used to adapt a single value into a [`chain()`] of other
/// kinds of iteration. Maybe you have an iterator that covers almost
/// everything, but you need an extra special case. Maybe you have a function
/// which works on iterators, but you only need to process one value.
///
/// [`chain`]: trait.Iterator.html#method.chain
/// [`chain()`]: Iterator::chain
///
/// # Examples
///
@ -393,10 +379,8 @@ pub fn once<T>(value: T) -> Once<T> {
/// An iterator that yields a single element of type `A` by
/// applying the provided closure `F: FnOnce() -> A`.
///
/// This `struct` is created by the [`once_with`] function.
/// This `struct` is created by the [`once_with()`] function.
/// See its documentation for more.
///
/// [`once_with`]: fn.once_with.html
#[derive(Clone, Debug)]
#[stable(feature = "iter_once_with", since = "1.43.0")]
pub struct OnceWith<F> {
@ -442,15 +426,14 @@ unsafe impl<A, F: FnOnce() -> A> TrustedLen for OnceWith<F> {}
/// Creates an iterator that lazily generates a value exactly once by invoking
/// the provided closure.
///
/// This is commonly used to adapt a single value generator into a [`chain`] of
/// This is commonly used to adapt a single value generator into a [`chain()`] of
/// other kinds of iteration. Maybe you have an iterator that covers almost
/// everything, but you need an extra special case. Maybe you have a function
/// which works on iterators, but you only need to process one value.
///
/// Unlike [`once`], this function will lazily generate the value on request.
/// Unlike [`once()`], this function will lazily generate the value on request.
///
/// [`once`]: fn.once.html
/// [`chain`]: trait.Iterator.html#method.chain
/// [`chain()`]: Iterator::chain
///
/// # Examples
///
@ -505,17 +488,16 @@ pub fn once_with<A, F: FnOnce() -> A>(gen: F) -> OnceWith<F> {
///
/// This allows creating a custom iterator with any behavior
/// without using the more verbose syntax of creating a dedicated type
/// and implementing the `Iterator` trait for it.
/// and implementing the [`Iterator`] trait for it.
///
/// Note that the `FromFn` iterator doesn’t make assumptions about the behavior of the closure,
/// and therefore conservatively does not implement [`FusedIterator`],
/// or override [`Iterator::size_hint`] from its default `(0, None)`.
///
/// [`FusedIterator`]: trait.FusedIterator.html
/// [`Iterator::size_hint`]: trait.Iterator.html#method.size_hint
/// or override [`Iterator::size_hint()`] from its default `(0, None)`.
///
/// The closure can use captures and its environment to track state across iterations. Depending on
/// how the iterator is used, this may require specifying the `move` keyword on the closure.
/// how the iterator is used, this may require specifying the [`move`] keyword on the closure.
///
/// [`move`]: ../../std/keyword.move.html
///
/// # Examples
///
@ -549,10 +531,10 @@ where
/// An iterator where each iteration calls the provided closure `F: FnMut() -> Option<T>`.
///
/// This `struct` is created by the [`iter::from_fn`] function.
/// This `struct` is created by the [`iter::from_fn()`] function.
/// See its documentation for more.
///
/// [`iter::from_fn`]: fn.from_fn.html
/// [`iter::from_fn()`]: from_fn
#[derive(Clone)]
#[stable(feature = "iter_from_fn", since = "1.34.0")]
pub struct FromFn<F>(F);
@ -601,10 +583,10 @@ where
/// An new iterator where each successive item is computed based on the preceding one.
///
/// This `struct` is created by the [`successors`] function.
/// This `struct` is created by the [`iter::successors()`] function.
/// See its documentation for more.
///
/// [`successors`]: fn.successors.html
/// [`iter::successors()`]: successors
#[derive(Clone)]
#[stable(feature = "iter_successors", since = "1.34.0")]
pub struct Successors<T, F> {

46
library/core/src/iter/traits/accum.rs
View File

@ -4,14 +4,13 @@ use crate::ops::{Add, Mul};
/// Trait to represent types that can be created by summing up an iterator.
///
/// This trait is used to implement the [`sum`] method on iterators. Types which
/// implement the trait can be generated by the [`sum`] method. Like
/// This trait is used to implement the [`sum()`] method on iterators. Types which
/// implement the trait can be generated by the [`sum()`] method. Like
/// [`FromIterator`] this trait should rarely be called directly and instead
/// interacted with through [`Iterator::sum`].
/// interacted with through [`Iterator::sum()`].
///
/// [`sum`]: #tymethod.sum
/// [`FromIterator`]: crate::iter::FromIterator
/// [`Iterator::sum`]: crate::iter::Iterator::sum
/// [`sum()`]: Sum::sum
/// [`FromIterator`]: iter::FromIterator
#[stable(feature = "iter_arith_traits", since = "1.12.0")]
pub trait Sum<A = Self>: Sized {
/// Method which takes an iterator and generates `Self` from the elements by
@ -23,14 +22,13 @@ pub trait Sum<A = Self>: Sized {
/// Trait to represent types that can be created by multiplying elements of an
/// iterator.
///
/// This trait is used to implement the [`product`] method on iterators. Types
/// which implement the trait can be generated by the [`product`] method. Like
/// This trait is used to implement the [`product()`] method on iterators. Types
/// which implement the trait can be generated by the [`product()`] method. Like
/// [`FromIterator`] this trait should rarely be called directly and instead
/// interacted with through [`Iterator::product`].
/// interacted with through [`Iterator::product()`].
///
/// [`product`]: #tymethod.product
/// [`FromIterator`]: crate::iter::FromIterator
/// [`Iterator::product`]: crate::iter::Iterator::product
/// [`product()`]: Product::product
/// [`FromIterator`]: iter::FromIterator
#[stable(feature = "iter_arith_traits", since = "1.12.0")]
pub trait Product<A = Self>: Sized {
/// Method which takes an iterator and generates `Self` from the elements by
@ -120,9 +118,9 @@ impl<T, U, E> Sum<Result<U, E>> for Result<T, E>
where
T: Sum<U>,
{
/// Takes each element in the `Iterator`: if it is an `Err`, no further
/// elements are taken, and the `Err` is returned. Should no `Err` occur,
/// the sum of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is an [`Err`], no further
/// elements are taken, and the [`Err`] is returned. Should no [`Err`]
/// occur, the sum of all elements is returned.
///
/// # Examples
///
@ -150,9 +148,9 @@ impl<T, U, E> Product<Result<U, E>> for Result<T, E>
where
T: Product<U>,
{
/// Takes each element in the `Iterator`: if it is an `Err`, no further
/// elements are taken, and the `Err` is returned. Should no `Err` occur,
/// the product of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is an [`Err`], no further
/// elements are taken, and the [`Err`] is returned. Should no [`Err`]
/// occur, the product of all elements is returned.
fn product<I>(iter: I) -> Result<T, E>
where
I: Iterator<Item = Result<U, E>>,
@ -166,9 +164,9 @@ impl<T, U> Sum<Option<U>> for Option<T>
where
T: Sum<U>,
{
/// Takes each element in the `Iterator`: if it is a `None`, no further
/// elements are taken, and the `None` is returned. Should no `None` occur,
/// the sum of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is a [`None`], no further
/// elements are taken, and the [`None`] is returned. Should no [`None`]
/// occur, the sum of all elements is returned.
///
/// # Examples
///
@ -193,9 +191,9 @@ impl<T, U> Product<Option<U>> for Option<T>
where
T: Product<U>,
{
/// Takes each element in the `Iterator`: if it is a `None`, no further
/// elements are taken, and the `None` is returned. Should no `None` occur,
/// the product of all elements is returned.
/// Takes each element in the [`Iterator`]: if it is a [`None`], no further
/// elements are taken, and the [`None`] is returned. Should no [`None`]
/// occur, the product of all elements is returned.
fn product<I>(iter: I) -> Option<T>
where
I: Iterator<Item = Option<U>>,

20
library/core/src/iter/traits/collect.rs
View File

@ -1,21 +1,15 @@
/// Conversion from an `Iterator`.
/// 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
/// [`FromIterator::from_iter()`] is rarely called explicitly, and is instead
/// used through [`Iterator::collect()`] method. See [`Iterator::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:
@ -30,7 +24,7 @@
/// assert_eq!(v, vec![5, 5, 5, 5, 5]);
/// ```
///
/// Using [`collect`] to implicitly use `FromIterator`:
/// Using [`Iterator::collect()`] to implicitly use `FromIterator`:
///
/// ```
/// let five_fives = std::iter::repeat(5).take(5);
@ -119,7 +113,7 @@ pub trait FromIterator<A>: Sized {
fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self;
}
/// Conversion into an `Iterator`.
/// Conversion into an [`Iterator`].
///
/// By implementing `IntoIterator` for a type, you define how it will be
/// converted to an iterator. This is common for types which describe a
@ -130,8 +124,6 @@ pub trait FromIterator<A>: Sized {
///
/// See also: [`FromIterator`].
///
/// [`FromIterator`]: trait.FromIterator.html
///
/// # Examples
///
/// Basic usage:
@ -326,7 +318,7 @@ pub trait Extend<A> {
/// As this is the only required method for this trait, the [trait-level] docs
/// contain more details.
///
/// [trait-level]: trait.Extend.html
/// [trait-level]: Extend
///
/// # Examples
///

39
library/core/src/iter/traits/double_ended.rs
View File

@ -10,11 +10,12 @@ use crate::ops::{ControlFlow, Try};
/// and do not cross: iteration is over when they meet in the middle.
///
/// In a similar fashion to the [`Iterator`] protocol, once a
/// `DoubleEndedIterator` returns `None` from a `next_back()`, calling it again
/// may or may not ever return `Some` again. `next()` and `next_back()` are
/// interchangeable for this purpose.
/// `DoubleEndedIterator` returns [`None`] from a [`next_back()`], calling it
/// again may or may not ever return [`Some`] again. [`next()`] and
/// [`next_back()`] are interchangeable for this purpose.
///
/// [`Iterator`]: trait.Iterator.html
/// [`next_back()`]: DoubleEndedIterator::next_back
/// [`next()`]: Iterator::next
///
/// # Examples
///
@ -42,7 +43,7 @@ pub trait DoubleEndedIterator: Iterator {
///
/// The [trait-level] docs contain more details.
///
/// [trait-level]: trait.DoubleEndedIterator.html
/// [trait-level]: DoubleEndedIterator
///
/// # Examples
///
@ -66,7 +67,7 @@ pub trait DoubleEndedIterator: Iterator {
/// # Remarks
///
/// The elements yielded by `DoubleEndedIterator`'s methods may differ from
/// the ones yielded by `Iterator`'s methods:
/// the ones yielded by [`Iterator`]'s methods:
///
/// ```
/// let vec = vec![(1, 'a'), (1, 'b'), (1, 'c'), (2, 'a'), (2, 'b')];
@ -87,25 +88,23 @@ pub trait DoubleEndedIterator: Iterator {
/// vec![(2, 'b'), (1, 'c')]
/// );
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
fn next_back(&mut self) -> Option<Self::Item>;
/// Returns the `n`th element from the end of the iterator.
///
/// This is essentially the reversed version of [`nth`]. Although like most indexing
/// operations, the count starts from zero, so `nth_back(0)` returns the first value from
/// the end, `nth_back(1)` the second, and so on.
/// This is essentially the reversed version of [`Iterator::nth()`].
/// Although like most indexing operations, the count starts from zero, so
/// `nth_back(0)` returns the first value from the end, `nth_back(1)` the
/// second, and so on.
///
/// Note that all elements between the end and the returned element will be
/// consumed, including the returned element. This also means that calling
/// `nth_back(0)` multiple times on the same iterator will return different
/// elements.
///
/// `nth_back()` will return [`None`] if `n` is greater than or equal to the length of the
/// iterator.
///
/// [`nth`]: crate::iter::Iterator::nth
/// `nth_back()` will return [`None`] if `n` is greater than or equal to the
/// length of the iterator.
///
/// # Examples
///
@ -145,10 +144,8 @@ pub trait DoubleEndedIterator: Iterator {
None
}
/// This is the reverse version of [`try_fold()`]: it takes elements
/// starting from the back of the iterator.
///
/// [`try_fold()`]: Iterator::try_fold
/// This is the reverse version of [`Iterator::try_fold()`]: it takes
/// elements starting from the back of the iterator.
///
/// # Examples
///
@ -195,8 +192,8 @@ pub trait DoubleEndedIterator: Iterator {
/// An iterator method that reduces the iterator's elements to a single,
/// final value, starting from the back.
///
/// This is the reverse version of [`fold()`]: it takes elements starting from
/// the back of the iterator.
/// This is the reverse version of [`Iterator::fold()`]: it takes elements
/// starting from the back of the iterator.
///
/// `rfold()` takes two arguments: an initial value, and a closure with two
/// arguments: an 'accumulator', and an element. The closure returns the value that
@ -213,8 +210,6 @@ pub trait DoubleEndedIterator: Iterator {
/// Folding is useful whenever you have a collection of something, and want
/// to produce a single value from it.
///
/// [`fold()`]: Iterator::fold
///
/// # Examples
///
/// Basic usage:

23
library/core/src/iter/traits/exact_size.rs
View File

@ -6,17 +6,14 @@
/// backwards, a good start is to know where the end is.
///
/// When implementing an `ExactSizeIterator`, you must also implement
/// [`Iterator`]. When doing so, the implementation of [`size_hint`] *must*
/// return the exact size of the iterator.
///
/// [`Iterator`]: trait.Iterator.html
/// [`size_hint`]: trait.Iterator.html#method.size_hint
/// [`Iterator`]. When doing so, the implementation of [`Iterator::size_hint`]
/// *must* return the exact size of the iterator.
///
/// The [`len`] method has a default implementation, so you usually shouldn't
/// implement it. However, you may be able to provide a more performant
/// implementation than the default, so overriding it in this case makes sense.
///
/// [`len`]: #method.len
/// [`len`]: ExactSizeIterator::len
///
/// # Examples
///
@ -72,17 +69,17 @@ pub trait ExactSizeIterator: Iterator {
/// Returns the exact length of the iterator.
///
/// The implementation ensures that the iterator will return exactly `len()`
/// more times a `Some(T)` value, before returning `None`.
/// more times a [`Some(T)`] value, before returning [`None`].
/// This method has a default implementation, so you usually should not
/// implement it directly. However, if you can provide a more efficient
/// implementation, you can do so. See the [trait-level] docs for an
/// example.
///
/// This function has the same safety guarantees as the [`size_hint`]
/// function.
/// This function has the same safety guarantees as the
/// [`Iterator::size_hint`] function.
///
/// [trait-level]: trait.ExactSizeIterator.html
/// [`size_hint`]: trait.Iterator.html#method.size_hint
/// [trait-level]: ExactSizeIterator
/// [`Some(T)`]: Some
///
/// # Examples
///
@ -108,8 +105,8 @@ pub trait ExactSizeIterator: Iterator {
/// Returns `true` if the iterator is empty.
///
/// This method has a default implementation using `self.len()`, so you
/// don't need to implement it yourself.
/// This method has a default implementation using
/// [`ExactSizeIterator::len()`], so you don't need to implement it yourself.
///
/// # Examples
///

1
library/core/src/iter/traits/iterator.rs
View File

@ -2203,7 +2203,6 @@ pub trait Iterator {
///
/// `iter.find_map(f)` is equivalent to `iter.filter_map(f).next()`.
///
///
/// # Examples
///
/// ```

18
library/core/src/iter/traits/marker.rs
View File

@ -2,14 +2,13 @@
///
/// Calling next on a fused iterator that has returned `None` once is guaranteed
/// to return [`None`] again. This trait should be implemented by all iterators
/// that behave this way because it allows optimizing [`Iterator::fuse`].
/// that behave this way because it allows optimizing [`Iterator::fuse()`].
///
/// Note: In general, you should not use `FusedIterator` in generic bounds if
/// you need a fused iterator. Instead, you should just call [`Iterator::fuse`]
/// you need a fused iterator. Instead, you should just call [`Iterator::fuse()`]
/// on the iterator. If the iterator is already fused, the additional [`Fuse`]
/// wrapper will be a no-op with no performance penalty.
///
/// [`Iterator::fuse`]: crate::iter::Iterator::fuse
/// [`Fuse`]: crate::iter::Fuse
#[stable(feature = "fused", since = "1.26.0")]
#[rustc_unsafe_specialization_marker]
@ -24,18 +23,18 @@ impl<I: FusedIterator + ?Sized> FusedIterator for &mut I {}
/// (lower bound is equal to upper bound), or the upper bound is [`None`].
/// The upper bound must only be [`None`] if the actual iterator length is
/// larger than [`usize::MAX`]. In that case, the lower bound must be
/// [`usize::MAX`], resulting in a [`.size_hint`] of `(usize::MAX, None)`.
/// [`usize::MAX`], resulting in a [`Iterator::size_hint()`] of
/// `(usize::MAX, None)`.
///
/// The iterator must produce exactly the number of elements it reported
/// or diverge before reaching the end.
///
/// # Safety
///
/// This trait must only be implemented when the contract is upheld.
/// Consumers of this trait must inspect [`.size_hint`]’s upper bound.
/// This trait must only be implemented when the contract is upheld. Consumers
/// of this trait must inspect [`Iterator::size_hint()`]’s upper bound.
///
/// [`usize::MAX`]: crate::usize::MAX
/// [`.size_hint`]: crate::iter::Iterator::size_hint
#[unstable(feature = "trusted_len", issue = "37572")]
#[rustc_unsafe_specialization_marker]
pub unsafe trait TrustedLen: Iterator {}
@ -46,11 +45,12 @@ unsafe impl<I: TrustedLen + ?Sized> TrustedLen for &mut I {}
/// An iterator that when yielding an item will have taken at least one element
/// from its underlying [`SourceIter`].
///
/// Calling next() guarantees that at least one value of the iterator's underlying source
/// Calling [`next()`] guarantees that at least one value of the iterator's underlying source
/// has been moved out and the result of the iterator chain could be inserted in its place,
/// assuming structural constraints of the source allow such an insertion.
/// In other words this trait indicates that an iterator pipeline can be collected in place.
///
/// [`SourceIter`]: ../../std/iter/trait.SourceIter.html
/// [`SourceIter`]: crate::iter::SourceIter
/// [`next()`]: Iterator::next
#[unstable(issue = "none", feature = "inplace_iteration")]
pub unsafe trait InPlaceIterable: Iterator {}