/// 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> {
/// 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
///
/// assert_eq!(Some(4), fours.next());
/// ```
///
-/// Going finite with [`take`]:
+/// Going finite with [`Iterator::take()`]:
///
/// ```
/// use std::iter;
/// 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> {
/// 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.
-///
-/// [`repeat`]: fn.repeat.html
+/// the [`repeat()`] function.
///
-/// 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:
/// 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>);
/// 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> {
/// 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
///
/// 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> {
/// 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
///
///
/// 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
///
/// 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 [`from_fn()`] function.
/// See its documentation for more.
-///
-/// [`iter::from_fn`]: fn.from_fn.html
#[derive(Clone)]
#[stable(feature = "iter_from_fn", since = "1.34.0")]
pub struct FromFn<F>(F);
/// 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 [`successors()`] function.
/// See its documentation for more.
-///
-/// [`successors`]: fn.successors.html
#[derive(Clone)]
#[stable(feature = "iter_successors", since = "1.34.0")]
pub struct Successors<T, F> {
/// 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
/// 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
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
///
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>>,
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
///
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>>,
-/// 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:
/// 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);
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
///
/// See also: [`FromIterator`].
///
-/// [`FromIterator`]: trait.FromIterator.html
-///
/// # Examples
///
/// Basic usage:
/// 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
///
/// 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
///
///
/// The [trait-level] docs contain more details.
///
- /// [trait-level]: trait.DoubleEndedIterator.html
+ /// [trait-level]: DoubleEndedIterator
///
/// # Examples
///
/// # 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')];
/// 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
///
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
///
/// 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
/// 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:
/// 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
///
/// 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
///
/// 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
///
///
/// `iter.find_map(f)` is equivalent to `iter.filter_map(f).next()`.
///
- ///
/// # Examples
///
/// ```
///
/// 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]
/// (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 {}
/// 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 {}
projects / rust.git / commitdiff