auto-tuple 0.2.0

Element-wise tuple-ization for traits: auto-generate tuple helper traits and blanket impls
Documentation

auto-tuple

CI crates.io docs.rs

Element-wise tuple-ization for Rust traits: an #[auto_tuple] attribute macro that generates, for each requested arity, a helper trait whose items forward element-wise to every element of an N-tuple. Package auto-tuple, crate auto_tuple.

use auto_tuple::auto_tuple;

#[auto_tuple]
trait Tr {
    fn zero() -> usize;
    fn bump(&mut self) -> usize;
    const MAX: usize;
    type Output;
}

struct X(usize);
struct Y(usize);

impl Tr for X {
    fn zero() -> usize { 1 }
    fn bump(&mut self) -> usize { self.0 += 1; self.0 }
    const MAX: usize = 5;
    type Output = u32;
}
impl Tr for Y {
    fn zero() -> usize { 2 }
    fn bump(&mut self) -> usize { self.0 += 1; self.0 }
    const MAX: usize = 50;
    type Output = u64;
}

// Generated for arity 2 (among others):
//
//   trait _TrTuple2<__T0, __T1> where __T0: Tr, __T1: Tr { ... }
//   impl<__T0: Tr, __T1: Tr> _TrTuple2<__T0, __T1> for (__T0, __T1) { ... }

fn main() {
    // No imports needed: the helper trait lives in this module, so method
    // resolution finds it automatically. Zero boilerplate.
    let mut t = (X(1), Y(2));
    assert_eq!(t.bump(), (2, 3));
    assert_eq!(t.0.0, 2);
    assert_eq!(<(X, Y)>::zero(), (1, 2));  // associated fn forwarding
    assert_eq!(<(X, Y)>::MAX, (5, 50));    // assoc const forwarding
    let _: <(X, Y) as _TrTuple2<X, Y>>::Output = (1u32, 2u64);
}

The helper traits are generated in the same module as the original trait and share its visibility. Within that module the tuple-ized methods are callable directly; cross-module calls need the helper trait imported, exactly like any other trait's methods (use std::io::Read to call .read()).

Core semantics

Every selected trait item is tuple-ized element-wise:

(x, y).foo(a, b)  == (x.foo(a, b), y.foo(a, b))
(A, B)::MAX       == (A::MAX, B::MAX)
(A, B)::Output    == (A::Output, B::Output)

There is no other semantics: no arithmetic merging, no short-circuiting.

Usage

