2 releases

0.1.1 Jan 17, 2023
0.1.0 Dec 2, 2022

#1446 in Procedural macros

Download history 1031/week @ 2023-11-24 1518/week @ 2023-12-01 1920/week @ 2023-12-08 1336/week @ 2023-12-15 543/week @ 2023-12-22 1011/week @ 2023-12-29 1397/week @ 2024-01-05 1416/week @ 2024-01-12 1331/week @ 2024-01-19 1437/week @ 2024-01-26 2511/week @ 2024-02-02 3140/week @ 2024-02-09 2794/week @ 2024-02-16 3466/week @ 2024-02-23 4005/week @ 2024-03-01 1422/week @ 2024-03-08

12,079 downloads per month
Used in range-set-blaze

MIT license

15KB
148 lines

syntactic-for

crates.io docs.rs

A syntactic "for" loop Rust macro.

For example, the following takes the sum of the bit-length of four integer types:

let sum = syntactic_for!{ ty in [ u8, u16, u32, u64 ] {
    [$( <$ty>::BITS ),*].into_iter().sum::<u32>()
}};
assert_eq!(sum, 120);

Usage

The syntax is as follows:

syntactic_for!{ IDENTIFIER in [ EXPRESSION, EXPRESSION, ... ] {
    BODY
}}

where BODY works similarly to macro_rules!, that is: $($IDENTIFIER)SEPARATOR* will expand and substitute IDENTIFIER with each EXPRESSION, separating the expansions with SEPARATOR.

SEPARATOR can be any non-* punctuation. Hence, the example from above could also be written without an iterator:

$( <$ty>::BITS )+*

Examples

Loop unrolling

Sum the elements of an array with loop unrolling:

let array = b"oh my, I am getting summed!";
let mut acc = 0u32;
let mut i = 0;
while i <= array.len()-4 {
    syntactic_for!{ offset in [ 0, 1, 2, 3 ] {$(
        acc += array[i + $offset] as u32;
    )*}}
    i += 4;
}
for j in i..array.len() {
    acc += array[j] as u32;
}
assert_eq!(acc, 2366);

Matching

Find the maximum value of an integer type of the given bit size:

let max_size = syntactic_for!{ ty in [ u8, u16, u32, u64, u128 ] {
    match bit_size {
        $(<$ty>::BITS => <$ty>::MAX as u128,)*
        other => panic!("No integer of size {other}"),
    }
}};

impl blocks

Implement a trait for a set of types:

syntactic_for!{ ty in [ u8, u16, u32, u64, u128 ] {$(
    impl MyTrait for $ty {
        // snip.
    }
)*}}

Custom syntactic loop

A useful design pattern is to define a custom macro that expands to a syntactic loop over a given set of expressions:

#[doc(hidden)]
pub extern crate syntactic_for;

#[macro_export]
macro_rules! for_each_custom_type {
    ($ident:ident { $($tt:tt)* }) => {
        $crate::syntactic_for::syntactic_for! { $ident in [
            $crate::CustomType1,
            $crate::CustomType2,
            // etc.
        ] { $($tt)* } }
    }
}

For example, a library could expose for_each_custom_type as a way of letting its users write syntactic loops over a set of types defined in the library. Then, it becomes possible to add types to that loop inside the library, whithout requiring any change on the user's end:

// Try and parse each library type in succession, stopping at the first
// success:
fn can_parse(input: &str) -> bool {
    my_library::for_each_custom_type! { ty {
        $(if let Ok(parsed) = <$ty>::parse(input) {
            return true;
        })*
    }}
    return false;
}

Dependencies

~1.5MB
~34K SLoC