auto-tuple
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;
;
;
// 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) { ... }
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..12excludes 12,2..=12includes it). - Compile cost: each arity generates one helper trait + blanket impl, so
the default
2..=12emits 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, foostill excludesfoo. 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
useto 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;
;
assert_eq!;
assert_eq!;
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/selfreceivers and associated functions- generic methods,
whereclauses, lifetimes (trait-level'ais lifted into the helper trait; elided-lifetime returns such asfn name(&self) -> &strwork) async fn(sequential await) andunsafe fn/unsafe traitimpl Trait(RPIT) returns: each element keeps its own opaque type (fn f() -> impl Iterator<Item = Self>becomes a tuple of per-element opaques)Selfanywhere in return types, recursively (&Self,Box<Self>,Vec<Self>,Self::Output, ...)Self,&Self,&mut Self,Self::Associn parameters (unpacked per element)- associated consts and types (incl. bounds such as
type Output: Clone;)
Unsupported (clear compile_error!):
Selfnested inside a generic container in parameters (Box<Self>params,Vec<Self>params)- by-value
impl Traitparameters (a single value cannot be forwarded to multiple elements; use a reference or aCopygeneric) impl Traitparameters mentioningSelf(a single value cannot satisfy the per-elementItemconstraints)- 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)
Selfinside 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-
Copyparameters of arity >= 2 ((A::g(x), B::g(x))movesxtwice -> E0382, as with any two calls) - generic
async fnif 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.