arcis 0.13.1

//! Operator overloading traits and range types accepted by the arcis interpreter.
//!
//! The traits in this module are documentation-only handles: they exist so
//! rustdoc renders a page per trait, with an auto-generated implementors list
//! showing which types the arcis interpreter recognizes the operator on.
//!
//! # Range types
//!
//! [`Range`], [`RangeInclusive`], [`RangeFrom`], [`RangeTo`], [`RangeToInclusive`],
//! and [`RangeFull`] are doc-only redefinitions of their [`std::ops`] counterparts.
//! Users write the syntax (`a..b`, `a..=b`, `a..`, `..b`, `..=b`, `..`) and the
//! interpreter constructs the appropriate value. See each type for iteration
//! capabilities and slice-indexing semantics.
//!
//! # Implementing
//!
//! Every trait in this module is **neither derivable nor implementable**
//! inside `#[encrypted]` code. The interpreter dispatches the corresponding
//! operator directly on the types listed below; there is no way to extend
//! that set from user code today. This may be revisited in a future PR.
//!
//! # Calling
//!
//! Only the operator form is accepted (e.g. `a + b`). The trait methods
//! (`.add(b)`, `Add::add(&a, &b)`, `<T as Add>::add(&a, &b)`) and the
//! associated types (e.g. `<T as Add>::Output`) are **not** accepted.
//!
//! Each trait in this module is a thin mirror of the same-named trait in
//! [`std::ops`].
//!
//! # Shift operators
//!
//! For [`Shl`] and [`Shr`], the right-hand side must be a **compile-time
//! known** value (a literal, a `const`, or anything else the interpreter can
//! resolve at lowering time). A shift by a runtime-determined amount is not
//! accepted.

// =================== Add / Sub / Mul / Div / Rem ===================
//
// Arithmetic-impl coverage differs by op:
//
// * `Add`, `Sub`, `Mul` (and their assigns) work on integers, floats, and `BaseField25519`.
// * `Div` (and `DivAssign`) work on integers and floats only. `BaseField25519` has no `/` impl —
//   use [`crate::BaseField25519::field_division`] or [`crate::BaseField25519::euclidean_division`]
//   instead.
// * `Rem` (and `RemAssign`) work on integers only. There is no `%` on floats or on
//   `BaseField25519`.

macro_rules! impl_for_integers {
    ($trait:ident) => {
        impl $trait for crate::std::integer::u8 {}
        impl $trait for crate::std::integer::u16 {}
        impl $trait for crate::std::integer::u32 {}
        impl $trait for crate::std::integer::u64 {}
        impl $trait for crate::std::integer::u128 {}
        impl $trait for crate::std::integer::usize {}

        impl $trait for crate::std::integer::i8 {}
        impl $trait for crate::std::integer::i16 {}
        impl $trait for crate::std::integer::i32 {}
        impl $trait for crate::std::integer::i64 {}
        impl $trait for crate::std::integer::i128 {}
        impl $trait for crate::std::integer::isize {}
    };
}

macro_rules! impl_for_integers_and_floats {
    ($trait:ident) => {
        impl_for_integers!($trait);
        impl $trait for crate::std::float::f32 {}
        impl $trait for crate::std::float::f64 {}
    };
}

macro_rules! impl_for_integers_floats_and_basefield {
    ($trait:ident) => {
        impl_for_integers_and_floats!($trait);
        impl $trait for crate::BaseField25519 {}
    };
}

/// Addition operator `+`. Mirrors [`std::ops::Add`].
///
/// Use `+` directly; the methods (`.add(b)`, `Add::add(&a, &b)`, `<T as Add>::add(&a, &b)`)
/// and the associated type `<T as Add>::Output` are not accepted.
pub trait Add {}
impl_for_integers_floats_and_basefield!(Add);

/// Subtraction operator `-`. Mirrors [`std::ops::Sub`].
///
/// Use `-` directly; the methods (`.sub(b)`, `Sub::sub(&a, &b)`, `<T as Sub>::sub(&a, &b)`)
/// and the associated type `<T as Sub>::Output` are not accepted.
pub trait Sub {}
impl_for_integers_floats_and_basefield!(Sub);

