arcis 0.14.1

//! Methods on `[T]` (slices) and `[T; N]` (arrays) accepted by the arcis
//! interpreter.
//!
//! Most methods listed in [`SupportedSlice`] are available on both slices and
//! arrays — the trait is implemented on `[T]`, and a `&[T; N]` coerces to
//! `&[T]` so the methods become callable on arrays as well. Methods that only
//! exist on owned arrays (such as [`map`](SupportedArray::map),
//! [`each_ref`](SupportedArray::each_ref), [`each_mut`](SupportedArray::each_mut))
//! live in [`SupportedArray`].
//!
//! The method bodies are documentation-only stubs that panic if called outside
//! the interpreter. Inside `#[encrypted]` code the interpreter intercepts the
//! call before the body runs.

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

/// Slice methods (`[T]` and via coercion `[T; N]`) accepted by the arcis
/// interpreter.
///
/// See the [module docs](self) for how to read this trait.
pub trait SupportedSlice<T> {
    /// Returns the number of elements in the slice.
    ///
    /// Mirrors [`<[T]>::len`](https://doc.rust-lang.org/std/primitive.slice.html#method.len).
    fn len(&self) -> usize {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns `true` if the slice has length 0.
    ///
    /// Mirrors [`<[T]>::is_empty`](https://doc.rust-lang.org/std/primitive.slice.html#method.is_empty).
    fn is_empty(&self) -> bool {
        unimplemented!("{STUB_MSG}")
    }

    /// Swaps two elements in the slice. Indices must be in bounds.
    ///
    /// Mirrors [`<[T]>::swap`](https://doc.rust-lang.org/std/primitive.slice.html#method.swap).
    fn swap(&mut self, a: usize, b: usize) {
        unimplemented!("{STUB_MSG}")
    }

    /// Fills the slice with copies of `value`.
    ///
    /// Mirrors [`<[T]>::fill`](https://doc.rust-lang.org/std/primitive.slice.html#method.fill).
    fn fill(&mut self, value: T)
    where
        T: Clone,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Reverses the slice in place.
    ///
    /// Mirrors [`<[T]>::reverse`](https://doc.rust-lang.org/std/primitive.slice.html#method.reverse).
    fn reverse(&mut self) {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns an iterator over the slice.
    ///
    /// Mirrors [`<[T]>::iter`](https://doc.rust-lang.org/std/primitive.slice.html#method.iter).
    /// `.into_iter()` on a slice reference and `for x in &slice {}` are also
    /// accepted and equivalent.
    fn iter(&self) -> ::std::slice::Iter<'_, T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns an iterator that allows modifying each element.
    ///
    /// Mirrors [`<[T]>::iter_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.iter_mut).
    fn iter_mut(&mut self) -> ::std::slice::IterMut<'_, T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns an iterator over overlapping subslices of length `size`.
    ///
    /// Mirrors [`<[T]>::windows`](https://doc.rust-lang.org/std/primitive.slice.html#method.windows).
    /// `size` must be a compile-time-known `usize`.
    fn windows(&self, size: usize) -> ::std::slice::Windows<'_, T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Copies all elements from `src` into `self`, using a memcpy.
    ///
    /// Mirrors [`<[T]>::copy_from_slice`](https://doc.rust-lang.org/std/primitive.slice.html#method.copy_from_slice).
    /// Slices must have the same length.
    fn copy_from_slice(&mut self, src: &[T])
    where
        T: Copy,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Copies the elements from `src` into `self` using clones.
    ///
    /// Mirrors [`<[T]>::clone_from_slice`](https://doc.rust-lang.org/std/primitive.slice.html#method.clone_from_slice).
    /// Slices must have the same length.
    fn clone_from_slice(&mut self, src: &[T])
    where
        T: Clone,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Divides one slice into two at `mid`.
    ///
    /// Mirrors [`<[T]>::split_at`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_at).
    fn split_at(&self, mid: usize) -> (&[T], &[T]) {
        unimplemented!("{STUB_MSG}")
    }

    /// Divides one mutable slice into two at `mid`.
    ///
    /// Mirrors [`<[T]>::split_at_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_at_mut).
    fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) {
        unimplemented!("{STUB_MSG}")
    }

    /// Rotates the slice in place so that the first `mid` elements move to the end.
    ///
    /// Mirrors [`<[T]>::rotate_left`](https://doc.rust-lang.org/std/primitive.slice.html#method.rotate_left).
    fn rotate_left(&mut self, mid: usize) {
        unimplemented!("{STUB_MSG}")
    }

    /// Rotates the slice in place so that the last `k` elements move to the front.
    ///
    /// Mirrors [`<[T]>::rotate_right`](https://doc.rust-lang.org/std/primitive.slice.html#method.rotate_right).
    fn rotate_right(&mut self, k: usize) {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns `true` if the slice contains an element equal to `x`.
    ///
    /// Mirrors [`<[T]>::contains`](https://doc.rust-lang.org/std/primitive.slice.html#method.contains).
    fn contains(&self, x: &T) -> bool
    where
        T: PartialEq,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns `true` if `needle` is a prefix of the slice.
    ///
    /// Mirrors [`<[T]>::starts_with`](https://doc.rust-lang.org/std/primitive.slice.html#method.starts_with).
    fn starts_with(&self, needle: &[T]) -> bool
    where
        T: PartialEq,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns `true` if `needle` is a suffix of the slice.
    ///
    /// Mirrors [`<[T]>::ends_with`](https://doc.rust-lang.org/std/primitive.slice.html#method.ends_with).
    fn ends_with(&self, needle: &[T]) -> bool
    where
        T: PartialEq,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a reference to the underlying slice.
    ///
    /// Available on arrays; mirrors [`<[T; N]>::as_slice`](https://doc.rust-lang.org/std/primitive.array.html#method.as_slice).
    /// On `[T]` itself, returns `self`.
    fn as_slice(&self) -> &[T] {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a mutable reference to the underlying slice.
    ///
    /// Available on arrays; mirrors [`<[T; N]>::as_mut_slice`](https://doc.rust-lang.org/std/primitive.array.html#method.as_mut_slice).
    fn as_mut_slice(&mut self) -> &mut [T] {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the first element, or `None` if empty.
    ///
    /// Mirrors [`<[T]>::first`](https://doc.rust-lang.org/std/primitive.slice.html#method.first).
    fn first(&self) -> Option<&T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a mutable reference to the first element, or `None` if empty.
    ///
    /// Mirrors [`<[T]>::first_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.first_mut).
    fn first_mut(&mut self) -> Option<&mut T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the last element, or `None` if empty.
    ///
    /// Mirrors [`<[T]>::last`](https://doc.rust-lang.org/std/primitive.slice.html#method.last).
    fn last(&self) -> Option<&T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a mutable reference to the last element, or `None` if empty.
    ///
    /// Mirrors [`<[T]>::last_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.last_mut).
    fn last_mut(&mut self) -> Option<&mut T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a reference to the element at `index`, or `None` if out of bounds.
    ///
    /// Mirrors [`<[T]>::get`](https://doc.rust-lang.org/std/primitive.slice.html#method.get).
    /// **Complexity:** `O(slice.len())` when `index` is not known at compile time.
    fn get(&self, index: usize) -> Option<&T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a mutable reference to the element at `index`, or `None` if out of bounds.
    ///
    /// Mirrors [`<[T]>::get_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.get_mut).
    /// **Complexity:** `O(slice.len())` when `index` is not known at compile time.
    fn get_mut(&mut self, index: usize) -> Option<&mut T> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the first element and the rest, or `None` if empty.
    ///
    /// Mirrors [`<[T]>::split_first`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_first).
    fn split_first(&self) -> Option<(&T, &[T])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a mutable reference to the first element and the rest, or `None` if empty.
    ///
    /// Mirrors [`<[T]>::split_first_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_first_mut).
    fn split_first_mut(&mut self) -> Option<(&mut T, &mut [T])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the last element and everything before it, or `None` if empty.
    ///
    /// Mirrors [`<[T]>::split_last`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_last).
    fn split_last(&self) -> Option<(&T, &[T])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a mutable reference to the last element and everything before it.
    ///
    /// Mirrors [`<[T]>::split_last_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_last_mut).
    fn split_last_mut(&mut self) -> Option<(&mut T, &mut [T])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a reference to the first `N` elements as an array, or `None` if shorter.
    ///
    /// Mirrors [`<[T]>::first_chunk`](https://doc.rust-lang.org/std/primitive.slice.html#method.first_chunk).
    fn first_chunk<const N: usize>(&self) -> Option<&[T; N]> {
        unimplemented!("{STUB_MSG}")
    }

    /// Mutable variant of [`first_chunk`](Self::first_chunk).
    fn first_chunk_mut<const N: usize>(&mut self) -> Option<&mut [T; N]> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns a reference to the last `N` elements as an array, or `None` if shorter.
    ///
    /// Mirrors [`<[T]>::last_chunk`](https://doc.rust-lang.org/std/primitive.slice.html#method.last_chunk).
    fn last_chunk<const N: usize>(&self) -> Option<&[T; N]> {
        unimplemented!("{STUB_MSG}")
    }

    /// Mutable variant of [`last_chunk`](Self::last_chunk).
    fn last_chunk_mut<const N: usize>(&mut self) -> Option<&mut [T; N]> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the first `N` elements as an array and the remaining slice, or `None` if shorter.
    ///
    /// Mirrors [`<[T]>::split_first_chunk`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_first_chunk).
    fn split_first_chunk<const N: usize>(&self) -> Option<(&[T; N], &[T])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Mutable variant of [`split_first_chunk`](Self::split_first_chunk).
    fn split_first_chunk_mut<const N: usize>(&mut self) -> Option<(&mut [T; N], &mut [T])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Returns the leading slice and the last `N` elements as an array, or `None` if shorter.
    ///
    /// Mirrors [`<[T]>::split_last_chunk`](https://doc.rust-lang.org/std/primitive.slice.html#method.split_last_chunk).
    fn split_last_chunk<const N: usize>(&self) -> Option<(&[T], &[T; N])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Mutable variant of [`split_last_chunk`](Self::split_last_chunk).
    fn split_last_chunk_mut<const N: usize>(&mut self) -> Option<(&mut [T], &mut [T; N])> {
        unimplemented!("{STUB_MSG}")
    }

    /// Tries to convert a slice into an array of compile-time-known length.
    ///
    /// Mirrors [`<[T]>::as_array`](https://doc.rust-lang.org/std/primitive.slice.html#method.as_array).
    /// Requires Rust 1.93+.
    fn as_array<const N: usize>(&self) -> Option<&[T; N]> {
        unimplemented!("{STUB_MSG}")
    }

    /// Mutable variant of [`as_array`](Self::as_array).
    fn as_mut_array<const N: usize>(&mut self) -> Option<&mut [T; N]> {
        unimplemented!("{STUB_MSG}")
    }

    /// Sorts the slice ascending.
    ///
    /// Mirrors [`<[T]>::sort`](https://doc.rust-lang.org/std/primitive.slice.html#method.sort)
    /// but **only accepted on arrays whose element type is an integer**.
    ///
    /// **Complexity:** `O(n · log²(n) · bit_size)`.
    fn sort(&mut self)
    where
        T: Ord,
    {
        unimplemented!("{STUB_MSG}")
    }
}

impl<T> SupportedSlice<T> for [T] {}

/// Methods only available on owned arrays `[T; N]`, not on slices.
///
/// See the [module docs](self) for how to read this trait.
pub trait SupportedArray<T, const N: usize> {
    /// Returns a new array where each element is the result of applying `f` to
    /// the corresponding element of `self`.
    ///
    /// Mirrors [`<[T; N]>::map`](https://doc.rust-lang.org/std/primitive.array.html#method.map).
    fn map<U, F>(self, f: F) -> [U; N]
    where
        Self: Sized,
        F: FnMut(T) -> U,
    {
        unimplemented!("{STUB_MSG}")
    }

    /// Borrows each element and returns a fresh array of references.
    ///
    /// Mirrors [`<[T; N]>::each_ref`](https://doc.rust-lang.org/std/primitive.array.html#method.each_ref).
    fn each_ref(&self) -> [&T; N] {
        unimplemented!("{STUB_MSG}")
    }

    /// Borrows each element mutably and returns a fresh array of references.
    ///
    /// Mirrors [`<[T; N]>::each_mut`](https://doc.rust-lang.org/std/primitive.array.html#method.each_mut).
    fn each_mut(&mut self) -> [&mut T; N] {
        unimplemented!("{STUB_MSG}")
    }
}

impl<T, const N: usize> SupportedArray<T, N> for [T; N] {}