Struct Modulus 

pub struct Modulus { /* private fields */ }

Modulus is a type of a positive integer larger than 1 that is used to do modulus operations.

Attributes:

• modulus: holds the value of the modulus

Examples

Create Modulus from str:

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;
use qfall_math::integer::Z;
let value = Z::from(10);

// instantiations
let _ = Modulus::from(10);
let a = Modulus::from_str("42").unwrap();
let b: Modulus = (&value).try_into().unwrap();

// clone
let clone = a.clone();

// properties
let is_prime: bool = a.is_prime();

// to_string incl. (de-)serialization
assert_eq!("42", &a.to_string());
assert_eq!(
    "{\"modulus\":\"42\"}",
    serde_json::to_string(&a).unwrap()
);

// comparison
assert_eq!(a, clone);

Implementations

impl Modulus

pub fn is_prime(&self) -> bool

Checks if a Modulus is prime.

Returns true if the modulus is prime.

use std::str::FromStr;
use qfall_math::integer_mod_q::Modulus;

let modulus = Modulus::from(17);
assert!(modulus.is_prime());

impl Modulus

pub unsafe fn get_fmpz_mod_ctx(&mut self) -> &mut fmpz_mod_ctx

Returns a mutable reference to the field modulus of type fmpz_mod_ctx.

WARNING: The returned struct is part of flint_sys. Any changes to this object are unsafe and may introduce memory leaks. Please be aware that most moduli are shared across multiple instances and all modifications of this struct will affect any other instance with a reference to this object.

This function is a passthrough to enable users of this library to use flint_sys and with that FLINT functions that might not be covered in our library yet. If this is the case, please consider contributing to this open-source project by opening a Pull Request at qfall_math to provide this feature in the future.

Safety

Any flint_sys struct and function is part of a FFI to the C-library FLINT. As FLINT is a C-library, it does not provide all memory safety features that Rust and our Wrapper provide. Thus, using functions of flint_sys can introduce memory leaks.

impl Modulus

pub unsafe fn set_fmpz_mod_ctx(&mut self, flint_struct: fmpz_mod_ctx)

Sets a mutable reference to the field modulus of type Modulus to a given fmpz_mod_ctx.

Parameters:

• flint_struct: value to set the attribute to

WARNING: The set struct is part of flint_sys. Any changes to this object are unsafe and may introduce memory leaks. Please be aware that most moduli are shared across multiple instances and all modifications of this struct will affect any other instance with a reference to this object.

This function is a passthrough to enable users of this library to use flint_sys and with that FLINT functions that might not be covered in our library yet. If this is the case, please consider contributing to this open-source project by opening a Pull Request at qfall_math to provide this feature in the future.

Safety

Ensure that the old modulus does not share any memory with any moduli that might be used in the future. The memory of the old modulus is freed using this function.

Any flint_sys struct and function is part of a FFI to the C-library FLINT. As FLINT is a C-library, it does not provide all memory safety features that Rust and our Wrapper provide. Thus, using functions of flint_sys can introduce memory leaks.

Trait Implementations

impl Clone for Modulus

fn clone(&self) -> Self

Clones the given element and returns another cloned reference to the fmpz_mod_ctx element.

Examples

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let a = Modulus::from(3);
let b = a.clone();

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

Performs copy-assignment from source.

impl Debug for Modulus

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Modulus

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Implements the deserialize option. This allows to create a Modulus from a given Json-object.

impl Display for Modulus

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

Allows to convert a modulus of type Modulus into a String.

Examples

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;
use core::fmt;

let modulus = Modulus::from(42);
println!("{modulus}");

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let modulus = Modulus::from(42);
let modulus_string = modulus.to_string();

impl<Integer: Into<Z>> Distance<Integer> for Modulus

fn distance(&self, other: Integer) -> Self::Output

Computes the absolute distance between a Modulus and a value that implements Into<Z>.

Parameters:

• other: specifies the Z value whose distance is calculated to self

Returns the absolute difference, i.e. distance between the Modulus instance and the value that implements Into<Z> as a new Z instance.

Examples

use qfall_math::integer::Z;
use qfall_math::integer_mod_q::Modulus;
use qfall_math::traits::*;

let a = Modulus::from(2);

let distance_0 = a.distance(5);
let distance_1 = a.distance(10);

type Output = Z

impl Drop for Modulus

fn drop(&mut self)

Drops the given reference to the fmpz_mod_ctx element and frees the allocated memory if no references are left.

Examples

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;
{
    let a = Modulus::from(3);
} // as a's scope ends here, it get's dropped

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let a = Modulus::from(3);
drop(a); // explicitly drops a's value

