Struct FieldElement 

pub struct FieldElement<const N: usize, F>(/* private fields */)
where
    F: FiniteField<N>;

An element of the finite field F.

All operations are performed modulo F::MODULUS.

Implementations

impl<const N: usize, F: FiniteField<N>> FieldElement<N, F>

pub const ZERO: Self

pub const ONE: Self

pub const unsafe fn new_unchecked(int: UBigInt<N>) -> Self

Creates a new FieldElement without checking if int is less than F::MODULUS.

Safety

int must be less than F::MODULUS. A violation of this will result in undefined behavior.

In most cases, it’s better to use the safe version: Self::try_new()

pub fn try_new(int: UBigInt<N>) -> Option<Self>

Creates a new FieldElement from int, returning an Err if int is greater than or equal to F::MODULUS.

This is the safe version of Self::new_unchecked()

pub fn inner(&self) -> &UBigInt<N>

pub fn into_inner(self) -> UBigInt<N>

pub fn count_digits(&self) -> usize

Returns the number of digits in self, not counting leading zeros

Constant-timedness

This function is constant-time.

pub fn add(&self, rhs: &Self) -> Self

Returns self + rhs modulo F::MODULUS.

Constant-timedness

This is a constant-time operation.

pub fn add_assign(&mut self, rhs: &Self)

pub fn double(&self) -> Self

pub fn double_assign(&mut self)

pub fn sub(&self, rhs: &Self) -> Self

Returns self - rhs modulo F::MODULUS.

Constant-timedness

This is a constant-time operation.

pub fn sub_assign(&mut self, rhs: &Self)

Sets self to self - rhs modulo F::MODULUS.

Constant-timedness

This is a constant-time operation.

pub fn neg(&self) -> Self

Returns the modular additive inverse of self.

The returned value has the property that, when added to self, the sum is FieldElement::ZERO.

pub unsafe fn neg_unchecked(&self) -> Self

Returns the modular additive inverse of self, assuming self isn’t FieldElement::ZERO.

Safety

self cannot be FieldElement::ZERO.

pub fn neg_assign(&mut self)

Sets self to the modular additive inverse of self.

The returned value has the property that, when added to self, the sum is FieldElement::ZERO.

pub unsafe fn neg_assign_unchecked(&mut self)

Safety

self cannot be FieldElement::ZERO

impl<F: FiniteField<3>> FieldElement<3, F>

pub fn new(value: UBigInt<3>) -> Self

Creates a new FieldElement from value.

If value is greater than F::MODULUS, it is properly reduced.

Because it always performs a division operation, this function is much slower than a simple type conversion. If higher performance, at the cost of falibility, is necessary, use Self::try_new() or its unsafe counterpart, Self::new_unchecked()

pub fn convert<G: FiniteField<3>>(&self) -> FieldElement<3, G>

pub fn mul(&self, rhs: &Self) -> Self

Returns self * rhs modulo F::MODULUS.

Constant-timedness

TODO: document constant-timedness

pub fn mul_assign(&mut self, rhs: &Self)

Sets self to self * rhs modulo F::MODULUS.

pub fn mul_digit_assign(&mut self, digit: u64)

pub fn mul_digit(&self, digit: u64) -> Self

pub fn div(&self, rhs: &Self) -> Self

Returns self / rhs modulo F::MODULUS.

Constant-timedness

TODO: document constant-timedness

pub fn sqr(&self) -> Self

Returns the square of self modulo F::MODULUS.

pub fn sqr_assign(&mut self)

Squares self module F::MODULUS and stores the result of self.

pub fn inverse(&self) -> Self

Returns the modular multiplicative inverse of self.

This value has the property that self.inverse() * self == 1

Panics

This function panics if self is FieldElement::ZERO in debug mode.

In release mode, FieldElement::ZERO.inverse() returns FieldElement::ZERO.

Constant-timedness

TODO: document constant-timedness

impl<F: FiniteField<4>> FieldElement<4, F>

pub fn new(value: UBigInt<4>) -> Self

Creates a new FieldElement from value.

If value is greater than F::MODULUS, it is properly reduced.

Because it always performs a division operation, this function is much slower than a simple type conversion. If higher performance, at the cost of falibility, is necessary, use Self::try_new() or its unsafe counterpart, Self::new_unchecked()

pub fn convert<G: FiniteField<4>>(&self) -> FieldElement<4, G>

pub fn mul(&self, rhs: &Self) -> Self

Returns self * rhs modulo F::MODULUS.

Constant-timedness

TODO: document constant-timedness

pub fn mul_assign(&mut self, rhs: &Self)

Sets self to self * rhs modulo F::MODULUS.

pub fn mul_digit_assign(&mut self, digit: u64)

pub fn mul_digit(&self, digit: u64) -> Self

pub fn div(&self, rhs: &Self) -> Self

Returns self / rhs modulo F::MODULUS.

Constant-timedness

TODO: document constant-timedness

pub fn sqr(&self) -> Self

Returns the square of self modulo F::MODULUS.

pub fn sqr_assign(&mut self)

