Rustのパニック「attempt to add with overflow」を修正する — 整数演算オーバーフロー

何が起きたのか

Rustプログラムをデバッグモードで実行したところ、次のエラーが発生しました：

thread 'main' panicked at 'attempt to add with overflow', src/main.rs:5:15

これは、整数演算の結果がその型の保持できる範囲を超えた場合に発生します。255のu8に1を加算するのが典型的な例です。i32::MAX（2,147,483,647）を超えたi32のカウンターも同様です。

注意すべき落とし穴があります：このパニックはデバッグビルドでのみ発生します。リリースモード（--release）では、Rustは警告なしにラップアラウンドします——パニックは起きず、ただ誤った値が返されます。これが、ステージング環境ではすべてのテストに合格し、本番環境でバグが爆発する原因となります。

再現方法

fn main() {
    let x: u8 = 255;
    let y = x + 1; // thread 'main' panicked at 'attempt to add with overflow'
    println!("{}", y);
}

cargo run（デバッグ）で実行するとパニックが発生します。cargo run --releaseに切り替えると、パニックの代わりに0が返されます——これは何も問題が通知されないため、さらに厄介です。

デバッグ：発生箇所を特定する

パニックメッセージにはファイル名と行番号が含まれています。通常はそれで十分です。深いコールスタックの場合は、次のコマンドを実行してください：

RUST_BACKTRACE=1 cargo run

バックトレースを確認し、自分のコード内の最初のフレームを探してください——stdやcoreの内部処理は無視します。それがオーバーフローの発生箇所です。

もう一つ確認すべき点：演算前に型のキャストを行っていますか？よくある落とし穴は、u64をasでu32に縮小してから、切り捨てられた値で演算を行うことです。オーバーフローはキャスト後に発生し、元の値は問題なさそうに見えます。

解決策

オプション1：チェック付き演算を使用する（失敗しうるロジックに推奨）

checked_add、checked_sub、checked_mulはOption<T>を返します。オーバーフローが発生するとNoneが返され、パニックの代わりに明示的に処理できます。

fn main() {
    let x: u8 = 255;
    match x.checked_add(1) {
        Some(result) => println!("Result: {}", result),
        None => println!("Overflow! Handle it here."),
    }
}

オーバーフローが本当に問題を意味する場合——バイト長の計算、配列インデックス、金額の合計、メッセージシーケンス番号——に使用してください。

オプション2：サチュレーティング演算を使用する（最小/最大でクランプ）

サチュレーティング演算は、ラップアラウンドやパニックの代わりに、型の境界値で止まります。上限に達したらそこに留まります。

fn main() {
    let x: u8 = 255;
    let y = x.saturating_add(1); // y == 255, not 0
    println!("{}", y);
}

カウンター、HPゲージ、信号強度の表示など、「最大値で止まる」動作がパニックや不正な値よりも適切な場合に最適です。

オプション3：ラッピング演算を使用する（明示的なラップアラウンド）

ハッシュ処理、チェックサム、低レベルのバイト操作では、意図的に剰余演算が必要な場合があります。wrapping_addを使うと、その意図がコード上で明確になります：

fn main() {
    let x: u8 = 255;
    let y = x.wrapping_add(1); // y == 0
    println!("{}", y);
}

このコードを読んだ人は、ラップが意図的なものであり、潜在的なバグではないことが分かります。

オプション4：より大きな整数型を使用する

単純により大きな型を使うのが正解な場合もあります。スコアをu32で保存しているが、2人のプレイヤーの合計が4,294,967,295を超える可能性がある場合は、u64に切り替えてください：

fn add_scores(a: u64, b: u64) -> u64 {
    a + b // safe up to 18,446,744,073,709,551,615
}

範囲が有界で、単に余裕が必要な場合に有効です。入力が本当に無制限な場合には適切な解決策ではありません——その場合はチェック付き演算の方が適しています。

オプション5：リリースモードでオーバーフローチェックを有効にする

リリースビルドはデフォルトでオーバーフローチェックをスキップします。Cargo.tomlでグローバルに有効にするには：

[profile.release]
overflow-checks = true

わずかなパフォーマンスコストがありますが、本番環境でもオーバーフローを検出できます。安全性が重要なコードや、微妙な算術バグの追跡中には価値があります。

適切な修正方法の選択

オーバーフローがバグである → checked_*を使用してNoneを明示的に処理する
オーバーフロー時にクランプすべき → saturating_*を使用する
オーバーフローが意図的 → wrapping_*を使用する
単に余裕が必要 → より大きな型（u64、i64、またはusize）を使用する

修正の確認

変更後に両方のビルドモードでテストしてください：

# Debug build — was panicking before
cargo run

# Release build — was silently wrong before
cargo run --release

checked_addを使用した場合は、テストでオーバーフローのケースをカバーしてください：

#[cfg(test)]
mod tests {
    #[test]
    fn test_no_overflow() {
        let x: u8 = 255;
        assert_eq!(x.checked_add(1), None);
    }

    #[test]
    fn test_normal_add() {
        let x: u8 = 100;
        assert_eq!(x.checked_add(50), Some(150));
    }
}

cargo testで実行して確認してください。

教訓

デバッグとリリースの動作の違いは本当に危険です。オーバーフローが大きなパニックを引き起こすため、テストはデバッグモードで合格します。リリースビルドをリリースすると、同じオーバーフローが静かにラップアラウンドします——誤った出力、エラーなし、手がかりなし。実際のRustのバグの多くが、まさにこのパターンに従っています。

目標は単にパニックを止めることではありません。オーバーフローの動作を意図的なものにすること——コードを読む次の人が、ラップ、クランプ、エラーのどれが正しい選択だったかを理解できるようにすることです。

演算が多いコードを監査する際は、小さな型を含む演算に注目してください：u8、u16、i32。それぞれについて、「この値が境界に達したらどうなるか？」と問いかけてください。その答えを理解するためにコールスタックを3つ遡る必要があるなら、それがシグナルです——裸の演算子をchecked_*やsaturating_*に置き換えて、意図を明確にしましょう。