impl From<&Modulus> for Modulus

fn from(value: &Modulus) -> Self

Alias for Modulus::clone.

impl From<&Modulus> for String

fn from(value: &Modulus) -> Self

Converts a Modulus into its String representation.

Parameters:

• value: specifies the modulus that will be represented as a String

Returns a String.

Examples

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;
let modulus = Modulus::from_str("6").unwrap();

let string: String = modulus.into();

impl<Integer: AsInteger + IntoModulus> From<Integer> for Modulus

fn from(value: Integer) -> Self

Creates a Modulus from a positive integer.

Parameters:

• value: the initial value the modulus should have. It must be larger than one.

Returns a Modulus or an panics, if the provided value is smaller than 2.

Examples

use qfall_math::integer_mod_q::Modulus;
use qfall_math::integer::Z;

let _ = Modulus::from(10);
let _ = Modulus::from(u64::MAX);
let _ = Modulus::from(Z::from(42));

Panics …

• if the provided value is smaller than 2.

impl From<Modulus> for String

fn from(value: Modulus) -> Self

Documentation can be found at String::from for &Modulus.

impl FromStr for Modulus

fn from_str(s: &str) -> Result<Self, Self::Err>

Creates a Modulus from a String.

Parameters:

• s: the modulus of form: "[0-9]+" and not all zeros.

Returns a Modulus or an MathError, if the provided string is not a valid modulus.

Examples

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let modulus = Modulus::from_str("42").unwrap();

Errors and Failures

• Returns a MathError of type StringConversionError if the provided string was not formatted correctly, e.g. not a correctly formatted Z.
• Returns a MathError of type InvalidModulus if the provided value is smaller than 2.

type Err = MathError

The associated error which can be returned from parsing.

impl Ord for Modulus

Enables the usage of max, min, and clamp.

Examples

use qfall_math::integer_mod_q::Modulus;
use std::cmp::{max, min};

let a: Modulus = Modulus::from(10);
let b: Modulus = Modulus::from(42);

assert_eq!(b, max(a.clone(), b.clone()));
assert_eq!(a, min(a.clone(), b.clone()));
assert_eq!(a, Modulus::from(2).clamp(a.clone(), b.clone()));

fn cmp(&self, other: &Self) -> Ordering

Compares two Modulus values. Used by the <, <=, >, and >= operators.

Parameters:

• other: the other value that is used to compare the elements

Returns the Ordering of the elements.

Examples

use qfall_math::integer_mod_q::Modulus;

let a: Modulus = Modulus::from(10);
let b: Modulus = Modulus::from(42);

assert!(a < b);
assert!(a <= b);
assert!(b > a);
assert!(b >= a);

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 PartialEq<Modulus> for Q

fn eq(&self, other: &Modulus) -> bool

Checks if an integer and a rational are equal. Used by the == and != operators. PartialEq is also implemented for Modulus using Q.

Parameters:

• other: the other value that is used to compare the elements

Returns true if the elements are equal, otherwise false.

Examples

use qfall_math::integer_mod_q::Modulus;
use qfall_math::rational::Q;
let a: Q = Q::from(42);
let b: Modulus = Modulus::from(42);

// These are all equivalent and return true.
let compared: bool = (a == b);
let compared: bool = (b == a);
let compared: bool = (&a == &b);
let compared: bool = (&b == &a);
let compared: bool = (a.eq(&b));
let compared: bool = (b.eq(&a));
let compared: bool = (Q::eq(&a, &b));
let compared: bool = (Modulus::eq(&b, &a));

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 PartialEq<Z> for Modulus

fn eq(&self, other: &Z) -> bool

Checks if an integer and a modulus are equal. Used by the == and != operators. PartialEq is also implemented for Z using Modulus.

Parameters:

• other: the other value that is used to compare the elements

Returns true if the elements are equal, otherwise false.

Examples

use qfall_math::integer::Z;
use qfall_math::integer_mod_q::Modulus;
let a: Modulus = Modulus::from(42);
let b: Z = Z::from(42);

// These are all equivalent and return true.
let compared: bool = (a == b);
let compared: bool = (b == a);
let compared: bool = (&a == &b);
let compared: bool = (&b == &a);
let compared: bool = (a.eq(&b));
let compared: bool = (b.eq(&a));
let compared: bool = (Z::eq(&b, &a));
let compared: bool = (Modulus::eq(&a, &b));

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 PartialEq for Modulus

fn eq(&self, other: &Self) -> bool

Compares the two fmpz structs hiding behind the given Modulus instances to check whether the given Modulus instances have the same value.

