arcis 0.12.0

//! Iterator methods accepted by the arcis interpreter inside `#[encrypted]` code.
//!
//! [`Iterator`] here is a documentation-only redefinition of
//! [`std::iter::Iterator`] — same shape, but with bodies that panic, since
//! the arcis interpreter intercepts the real method before they run.
//!
//! The blanket impl `impl<I: std::iter::Iterator> Iterator for I` makes every
//! standard iterator (slice iterators, ranges, etc.) usable inside
//! `#[encrypted]` code with the methods documented below.

const STUB_MSG: &str = "arcis::std::iter is documentation-only; \
    inside `#[encrypted]` code the interpreter intercepts the real method before this stub runs.";

/// Documentation of methods on [`Iterator`](std::iter::Iterator) accepted by
/// the arcis interpreter. Mirrors [`std::iter::Iterator`]'s shape.
pub trait Iterator {
    /// The type of items yielded by the iterator.
    type Item;

    /// Advances the iterator and returns the next item. Mirrors [`std::iter::Iterator::next`].
    fn next(&mut self) -> Option<Self::Item>;

    /// Wraps each item with its index. Mirrors [`std::iter::Iterator::enumerate`].
    fn enumerate(self) -> ::std::iter::Enumerate<Self>
    where
        Self: Sized,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Concatenates with another iterator yielding the same item type. Mirrors
    /// [`std::iter::Iterator::chain`].
    fn chain<U>(self, other: U) -> ::std::iter::Chain<Self, U::IntoIter>
    where
        Self: Sized,
        U: IntoIterator<Item = Self::Item>,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Clones each `&T` item to yield owned `T`. Mirrors [`std::iter::Iterator::cloned`].
    fn cloned<'a, T>(self) -> ::std::iter::Cloned<Self>
    where
        Self: Sized + Iterator<Item = &'a T>,
        T: Clone + 'a,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Copies each `&T` item to yield owned `T`. Mirrors [`std::iter::Iterator::copied`].
    fn copied<'a, T>(self) -> ::std::iter::Copied<Self>
    where
        Self: Sized + Iterator<Item = &'a T>,
        T: Copy + 'a,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Consumes the iterator and returns the number of items it yielded. Mirrors
    /// [`std::iter::Iterator::count`].
    fn count(self) -> usize
    where
        Self: Sized,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Reverses iteration order. Mirrors [`std::iter::Iterator::rev`].
    fn rev(self) -> ::std::iter::Rev<Self>
    where
        Self: Sized + DoubleEndedIterator,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Pairs up items from two iterators. Mirrors [`std::iter::Iterator::zip`].
    fn zip<U>(self, other: U) -> ::std::iter::Zip<Self, U::IntoIter>
    where
        Self: Sized,
        U: IntoIterator,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Maps each item through `f`. Mirrors [`std::iter::Iterator::map`].
    fn map<B, F>(self, f: F) -> ::std::iter::Map<Self, F>
    where
        Self: Sized,
        F: FnMut(Self::Item) -> B,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Consumes the iterator, calling `f` on each item. Mirrors [`std::iter::Iterator::for_each`].
    fn for_each<F>(self, f: F)
    where
        Self: Sized,
        F: FnMut(Self::Item),
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Folds the items into a single accumulator. Mirrors [`std::iter::Iterator::fold`].
    fn fold<B, F>(self, init: B, f: F) -> B
    where
        Self: Sized,
        F: FnMut(B, Self::Item) -> B,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Sums up all items. Mirrors [`std::iter::Iterator::sum`].
    fn sum<S>(self) -> S
    where
        Self: Sized,
        S: ::std::iter::Sum<Self::Item>,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Multiplies all items together. Mirrors [`std::iter::Iterator::product`].
    fn product<P>(self) -> P
    where
        Self: Sized,
        P: ::std::iter::Product<Self::Item>,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Collects the iterator into a collection.
    ///
    /// Only `B = Box<[Self::Item]>` is currently supported by the arcis interpreter
    /// (i.e. you must write `.collect::<Box<[_]>>()`). Mirrors [`std::iter::Iterator::collect`].
    fn collect<B>(self) -> B
    where
        Self: Sized,
        B: FromIterator<Self::Item>,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Consumes the iterator and yields its last item. Mirrors [`std::iter::Iterator::last`].
    fn last(self) -> Option<Self::Item>
    where
        Self: Sized,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the `n`-th item, advancing the iterator by `n+1` positions. Mirrors
    /// [`std::iter::Iterator::nth`].
    fn nth(&mut self, n: usize) -> Option<Self::Item> {
        unimplemented!("{STUB_MSG}")
    }

    /// Folds without an initial value, returning `None` if the iterator is empty. Mirrors
    /// [`std::iter::Iterator::reduce`].
    fn reduce<F>(self, f: F) -> Option<Self::Item>
    where
        Self: Sized,
        F: FnMut(Self::Item, Self::Item) -> Self::Item,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the maximum item, or `None` if the iterator is empty. Mirrors
    /// [`std::iter::Iterator::max`].
    fn max(self) -> Option<Self::Item>
    where
        Self: Sized,
        Self::Item: Ord,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the minimum item, or `None` if the iterator is empty. Mirrors
    /// [`std::iter::Iterator::min`].
    fn min(self) -> Option<Self::Item>
    where
        Self: Sized,
        Self::Item: Ord,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the item with the maximum key. Mirrors [`std::iter::Iterator::max_by_key`].
    fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>
    where
        Self: Sized,
        B: Ord,
        F: FnMut(&Self::Item) -> B,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the item with the minimum key. Mirrors [`std::iter::Iterator::min_by_key`].
    fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>
    where
        Self: Sized,
        B: Ord,
        F: FnMut(&Self::Item) -> B,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Yields at most `n` items. **`n` must be compile-time known.** Mirrors
    /// [`std::iter::Iterator::take`].
    fn take(self, n: usize) -> ::std::iter::Take<Self>
    where
        Self: Sized,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Discards the first `n` items. **`n` must be compile-time known.** Mirrors
    /// [`std::iter::Iterator::skip`].
    fn skip(self, n: usize) -> ::std::iter::Skip<Self>
    where
        Self: Sized,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Yields every `n`-th item. **`n` must be compile-time known.** Mirrors
    /// [`std::iter::Iterator::step_by`].
    fn step_by(self, step: usize) -> ::std::iter::StepBy<Self>
    where
        Self: Sized,
    {
        unimplemented!("{STUB_MSG}")
    }
}