/// Multiplication operator `*`. Mirrors [`std::ops::Mul`].
///
/// Use `*` directly; the methods (`.mul(b)`, `Mul::mul(&a, &b)`, `<T as Mul>::mul(&a, &b)`)
/// and the associated type `<T as Mul>::Output` are not accepted.
pub trait Mul {}
impl_for_integers_floats_and_basefield!(Mul);

/// Division operator `/`. Mirrors [`std::ops::Div`].
///
/// `BaseField25519` does **not** implement `/`. Use
/// [`crate::BaseField25519::field_division`] or
/// [`crate::BaseField25519::euclidean_division`] instead.
///
/// Use `/` directly; the methods (`.div(b)`, `Div::div(&a, &b)`, `<T as Div>::div(&a, &b)`)
/// and the associated type `<T as Div>::Output` are not accepted.
pub trait Div {}
impl_for_integers_and_floats!(Div);

/// Remainder operator `%`. Mirrors [`std::ops::Rem`].
///
/// Integers only — there is no `%` on floats or on `BaseField25519`.
///
/// Use `%` directly; the methods (`.rem(b)`, `Rem::rem(&a, &b)`, `<T as Rem>::rem(&a, &b)`)
/// and the associated type `<T as Rem>::Output` are not accepted.
pub trait Rem {}
impl_for_integers!(Rem);

/// Compound assignment `+=`. Mirrors [`std::ops::AddAssign`].
///
/// Use `+=` directly; `.add_assign(b)`, `AddAssign::add_assign(&mut a, b)`, and
/// `<T as AddAssign>::add_assign(&mut a, b)` are not accepted.
pub trait AddAssign {}
impl_for_integers_floats_and_basefield!(AddAssign);

/// Compound assignment `-=`. Mirrors [`std::ops::SubAssign`].
///
/// Use `-=` directly; `.sub_assign(b)`, `SubAssign::sub_assign(&mut a, b)`, and
/// `<T as SubAssign>::sub_assign(&mut a, b)` are not accepted.
pub trait SubAssign {}
impl_for_integers_floats_and_basefield!(SubAssign);

/// Compound assignment `*=`. Mirrors [`std::ops::MulAssign`].
///
/// Use `*=` directly; `.mul_assign(b)`, `MulAssign::mul_assign(&mut a, b)`, and
/// `<T as MulAssign>::mul_assign(&mut a, b)` are not accepted.
pub trait MulAssign {}
impl_for_integers_floats_and_basefield!(MulAssign);

/// Compound assignment `/=`. Mirrors [`std::ops::DivAssign`].
///
/// See [`Div`] for the BaseField caveat.
///
/// Use `/=` directly; `.div_assign(b)`, `DivAssign::div_assign(&mut a, b)`, and
/// `<T as DivAssign>::div_assign(&mut a, b)` are not accepted.
pub trait DivAssign {}
impl_for_integers_and_floats!(DivAssign);

/// Compound assignment `%=`. Mirrors [`std::ops::RemAssign`].
///
/// Integers only.
///
/// Use `%=` directly; `.rem_assign(b)`, `RemAssign::rem_assign(&mut a, b)`, and
/// `<T as RemAssign>::rem_assign(&mut a, b)` are not accepted.
pub trait RemAssign {}
impl_for_integers!(RemAssign);

// =================== Neg ===================

/// Unary negation operator `-`. Mirrors [`std::ops::Neg`].
///
/// Use `-x` directly; the methods (`.neg()`, `Neg::neg(x)`, `<T as Neg>::neg(x)`)
/// and the associated type `<T as Neg>::Output` are not accepted.
pub trait Neg {}

impl Neg for crate::std::integer::i8 {}
impl Neg for crate::std::integer::i16 {}
impl Neg for crate::std::integer::i32 {}
impl Neg for crate::std::integer::i64 {}
impl Neg for crate::std::integer::i128 {}
impl Neg for crate::std::integer::isize {}

