Day 063 — 2026-10-03 | マクロ① macro_rules! ⑧ 「マクロにするか、関数・型にするか」：hashmap!・square!・ensure!・log!・newtype!・check_eq! を実測で仕分ける

📚 背景知識（読んでから問題へ）

Day 057〜062 で hashmap!・fsm!・count! と、マクロを書く練習を続けてきました。ここで一度立ち止まります。書けることと、書くべきことは別です。 マクロは、読む人にもツールにも高くつきます（エラーが展開後のコードを指す、引数が文字列の並び「トークン」で見えて型が見えない、IDE の補完が効きにくい）。それでも要る場面があります。今日は「関数や型で足りるのに、マクロにしてしまった」ものと、「マクロでないと書けない」ものを、実際に動かして仕分けることが問題です。

マクロでないと書けない理由は、突き詰めると次の4つに絞れます（筆者の整理。一次資料の言い回しではありません）。

標準ライブラリはこの線引きに沿っています。vec![..] はマクロですが、HashMap::from([(k, v), ..]) は関数（Rust 1.56 以降の From<[(K, V); N]>）です。つまり Day 057 で書いた hashmap! は、今の標準ライブラリでは要らないマクロになっています（HashMap::from の存在は、今日の rustc 1.96.0 でコンパイルして確認）。

実務では、マクロの「追加」はレビューで必ず聞かれます。「これ関数じゃだめ？」に、数値と理由で答えられることが目的です。

📝 問題

環境は rustc 1.96.0、edition 2021。rustc を直接、または cargo test を使います。

Part 1: 仕分けを予想する（実行する前に答える）

次の6つのうち、マクロが必要なものに ○、関数・型で足りるものに × を付け、上の4つの理由のどれかを書いてください。

Part 2: 実測する（予想と比べる）

次の5つを、cargo test で通るテストとして書いてください（模範解答は 6 本）。

1. square! の $x * $x は、引数に副作用があると 2 回評価される。square(i64) 関数は 1 回。テストで示す（i を 1 ずつ増やすブロックを渡す）
2. hashmap! の結果が HashMap::from([..]) と等しい（K1 は関数で足りることの確認）
3. ensure を 関数＋? に置き換えて、check(5)・check(-1)・check(500) が通る
4. ログが無効のとき、expensive() が何回呼ばれるかを3方式で数える: ①普通の関数に &expensive() を渡す／②クロージャを渡す関数／③マクロ。予想は「1・0・0」
5. newtype! で作った UserId と OrderId は、中身が同じ u64 でも比べられない（コメントアウトしたコンパイルエラーの行を残す）

Part 3: コストを測って、マクロの追加基準を決める

square! と square() を 20,000 か所呼ぶだけのファイルを作り、rustc のコンパイル時間を各 5 回測ってください（-O なし）。「マクロの方が速い（展開が軽い）」「関数の方が速い」のどちらも先入観で書かず、数値で書くこと。あわせて square!("a") と square("a") で出るエラーメッセージを見比べてください。

最後に、「マクロを追加してよい基準」の判断記録（ADR）を 15 行以内で書いてください。必ず含めること。

• (a) 採る基準と、採らなかった基準（例:「コードが短くなるから」「速いから」）の却下理由。却下理由には今日の実測値を使う
• (b) 前提が変わったら判断がどう変わるか（2つ以上）
• (c) 今日の実測で測れなかったこと（1つ以上）

💡 ヒント

📋 コピーuse std::cell::Cell;
thread_local! { static EVALS: Cell<u32> = const { Cell::new(0) }; }
fn expensive() -> String { EVALS.with(|e| e.set(e.get() + 1)); "x".repeat(10) }

fn log_eager(msg: &str) { /* 有効なら println */ }
fn log_lazy<F: FnOnce() -> String>(f: F) { /* 有効なら f() を呼んで println */ }
macro_rules! log_m { ($($arg:tt)*) => { if ENABLED.with(|e| e.get()) { println!($($arg)*); } }; }

✅ 模範解答

Part 2 の答え（cargo test で 6 本通過を確認）

cargo new decide --lib の src/lib.rs にそのまま貼れば検証できます（依存クレートなし）。cargo test は警告（未使用）を数件出しますが、テストは通ります。

📋 コピーuse std::cell::Cell;
use std::collections::HashMap;

