<commit_before>use crate::cmp;
use crate::fmt;
use crate::intrinsics;
use crate::ops::{Add, AddAssign, ControlFlow, Try};

use super::from_fn;
use super::{
    DoubleEndedIterator, ExactSizeIterator, FusedIterator, InPlaceIterable, Iterator, TrustedLen,
};

mod chain;
mod flatten;
mod fuse;
mod zip;

pub use self::chain::Chain;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::flatten::{FlatMap, Flatten};
pub use self::fuse::Fuse;
use self::zip::try_get_unchecked;
pub(crate) use self::zip::TrustedRandomAccess;
pub use self::zip::Zip;

/// This trait provides transitive access to source-stages in an interator-adapter pipeline
/// under the conditions that
/// * the iterator source `S` itself implements `SourceIter<Source = S>`
/// * there is a delegating implementation of this trait for each adapter in the pipeline between
///   the source and the pipeline consumer.
///
/// When the source is an owning iterator struct (commonly called `IntoIter`) then
/// this can be useful for specializing [`FromIterator`] implementations or recovering the
/// remaining elements after an iterator has been partially exhausted.
///
/// Note that implementations do not necessarily have to provide access to the inner-most
/// source of a pipeline. A stateful intermediate adapter might eagerly evaluate a part
/// of the pipeline and expose its internal storage as source.
///
/// The trait is unsafe because implementers must uphold additional safety properties.
/// See [`as_inner`] for details.
///
/// # Examples
///
/// Retrieving a partially consumed source:
///
/// ```
/// # #![feature(inplace_iteration)]
/// # use std::iter::SourceIter;
///
/// let mut iter = vec![9, 9, 9].into_iter().map(|i| i * i);
/// let _ = iter.next();
/// let mut remainder = std::mem::replace(iter.as_inner(), Vec::new().into_iter());
/// println!("n = {} elements remaining", remainder.len());
/// ```
///
/// [`FromIterator`]: trait.FromIterator.html
/// [`as_inner`]: #method.as_inner
#[unstable(issue = "0", feature = "inplace_iteration")]
pub unsafe trait SourceIter {
    /// A source stage in an iterator pipeline.
    type Source: Iterator;

    /// Extract the source of an iterator pipeline.
    ///
    /// Callers may assume that calls to [`next()`] or any method taking `&self`
    /// does no replace the referenced value.
    /// But callers may replace the referenced values as long they in turn do not
    /// expose it through a delegating implementation of this trait.
    /// Which means that while adapters may not modify the reference they cannot
    /// rely on it not being modified.
    ///
    /// Adapters must not rely on exclusive ownership or immutability of the source.
    /// For example a peeking adapter could either exploit [`TrustedRandomAccess`] to look ahead
    /// or implement this trait, but it cannot do both because a caller could call `next()` or any
    /// other mutating method on the source between iteration steps and thus invalidate the peeked
    /// values.
    /// The lack of exclusive ownership also requires that adapters must uphold the source's
    /// public API even when they have crate- or module-internal access.
    ///
    /// Callers in turn must expect the source to be in any state that is consistent with
    /// its public API since adapters sitting between it and the source have the same
    /// access. In particular an adapter may have consumed more elements than strictly necessary.
    ///
    /// The overall goal of these requirements is to grant the consumer of a pipeline
    /// access to the underlying storage of an iterator while restricting any statefulness
    /// and side-effects of the pipeline stages from affecting or relying on that storage.
    ///
    /// [`TrustedRandomAccess`]: trait.TrustedRandomAccess.html
    /// [`next`]: trait.Iterator.html#method.next
    fn as_inner(&mut self) -> &mut Self::Source;
}

/// A double-ended iterator with the direction inverted.
///
/// This `struct` is created by the [`rev`] method on [`Iterator`]. See its
/// documentation for more.
///
/// [`rev`]: trait.Iterator.html#method.rev
/// [`Iterator`]: trait.Iterator.html
#[derive(Clone, Debug)]
#[must_use = "iterators are lazy and do nothing unless consumed"]<commit_msg>fix doc link<commit_after>use crate::cmp;
use crate::fmt;
use crate::intrinsics;
use crate::ops::{Add, AddAssign, ControlFlow, Try};

