ctutils: add CtFind trait (#1361)

Adds a trait with a similar shape to the `Iterator::find` method, which
returns the first item in a collection that matches a given predicate.

The trait is impl'd for `[T; N] and `[T]` where `T: CtSelect + Default`.

This also adds a helper method used in the implementation
`CtOption::insert_if` which is made public, and `CtOption::insert` which
mirrors `Option::insert` for consistency.

Author: tarcieri

ctutils/src/ct_option.rs

@@ -150,6 +150,24 @@ impl<T> CtOption<T> {
         self.as_inner_unchecked()
     }
 
+    /// Inserts `value` into the [`CtOption`], then returns a mutable reference to it.
+    ///
+    /// If the option already contains a value, the old value is dropped.
+    pub fn insert(&mut self, value: T) -> &mut T {
+        self.value = value;
+        self.is_some = Choice::TRUE;
+        &mut self.value
+    }
+
+    /// Conditionally inserts `value` into the [`CtOption`] if the given condition holds.
+    pub fn insert_if(&mut self, value: &T, condition: Choice)
+    where
+        T: CtSelect,
+    {
+        self.value.ct_assign(value, condition);
+        self.is_some.ct_assign(&Choice::TRUE, condition);
+    }
+
     /// Convert the [`CtOption`] wrapper into an [`Option`], depending on whether
     /// [`CtOption::is_some`] is a truthy or falsy [`Choice`].
     ///
@@ -735,6 +753,28 @@ mod tests {
         assert_eq!(SOME.filter_by(Choice::TRUE).unwrap(), VALUE);
     }
 
+    #[test]
+    fn insert() {
+        let mut example = NONE;
+        assert!(example.is_none().to_bool());
+
+        let ret = example.insert(42);
+        assert_eq!(ret, &42);
+        assert!(example.is_some().to_bool());
+    }
+
+    #[test]
+    fn insert_if() {
+        let mut example = NONE;
+        assert!(example.is_none().to_bool());
+
+        example.insert_if(&42, Choice::FALSE);
+        assert!(example.is_none().to_bool());
+
+        example.insert_if(&42, Choice::TRUE);
+        assert_eq!(example.unwrap(), 42);
+    }
+
     #[test]
     fn map() {
         assert!(NONE.map(|value| value + 1).ct_eq(&NONE).to_bool());

ctutils/src/lib.rs

@@ -94,4 +94,6 @@ mod traits;
 pub use bytes::{BytesCtEq, BytesCtSelect};
 pub use choice::Choice;
 pub use ct_option::CtOption;
-pub use traits::{ct_eq::CtEq, ct_gt::CtGt, ct_lt::CtLt, ct_neg::CtNeg, ct_select::CtSelect};
+pub use traits::{
+    ct_eq::CtEq, ct_find::CtFind, ct_gt::CtGt, ct_lt::CtLt, ct_neg::CtNeg, ct_select::CtSelect,
+};

ctutils/src/traits.rs

@@ -4,6 +4,7 @@
 //! on in the same module.
 
 pub(crate) mod ct_eq;
+pub(crate) mod ct_find;
 pub(crate) mod ct_gt;
 pub(crate) mod ct_lt;
 pub(crate) mod ct_neg;

ctutils/src/traits/ct_find.rs

@@ -0,0 +1,91 @@
+use crate::{Choice, CtOption, CtSelect};
+
+#[cfg(doc)]
+use core::iter::Iterator;
+
+/// Constant-time equivalent of [`Iterator::find`], which can search a collection by iterating over
+/// every element and applying the given predicate to each item, then selecting the first matching
+/// entry.
+pub trait CtFind<T: CtSelect> {
+    /// Iterate through every `T` item in `&self`, applying the given `predicate` which can select
+    /// a specific item by returning [`Choice::TRUE`].
+    ///
+    /// The first item where `predicate` returns [`Choice::TRUE`] is selected, or the [`CtOption`]
+    /// equivalent of `None` is returned if the `predicate` returns [`Choice::FALSE`] for all items.
+    fn ct_find<P>(&self, predicate: P) -> CtOption<T>
+    where
+        P: Fn(&T) -> Choice;
+}
+
+impl<T> CtFind<T> for [T]
+where
+    T: CtSelect + Default,
+{
+    fn ct_find<P>(&self, predicate: P) -> CtOption<T>
+    where
+        P: Fn(&T) -> Choice,
+    {
+        let mut ret = CtOption::none();
+
+        for item in self {
+            ret.insert_if(item, predicate(item) & ret.is_none());
+        }
+
+        ret
+    }
+}
+
+impl<T, const N: usize> CtFind<T> for [T; N]
+where
+    T: CtSelect + Default,
+{
+    fn ct_find<P>(&self, predicate: P) -> CtOption<T>
+    where
+        P: Fn(&T) -> Choice,
+    {
+        self.as_slice().ct_find(predicate)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::CtFind;
+
+    mod array {
+        use super::*;
+        use crate::{CtEq, CtGt};
+
+        const ARRAY: [u8; 6] = [0, 0, 0, 1, 2, 3];
+
+        #[test]
+        fn ct_find() {
+            // Find the first nonzero even number
+            assert_eq!(
+                ARRAY.ct_find(|n| n.ct_ne(&0) & (n & 1).ct_eq(&0)).unwrap(),
+                2
+            );
+
+            // Predicate where nothing matches
+            assert!(ARRAY.ct_find(|n| n.ct_gt(&3)).is_none().to_bool());
+        }
+    }
+
+    mod slice {
+        use super::*;
+        use crate::{CtEq, CtGt};
+
+        const SLICE: &[u8] = &[0, 0, 0, 1, 2, 3];
+
+        #[test]
+        fn ct_find() {
+            // Find the first nonzero even number
+            assert_eq!(
+                SLICE.ct_find(|n| n.ct_ne(&0) & (n & 1).ct_eq(&0)).unwrap(),
+                2
+            );
+
+            // Predicate where nothing matches
+            assert!(SLICE.ct_find(|n| n.ct_gt(&3)).is_none().to_bool());
+        }
+    }
+}