impl Neg for crate::std::float::f32 {}
impl Neg for crate::std::float::f64 {}

impl Neg for crate::BaseField25519 {}

// =================== Not ===================

/// Unary `!` operator. Mirrors [`std::ops::Not`].
///
/// On [`bool`](crate::std::boolean::bool) this is logical negation. On integer
/// types it is bitwise complement.
///
/// Use `!x` directly; the methods (`.not()`, `Not::not(x)`, `<T as Not>::not(x)`)
/// and the associated type `<T as Not>::Output` are not accepted.
pub trait Not {}

impl Not for crate::std::boolean::bool {}

impl Not for crate::std::integer::u8 {}
impl Not for crate::std::integer::u16 {}
impl Not for crate::std::integer::u32 {}
impl Not for crate::std::integer::u64 {}
impl Not for crate::std::integer::u128 {}
impl Not for crate::std::integer::usize {}

impl Not for crate::std::integer::i8 {}
impl Not for crate::std::integer::i16 {}
impl Not for crate::std::integer::i32 {}
impl Not for crate::std::integer::i64 {}
impl Not for crate::std::integer::i128 {}
impl Not for crate::std::integer::isize {}

// =================== Bitwise ===================
//
// `&`, `|`, `^` (and their assigns) work on every integer type and on `bool`.
// Note: `&&` and `||` are short-circuit operators handled separately by the
// interpreter and do not go through `BitAnd` / `BitOr`.

macro_rules! impl_bit_for_integers_and_bool {
    ($trait:ident) => {
        impl $trait for crate::std::boolean::bool {}

        impl $trait for crate::std::integer::u8 {}
        impl $trait for crate::std::integer::u16 {}
        impl $trait for crate::std::integer::u32 {}
        impl $trait for crate::std::integer::u64 {}
        impl $trait for crate::std::integer::u128 {}
        impl $trait for crate::std::integer::usize {}

        impl $trait for crate::std::integer::i8 {}
        impl $trait for crate::std::integer::i16 {}
        impl $trait for crate::std::integer::i32 {}
        impl $trait for crate::std::integer::i64 {}
        impl $trait for crate::std::integer::i128 {}
        impl $trait for crate::std::integer::isize {}
    };
}

/// Bitwise / boolean `&`. Mirrors [`std::ops::BitAnd`].
///
/// Use `&` directly; the methods (`.bitand(b)`, `BitAnd::bitand(&a, &b)`,
/// `<T as BitAnd>::bitand(&a, &b)`) and the associated type `<T as BitAnd>::Output`
/// are not accepted.
pub trait BitAnd {}
impl_bit_for_integers_and_bool!(BitAnd);

/// Bitwise / boolean `|`. Mirrors [`std::ops::BitOr`].
///
/// Use `|` directly; the methods (`.bitor(b)`, `BitOr::bitor(&a, &b)`,
/// `<T as BitOr>::bitor(&a, &b)`) and the associated type `<T as BitOr>::Output`
/// are not accepted.
pub trait BitOr {}
impl_bit_for_integers_and_bool!(BitOr);

/// Bitwise / boolean `^`. Mirrors [`std::ops::BitXor`].
///
/// Use `^` directly; the methods (`.bitxor(b)`, `BitXor::bitxor(&a, &b)`,
/// `<T as BitXor>::bitxor(&a, &b)`) and the associated type `<T as BitXor>::Output`
/// are not accepted.
pub trait BitXor {}
impl_bit_for_integers_and_bool!(BitXor);

/// Compound assignment `&=`. Mirrors [`std::ops::BitAndAssign`].
///
/// Use `&=` directly; `.bitand_assign(b)`, `BitAndAssign::bitand_assign(&mut a, b)`, and
/// `<T as BitAndAssign>::bitand_assign(&mut a, b)` are not accepted.
pub trait BitAndAssign {}
impl_bit_for_integers_and_bool!(BitAndAssign);