Parameters:

• other: holds another Modulus object which self is compared to

Examples

use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let a = Modulus::from(3);
let b = Modulus::from(3);
let c = Modulus::from(4);

assert_eq!(a, b);
assert_ne!(a, c);

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 PartialOrd<Modulus> for Z

fn partial_cmp(&self, other: &Modulus) -> Option<Ordering>

Compares a Z value with a Modulus. Used by the <, <=, >, and >= operators. PartialOrd is also implemented for Z using Modulus.

Parameters:

• other: the other value that is used to compare the elements

Returns the Ordering of the elements.

Examples

use qfall_math::integer::Z;
use qfall_math::integer_mod_q::Modulus;

let a: Modulus = Modulus::from(10);
let b: Z = Z::from(42);

assert!(a < b);
assert!(a <= b);
assert!(b > a);
assert!(b >= a);

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 PartialOrd<Z> for Modulus

fn partial_cmp(&self, other: &Z) -> Option<Ordering>

Compares a Z value with a Modulus. Used by the <, <=, >, and >= operators. PartialOrd is also implemented for Z using Modulus.

Parameters:

• other: the other value that is used to compare the elements

Returns the Ordering of the elements.

Examples

use qfall_math::integer::Z;
use qfall_math::integer_mod_q::Modulus;

let a: Modulus = Modulus::from(10);
let b: Z = Z::from(42);

assert!(a < b);
assert!(a <= b);
assert!(b > a);
assert!(b >= a);

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 PartialOrd for Modulus

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Compares two Modulus values. Used by the <, <=, >, and >= operators.

Parameters:

• other: the other value that is used to compare the elements

Returns the Ordering of the elements.

Examples

use qfall_math::integer_mod_q::Modulus;

let a: Modulus = Modulus::from(10);
let b: Modulus = Modulus::from(42);

assert!(a < b);
assert!(a <= b);
assert!(b > a);
assert!(b >= a);

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 Rem<&Modulus> for &MatPolyOverZ

fn rem(self, modulus: &Modulus) -> Self::Output

Computes self mod modulus as long as modulus is greater than 1. For negative entries in self, the smallest positive representative is returned.

Parameters:

• modulus: specifies a non-zero integer over which the positive remainders are computed

Returns self mod modulus as a MatPolyOverZ instance.

Examples

use qfall_math::integer::MatPolyOverZ;
use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let a: MatPolyOverZ = MatPolyOverZ::from_str("[[2  1 -2],[1  42]]").unwrap();
let b = Modulus::from(24);

let c: MatPolyOverZ = &a % &b;

type Output = MatPolyOverZ

The resulting type after applying the % operator.

impl Rem<&Modulus> for &MatZ

fn rem(self, modulus: &Modulus) -> Self::Output

Computes self mod modulus. For negative entries in self, the smallest positive representative is returned.

Parameters:

• modulus: specifies a non-zero integer over which the positive remainders are computed

Returns self mod modulus as a MatZ instance.

Examples

use qfall_math::integer::MatZ;
use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let a: MatZ = MatZ::from_str("[[-2],[42]]").unwrap();
let b = Modulus::from(24);

let c: MatZ = &a % &b;

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<&Modulus> for &PolyOverZ

fn rem(self, modulus: &Modulus) -> Self::Output

Computes self mod modulus as long as modulus is greater than 1. For negative values of self, the smallest positive representative is returned.

Parameters:

• modulus: specifies a non-zero integer over which the positive remainder is computed

Returns self mod modulus as a PolyOverZ instance.

Examples

use qfall_math::integer_mod_q::Modulus;
use qfall_math::integer::{PolyOverZ, Z};
use std::str::FromStr;

let a: PolyOverZ = PolyOverZ::from_str("2  -2 42").unwrap();
let b = Modulus::from(24);

let c: PolyOverZ = a % b;

type Output = PolyOverZ

The resulting type after applying the % operator.

impl Rem<&Modulus> for &Z

fn rem(self, modulus: &Modulus) -> Self::Output

Computes self mod modulus as long as modulus is greater than 1. For negative values of self, the smallest positive representative is returned.

Parameters:

• modulus: specifies a non-zero integer over which the positive remainder is computed

Returns self mod modulus as a Z instance.

Examples

use qfall_math::integer::Z;
use qfall_math::integer_mod_q::Modulus;

let a: Z = Z::from(42);
let b = Modulus::from(24);

let c: Z = a % &b;

type Output = Z

The resulting type after applying the % operator.

impl Serialize for Modulus

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Implements the serialize option. This allows to create a Json-object from a given Modulus.

impl Eq for Modulus