#[auto_tuple]                 // default arities 2..=12, all fn/const/type items
#[auto_tuple(2..=12)]         // explicit arity range
#[auto_tuple(0..=1)]          // arities 0 and 1
#[auto_tuple(foo, 2..=4)]     // only the `foo` method
#[auto_tuple(MAX, Output)]    // only assoc const `MAX` and assoc type `Output`
#[auto_tuple(@all_methods)]  // all methods, including associated functions
#[auto_tuple(@all_methods, MAX)] // union: methods plus MAX
#[auto_tuple(-reset)]        // all items except reset
#[auto_tuple(@all, -@all_types)] // all items except associated types
#[auto_tuple(@all_methods, -[reset, clear], 2..=4)]
#[auto_tuple(pub(crate), name = "Reader", @all_ref_methods)]
  • Ranges follow Rust range semantics (2..12 excludes 12, 2..=12 includes it).
  • Compile cost: each arity generates one helper trait + blanket impl, so the default 2..=12 emits 11 pairs per annotated trait. For heavy trait graphs prefer a tighter range (#[auto_tuple(2..=4)]) to keep build times down.
  • Without a positive selector all methods, associated constants and associated types are selected, including when only exclusions are given.
  • Positive names and families form a union; exclusions are applied last, so @all, -foo, foo still excludes foo. Duplicates are removed. Flat lists ([foo, MAX], -[@all_types, reset]) are also supported.
  • Unknown member names (including exclusions) and unknown families are errors. An empty family or a fully excluded set stays empty and generates empty helper traits; it never falls back to all members. Unsupported items are checked only after selection and are not silently skipped.
  • A visibility override (pub, pub(crate), ...) applies to the generated helper traits; by default they inherit the original trait's visibility.
  • The helper traits are generated in the same module as the original trait and share its visibility; bring them into scope with use to call the tuple-ized methods.

Member selector families

The names and filters match batch-impl's member families:

Family Selects
@all All methods, associated constants and associated types
@all_methods / @all_constants / @all_types All members of that kind
@all_required / @all_default Members without / with a default body or value
@all_required_methods / @all_default_methods Methods filtered by default body
@all_required_constants / @all_default_constants Constants filtered by default value
@all_required_types / @all_default_types Associated types filtered by default type
@all_ref_methods Methods with &self or &mut self
@all_value_methods Methods with self, including typed receivers
@all_static_methods Associated functions without a receiver

A family classifies syntax; it does not enable unsupported language features. For example, selecting a typed receiver still reports the custom-receiver diagnostic. A selected default method forwards to each element's implementation.

use auto_tuple::auto_tuple;

#[auto_tuple(@all_ref_methods, MAX, -reset, 2..=2)]
trait Read {
    fn read(&self) -> usize;
    fn reset(&mut self);
    fn consume(self: Box<Self>); // excluded before receiver validation
    const MAX: usize = 10;
}

struct Reader;
impl Read for Reader {
    fn read(&self) -> usize { 7 }
    fn reset(&mut self) {}
    fn consume(self: Box<Self>) {}
}

assert_eq!((Reader, Reader).read(), (7, 7));
assert_eq!(<(Reader, Reader)>::MAX, (10, 10));

Migrating from 0.1.x

Replace a bare #[auto_tuple] with #[auto_tuple(@all_methods)] to preserve the former methods-only default. Existing explicit member lists retain their meaning. The new default may select unsupported associated types or change Shared/All analysis when an associated item's bounds mention a trait parameter; review helper-trait imports and explicit UFCS paths when adopting it.

Two shapes: shared and All

Whether a trait lands in the shared or the All shape is decided by whether any selected item's signature references an original trait generic parameter:

Shared All
Trigger a selected item's signature references an original generic param no selected item references the original generic params (any shape: multiple type params, lifetimes, const params)
Helper trait _TrTuple2<__T0, __T1, T> where __T0: Tr<T>, __T1: Tr<T> _TrTuple2All<__T0, __T1, <per-element param groups>> where __T0: Tr<...>, __T1: Tr<...>
Element params shared original params one independent param group per element (A: Tr<i32, S>, B: Tr<String, U> allowed)
Bounds original params lifted as-is original type param bounds carry to the element group (Tr<T: Clone> → per-element Clone)
Arity 0/1 names _TrTuple0 / _TrTuple1 _TrTuple0All / _TrTuple1All

Traits without generic parameters always use the plain name and an unparameterized element bound (__T0: Tr).

Supported / unsupported

Supported:

  • &self / &mut self / self receivers and associated functions
  • generic methods, where clauses, lifetimes (trait-level 'a is lifted into the helper trait; elided-lifetime returns such as fn name(&self) -> &str work)
  • async fn (sequential await) and unsafe fn / unsafe trait
  • impl Trait (RPIT) returns: each element keeps its own opaque type (fn f() -> impl Iterator<Item = Self> becomes a tuple of per-element opaques)
  • Self anywhere in return types, recursively (&Self, Box<Self>, Vec<Self>, Self::Output, ...)
  • Self, &Self, &mut Self, Self::Assoc in parameters (unpacked per element)
  • associated consts and types (incl. bounds such as type Output: Clone;)

Unsupported (clear compile_error!):

  • Self nested inside a generic container in parameters (Box<Self> params, Vec<Self> params)
  • by-value impl Trait parameters (a single value cannot be forwarded to multiple elements; use a reference or a Copy generic)
  • impl Trait parameters mentioning Self (a single value cannot satisfy the per-element Item constraints)
  • custom receivers (self: Box<Self> etc.)
  • + use<..> precise capturing in returns (the trait/impl capture lists of the per-element opaques are not yet handled)
  • generic associated types (GATs)
  • Self inside where-clause bounds in non-subject position
  • auto traits
  • multiple arity ranges in one attribute

Left to the compiler (no pre-emption):

  • by-value non-Copy parameters of arity >= 2 ((A::g(x), B::g(x)) moves x twice -> E0382, as with any two calls)
  • generic async fn if the toolchain rejects them

Design

See docs/design.md for the full design: semantics, two-track decision procedure, type rewriting rules, error handling and the edge-case matrix.

Contributing

See docs/development-guide.md for the development and release conventions, and CONTRIBUTING.md for quick checks.

License

MIT — see LICENSE.