use super::from_fn;
use super::{
    DoubleEndedIterator, ExactSizeIterator, FusedIterator, InPlaceIterable, Iterator, TrustedLen,
};

mod chain;
mod flatten;
mod fuse;
mod zip;

pub use self::chain::Chain;
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::flatten::{FlatMap, Flatten};
pub use self::fuse::Fuse;
use self::zip::try_get_unchecked;
pub(crate) use self::zip::TrustedRandomAccess;
pub use self::zip::Zip;

/// This trait provides transitive access to source-stages in an interator-adapter pipeline
/// under the conditions that
/// * the iterator source `S` itself implements `SourceIter<Source = S>`
/// * there is a delegating implementation of this trait for each adapter in the pipeline between
///   the source and the pipeline consumer.
///
/// When the source is an owning iterator struct (commonly called `IntoIter`) then
/// this can be useful for specializing [`FromIterator`] implementations or recovering the
/// remaining elements after an iterator has been partially exhausted.
///
/// Note that implementations do not necessarily have to provide access to the inner-most
/// source of a pipeline. A stateful intermediate adapter might eagerly evaluate a part
/// of the pipeline and expose its internal storage as source.
///
/// The trait is unsafe because implementers must uphold additional safety properties.
/// See [`as_inner`] for details.
///
/// # Examples
///
/// Retrieving a partially consumed source:
///
/// ```
/// # #![feature(inplace_iteration)]
/// # use std::iter::SourceIter;
///
/// let mut iter = vec![9, 9, 9].into_iter().map(|i| i * i);
/// let _ = iter.next();
/// let mut remainder = std::mem::replace(iter.as_inner(), Vec::new().into_iter());
/// println!("n = {} elements remaining", remainder.len());
/// ```
///
/// [`FromIterator`]: trait.FromIterator.html
/// [`as_inner`]: #method.as_inner
#[unstable(issue = "0", feature = "inplace_iteration")]
pub unsafe trait SourceIter {
    /// A source stage in an iterator pipeline.
    type Source: Iterator;

    /// Extract the source of an iterator pipeline.
    ///
    /// Callers may assume that calls to [`next()`] or any method taking `&self`
    /// does no replace the referenced value.
    /// But callers may replace the referenced values as long they in turn do not
    /// expose it through a delegating implementation of this trait.
    /// Which means that while adapters may not modify the reference they cannot
    /// rely on it not being modified.
    ///
    /// Adapters must not rely on exclusive ownership or immutability of the source.
    /// For example a peeking adapter could either exploit [`TrustedRandomAccess`] to look ahead
    /// or implement this trait, but it cannot do both because a caller could call `next()` or any
    /// other mutating method on the source between iteration steps and thus invalidate the peeked
    /// values.
    /// The lack of exclusive ownership also requires that adapters must uphold the source's
    /// public API even when they have crate- or module-internal access.
    ///
    /// Callers in turn must expect the source to be in any state that is consistent with
    /// its public API since adapters sitting between it and the source have the same
    /// access. In particular an adapter may have consumed more elements than strictly necessary.
    ///
    /// The overall goal of these requirements is to grant the consumer of a pipeline
    /// access to the underlying storage of an iterator while restricting any statefulness
    /// and side-effects of the pipeline stages from affecting or relying on that storage.
    ///
    /// [`TrustedRandomAccess`]: trait.TrustedRandomAccess.html
    /// [`next()`]: trait.Iterator.html#method.next
    fn as_inner(&mut self) -> &mut Self::Source;
}

/// A double-ended iterator with the direction inverted.
///
/// This `struct` is created by the [`rev`] method on [`Iterator`]. See its
/// documentation for more.
///
/// [`rev`]: trait.Iterator.html#method.rev
/// [`Iterator`]: trait.Iterator.html
#[derive(Clone, Debug)]
#[must_use = "iterators are lazy and do nothing unless consumed"]
{'fraction_non_alphanumeric': 0.12401644157369349, 'fraction_numerical': 0.0018790369935408103, 'mean_word_length': 3.351558507920286, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7042805', 'n_tokens_mistral': 2260, 'n_tokens_neox': 2224, 'n_words': 1007}