Squares self module F::MODULUS and stores the result of self.

pub fn inverse(&self) -> Self

Returns the modular multiplicative inverse of self.

This value has the property that self.inverse() * self == 1

Panics

This function panics if self is FieldElement::ZERO in debug mode.

In release mode, FieldElement::ZERO.inverse() returns FieldElement::ZERO.

Constant-timedness

TODO: document constant-timedness

Methods from Deref<Target = UBigInt<N>>

pub const ZERO: Self

pub const MAX: Self

pub const MIN: Self = Self::ZERO

pub const ONE: Self

pub fn overflowing_sub(&self, rhs: &Self) -> (Self, bool)

Subtracts rhs from self, returning the result and whether the operation overflowed.

If overflow occurs, it wraps around.

Constant-timedness

This operation is constant-time.

pub fn overflowing_add(&self, rhs: &Self) -> (Self, bool)

Adds self and rhs, returning the result and whether the operation overflowed.

If overflow occurs, it wraps around.

Constant-timedness

This operation is constant-time.

pub fn count_digits_fast(&self) -> usize

Returns the number of used digits in self.

This is not the same as Self::len().

Note: this function has not yet been benchmarked. It may not actually be any faster.

Constant-timedness

This operation is NOT constant-time. If constant-time is needed, use Self::count_digits().

pub fn count_digits(&self) -> usize

Returns the number of digits in self.

This is the same as floor(log64(self))

This is not the same as Self::len().

Examples

use crylib::big_int::UBigInt;

let large_int = UBigInt([0x0123456789abcdef, 0xfedcba9876543210, 0x0, 0x0]);

assert_eq!(large_int.count_digits(), 2);

Constant-timedness

This is a constant-time operation. If constant-time is not needed, consider using Self::count_digits_fast().

pub fn add(&self, rhs: &Self) -> Self

Returns self + rhs, wrapping on overflow.

If overflow occurs, it wraps around.

Examples

use crylib::big_int::UBigInt;

assert_eq!(UBigInt::<4>::ZERO.add(&UBigInt::ONE), UBigInt::ONE);
assert_eq!(UBigInt::<4>::MAX.add(&UBigInt::ONE), UBigInt::ZERO);

Constant-timedness

This is a constant-time operation.

pub fn double(&self) -> Self

pub fn mul_digit(&self, digit: u64) -> Self

Returns self * digit, wrapping on overflow.

pub fn overflowing_mul_digit(&self, digit: u64) -> (Self, u64)

pub fn sub(&self, rhs: &Self) -> Self

Returns self - rhs, wrapping on overflow.

Examples

use crylib::big_int::UBigInt;

assert_eq!(UBigInt::<4>::ONE.sub(&UBigInt::ONE), UBigInt::ZERO);
assert_eq!(UBigInt::<4>::ZERO.sub(&UBigInt::ONE), UBigInt::MAX);

Constant-timedness

This is a constant-time operation

pub fn and_bool(&self, rhs: bool) -> Self

Returns self if rhs is true, otherwise Self::ZERO.

Constant-timedness

This is a constant-time operation.

pub fn shift_right(&self, rhs: u64) -> Self

Performs a bitshift rhs % 64 to the right and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn shift_left(&self, rhs: u64) -> Self

Performs a bitshift rhs to the right and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn not(&self) -> Self

Returns the one’s compliment of self

Constant-timedness

This is a constant-time operation.

pub fn xor(&self, rhs: &Self) -> Self

Performs a bitwise XOR on self and rhs and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn and(&self, rhs: &Self) -> Self

Performs a bitwise AND on self and rhs and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn or(&self, rhs: &Self) -> Self

Performs a bitwise OR on self and rhs and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn nor(&self, rhs: &Self) -> Self

Performs a bitwise NOR on self and rhs and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn xnor(&self, rhs: &Self) -> Self

Performs a bitwise XNOR on self and rhs and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn nand(&self, rhs: &Self) -> Self

Performs a bitwise NAND on self and rhs and returns the result.

Constant-timedness

This is a constant-time operation.

pub fn len(&self) -> usize

Returns the number of digits self can store.

Examples

use crylib::big_int::UBigInt;

assert_eq!(UBigInt::<4>::ZERO.len(), 4);
assert_eq!(UBigInt::<3>::MAX.len(), 3);

Constant-timedness

This is a constant-time operation.

pub fn get_bit(&self, bit: usize) -> bool

pub fn count_bits(&self) -> usize

Counts the number of significant bits in self.

This is the same as floor(log2(self))

pub fn widening_mul(&self, rhs: &Self) -> UBigInt<{ _ }>

Calculates self * rhs, widening the output to avoid overflow.

Constant-timedness

This is a constant-time operation.

pub fn widening_shift_left(&self, rhs: u64) -> UBigInt<{ _ }>

Left-shifts self by rhs % 64 bits.

The output is 64 bits longer, so ovelflow never occurs.

Constant-timedness

This is a constant-time operation.

pub fn div(&self, rhs: &Self) -> (Self, Self)

Calculates self / rhs, returning the quotient and the remainder.

Panics

