field-cat 0.1.0

//! The [`Field`] trait: minimal algebraic interface for a finite field.
//!
//! A finite field provides the algebraic operations needed for
//! constraint systems and proof protocols.  The trait uses
//! `std::ops` supertraits for arithmetic and adds only `zero`,
//! `one`, and `inv`.

use crate::error::Error;

/// A finite field element.
///
/// Implementations must satisfy the field axioms: associativity,
/// commutativity, distributivity of multiplication over addition,
/// and existence of additive and multiplicative inverses.
///
/// # Examples
///
/// ```
/// use field_cat::{BabyBear, Field};
///
/// let a = BabyBear::new(7);
/// let b = BabyBear::new(11);
///
/// // Field axioms hold:
/// assert_eq!(a + BabyBear::zero(), a);
/// assert_eq!(a * BabyBear::one(), a);
/// assert_eq!(a + (-a), BabyBear::zero());
///
/// let a_inv = a.inv()?;
/// assert_eq!(a * a_inv, BabyBear::one());
/// # Ok::<(), field_cat::Error>(())
/// ```
pub trait Field:
    Sized
    + Clone
    + PartialEq
    + Eq
    + core::fmt::Debug
    + std::ops::Add<Output = Self>
    + std::ops::Sub<Output = Self>
    + std::ops::Mul<Output = Self>
    + std::ops::Neg<Output = Self>
{
    /// The additive identity.
    #[must_use]
    fn zero() -> Self;

    /// The multiplicative identity.
    #[must_use]
    fn one() -> Self;

    /// Multiplicative inverse.
    ///
    /// # Errors
    ///
    /// Returns [`Error::DivisionByZero`] if `self` is zero.
    fn inv(&self) -> Result<Self, Error>;
}