/// Compound assignment `|=`. Mirrors [`std::ops::BitOrAssign`].
///
/// Use `|=` directly; `.bitor_assign(b)`, `BitOrAssign::bitor_assign(&mut a, b)`, and
/// `<T as BitOrAssign>::bitor_assign(&mut a, b)` are not accepted.
pub trait BitOrAssign {}
impl_bit_for_integers_and_bool!(BitOrAssign);

/// Compound assignment `^=`. Mirrors [`std::ops::BitXorAssign`].
///
/// Use `^=` directly; `.bitxor_assign(b)`, `BitXorAssign::bitxor_assign(&mut a, b)`, and
/// `<T as BitXorAssign>::bitxor_assign(&mut a, b)` are not accepted.
pub trait BitXorAssign {}
impl_bit_for_integers_and_bool!(BitXorAssign);

// =================== Shifts ===================
//
// The right-hand side of every shift must be **compile-time known** — a
// literal, a `const`, or anything else the interpreter resolves at lowering
// time. A shift by a runtime-determined amount is rejected.

// Per-impl helper: emits a single `impl` carrying the per-type compile-time
// caveat doc, so the note shows up next to the impl on the type's own page
// (e.g. `arcis::std::integer::u32`), not just on the trait page.
macro_rules! impl_shift {
    ($trait:ident, $ty:ty) => {
        /// Right-hand side must be **compile-time known**.
        impl $trait for $ty {}
    };
}

macro_rules! impl_shift_for_integers {
    ($trait:ident) => {
        impl_shift!($trait, crate::std::integer::u8);
        impl_shift!($trait, crate::std::integer::u16);
        impl_shift!($trait, crate::std::integer::u32);
        impl_shift!($trait, crate::std::integer::u64);
        impl_shift!($trait, crate::std::integer::u128);
        impl_shift!($trait, crate::std::integer::usize);

        impl_shift!($trait, crate::std::integer::i8);
        impl_shift!($trait, crate::std::integer::i16);
        impl_shift!($trait, crate::std::integer::i32);
        impl_shift!($trait, crate::std::integer::i64);
        impl_shift!($trait, crate::std::integer::i128);
        impl_shift!($trait, crate::std::integer::isize);
    };
}

/// Left-shift operator `<<`. Mirrors [`std::ops::Shl`].
///
/// The right-hand side must be **compile-time known**.
///
/// Use `<<` directly; the methods (`.shl(b)`, `Shl::shl(a, b)`, `<T as Shl>::shl(a, b)`)
/// and the associated type `<T as Shl>::Output` are not accepted.
pub trait Shl {}
impl_shift_for_integers!(Shl);

/// Right-shift operator `>>`. Mirrors [`std::ops::Shr`].
///
/// The right-hand side must be **compile-time known**.
///
/// Use `>>` directly; the methods (`.shr(b)`, `Shr::shr(a, b)`, `<T as Shr>::shr(a, b)`)
/// and the associated type `<T as Shr>::Output` are not accepted.
pub trait Shr {}
impl_shift_for_integers!(Shr);

/// Compound assignment `<<=`. Mirrors [`std::ops::ShlAssign`].
///
/// The right-hand side must be **compile-time known**.
///
/// Use `<<=` directly; `.shl_assign(b)`, `ShlAssign::shl_assign(&mut a, b)`, and
/// `<T as ShlAssign>::shl_assign(&mut a, b)` are not accepted.
pub trait ShlAssign {}
impl_shift_for_integers!(ShlAssign);

/// Compound assignment `>>=`. Mirrors [`std::ops::ShrAssign`].
///
/// The right-hand side must be **compile-time known**.
///
/// Use `>>=` directly; `.shr_assign(b)`, `ShrAssign::shr_assign(&mut a, b)`, and
/// `<T as ShrAssign>::shr_assign(&mut a, b)` are not accepted.
pub trait ShrAssign {}
impl_shift_for_integers!(ShrAssign);