This function will panic if divisor equals Self::ZERO.

Constant-timedness

TODO: document constant-timedness

pub fn widening_mul(&self, rhs: &Self) -> UBigInt<{ _ }>

Calculates self * rhs, widening the output to avoid overflow.

Constant-timedness

This is a constant-time operation.

pub fn widening_shift_left(&self, rhs: u64) -> UBigInt<{ _ }>

Left-shifts self by rhs % 64 bits.

The output is 64 bits longer, so ovelflow never occurs.

Constant-timedness

This is a constant-time operation.

pub fn div(&self, rhs: &Self) -> (Self, Self)

Calculates self / rhs, returning the quotient and the remainder.

Panics

This function will panic if divisor equals Self::ZERO.

Constant-timedness

TODO: document constant-timedness

pub fn widening_mul(&self, rhs: &Self) -> UBigInt<{ _ }>

Calculates self * rhs, widening the output to avoid overflow.

Constant-timedness

This is a constant-time operation.

pub fn widening_shift_left(&self, rhs: u64) -> UBigInt<{ _ }>

Left-shifts self by rhs % 64 bits.

The output is 64 bits longer, so ovelflow never occurs.

Constant-timedness

This is a constant-time operation.

pub fn div(&self, rhs: &Self) -> (Self, Self)

Calculates self / rhs, returning the quotient and the remainder.

Panics

This function will panic if divisor equals Self::ZERO.

Constant-timedness

TODO: document constant-timedness

pub fn widening_mul(&self, rhs: &Self) -> UBigInt<{ _ }>

Calculates self * rhs, widening the output to avoid overflow.

Constant-timedness

This is a constant-time operation.

pub fn widening_shift_left(&self, rhs: u64) -> UBigInt<{ _ }>

Left-shifts self by rhs % 64 bits.

The output is 64 bits longer, so ovelflow never occurs.

Constant-timedness

This is a constant-time operation.

pub fn div(&self, rhs: &Self) -> (Self, Self)

Calculates self / rhs, returning the quotient and the remainder.

Panics

This function will panic if divisor equals Self::ZERO.

Constant-timedness

TODO: document constant-timedness

pub fn widening_mul(&self, rhs: &Self) -> UBigInt<{ _ }>

Calculates self * rhs, widening the output to avoid overflow.

Constant-timedness

This is a constant-time operation.

pub fn widening_shift_left(&self, rhs: u64) -> UBigInt<{ _ }>

Left-shifts self by rhs % 64 bits.

The output is 64 bits longer, so ovelflow never occurs.

Constant-timedness

This is a constant-time operation.

pub fn div(&self, rhs: &Self) -> (Self, Self)

Calculates self / rhs, returning the quotient and the remainder.

Panics

This function will panic if divisor equals Self::ZERO.

Constant-timedness

TODO: document constant-timedness

pub fn widening_mul(&self, rhs: &Self) -> UBigInt<{ _ }>

Calculates self * rhs, widening the output to avoid overflow.

Constant-timedness

This is a constant-time operation.

pub fn widening_shift_left(&self, rhs: u64) -> UBigInt<{ _ }>

Left-shifts self by rhs % 64 bits.

The output is 64 bits longer, so ovelflow never occurs.

Constant-timedness

This is a constant-time operation.

pub fn div(&self, rhs: &Self) -> (Self, Self)

Calculates self / rhs, returning the quotient and the remainder.

Panics

This function will panic if divisor equals Self::ZERO.

Constant-timedness

TODO: document constant-timedness

Trait Implementations

impl<const N: usize, F> Clone for FieldElement<N, F>

where F: FiniteField<N> + Clone,

fn clone(&self) -> FieldElement<N, F>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const N: usize, F: FiniteField<N>> Debug for FieldElement<N, F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const N: usize, F: FiniteField<N>> Deref for FieldElement<N, F>

type Target = UBigInt<N>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<const N: usize, F> Display for FieldElement<N, F>

where F: FiniteField<N>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const N: usize, F> Ord for FieldElement<N, F>

where F: FiniteField<N> + Ord,

fn cmp(&self, other: &FieldElement<N, F>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<const N: usize, F> PartialEq for FieldElement<N, F>

where F: FiniteField<N> + PartialEq,

fn eq(&self, other: &FieldElement<N, F>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const N: usize, F> PartialOrd for FieldElement<N, F>

where F: FiniteField<N> + PartialOrd,

fn partial_cmp(&self, other: &FieldElement<N, F>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const N: usize, F: FiniteField<N>> TryFrom<UBigInt<N>> for FieldElement<N, F>

type Error = InputTooLargeError

The type returned in the event of a conversion error.

fn try_from(value: UBigInt<N>) -> Result<Self, Self::Error>

Performs the conversion.

impl<const N: usize, F> Copy for FieldElement<N, F>

where F: FiniteField<N> + Copy,

impl<const N: usize, F> Eq for FieldElement<N, F>

where F: FiniteField<N> + Eq,

impl<const N: usize, F> StructuralPartialEq for FieldElement<N, F>

where F: FiniteField<N>,