API Reference

Relevant source files

• README.md
• src/lib.rs

This document provides comprehensive reference documentation for all public APIs and generated functionality provided by the tuple_for_each crate. It covers the TupleForEach derive macro and all code it generates, including macros and methods added to tuple structs.

For implementation details about how the derive macro works internally, see Implementation Guide. For basic usage examples and getting started information, see Getting Started.

API Surface Overview

The tuple_for_each crate provides a single derive macro that generates multiple APIs for tuple structs. The following diagram shows the complete API surface generated by the derive macro:

flowchart TD
subgraph subGraph2["Macro Variants"]
    ForEachImmutable["for_each!(x in tuple { ... })"]
    ForEachMutable["for_each!(x in mut tuple { ... })"]
    EnumerateImmutable["enumerate!((i, x) in tuple { ... })"]
    EnumerateMutable["enumerate!((i, x) in mut tuple { ... })"]
end
subgraph subGraph1["Generated APIs"]
    LenMethod["len() -> usize method"]
    IsEmptyMethod["is_empty() -> bool method"]
    ForEachMacro["*_for_each! macro"]
    EnumerateMacro["*_enumerate! macro"]
end
subgraph subGraph0["User Input"]
    TupleStruct["Tuple Struct with #[derive(TupleForEach)]"]
end

EnumerateMacro --> EnumerateImmutable
EnumerateMacro --> EnumerateMutable
ForEachMacro --> ForEachImmutable
ForEachMacro --> ForEachMutable
TupleStruct --> EnumerateMacro
TupleStruct --> ForEachMacro
TupleStruct --> IsEmptyMethod
TupleStruct --> LenMethod

Sources: src/lib.rs(L10 - L24)  src/lib.rs(L88 - L121) 

TupleForEach Derive Macro

The TupleForEach derive macro is the primary entry point of the crate, implemented as a procedural macro that transforms tuple struct definitions at compile time.

Validation Rules

The derive macro validates input and only accepts tuple structs:

• Accepted: struct MyTuple(Type1, Type2, Type3);
• Rejected: Named struct fields, unit structs, enums
• Error Message: "attribute 'tuple_for_each' can only be attached to tuple structs"

The validation logic checks for Data::Struct with Fields::Unnamed at src/lib.rs(L13 - L14) 

Sources: src/lib.rs(L10 - L24) 

Generated API Components

When applied to a tuple struct, the derive macro generates four distinct API components. The following diagram shows the code generation pipeline and relationships:

flowchart TD
subgraph subGraph0["Field Iteration Logic"]
    ForEachGen["*_for_each! macro generation"]
    EnumGen["*_enumerate! macro generation"]
    ForEachLoop["for i in 0..field_num"]
    EnumLoop["for i in 0..field_num"]
    FieldAccess["$tuple.#idx access"]
    IndexedAccess["#idx, $tuple.#idx access"]
end
Input["TupleStruct(Field1, Field2, ...)"]
EntryPoint["tuple_for_each()"]
Parser["syn::parse_macro_input!"]
CoreLogic["impl_for_each()"]
NameGen["pascal_to_snake()"]
MacroNames["macro_for_each, macro_enumerate"]
MethodGen["len() & is_empty() methods"]
ConstMethods["const fn len(), const fn is_empty()"]
MacroRules["macro_rules! expansion"]
Output["Generated TokenStream"]

CoreLogic --> EnumGen
CoreLogic --> ForEachGen
CoreLogic --> MethodGen
CoreLogic --> NameGen
EntryPoint --> Parser
EnumGen --> EnumLoop
EnumLoop --> IndexedAccess
FieldAccess --> MacroRules
ForEachGen --> ForEachLoop
ForEachLoop --> FieldAccess
IndexedAccess --> MacroRules
Input --> EntryPoint
MacroRules --> Output
MethodGen --> ConstMethods
NameGen --> MacroNames
Parser --> CoreLogic

Sources: src/lib.rs(L58 - L122)  src/lib.rs(L124 - L133) 

Methods Added to Tuple Structs

Two constant methods are added to every tuple struct via an impl block:

Both methods are const fn, allowing compile-time evaluation. The len() method returns the literal field count (#field_num), while is_empty() compares against zero.

Generated Iteration Macros

Two macro families are generated, each with immutable and mutable variants:

*_for_each! Macro

<snake_case_name>_for_each!(item in tuple { code_block })
<snake_case_name>_for_each!(item in mut tuple { code_block })

• Pattern: $item:ident in $tuple:ident $code:block
• Mutable Pattern: $item:ident in mut $tuple:ident $code:block
• Implementation: src/lib.rs(L102 - L109) 

*_enumerate! Macro

<snake_case_name>_enumerate!((index, item) in tuple { code_block })
<snake_case_name>_enumerate!((index, item) in mut tuple { code_block })

• Pattern: ($idx:ident, $item:ident) in $tuple:ident $code:block
• Mutable Pattern: ($idx:ident, $item:ident) in mut $tuple:ident $code:block
• Implementation: src/lib.rs(L113 - L120) 

Sources: src/lib.rs(L100 - L121) 

Name Generation Strategy

The macro names are derived from the tuple struct name using a pascal_to_snake conversion:

flowchart TD
PascalCase["MyTupleStruct"]
Conversion["pascal_to_snake()"]
SnakeCase["my_tuple_struct"]
ForEachName["my_tuple_struct_for_each!"]
EnumName["my_tuple_struct_enumerate!"]

Conversion --> SnakeCase
PascalCase --> Conversion
SnakeCase --> EnumName
SnakeCase --> ForEachName

The conversion algorithm at src/lib.rs(L124 - L133)  processes each character, inserting underscores before uppercase letters (except the first) and converting to lowercase.

Sources: src/lib.rs(L60 - L62)  src/lib.rs(L124 - L133) 

Documentation Generation

The generated macros include automatically generated documentation using the gen_doc() function at src/lib.rs(L26 - L56)  Documentation templates provide usage examples and link back to the derive macro.

Documentation Template Variables

Sources: src/lib.rs(L26 - L56)  src/lib.rs(L85 - L86) 

Complete API Reference

For detailed information about specific components:

• TupleForEach Derive Macro: See TupleForEach Derive Macro
• Generated Macros: See Generated Macros
• Generated Methods: See Generated Methods

Each subsection provides comprehensive documentation, usage patterns, and implementation details for the respective API components.

Sources: src/lib.rs(L1 - L134)  README.md(L1 - L40)