Trait nom::lib::std::iter::SourceIter

pub unsafe trait SourceIter {
    type Source: Iterator;
    unsafe fn as_inner(&mut self) -> &mut Self::Source;
}

🔬 This is a nightly-only experimental API. (inplace_iteration)

This trait provides transitive access to source-stage 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:

let mut iter = vec![9, 9, 9].into_iter().map(|i| i * i);
let _ = iter.next();
let mut remainder = std::mem::replace(unsafe { iter.as_inner() }, Vec::new().into_iter());
println!("n = {} elements remaining", remainder.len());

Associated Types

type Source: Iterator

🔬 This is a nightly-only experimental API. (inplace_iteration)

A source stage in an iterator pipeline.

Loading content...

Required methods

unsafe fn as_inner(&mut self) -> &mut Self::Source

🔬 This is a nightly-only experimental API. (inplace_iteration)

Retrieve the source of an iterator pipeline.

Safety

Implementations of must return the same mutable reference for their lifetime, unless replaced by a caller. Callers may only replace the reference when they stopped iteration and drop the iterator pipeline after extracting the source.

This means iterator adapters can rely on the source not changing during iteration but they cannot rely on it in their Drop implementations.

Implementing this method means adapters relinquish private-only access to their source and can only rely on guarantees made based on method receiver types. The lack of restricted access also requires that adapters must uphold the source's public API even when they have access to its internals.

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 let the consumer of a pipeline use

• whatever remains in the source after iteration has stopped
• the memory that has become unused by advancing a consuming iterator

Loading content...

Implementors

impl<S, A, B> SourceIter for Zip<A, B> where
    A: SourceIter<Source = S>,
    B: Iterator,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, B, I, F> SourceIter for FilterMap<I, F> where
    F: FnMut(<I as Iterator>::Item) -> Option<B>,
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, B, I, F> SourceIter for Map<I, F> where
    F: FnMut(<I as Iterator>::Item) -> B,
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, B, I, P> SourceIter for MapWhile<I, P> where
    I: Iterator + SourceIter<Source = S>,
    P: FnMut(<I as Iterator>::Item) -> Option<B>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, I> SourceIter for Enumerate<I> where
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, I> SourceIter for Fuse<I> where
    I: FusedIterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, I> SourceIter for Peekable<I> where
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, I> SourceIter for Skip<I> where
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, I> SourceIter for Take<I> where
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, I, F> SourceIter for Inspect<I, F> where
    F: FnMut(&<I as Iterator>::Item),
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, P, I> SourceIter for Filter<I, P> where
    I: Iterator + SourceIter<Source = S>,
    P: FnMut(&<I as Iterator>::Item) -> bool,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, P, I> SourceIter for SkipWhile<I, P> where
    I: Iterator + SourceIter<Source = S>,
    P: FnMut(&<I as Iterator>::Item) -> bool,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<S, P, I> SourceIter for TakeWhile<I, P> where
    I: Iterator + SourceIter<Source = S>,
    P: FnMut(&<I as Iterator>::Item) -> bool,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<St, F, B, S, I> SourceIter for Scan<I, St, F> where
    F: FnMut(&mut St, <I as Iterator>::Item) -> Option<B>,
    I: Iterator + SourceIter<Source = S>,
    S: Iterator, 

type Source = S

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut S

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<T> SourceIter for nom::lib::std::collections::binary_heap::IntoIter<T>

type Source = IntoIter<T>

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut <IntoIter<T> as SourceIter>::Source

🔬 This is a nightly-only experimental API. (inplace_iteration)

impl<T> SourceIter for nom::lib::std::vec::IntoIter<T>

type Source = IntoIter<T>

🔬 This is a nightly-only experimental API. (inplace_iteration)

unsafe fn as_inner(&mut self) -> &mut <IntoIter<T> as SourceIter>::Source

🔬 This is a nightly-only experimental API. (inplace_iteration)

Loading content...