thread_local! {
    static EVALS: Cell<u32> = const { Cell::new(0) };
    static ENABLED: Cell<bool> = const { Cell::new(false) };
}
fn evals() -> u32 { EVALS.with(|e| e.get()) }
fn reset() { EVALS.with(|e| e.set(0)); }
fn expensive() -> String { EVALS.with(|e| e.set(e.get() + 1)); "x".repeat(10) }

// ---- 関数で足りるもの ----
pub fn square(x: i64) -> i64 { x * x }

#[derive(Debug, PartialEq)]
pub struct Err1(pub &'static str);
pub fn ensure(cond: bool, err: Err1) -> Result<(), Err1> { if cond { Ok(()) } else { Err(err) } }
pub fn check(x: i32) -> Result<i32, Err1> {
    ensure(x > 0, Err1("neg"))?;
    ensure(x < 100, Err1("big"))?;
    Ok(x)
}

// ---- 遅延評価: 関数(クロージャ)で足りる版とマクロ版 ----
fn log_eager(msg: &str) -> bool { if ENABLED.with(|e| e.get()) { println!("{msg}"); true } else { false } }
fn log_lazy<F: FnOnce() -> String>(f: F) -> bool { if ENABLED.with(|e| e.get()) { println!("{}", f()); true } else { false } }
macro_rules! log_m {
    ($($arg:tt)*) => { if ENABLED.with(|e| e.get()) { println!($($arg)*); true } else { false } };
}

// ---- マクロが要るもの ----
// (1) item を定義する
macro_rules! newtype {
    ($name:ident, $inner:ty) => {
        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
        pub struct $name($inner);
        impl From<$inner> for $name { fn from(v: $inner) -> Self { $name(v) } }
    };
}
newtype!(UserId, u64);
newtype!(OrderId, u64);

// (2) ソース文字列が要る
macro_rules! check_eq {
    ($l:expr, $r:expr) => {
        if $l != $r { Err(format!("{} != {} (line {})", stringify!($l), stringify!($r), line!())) } else { Ok(()) }
    };
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn square_macro_double_evaluates_but_fn_does_not() {
        macro_rules! square_m { ($x:expr) => { $x * $x }; }
        let mut i = 2i64;
        let a = square_m!({ i += 1; i });
        assert_eq!((i, a), (4, 12)); // 副作用が 2 回走る（3 * 4）
        let mut j = 2i64;
        let b = square(if true { j += 1; j } else { 0 });
        assert_eq!((j, b), (3, 9));
    }

    #[test]
    fn hashmap_macro_is_unnecessary() {
        macro_rules! hashmap { ($($k:expr => $v:expr),* $(,)?) => { HashMap::from([$(($k, $v)),*]) }; }
        assert_eq!(hashmap! { "a" => 1, "b" => 2 }, HashMap::from([("a", 1), ("b", 2)]));
    }

    #[test]
    fn ensure_function_with_question_mark() {
        assert_eq!(check(5), Ok(5));
        assert_eq!(check(-1), Err(Err1("neg")));
        assert_eq!(check(500), Err(Err1("big")));
    }

    #[test]
    fn eager_vs_lazy_logging() {
        ENABLED.with(|e| e.set(false));
        reset(); log_eager(&expensive()); assert_eq!(evals(), 1);
        reset(); log_lazy(expensive);     assert_eq!(evals(), 0);
        reset(); log_m!("{}", expensive()); assert_eq!(evals(), 0);
        ENABLED.with(|e| e.set(true));
        reset(); assert!(log_m!("{}", expensive())); assert_eq!(evals(), 1);
    }

    #[test]
    fn newtypes_are_distinct_types() {
        let u: UserId = 7u64.into();
        let o: OrderId = 7u64.into();
        assert_eq!(u, UserId(7));
        assert_eq!(o, OrderId(7));
        // assert_eq!(u, o); // ← コンパイルエラー: 型が違う（E0308）
    }

    #[test]
    fn check_eq_reports_source_text() {
        let x = 3;
        let msg = check_eq!(x + 1, 5).unwrap_err();
        assert!(msg.starts_with("x + 1 != 5 (line "), "{msg}");
    }
}

Part 1 の答え

6 つのうち、マクロが唯一の手段なのは K5・K6 の 2 つだけです。K4 は「書き味」、K3 は「エラー構築の遅延」でマクロが残る余地があり、K1・K2 は不要でした。

Part 3 の答え（今回の実測）

20,000 か所の呼び出しを rustc --edition 2021 -o（-O なし）でコンパイルした時間（5 回、単位は秒、開発機は他のプロセスと同居）:

差はぶれの範囲内で、「マクロの方が速い」とも「遅い」とも言えません（最小値の差 0.13 秒、関数側の最大 4.01 秒は同居プロセスの影響と推定。要因は未調査）。したがって「コンパイルが速くなるからマクロにする」は基準にできません。

エラーメッセージの比較（実出力の要点、square!("a") と square("a")）:

マクロ版は「&str を掛けられない」と展開後の $x * $x を指し、利用者は sq! のシグネチャ（何型を受けるか）を知る手段がありません。関数版は「期待は i64」と型で教えます。

📋 コピーADR-063 マクロを追加してよい基準
決定: 次の「関数・型では書けない」場合だけ新しいマクロを追加する。
  ①呼び出し元の制御フローを変え、かつ `?` で書けない  ②引数の評価を遅らせ、かつクロージャ引数で書けない
  ③stringify!/line!/file! などソース情報が要る  ④struct・impl・enum などの item を生成する
採らなかった基準:
  「コードが短くなる」: hashmap!/square! は短いが、square! は引数を 2 回評価し（i=4, 結果 12 対 9）、
    hashmap! は HashMap::from で足りる（実測）。短さは副作用の見えにくさと引き換え。
  「コンパイルが速い」: 20,000 か所で最小 2.47 秒対 2.60 秒、5 回のぶれは 2.47〜4.01 秒（実測）。差が測れない。
  「マクロは上級者の書き方」: 理由にならない。エラーも型を言わないぶん利用者に不利（E0369 対 E0308、実測）。
前提が変わったら: ①`macro_metavar_expr` 等が stable になり関数で書ける範囲が増えるなら基準①〜④を見直す
  ②入力が 1 万か所を超え、-O ありでマクロ展開が支配的になる計測が出たなら速度を基準に加える
  ③チーム全員が proc-macro を読み書きできるなら、④は derive へ寄せる。
測れていないこと: release ビルド(-O)の時間、実行時の速度差（インライン化後は同一と推定のみ）、
  IDE の補完・ジャンプの実害、`ensure` 関数版で重いエラー値を先に作るコスト。

👣 Step-by-Step 解説

Step 1: 引数を 2 回評価する（K2）

macro_rules! square_m { ($x:expr) => { $x * $x }; } に { i += 1; i } を渡すと、i は 2 回増えて (i=4, 結果=3*4=12) になります。マクロは値を受け取るのではなく、式のトークンをそのまま埋め込むからです。関数は呼ぶ前に引数を 1 回だけ評価するので (j=3, 結果=9) です。$x を 2 か所に書くマクロでは、副作用のある式を渡す人に必ず罠になります。直すには let x = $x; x * x と一度束縛しますが、それは関数で足りるという合図です。

Step 2: 標準ライブラリが関数に寄ってきた（K1）

hashmap! を書いた当時（Day 057）は価値がありました。今の標準では HashMap::from([("a", 1), ("b", 2)]) で足ります。マクロが埋めていた隙間は、言語・標準が追いつくと消えるので、マクロは「負債」になりえます。残す理由は書き味だけです。

Step 3: ? で呼び出し元を戻す（K3）

return は関数の中でしか効きませんが、? 演算子は「Err なら呼び出し元に戻る」ので、ensure(cond, err)?; で同じ制御フローになります。制御フローの変更＝マクロ必須、ではない点が盲点です。残る差は、Err1("neg") を成否にかかわらず先に作ってしまうことだけです（文字列リテラルなら無料、format! を含むなら有料。今日は未測定）。

Step 4: 評価の遅延は、クロージャでも書ける（K4）

3 方式の評価回数は log_eager=1、log_lazy=0、log_m!=0（実測）。マクロが唯一ではないことが数字で出ます。マクロが残る理由は、log_m!("{} {}", a, b) と format! と同じ書き味にできる点です（クロージャ版は log_lazy(|| format!(...)) と一段長い）。この差を許容できるかが判断です。

Step 5: item の生成は、マクロでしか書けない（K5）

newtype!(UserId, u64) は struct と impl From を作ります。関数もジェネリクスも item を作れないので、マクロの本来の領分です。UserId と OrderId を == で比べるとコンパイルエラー（E0308）になり、取り違えを型が止めます。

Step 6: ソース文字列は、マクロでしか取れない（K6）

stringify!($l) が x + 1 という書いたとおりの文字列を返し、line!() が行番号を返します。関数は値（4）しか見えないので、「4 != 5」までしか言えません。assert_eq! が標準でマクロなのはこの理由です。

Step 7: 速さではなく「何を知らせられるか」で決める

20,000 か所でも差は測れませんでした。差が出たのはエラーの出方です。関数は「i64 が期待される」と型を言い、マクロは展開後の定義を指します（実測）。マクロにすると、型という API の説明がコンパイラから消える。これがコストです。

🧠 設計思想・なぜこう書くのか

Rust の型システムは、引数の型・評価の回数・所有権の移動を関数のシグネチャに書かせることで、コンパイラが利用者を守る設計です。マクロはその外側（トークンの世界）に出る手段で、守りを捨てる代わりに表現力を得る取引です。だから「型が書けるなら型で、値で足りるなら関数で、それでも書けないときだけマクロ」という順序になります。

迷った他案と採らなかった理由

前提が変わったら: 標準が ${count} のような機能を stable にすれば、マクロで書いていた隙間はさらに減ります。逆に、チーム内で DSL を多用する前提なら、基準④の範囲を広げる判断もありえます。

🛠️ コンパイルエラーが出た場合（デバッグ問題では必須）

今日はデバッグ問題ではありませんが、Part 3 の比較に使う実出力（rustc 1.96.0）を残します。上の ADR の節にある E0369（マクロ版）と E0308（関数版）が該当します。読み方の要点は次のとおりです。

• マクロ由来のエラーは「this error originates in the macro」の注記が付き、位置がマクロ定義側を指す。呼び出し側を見るには -Z macro-backtrace（nightly）が要る
• 関数由来のエラーは、呼び出し側の引数に「期待される型」が付く。直し方も読み取りやすい
• UserId と OrderId を == で比較すると E0308（mismatched types）。型が別なので止まる（テストではコメントアウトした行）

🔀 他言語との比較（該当する場合）

Rust のマクロは衛生的（変数名の衝突を避ける）ぶん、C のマクロより安全ですが、「引数を 2 回評価する」罠は同じです。

🏭 実務での使いどころ

• コードレビューで「このマクロは関数・型でだめか」を聞く基準として、上の ADR（4 つの理由）をそのまま使えます。
• 標準ライブラリで vec!・format!・assert_eq!・matches! がマクロである理由は、上の 4 つの理由で説明できます（各マクロの実装は今日は取得し直して照合していません。一次資料は末尾）。
• 古いコードにある自作の hashmap!・max! は、現在の標準で置き換えられるかを cargo clippy や手動で見直す価値があります（置き換え作業は今日は未実施）。

⚠️ よくある誤解・ミス

📖 一次資料（参照日: 2026-10-03。今回は取得し直して照合していません。記述は要旨で、原文の引用ではありません）

• The Rust Reference, Macros By Example（展開の仕組み・衛生性）: https://doc.rust-lang.org/reference/macros-by-example.html
• The Rust Programming Language, Macros の章（マクロと関数の違い）: https://doc.rust-lang.org/book/ch20-05-macros.html
• std HashMap の From<[(K, V); N]>（今日は rustc 1.96.0 でコンパイルして存在を確認した）: https://doc.rust-lang.org/std/collections/struct.HashMap.html

🚧 今日扱わなかった範囲（次回以降）

3 問の自己点検（/ai-smell-audit 相当）

1. 同じ指示を AI に出せば数時間で出るか — 「マクロが必要な理由 4 つ」は出る。ただし「二重評価で i=4・結果 12」「評価回数 1・0・0」「20,000 か所で 2.47 秒対 2.60 秒（差が測れない）」「E0369 と E0308 の指す位置の違い」は、実際に動かさないと出ない。
2. AI に指示するだけでは出ない部分 — 「速さを基準にできない」という否定的な実測、ADR の「採らなかった基準」と「測れていないこと」。
3. 世界の実物と比べて何割か — 標準ライブラリのマクロ全体（vec!・format!・matches!・thread_local! など 10 個以上）のうち、今日は仕分け対象の 6 個を扱った。実在クレートの照合は未実施（上の表に明記）。

➡️ 次のステップ

• 発展: 自分の過去のマクロ（hashmap!・fsm!・count!）に ADR の 4 基準を当て、残すものと関数・型に直すものを仕分ける。直した後に cargo test の結果が変わらないか確認する
• 次回予告: マクロ① の最終日に向けて、ガード付き遷移（$from:pat if $g:expr）、または実在クレートのマクロの読解（一次資料を取得して照合する）

🎯 自己評価（解いた後に記入）

自分の回答

気づき・メモ