// =================== Index / IndexMut ===================
//
// `a[i]` and `a[i] = …` work on arrays, slices, and `Box<[T]>`. The index `i`
// may be a `usize` (single element) or any of the range types in this module
// (slice).
//
// If the index is known at compile time, the access compiles to a direct
// reference. If it is determined at runtime, the access compiles to a circuit
// of size O(`a.len()`) — every element is conditionally selected.

macro_rules! impl_index_for_sequences {
    ($trait:ident) => {
        impl<T, const N: usize> $trait<crate::std::integer::usize> for [T; N] {}
        impl<T> $trait<crate::std::integer::usize> for [T] {}
        impl<T> $trait<crate::std::integer::usize> for crate::std::boxed::Box<[T]> {}
    };
}

/// Indexing operator `a[i]`. Mirrors [`std::ops::Index`].
///
/// Use the `a[i]` form directly; the method (`.index(i)`,
/// `Index::index(&a, i)`, `<T as Index<Idx>>::index(&a, i)`) and the
/// associated type `<T as Index<Idx>>::Output` are not accepted.
///
/// **Index types:**
///
/// * `usize` — single-element access.
/// * Any range type — yields a slice. Bounds that are specified must be compile-time known.
///   * [`Range<usize>`](Range), [`RangeInclusive<usize>`](RangeInclusive) — `arr[2..5]`,
///     `arr[2..=4]`.
///   * [`RangeFrom<usize>`](RangeFrom), [`RangeTo<usize>`](RangeTo),
///     [`RangeToInclusive<usize>`](RangeToInclusive) — `arr[2..]`, `arr[..5]`, `arr[..=4]`.
///   * [`RangeFull`] — `arr[..]` clones the whole array.
///
/// **Complexity:** if the index / range bounds are compile-time known, the
/// access compiles to a direct reference. If determined at runtime, the access
/// compiles to a circuit of size O(`a.len()`).
///
/// **Autoderef:** indexing through one or more layers of reference is accepted
/// (`(&arr)[0]`, `(&&arr)[0]`, …). Rust's method-call autoderef peels them
/// before reaching the `Index` impl, so the implementor list below only
/// mentions the underlying types.
pub trait Index<Idx> {}
impl_index_for_sequences!(Index);

/// Mutable indexing operator `a[i] = …`. Mirrors [`std::ops::IndexMut`].
///
/// Use the `a[i] = …` form (or `a[i] += …`, etc.) directly; the method forms
/// (`.index_mut(i)`, `IndexMut::index_mut(&mut a, i)`,
/// `<T as IndexMut<Idx>>::index_mut(&mut a, i)`) are not accepted.
///
/// Same constraints as [`Index`] for the index types, the runtime cost, and
/// autoderef.
pub trait IndexMut<Idx>: Index<Idx> {}
impl_index_for_sequences!(IndexMut);

// =================== Ranges ===================
//
// Each type mirrors the same-named type in [`std::ops`]. The interpreter
// constructs them from the corresponding range syntax; users typically don't
// spell the type name.
//
// **Iteration:**
// * [`Range`] (`a..b`), [`RangeInclusive`] (`a..=b`) — fully iterable.
// * [`RangeFrom`] (`a..`) — forward iteration works; anything requiring a total length (`.count()`,
//   `.rev()`, iterator adapters that need `.len()`) panics.
// * [`RangeTo`] (`..b`), [`RangeToInclusive`] (`..=b`), [`RangeFull`] (`..`) — not iterable; every
//   iterator method panics. Slice-indexing only.
//
// **Slice indexing:** all six work as slice indices (see [`Index`]).
//
// **Field visibility** follows [`std::ops`] — public fields where std has them,
// private fields on [`RangeInclusive`] with `.start()` / `.end()` accessors.

const RANGE_STUB_MSG: &str = "arcis::std::ops range types are documentation-only; \
    inside `#[encrypted]` code the interpreter intercepts real range \
    construction / iteration / slicing before these stubs run.";

