hetero-cartesian

hetero-cartesian is a Rust procedural macro designed to elegantly flatten nested, callback-based heterogeneous control flows (like deeply nested visitors or inverted iterations) into a clean, unified cartesian product block with absolute zero overhead.

Why this crate?

Iterators are great, but they require all yielded elements to be of the exact same type. When dealing with control flows that yield highly heterogeneous data (different types, varying const bounds) via callback traits, you can't just collect them into a Vec or use itertools.

Imagine two disjoint systems. One yields arrays of varying lengths (const generic N), and another yields tuples of completely different types (type generics T, U):

use std::fmt::Display;

trait ArrayHandler {
    fn process_array<const N: usize>(&mut self, arr: [i32; N]);
}

trait TupleHandler {
    fn process_tuple<T: Display, U: Display>(&mut self, val: (T, U));
}

fn drive_arrays<H: ArrayHandler>(h: &mut H) {
    h.process_array([1, 2]); // N = 2
    h.process_array([3, 4, 5]); // N = 3
}

fn drive_tuples<H: TupleHandler>(h: &mut H) {
    h.process_tuple((42u32, true)); // T = u32,  U = bool
    h.process_tuple(("hello", 'x')); // T = &str, U = char
}

If you want to iterate over the cartesian product of these two systems, standard for loops or iterators completely fail here. Cleanly connecting these requires you to write complex, deeply nested overlapping struct implementations manually.

cartesian_fn! elegantly flattens this with absolute zero overhead:

• 0 Dynamic Dispatch: It generates strictly typed, nested generic struct implementations on the fly. No Box<dyn Trait> or runtime type checks.
• 0 Memory Allocations: Your local environment is captured and passed seamlessly down the call stack. No heap allocation is required.
• 100% Static Context: Bounds are propagated precisely. The control flow is flattened into a unified block where the innermost execution has full access to exact compile-time types, trait bounds, and const generics.

Usage

Define your environments, map your driver iterations to their struct boundaries, and let the macro do the heavy lifting:

use hetero_cartesian::cartesian_fn;

// The attribute macro expands this into a plain fn that takes all args.
// No env-capture boilerplate, no type duplication.
#[cartesian_fn(
    drive_arrays(_) => ArrayHandler::process_array<const N: usize>(arr: [i32; N]);
    drive_tuples(_) => TupleHandler::process_tuple<T: Display, U: Display>(val: (T, U));
)]
fn run(sum: &mut i32, length: &mut usize, dim: &mut usize, comb: &mut usize, s: &mut Vec<String>) {
    let (first, second) = val;
    s.push(format!("arr: {arr:?}, val: ({first}, {second})"));
    *sum += arr.iter().sum::<i32>();
    *length += arr.len();
    *length += first.to_string().len() + second.to_string().len();
    *dim += N;
    *comb += 1;
}


fn main() {
    let mut total_array_sum: i32 = 0;
    let mut total_length: usize = 0;
    let mut total_dimensions: usize = 0;
    let mut combinations_count: usize = 0;
    let mut strings: Vec<String> = Vec::new();

    run(
        &mut total_array_sum,
        &mut total_length,
        &mut total_dimensions,
        &mut combinations_count,
        &mut strings,
    );

    assert_eq!(total_array_sum, 30); // (1+2)*2 + (3+4+5)*2 = 6 + 24
    assert_eq!(total_dimensions, 10); // N: 2+2+3+3
    assert_eq!(combinations_count, 4); // 2 array calls × 2 tuple calls
    assert_eq!(
        strings,
        [
            "arr: [1, 2], val: (42, true)",
            "arr: [1, 2], val: (hello, x)",
            "arr: [3, 4, 5], val: (42, true)",
            "arr: [3, 4, 5], val: (hello, x)",
        ]
    );
    // total_length = arr.len() + str-lengths for each of the 4 combinations
    // [1,2]: len=2; val (42,true): "42"=2, "true"=4; total per combo=2+2+4=8
    // [1,2]: len=2; val (hello,x): "hello"=5, "x"=1; total per combo=2+5+1=8
    // [3,4,5]: len=3; val (42,true): 3+2+4=9
    // [3,4,5]: len=3; val (hello,x): 3+5+1=9
    // total = 8+8+9+9 = 34
    assert_eq!(total_length, 34);
}