[WIP] ctutils: CtOption methods for crypto-bigint

Adds the methods needed to replace `ConstCtOption` in `crypto-bigint`
with `ctutils::CtOption`.

Author: tarcieri

ctutils/src/ct_option.rs

@@ -1,6 +1,17 @@
 use crate::{Choice, CtEq, CtSelect};
 use core::ops::{Deref, DerefMut};
 
+/// Helper macro for providing behavior like the `unwrap_or` combinator that works in a `const fn`
+/// context.
+///
+/// Requires a provided selector function to do the constant-time selection.
+#[macro_export]
+macro_rules! unwrap_or {
+    ($opt:expr, $default:expr, $select:path) => {
+        $select(&$default, $opt.as_inner_unchecked(), $opt.is_some())
+    };
+}
+
 /// Equivalent of [`Option`] but predicated on a [`Choice`] with combinators that allow for
 /// constant-time operations which always perform the same sequence of instructions regardless of
 /// the value of `is_some`.
@@ -23,6 +34,21 @@ impl<T> CtOption<T> {
         Self { value, is_some }
     }
 
+    /// Construct a new [`CtOption`] where `self.is_some()` is [`Choice::TRUE`].
+    #[inline]
+    pub const fn some(value: T) -> CtOption<T> {
+        Self::new(value, Choice::TRUE)
+    }
+
+    /// Construct a new [`CtOption`] with the [`Default`] value, and where `self.is_some()` is
+    /// [`Choice::FALSE`].
+    pub fn none() -> CtOption<T>
+    where
+        T: Default,
+    {
+        Self::new(Default::default(), Choice::FALSE)
+    }
+
     /// Convert from a `&mut CtOption<T>` to `CtOption<&mut T>`.
     #[inline]
     pub const fn as_mut(&mut self) -> CtOption<&mut T> {
@@ -80,7 +106,7 @@ impl<T> CtOption<T> {
     // (needs `const_precise_live_drops`)
     #[inline]
     #[track_caller]
-    pub const fn expect_copied(&self, msg: &str) -> T
+    pub const fn expect_copied(self, msg: &str) -> T
     where
         T: Copy,
     {
@@ -99,7 +125,7 @@ impl<T> CtOption<T> {
     pub const fn expect_ref(&self, msg: &str) -> &T {
         // TODO(tarcieri): use `self.is_some().to_bool()` when MSRV is 1.86
         assert!(self.is_some.to_bool_vartime(), "{}", msg);
-        &self.value
+        self.as_inner_unchecked()
     }
 
     /// Convert the [`CtOption`] wrapper into an [`Option`], depending on whether
@@ -124,6 +150,29 @@ impl<T> CtOption<T> {
         }
     }
 
+    /// Convert the [`CtOption`] wrapper into an [`Option`] in a `const fn`-friendly manner.
+    ///
+    /// This is the equivalent of [`CtOption::into_option`] but is `const fn`-friendly by only
+    /// allowing `Copy` types which are implicitly `!Drop` and don't run into problems with
+    /// `const fn` and destructors.
+    ///
+    /// <div class="warning">
+    /// This implementation doesn't intend to be constant-time nor try to protect the leakage of the
+    /// `T` value since the [`Option`] will do it anyway.
+    /// </div>
+    #[inline]
+    pub const fn into_option_copied(self) -> Option<T>
+    where
+        T: Copy,
+    {
+        // TODO(tarcieri): use `self.is_some().to_bool()` when MSRV is 1.86
+        if self.is_some.to_bool_vartime() {
+            Some(self.value)
+        } else {
+            None
+        }
+    }
+
     /// Returns [`Choice::TRUE`] if the option is the equivalent of a `Some`.
     #[inline]
     #[must_use]
@@ -146,6 +195,13 @@ impl<T> CtOption<T> {
         optb
     }
 
+    /// Apply an additional [`Choice`] requirement to `is_some`.
+    #[inline]
+    pub const fn and_choice(mut self, is_some: Choice) -> Self {
+        self.is_some = self.is_some.and(is_some);
+        self
+    }
+
     /// Calls the provided callback with the wrapped inner value, returning the resulting
     /// [`CtOption`] value in the event that `self.is_some()` is [`Choice::TRUE`], or if not
     /// returns a [`CtOption`] with `self.is_none()`.
@@ -164,6 +220,34 @@ impl<T> CtOption<T> {
         ret
     }
 
+    /// Obtain a reference to the inner value without first checking that `self.is_some()` is
+    /// [`Choice::TRUE`].
+    ///
+    /// This method is primarily intended for use in `const fn` scenarios where it's not yet
+    /// possible to use the safe combinator methods, and returns a reference to avoid issues with
+    /// `const fn` destructors.
+    ///
+    /// <div class="warning">
+    /// <b>Use with care!</b>
+    ///
+    /// This method does not ensure the `value` is actually valid. Callers of this method should
+    /// take great care to ensure that `self.is_some()` is checked elsewhere.
+    /// </div>
+    #[inline]
+    pub const fn as_inner_unchecked(&self) -> &T {
+        &self.value
+    }
+
+    /// DEPRECATED: legacy compatibility method for `crypto-bigint`
+    #[inline]
+    #[deprecated(since = "0.1.1", note = "use `as_inner_unchecked` instead")]
+    pub const fn components_ref(&self) -> (&T, Choice) {
+        // 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)
+    }
+
     /// Calls the provided callback with the wrapped inner value, which computes a [`Choice`],
     /// and updates `self.is_some()`.
     ///
@@ -247,6 +331,27 @@ impl<T> CtOption<T> {
         }
     }
 
+    /// Obtain a copy of the inner value without first checking that `self.is_some()` is
+    /// [`Choice::TRUE`].
+    ///
+    /// This method is primarily intended for use in `const fn` scenarios where it's not yet
+    /// possible to use the safe combinator methods, and uses a `Copy` bound to avoid issues with
+    /// `const fn` destructors.
+    ///
+    /// <div class="warning">
+    /// <b>Use with care!</b>
+    ///
+    /// This method does not ensure the `value` is actually valid. Callers of this method should
+    /// take great care to ensure that `self.is_some()` is checked elsewhere.
+    /// </div>
+    #[inline]
+    pub const fn to_inner_unchecked(self) -> T
+    where
+        T: Copy,
+    {
+        self.value
+    }
+
     /// Return the contained value, consuming the `self` value.
     ///
     /// Use of this function is discouraged due to panic potential. Instead, prefer non-panicking
@@ -400,6 +505,12 @@ impl<T: CtSelect> CtSelect for CtOption<T> {
     }
 }
 
+impl<T: Default> Default for CtOption<T> {
+    fn default() -> Self {
+        Self::none()
+    }
+}
+
 /// Convert the [`CtOption`] wrapper into an [`Option`], depending on whether
 /// [`CtOption::is_some`] is a truthy or falsy [`Choice`].
 ///