/// A (half-open) range `start..end`. Mirrors [`std::ops::Range`].
///
/// Contains all values with `start <= x < end`; empty when `start >= end`.
///
/// Iterable — yields `start`, `start + 1`, …, `end - 1`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Range<Idx> {
    /// The lower bound (inclusive).
    pub start: Idx,
    /// The upper bound (exclusive).
    pub end: Idx,
}

impl<Idx> Range<Idx> {
    /// Returns whether `t` lies in the range: `start <= t < end`.
    pub fn contains(&self, _t: Idx) -> bool {
        unimplemented!("{RANGE_STUB_MSG}")
    }
}

/// A closed range `start..=end`. Mirrors [`std::ops::RangeInclusive`].
///
/// Contains all values with `start <= x <= end`; empty when `start > end`.
///
/// Iterable — yields `start`, `start + 1`, …, `end`.
///
/// Fields are private (matching [`std::ops::RangeInclusive`]); use
/// [`Self::start`] and [`Self::end`] to read them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RangeInclusive<Idx> {
    start: Idx,
    end: Idx,
}

impl<Idx> RangeInclusive<Idx> {
    /// Constructs a new `start..=end`.
    pub fn new(_start: Idx, _end: Idx) -> Self {
        unimplemented!("{RANGE_STUB_MSG}")
    }
    /// Returns a reference to the range's start.
    pub fn start(&self) -> &Idx {
        unimplemented!("{RANGE_STUB_MSG}")
    }
    /// Returns a reference to the range's end.
    pub fn end(&self) -> &Idx {
        unimplemented!("{RANGE_STUB_MSG}")
    }
    /// Returns whether `t` lies in the range: `start <= t <= end`.
    pub fn contains(&self, _t: Idx) -> bool {
        unimplemented!("{RANGE_STUB_MSG}")
    }
}

/// A range with only a lower bound: `start..`. Mirrors [`std::ops::RangeFrom`].
///
/// Forward iteration (`.next()`) yields `start`, `start + 1`, … indefinitely.
/// Any operation that needs the total length — `.count()`, `.rev()`, adapters
/// that require `.len()` — panics at interpret time because the length is
/// unbounded.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RangeFrom<Idx> {
    /// The lower bound (inclusive).
    pub start: Idx,
}

impl<Idx> RangeFrom<Idx> {
    /// Returns whether `t` lies in the range: `start <= t`.
    pub fn contains(&self, _t: Idx) -> bool {
        unimplemented!("{RANGE_STUB_MSG}")
    }
}

/// A range with only an exclusive upper bound: `..end`. Mirrors [`std::ops::RangeTo`].
///
/// Not iterable — every iterator method panics at interpret time. Use as a
/// slice index only.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RangeTo<Idx> {
    /// The upper bound (exclusive).
    pub end: Idx,
}

impl<Idx> RangeTo<Idx> {
    /// Returns whether `t` lies in the range: `t < end`.
    pub fn contains(&self, _t: Idx) -> bool {
        unimplemented!("{RANGE_STUB_MSG}")
    }
}

/// A range with only an inclusive upper bound: `..=end`. Mirrors
/// [`std::ops::RangeToInclusive`].
///
/// Not iterable — every iterator method panics at interpret time. Use as a
/// slice index only.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RangeToInclusive<Idx> {
    /// The upper bound (inclusive).
    pub end: Idx,
}

impl<Idx> RangeToInclusive<Idx> {
    /// Returns whether `t` lies in the range: `t <= end`.
    pub fn contains(&self, _t: Idx) -> bool {
        unimplemented!("{RANGE_STUB_MSG}")
    }
}

/// The unbounded range `..`. Mirrors [`std::ops::RangeFull`].
///
/// Not iterable — every iterator method panics at interpret time. Used mainly
/// as a slice index (`arr[..]` clones the whole array).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct RangeFull;

impl RangeFull {
    /// Always `true` — every value is contained in the full range.
    pub fn contains<T>(&self, _t: T) -> bool {
        unimplemented!("{RANGE_STUB_MSG}")
    }
}