qfall_math/integer_mod_q/
z_q.rs

1// Copyright © 2023 Marcel Luca Schmidt, Niklas Siemer
2//
3// This file is part of qFALL-math.
4//
5// qFALL-math is free software: you can redistribute it and/or modify it under
6// the terms of the Mozilla Public License Version 2.0 as published by the
7// Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
8
9//! This module implements [`Zq`].
10//!
11//! This implementation uses [`fmpz_mod`](https://www.flintlib.org/doc/fmpz_mod.html)
12//! from the [FLINT](https://flintlib.org/) library.
13//! FLINT uses a `fmpz_mod_ctx_struct` to store functions and data used for
14//! optimizing modulo operations.
15//! This struct is wrapped in [`Modulus`] for easy use.
16
17// For **DEVELOPERS**: Many functions assume that the [`Zq`] instances are reduced.
18// To avoid unnecessary checks and reductions, always return canonical/reduced
19// values. The end-user should be unable to obtain a non-reduced value.
20
21use super::Modulus;
22use crate::integer::Z;
23use serde::{Deserialize, Serialize};
24use std::fmt;
25
26mod arithmetic;
27mod cmp;
28pub(crate) mod fmpz_mod_helpers;
29mod from;
30mod get;
31mod properties;
32mod reduce;
33mod sample;
34mod to_string;
35mod unsafe_functions;
36
37/// [`Zq`] is an arbitrary integer value in a residue class.
38///
39/// Attributes:
40/// - `value`: holds a [`Z`] value for an integer value
41/// - `modulus`: holds a [`Modulus`] above which the value is reduced
42///
43/// # Examples
44/// ```
45/// # use qfall_math::error::MathError;
46/// use qfall_math::integer_mod_q::Zq;
47/// use std::str::FromStr;
48///
49/// // instantiation
50/// let a = Zq::from((5, 10));
51/// let b = Zq::from_str("93 mod 10")?;
52/// let _ = a.clone();
53///
54/// // arithmetics
55/// let _ = &a + &b;
56/// let _ = &a * &b;
57///
58/// // to_string incl. (de-)serialization
59/// assert_eq!("5 mod 10", &a.to_string());
60/// let _ = serde_json::to_string(&a).unwrap();
61///
62/// # Ok::<(), MathError>(())
63/// ```
64#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
65pub struct Zq {
66    pub(crate) value: Z,
67    pub(crate) modulus: Modulus,
68}
69
70impl fmt::Debug for Zq {
71    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
72        write!(
73            f,
74            "Zq {{value: {}, modulus: {}, storage: {{value: {:?} , modulus: {:?}}}}}",
75            self.value, self.modulus, self.value, self.modulus,
76        )
77    }
78}
qfall_math/integer_mod_q/z_q.rs

qfall_math/integer_mod_q/
z_q.rs
