Created NestedTupleOptionWith

Author: LucaCappelletti94

CHANGELOG.md

@@ -29,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `NestedTupleIndex<Idx>` and `NestedTupleIndexMut<Idx>` traits for compile-time indexing into nested tuples using flat indices
 - `NestedTupleOption` trait for transposing nested tuples of options into options of nested tuples
 - `IntoNestedTupleOption` trait for converting nested tuples into nested tuples of options
+- `NestedTupleOptionWith<H>` trait providing `first_none_with`, `first_some_with`, and `transpose_or` helpers that work with a parallel homogeneous nested tuple `H` for result/error mapping
 - `NestedTupleReplicate<T>` trait for creating nested tuples by replicating a single value across all positions
 - `NestedTuplePopFront`, `NestedTuplePopBack`, `NestedTuplePushFront`, `NestedTuplePushBack` traits for manipulating nested tuples by popping/pushing elements at the front or back while preserving nested structure
 - `NestedTuplePopFront`, `NestedTuplePopBack`, `NestedTuplePushFront`, `NestedTuplePushBack` traits for manipulating nested tuples by popping/pushing elements at the front or back while preserving nested structure

README.md

@@ -31,6 +31,7 @@ The library provides several traits for working with tuples:
 - [`IntoTupleOption`](https://docs.rs/tuplities-option/latest/tuplities_option/trait.IntoTupleOption.html): Provides an [`into_options()`](https://docs.rs/tuplities-option/latest/tuplities_option/trait.IntoTupleOption.html#tymethod.into_options) method to convert a tuple into a tuple of options.
 - [`NestedTupleOption`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleOption.html): Provides a [`transpose()`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleOption.html#tymethod.transpose) method to transpose nested tuples of options into options of nested tuples.
 - [`IntoNestedTupleOption`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.IntoNestedTupleOption.html): Provides an [`into_options()`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.IntoNestedTupleOption.html#tymethod.into_options) method to convert nested tuples into nested tuples of options.
+- [`NestedTupleOptionWith<H>`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleOptionWith.html): Provides `first_none_with`, `first_some_with`, and `transpose_or` helpers which operate with a parallel homogeneous nested tuple of `H` used for result/error mapping.
 - [`NestedTupleTryFrom<T, E>`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleTryFrom.html): Provides a [`nested_tuple_try_from()`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleTryFrom.html#tymethod.nested_tuple_try_from) method to fallibly convert nested tuple types element-wise using `TryFrom` conversions.
 - [`NestedTupleTryInto<T, E>`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleTryInto.html): Provides a [`nested_tuple_try_into()`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleTryInto.html#tymethod.nested_tuple_try_into) convenience method to perform fallible conversions using `NestedTupleTryFrom`.
 - [`NestedTupleReplicate<T>`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleReplicate.html): Provides a [`nested_tuple_replicate(value)`](https://docs.rs/tuplities-flatten-nest/latest/tuplities_flatten_nest/trait.NestedTupleReplicate.html#tymethod.nested_tuple_replicate) method to create nested tuples by replicating a single value across all positions.
@@ -91,7 +92,7 @@ The following features enable individual trait crates:
 - `debug`: Enables `TupleDebug` trait
 - `tuple-default`: Enables `TupleDefault` trait
 - `eq`: Enables `TupleEq` trait
-- `flatten-nest`: Enables `FlattenNestedTuple`, `NestTuple`, `NestedTupleIndex`, `NestedTupleIndexMut`, `NestedTupleTryFrom`, `NestedTupleTryInto`, `NestTupleMatrix`, and `FlattenNestedTupleMatrix` traits
+- `flatten-nest`: Enables `FlattenNestedTuple`, `NestTuple`, `NestedTupleIndex`, `NestedTupleIndexMut`, `NestedTupleTryFrom`, `NestedTupleTryInto`, `NestTupleMatrix`, `FlattenNestedTupleMatrix`, `NestedTupleOption`, `IntoNestedTupleOption`, and `NestedTupleOptionWith` traits
 - `from`: Enables `TupleFrom` and `TupleInto` traits
 - `hash`: Enables `TupleHash` trait
 - `mut`: Enables `TupleMut` and `TupleMutMap` traits

tuplities-flatten-nest/src/lib.rs

@@ -20,7 +20,7 @@ pub use matrix::{
 };
 pub use nest::NestTuple;
 pub use nested_index::{NestedTupleIndex, NestedTupleIndexMut};
-pub use nested_option::{IntoNestedTupleOption, NestedTupleOption};
+pub use nested_option::{IntoNestedTupleOption, NestedTupleOption, NestedTupleOptionWith};
 pub use nested_push_pop::{
     NestedTuplePopBack, NestedTuplePopFront, NestedTuplePushBack, NestedTuplePushFront,
 };

tuplities-flatten-nest/src/nested_option.rs

@@ -25,35 +25,38 @@ pub trait NestedTupleOption {
     /// The transposed type: an option of the nested tuple of the inner types.
     type Transposed: IntoNestedTupleOption<IntoOptions = Self>;
 
-    /// A nested homogeneous tuple type with the same shape as `Self` where each element is `H`.
-    ///
-    /// Example: for `Self = (Option<T>, (Option<U>,))` then
-    /// `Self::SameDepth<H>` == `(H, (H,))`.
-    type SameDepth<H>;
-
     /// Transposes the nested tuple of options into an option of the nested tuple.
     ///
     /// Returns `Some(nested_tuple)` if all elements are `Some`, otherwise `None`.
     fn transpose(self) -> Option<Self::Transposed>;
 
-    /// Given a parallel homogeneous nested tuple `xs` (same shape as `self`),
-    /// returns the first `H` that corresponds to the first `None` in `self`,
-    /// or `None` if no elements are `None`.
-    fn first_none_with<H>(self, xs: Self::SameDepth<H>) -> Option<H>;
+    // Note: the `first_none_with`, `first_some_with`, and `transpose_or` helpers were moved
+    // to the `NestedTupleOptionWith<H>` trait to keep `NestedTupleOption` focused on
+    // transposition behavior.
+}
+
+/// Helper trait for operating on nested `Option` structures with a parallel homogeneous
+/// nested tuple type `SameDepth` carrying elements of type `H`.
+pub trait NestedTupleOptionWith<H>: NestedTupleOption {
+    /// The parallel homogeneous nested tuple type for `H` which has the same shape as `Self`.
+    type SameDepth;
 
-    /// Given a parallel homogeneous nested tuple `xs` (same shape as `self`),
-    /// returns the first `H` that corresponds to the first `Some` in `self`,
-    /// or `None` if no elements are `Some`.
-    fn first_some_with<H>(self, xs: Self::SameDepth<H>) -> Option<H>;
+    /// Returns the first `H` corresponding to the first `None` in `self`.
+    fn first_none_with(self, xs: Self::SameDepth) -> Option<H>;
+
+    /// Returns the first `H` corresponding to the first `Some` in `self`.
+    fn first_some_with(self, xs: Self::SameDepth) -> Option<H>;
 
     /// Like `transpose`, but returns a `Result` with `Ok(Transposed)` when all elements
     /// are `Some`, or `Err(H)` with the first `H` corresponding to the first `None`.
     ///
     /// # Errors
     ///
-    /// Returns `Err(H)` if any element is `None`, where `H` is from the parallel
-    /// homogeneous nested tuple `xs`.
-    fn transpose_or<H>(self, xs: Self::SameDepth<H>) -> Result<Self::Transposed, H>;
+    /// Returns `Err(h)` when any element in `self` is `None`. The `h` returned is the
+    /// corresponding element of the parallel homogeneous nested tuple `xs` for the first
+    /// `None` encountered (traversed left-to-right, depth-first in the nested pair
+    /// representation).
+    fn transpose_or(self, xs: Self::SameDepth) -> Result<Self::Transposed, H>;
 }
 
 /// A trait for converting nested tuples into nested tuples of options.
@@ -81,41 +84,95 @@ pub trait IntoNestedTupleOption {
 
 impl NestedTupleOption for () {
     type Transposed = ();
-    type SameDepth<H> = ();
 
     #[inline]
     fn transpose(self) -> Option<Self::Transposed> {
         Some(())
     }
+}
+
+impl<T> NestedTupleOption for (Option<T>,) {
+    type Transposed = (T,);
 
     #[inline]
-    fn first_none_with<H>(self, _xs: Self::SameDepth<H>) -> Option<H> {
-        None
+    fn transpose(self) -> Option<Self::Transposed> {
+        let (opt,) = self;
+        opt.map(|t| (t,))
     }
+}
+
+impl<Head, Tail> NestedTupleOption for (Option<Head>, Tail)
+where
+    Tail: NestedTupleOption,
+{
+    type Transposed = (Head, Tail::Transposed);
 
     #[inline]
-    fn first_some_with<H>(self, _xs: Self::SameDepth<H>) -> Option<H> {
-        None
+    fn transpose(self) -> Option<Self::Transposed> {
+        let (head_opt, tail) = self;
+        match (head_opt, tail.transpose()) {
+            (Some(head), Some(tail_transposed)) => Some((head, tail_transposed)),
+            _ => None,
+        }
     }
+}
+
+// Implementations for IntoNestedTupleOption
+
+impl IntoNestedTupleOption for () {
+    type IntoOptions = ();
 
     #[inline]
-    fn transpose_or<H>(self, _xs: Self::SameDepth<H>) -> Result<Self::Transposed, H> {
-        Ok(())
+    fn into_options(self) -> Self::IntoOptions {}
+}
+
+impl<T> IntoNestedTupleOption for (T,) {
+    type IntoOptions = (Option<T>,);
+
+    #[inline]
+    fn into_options(self) -> Self::IntoOptions {
+        let (t,) = self;
+        (Some(t),)
     }
 }
 
-impl<T> NestedTupleOption for (Option<T>,) {
-    type Transposed = (T,);
-    type SameDepth<H> = (H,);
+impl<Head, Tail> IntoNestedTupleOption for (Head, Tail)
+where
+    Tail: IntoNestedTupleOption,
+{
+    type IntoOptions = (Option<Head>, Tail::IntoOptions);
 
     #[inline]
-    fn transpose(self) -> Option<Self::Transposed> {
-        let (opt,) = self;
-        opt.map(|t| (t,))
+    fn into_options(self) -> Self::IntoOptions {
+        let (head, tail) = self;
+        (Some(head), tail.into_options())
     }
+}
+
+impl<H> NestedTupleOptionWith<H> for () {
+    type SameDepth = ();
 
     #[inline]
-    fn first_none_with<H>(self, xs: Self::SameDepth<H>) -> Option<H> {
+    fn first_none_with(self, _xs: Self::SameDepth) -> Option<H> {
+        None
+    }
+
+    #[inline]
+    fn first_some_with(self, _xs: Self::SameDepth) -> Option<H> {
+        None
+    }
+
+    #[inline]
+    fn transpose_or(self, _xs: Self::SameDepth) -> Result<Self::Transposed, H> {
+        Ok(())
+    }
+}
+
+impl<T, H> NestedTupleOptionWith<H> for (Option<T>,) {
+    type SameDepth = (H,);
+
+    #[inline]
+    fn first_none_with(self, xs: Self::SameDepth) -> Option<H> {
         let (opt,) = self;
         let (h,) = xs;
         match opt {
@@ -125,14 +182,14 @@ impl<T> NestedTupleOption for (Option<T>,) {
     }
 
     #[inline]
-    fn first_some_with<H>(self, xs: Self::SameDepth<H>) -> Option<H> {
+    fn first_some_with(self, xs: Self::SameDepth) -> Option<H> {
         let (opt,) = self;
         let (h,) = xs;
         opt.map(|_| h)
     }
 
     #[inline]
-    fn transpose_or<H>(self, xs: Self::SameDepth<H>) -> Result<Self::Transposed, H> {
+    fn transpose_or(self, xs: Self::SameDepth) -> Result<Self::Transposed, H> {
         let (opt,) = self;
         let (h,) = xs;
         match opt {
@@ -142,24 +199,14 @@ impl<T> NestedTupleOption for (Option<T>,) {
     }
 }
 
-impl<Head, Tail> NestedTupleOption for (Option<Head>, Tail)
+impl<Head, Tail, H> NestedTupleOptionWith<H> for (Option<Head>, Tail)
 where
-    Tail: NestedTupleOption,
+    Tail: NestedTupleOptionWith<H>,
 {
-    type Transposed = (Head, Tail::Transposed);
-    type SameDepth<H> = (H, Tail::SameDepth<H>);
-
-    #[inline]
-    fn transpose(self) -> Option<Self::Transposed> {
-        let (head_opt, tail) = self;
-        match (head_opt, tail.transpose()) {
-            (Some(head), Some(tail_transposed)) => Some((head, tail_transposed)),
-            _ => None,
-        }
-    }
+    type SameDepth = (H, Tail::SameDepth);
 
     #[inline]
-    fn first_none_with<H>(self, xs: Self::SameDepth<H>) -> Option<H> {
+    fn first_none_with(self, xs: Self::SameDepth) -> Option<H> {
         let (head_opt, tail) = self;
         let (h_head, h_tail) = xs;
         match head_opt {
@@ -169,7 +216,7 @@ where
     }
 
     #[inline]
-    fn first_some_with<H>(self, xs: Self::SameDepth<H>) -> Option<H> {
+    fn first_some_with(self, xs: Self::SameDepth) -> Option<H> {
         let (head_opt, tail) = self;
         let (h_head, h_tail) = xs;
         match head_opt {
@@ -179,7 +226,7 @@ where
     }
 
     #[inline]
-    fn transpose_or<H>(self, xs: Self::SameDepth<H>) -> Result<Self::Transposed, H> {
+    fn transpose_or(self, xs: Self::SameDepth) -> Result<Self::Transposed, H> {
         let (head_opt, tail) = self;
         let (h_head, h_tail) = xs;
         match head_opt {
@@ -192,38 +239,6 @@ where
     }
 }
 
-// Implementations for IntoNestedTupleOption
-
-impl IntoNestedTupleOption for () {
-    type IntoOptions = ();
-
-    #[inline]
-    fn into_options(self) -> Self::IntoOptions {}
-}
-
-impl<T> IntoNestedTupleOption for (T,) {
-    type IntoOptions = (Option<T>,);
-
-    #[inline]
-    fn into_options(self) -> Self::IntoOptions {
-        let (t,) = self;
-        (Some(t),)
-    }
-}
-
-impl<Head, Tail> IntoNestedTupleOption for (Head, Tail)
-where
-    Tail: IntoNestedTupleOption,
-{
-    type IntoOptions = (Option<Head>, Tail::IntoOptions);
-
-    #[inline]
-    fn into_options(self) -> Self::IntoOptions {
-        let (head, tail) = self;
-        (Some(head), tail.into_options())
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

tuplities/src/lib.rs

@@ -17,9 +17,10 @@ pub mod prelude {
     pub use tuplities_flatten_nest::{
         FlattenMatrixElements, FlattenNestedTuple, FlattenNestedTupleMatrix, IntoNestedTupleOption,
         NestMatrixElements, NestTuple, NestTupleMatrix, NestedTupleIndex, NestedTupleIndexMut,
-        NestedTupleMut, NestedTupleOption, NestedTuplePopBack, NestedTuplePopFront,
-        NestedTuplePushBack, NestedTuplePushFront, NestedTupleRef, NestedTupleReplicate,
-        NestedTupleRow, NestedTupleRowMut, NestedTupleTryFrom, NestedTupleTryInto,
+        NestedTupleMut, NestedTupleOption, NestedTupleOptionWith, NestedTuplePopBack,
+        NestedTuplePopFront, NestedTuplePushBack, NestedTuplePushFront, NestedTupleRef,
+        NestedTupleReplicate, NestedTupleRow, NestedTupleRowMut, NestedTupleTryFrom,
+        NestedTupleTryInto,
     };
     #[cfg(feature = "from")]
     pub use tuplities_from::{TupleFrom, TupleInto};