Add ConstOption struct

Author: fjarri

benches/uint.rs

@@ -160,8 +160,8 @@ fn bench_inv_mod(c: &mut Criterion) {
                 let m = U256::random(&mut OsRng) | U256::ONE;
                 loop {
                     let x = U256::random(&mut OsRng);
-                    let (_, is_some) = x.inv_odd_mod(&m);
-                    if is_some.into() {
+                    let inv_x = x.inv_odd_mod(&m);
+                    if inv_x.is_some().into() {
                         break (x, m);
                     }
                 }
@@ -177,8 +177,8 @@ fn bench_inv_mod(c: &mut Criterion) {
                 let m = U256::random(&mut OsRng) | U256::ONE;
                 loop {
                     let x = U256::random(&mut OsRng);
-                    let (_, is_some) = x.inv_odd_mod(&m);
-                    if is_some.into() {
+                    let inv_x = x.inv_odd_mod(&m);
+                    if inv_x.is_some().into() {
                         break (x, m);
                     }
                 }
@@ -194,8 +194,8 @@ fn bench_inv_mod(c: &mut Criterion) {
                 let m = U256::random(&mut OsRng);
                 loop {
                     let x = U256::random(&mut OsRng);
-                    let (_, is_some) = black_box(x.inv_mod(&m));
-                    if is_some.into() {
+                    let inv_x = x.inv_mod(&m);
+                    if inv_x.is_some().into() {
                         break (x, m);
                     }
                 }

src/const_choice.rs

@@ -1,6 +1,6 @@
-use subtle::Choice;
+use subtle::{Choice, CtOption};
 
-use crate::Word;
+use crate::{NonZero, Uint, Word};
 
 /// A boolean value returned by constant-time `const fn`s.
 // TODO: should be replaced by `subtle::Choice` or `CtOption`
@@ -174,6 +174,125 @@ impl PartialEq for ConstChoice {
     }
 }
 
+/// An equivalent of `subtle::CtOption` usable in a `const fn` context.
+#[derive(Debug, Clone)]
+pub struct ConstOption<T> {
+    value: T,
+    is_some: ConstChoice,
+}
+
+impl<T> ConstOption<T> {
+    #[inline]
+    pub(crate) const fn new(value: T, is_some: ConstChoice) -> Self {
+        Self { value, is_some }
+    }
+
+    #[inline]
+    pub(crate) const fn some(value: T) -> Self {
+        Self {
+            value,
+            is_some: ConstChoice::TRUE,
+        }
+    }
+
+    #[inline]
+    pub(crate) const fn none(dummy_value: T) -> Self {
+        Self {
+            value: dummy_value,
+            is_some: ConstChoice::FALSE,
+        }
+    }
+
+    /// Returns a reference to the contents of this structure.
+    ///
+    /// **Note:** if the second element is `None`, the first value may take any value.
+    #[inline]
+    pub(crate) const fn components_ref(&self) -> (&T, ConstChoice) {
+        // Since Rust is not smart enough to tell that we would be moving the value,
+        // and hence no destructors will be called, we have to return a reference instead.
+        // See https://github.com/rust-lang/rust/issues/66753
+        (&self.value, self.is_some)
+    }
+
+    /// Returns a true [`ConstChoice`] if this value is `Some`.
+    #[inline]
+    pub const fn is_some(&self) -> ConstChoice {
+        self.is_some
+    }
+
+    /// Returns a true [`ConstChoice`] if this value is `None`.
+    #[inline]
+    pub const fn is_none(&self) -> ConstChoice {
+        self.is_some.not()
+    }
+
+    /// This returns the underlying value but panics if it is not `Some`.
+    #[inline]
+    pub fn unwrap(self) -> T {
+        assert!(self.is_some.is_true_vartime());
+        self.value
+    }
+}
+
+impl<T> From<ConstOption<T>> for CtOption<T> {
+    #[inline]
+    fn from(value: ConstOption<T>) -> Self {
+        CtOption::new(value.value, value.is_some.into())
+    }
+}
+
+// Need specific implementations to work around the
+// "destructors cannot be evaluated at compile-time" error
+// See https://github.com/rust-lang/rust/issues/66753
+
+impl<const LIMBS: usize> ConstOption<Uint<LIMBS>> {
+    /// This returns the underlying value if it is `Some` or the provided value otherwise.
+    #[inline]
+    pub const fn unwrap_or(self, def: Uint<LIMBS>) -> Uint<LIMBS> {
+        Uint::select(&def, &self.value, self.is_some)
+    }
+
+    /// Returns the contained value, consuming the `self` value.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the value is none with a custom panic message provided by
+    /// `msg`.
+    #[inline]
+    pub const fn expect(self, msg: &str) -> Uint<LIMBS> {
+        assert!(self.is_some.is_true_vartime(), "{}", msg);
+        self.value
+    }
+}
+
+impl<const LIMBS: usize> ConstOption<(Uint<LIMBS>, Uint<LIMBS>)> {
+    /// Returns the contained value, consuming the `self` value.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the value is none with a custom panic message provided by
+    /// `msg`.
+    #[inline]
+    pub const fn expect(self, msg: &str) -> (Uint<LIMBS>, Uint<LIMBS>) {
+        assert!(self.is_some.is_true_vartime(), "{}", msg);
+        self.value
+    }
+}
+
+impl<const LIMBS: usize> ConstOption<NonZero<Uint<LIMBS>>> {
+    /// Returns the contained value, consuming the `self` value.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the value is none with a custom panic message provided by
+    /// `msg`.
+    #[inline]
+    pub const fn expect(self, msg: &str) -> NonZero<Uint<LIMBS>> {
+        assert!(self.is_some.is_true_vartime(), "{}", msg);
+        self.value
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::ConstChoice;

src/lib.rs

@@ -176,7 +176,7 @@ mod wrapping;
 
 pub use crate::{
     checked::Checked,
-    const_choice::ConstChoice,
+    const_choice::{ConstChoice, ConstOption},
     limb::{Limb, WideWord, Word},
     non_zero::NonZero,
     traits::*,

src/modular/dyn_residue.rs

@@ -50,8 +50,9 @@ impl<const LIMBS: usize> DynResidueParams<LIMBS> {
         let r = Uint::MAX.rem(&nz_modulus).wrapping_add(&Uint::ONE);
         let r2 = Uint::rem_wide(r.square_wide(), &nz_modulus);
 
+        let maybe_inverse = modulus.inv_mod2k_vartime(Word::BITS);
         // If the inverse exists, it means the modulus is odd.
-        let (inv_mod_limb, modulus_is_odd) = modulus.inv_mod2k_vartime(Word::BITS);
+        let (inv_mod_limb, modulus_is_odd) = maybe_inverse.components_ref();
         let mod_neg_inv = Limb(Word::MIN.wrapping_sub(inv_mod_limb.limbs[0].0));
 
         let r3 = montgomery_reduction(&r2.square_wide(), modulus, mod_neg_inv);

src/modular/dyn_residue/inv.rs

@@ -4,7 +4,7 @@ use super::{DynResidue, DynResidueParams};
 use crate::{
     modular::{inv::inv_montgomery_form, BernsteinYangInverter},
     traits::Invert,
-    ConstChoice, Inverter, PrecomputeInverter, PrecomputeInverterWithAdjuster, Uint,
+    ConstOption, Inverter, PrecomputeInverter, PrecomputeInverterWithAdjuster, Uint,
 };
 use core::fmt;
 use subtle::CtOption;
@@ -14,28 +14,28 @@ impl<const LIMBS: usize> DynResidue<LIMBS> {
     /// I.e. `self * self^-1 = 1`.
     /// If the number was invertible, the second element of the tuple is the truthy value,
     /// otherwise it is the falsy value (in which case the first element's value is unspecified).
-    pub const fn invert(&self) -> (Self, ConstChoice) {
-        let (montgomery_form, is_some) = inv_montgomery_form(
+    pub const fn invert(&self) -> ConstOption<Self> {
+        let maybe_inverse = inv_montgomery_form(
             &self.montgomery_form,
             &self.residue_params.modulus,
             &self.residue_params.r3,
             self.residue_params.mod_neg_inv,
         );
+        let (montgomery_form, is_some) = maybe_inverse.components_ref();
 
         let value = Self {
-            montgomery_form,
+            montgomery_form: *montgomery_form,
             residue_params: self.residue_params,
         };
 
-        (value, is_some)
+        ConstOption::new(value, is_some)
     }
 }
 
 impl<const LIMBS: usize> Invert for DynResidue<LIMBS> {
     type Output = CtOption<Self>;
     fn invert(&self) -> Self::Output {
-        let (value, is_some) = self.invert();
-        CtOption::new(value, is_some.into())
+        self.invert().into()
     }
 }
 
@@ -114,7 +114,7 @@ mod tests {
             U256::from_be_hex("77117F1273373C26C700D076B3F780074D03339F56DD0EFB60E7F58441FD3685");
         let x_mod = DynResidue::new(&x, params);
 
-        let (inv, _is_some) = x_mod.invert();
+        let inv = x_mod.invert().unwrap();
         let res = x_mod * inv;
 
         assert_eq!(res.retrieve(), U256::ONE);

src/modular/inv.rs

@@ -1,13 +1,14 @@
-use crate::{modular::reduction::montgomery_reduction, ConstChoice, Limb, Uint};
+use crate::{modular::reduction::montgomery_reduction, ConstOption, Limb, Uint};
 
 pub const fn inv_montgomery_form<const LIMBS: usize>(
     x: &Uint<LIMBS>,
     modulus: &Uint<LIMBS>,
     r3: &Uint<LIMBS>,
     mod_neg_inv: Limb,
-) -> (Uint<LIMBS>, ConstChoice) {
-    let (inverse, is_some) = x.inv_odd_mod(modulus);
-    (
+) -> ConstOption<Uint<LIMBS>> {
+    let maybe_inverse = x.inv_odd_mod(modulus);
+    let (inverse, is_some) = maybe_inverse.components_ref();
+    ConstOption::new(
         montgomery_reduction(&inverse.split_mul(r3), modulus, mod_neg_inv),
         is_some,
     )

src/modular/residue/inv.rs

@@ -3,7 +3,7 @@
 use super::{Residue, ResidueParams};
 use crate::{
     modular::{inv::inv_montgomery_form, BernsteinYangInverter},
-    ConstChoice, Invert, Inverter, NonZero, PrecomputeInverter, Uint,
+    ConstChoice, ConstOption, Invert, Inverter, NonZero, PrecomputeInverter, Uint,
 };
 use core::{fmt, marker::PhantomData};
 use subtle::CtOption;
@@ -13,36 +13,37 @@ impl<MOD: ResidueParams<LIMBS>, const LIMBS: usize> Residue<MOD, LIMBS> {
     /// I.e. `self * self^-1 = 1`.
     /// If the number was invertible, the second element of the tuple is the truthy value,
     /// otherwise it is the falsy value (in which case the first element's value is unspecified).
-    pub const fn invert(&self) -> (Self, ConstChoice) {
-        let (montgomery_form, is_some) = inv_montgomery_form(
+    pub const fn invert(&self) -> ConstOption<Self> {
+        let maybe_inverse = inv_montgomery_form(
             &self.montgomery_form,
             &MOD::MODULUS.0,
             &MOD::R3,
             MOD::MOD_NEG_INV,
         );
+        let (montgomery_form, is_some) = maybe_inverse.components_ref();
 
         let value = Self {
-            montgomery_form,
+            montgomery_form: *montgomery_form,
             phantom: PhantomData,
         };
 
-        (value, is_some)
+        ConstOption::new(value, is_some)
     }
 }
 
 impl<MOD: ResidueParams<LIMBS>, const LIMBS: usize> Invert for Residue<MOD, LIMBS> {
     type Output = CtOption<Self>;
     fn invert(&self) -> Self::Output {
-        let (value, is_some) = self.invert();
-        CtOption::new(value, is_some.into())
+        self.invert().into()
     }
 }
 
 impl<MOD: ResidueParams<LIMBS>, const LIMBS: usize> Invert for NonZero<Residue<MOD, LIMBS>> {
     type Output = Self;
     fn invert(&self) -> Self::Output {
         // Always succeeds for a non-zero argument
-        let (value, _is_some) = self.as_ref().invert();
+        let value = self.as_ref().invert().unwrap();
+        // An inverse is necessarily non-zero
         NonZero::new(value).unwrap()
     }
 }
@@ -136,7 +137,7 @@ mod tests {
             U256::from_be_hex("77117F1273373C26C700D076B3F780074D03339F56DD0EFB60E7F58441FD3685");
         let x_mod = const_residue!(x, Modulus);
 
-        let (inv, _is_some) = x_mod.invert();
+        let inv = x_mod.invert().unwrap();
         let res = x_mod * inv;
 
         assert_eq!(res.retrieve(), U256::ONE);

src/modular/residue/macros.rs

@@ -29,7 +29,7 @@ macro_rules! impl_modulus {
                 }
 
                 // Can unwrap `NonZero::const_new()` here since `res` was asserted to be odd.
-                $crate::NonZero::<$uint_type>::const_new(res).0
+                $crate::NonZero::<$uint_type>::const_new(res).expect("modulus ensured non-zero")
             };
 
             const R: $uint_type = $crate::Uint::MAX
@@ -41,7 +41,7 @@ macro_rules! impl_modulus {
                     Self::MODULUS
                         .as_ref()
                         .inv_mod2k_vartime($crate::Word::BITS)
-                        .0
+                        .expect("modulus ensured odd")
                         .as_limbs()[0]
                         .0,
                 ),

src/non_zero.rs

@@ -1,6 +1,6 @@
 //! Wrapper type for non-zero integers.
 
-use crate::{Bounded, ConstChoice, Constants, Encoding, Limb, Uint, Zero};
+use crate::{Bounded, ConstOption, Constants, Encoding, Limb, Uint, Zero};
 use core::{
     fmt,
     num::{NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8},
@@ -27,16 +27,16 @@ pub struct NonZero<T: Zero>(pub(crate) T);
 impl NonZero<Limb> {
     /// Creates a new non-zero limb in a const context.
     /// The second return value is `FALSE` if `n` is zero, `TRUE` otherwise.
-    pub const fn const_new(n: Limb) -> (Self, ConstChoice) {
-        (Self(n), n.is_nonzero())
+    pub const fn const_new(n: Limb) -> ConstOption<Self> {
+        ConstOption::new(Self(n), n.is_nonzero())
     }
 }
 
 impl<const LIMBS: usize> NonZero<Uint<LIMBS>> {
     /// Creates a new non-zero integer in a const context.
     /// The second return value is `FALSE` if `n` is zero, `TRUE` otherwise.
-    pub const fn const_new(n: Uint<LIMBS>) -> (Self, ConstChoice) {
-        (Self(n), n.is_nonzero())
+    pub const fn const_new(n: Uint<LIMBS>) -> ConstOption<Self> {
+        ConstOption::new(Self(n), n.is_nonzero())
     }
 }