通过例子学习Rust

49.3 定义宏macro_rules!

Rust provides a powerful macro system that allows metaprogramming. As you've seen in previous chapters, macros look like functions, except that their name ends with a bang !, but instead of generating a function call, macros are expanded into source code that gets compiled with the rest of the program.

Macros are created using the macro_rules! macro.

// simple.rs
// macros are behind a feature gate
#![feature(macro_rules)]

// This is the simplest macro, `say_hello` is the name of the macro
macro_rules! say_hello {
    // `()` indicates that the macro takes no argument
    () => {
        // the macro will expand into the contents of this block
        println!("Hello!");
    }
}

fn main() {
    // this call will expand into `println!("Hello");`
    say_hello!()
}

{simple.out}

The arguments of a macro are prefixed by a dollar sign $ and type annotated with a designator.

// designators.rs
#![feature(macro_rules)]

macro_rules! create_function {
    // this macro takes an argument of "type" `ident`
    // the `ident` designator is used for variable/function names
    ($func_name:ident) => {
        // this macro creates a function with name `$func_name`
        fn $func_name() {
            // the stringify! macro converts an `ident` into a string
            println!("You called {}()",
                     stringify!($func_name))
        }
    }
}

create_function!(foo);
create_function!(bar);

macro_rules! print_result {
    // the `expr` designator is used for expressions
    ($expression:expr) => {
        // stringify! will convert the expression *as it is* into a string
        println!("{} = {}",
                 stringify!($expression),
                 $expression)
    }
}

fn main() {
    foo();
    bar();

    print_result!(1u + 1);

    // remember that blocks are expressions
    print_result!({
        let x = 1u;

        x * x + 2 * x - 1
    });
}

{designators.out}

Macros can be overloaded to accept different combinations of arguments.

// overload.rs
#![feature(macro_rules)]

// macro_rules! is similar to a match block
macro_rules! test {
    // the arguments don't need to be separated by a comma
    // any template can be used
    ($left:expr and $right:expr) => {
        println!("{} and {} is {}",
                 stringify!($left),
                 stringify!($right),
                 $left && $right)
    };
    // ^ each arm must be ended with a semicolon
    ($left:expr or $right:expr) => {
        println!("{} or {} is {}",
                 stringify!($left),
                 stringify!($right),
                 $left || $right)
    };
}

fn main() {
    test!(1i + 1 == 2i and 2i * 2 == 4i);
    test!(true or false);
}

{overload.out}

Macros can use + in the argument list, to indicate that an argument may repeat at least once, or *, to indicate that the argument may repeat zero or more times.

// repeat.rs
#![feature(macro_rules)]

// min! will calculate the minimum of any number of arguments
macro_rules! min {
    // base case
    ($x:expr) => {
        $x
    };
    // `$x` followed by at least one `$y,`
    ($x:expr, $($y:expr),+) => {
        // call min! on the tail `$y`
        std::cmp::min($x, min!($($y),+))
    }
}

fn main() {
    println!("{}", min!(1u));
    println!("{}", min!(1u + 2 , 2u));
    println!("{}", min!(5u, 2u * 3, 4u));
}

{repeat.out}

Macros allow writing DRY code, by factoring out the common parts of functions and/or test suites. Here is an example that implements and tests the +=, *= and -= operators on Vec<T>.

// dry.rs
#![feature(macro_rules)]
use std::iter;

macro_rules! assert_equal_len {
    ($a:ident, $b: ident, $func:ident, $op:tt) => {
        assert!($a.len() == $b.len(),
                "{}: dimension mismatch: {} {} {}",
                stringify!($func),
                ($a.len(),),
                stringify!($op),
                ($b.len(),));
    }
}

macro_rules! op {
    ($func:ident, $bound:ident, $op:tt, $method:ident) => {
        fn $func<T: $bound<T, T> + Copy>(xs: &mut Vec<T>, ys: &Vec<T>) {
            assert_equal_len!(xs, ys, $func, $op);

            for (x, y) in xs.iter_mut().zip(ys.iter()) {
                *x = $bound::$method(*x, *y);
                // *x = x.$method(*y);
            }
        }
    }
}

// implement add_assign, mul_assign, and sub_assign functions
op!(add_assign, Add, +=, add);
op!(mul_assign, Mul, *=, mul);
op!(sub_assign, Sub, -=, sub);

fn main() {
    let mut xs = iter::repeat(0f64).take(5).collect();
    let ys = iter::repeat(1f64).take(6).collect();

    // this operation will fail at runtime
    add_assign(&mut xs, &ys);
}

mod test {
    macro_rules! test {
        ($func: ident, $x:expr, $y:expr, $z:expr) => {
            #[test]
            fn $func() {
                for size in range(0u, 10) {
                    let mut x = Vec::from_elem(size, $x);
                    let y = Vec::from_elem(size, $y);
                    let z = Vec::from_elem(size, $z);

                    super::$func(&mut x, &y);

                    assert_eq!(x, z);
                }
            }
        }
    }

    // test add_assign, mul_assign and sub_assign
    test!(add_assign, 1u, 2u, 3u);
    test!(mul_assign, 2u, 3u, 6u);
    test!(sub_assign, 3u, 2u, 1u);
}

{dry.out}

$ rustc --test dry.rs && ./dry
running 3 tests
test test::mul_assign ... ok
test test::add_assign ... ok
test test::sub_assign ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured