イテレータの消費とは

イテレータ（Iterator）とは、値の列を生成する値で、要素を順番に取り出すことができる仕組みです。イテレータの基本やイテレータアダプタについて理解が不十分な方は、以下にまとめていますので参考にしてください。

• イテレータ（Iterator）の基本を分かりやすく解説
• Iterator のアダプタ（map・filter など）を分かりやすく解説

上記では、イテレータの基本とアダプタを使って別のイテレータを作る方法を紹介しました。

イテレータは、next を使って順に値を取り出すことができます。next を繰り返し呼び出すことで、イテレータの要素を最後まで（または途中まで）使い切ることを「消費」と言います。イテレータを消費しつつ、最終的な計算結果を得るメソッドを「消費アダプタ（consuming adapter）」と言います。

この記事では、代表的な消費アダプタを紹介しつつ、イテレータを消費する方法を紹介します。

代表的な消費アダプタ

以降では、よく使用される代表的な消費アダプタを紹介していきます。

collect：コレクションに集約する

collect は、イテレータの要素をコレクションにまとめることができる消費アダプタです。

Vec への集約

以下は、numbers を 2 倍した数値列を Vec に集約する例です。

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];

    // map を適用したイテレータを collect して新しい Vec に集約
    let result_vec: Vec<_> = numbers.iter().map(|x| x * 2).collect();

    // 結果を表示
    println!("{:?}", result_vec);
}

【実行結果】
[2, 4, 6, 8, 10]

例で「numbers.iter().map(|x| x * 2)」は、map というイテレータアダプタを使い、各要素を 2 倍したイテレータを返します。この段階では、x * 2 の計算は適用されていません。その後、collect という消費アダプタが適用されることで計算が実行されて Vec の result_vec にまとめられます。

なお、collect は、任意のコレクションにまとめることができるため「result_vec: Vec<i32>」という型注釈をつけるか、「collect::<Vec<_>>() 」のようにどの型に変換するかを明示する必要があります。

その他のコレクションへの集約

上記で Vec への集約を紹介しましたが、任意のコレクションにまとめられると説明しました。1 例として HashSet に集約する例を見ておきましょう。

以下は、numbers の 値を 2 倍にした後、HashSet に集約しています。HashSet を用いると、重複を取り除いた集合として扱うことができます。

use std::collections::HashSet;

fn main() {
    let numbers = vec![1, 2, 3, 1, 2, 5];

    // HashSet を使用して、重複を排除したコレクションに集約
    let result_set: HashSet<_> = numbers.iter().map(|x| x * 2).collect();

    // 結果を表示
    println!("{:?}", result_set);
}

【実行結果例】※ HashSet は順序保証がされないため、順序は実行により異なります
{4, 2, 6, 10}

型注釈で「: HashSet<_>」を付けることで、HashSet に集約できます。このように、collect は変換先のコレクションの型によって結果が変わることが特徴的です。

省略しますが、同様に HashMap などのその他コレクションも同様に扱うことができます。

無限のシーケンスの場合

イテレータの強力な特徴は、無限のデータシーケンスも扱うことができる点です。ただし、collect を使用する場合には、注意が必要です。以下のように take や take_while などで、データの範囲を制限して適用をする必要があります。

fn main() {
    // 無限の数値列を生成するイテレータ
    let infinite_numbers = 1..;

    // 無限の数値列から最初の 5 個を collect して Vec に集約
    let result_vec: Vec<_> = infinite_numbers.take(5).collect();

    // 結果を表示
    println!("{:?}", result_vec);
}

【実行結果】
[1, 2, 3, 4, 5]

例では「1..」により、RangeFrom<i32> のイテレータを生成しています。このイテレータは 1 から順番に数値を取り出せますが、末尾が決まっていません。そのため、take により先頭 5 個を取り出すイテレータアダプタを適用してから collect を適用しています。

無限のデータシーケンスの場合は、消費アダプタの使用には注意が必要です。以降で紹介する消費アダプタについても同様に無限に続くイテレータの場合は注意して使用してください。

count：件数を取得する

count は、イテレータの要素数を取得する消費アダプタです。count はイテレータを消費し、要素を最後まで走査することで件数を返します。

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];

    // count() メソッドを使用して、イテレータの要素数を数える
    let count = numbers.iter().count();

    // 結果を表示
    println!("{}", count);
}

【実行結果】
5

sum / product：数値の合計や積を計算する

sum は要素の合計、product は要素の積を計算するための消費アダプタです。これらは、数値を集約したいときに便利です。

fn main() {
    let numbers = [1, 2, 3, 4, 5];

    let sum: i32 = numbers.iter().sum();
    let product: i32 = numbers.iter().product();

    println!("sum: {}", sum);
    println!("product: {}", product);
}

【実行結果】
sum: 15
product: 120

sum や product は、戻り値の型をコンパイラが決められないため、基本的には型注釈が必要になります（例「sum : i32」）。ただし、関数の戻り値型などから型が明らかな場合は、型推論により型注釈を省略できることもあります。なお、sum は数値型に対してのみ使用可能です。

max / min：最大値や最小値を取得する

max と min は、それぞれ最大値・最小値を取得するための消費アダプタです。

fn main() {
    let numbers = [3, 2, 5, 1, 4];

    // 最大値と最小値を求める
    let max = numbers.iter().max();
    let min = numbers.iter().min();

    // 結果を表示
    println!("max: {:?}", max);
    println!("min: {:?}", min);
}

【実行結果】
max: Some(5)
min: Some(1)

max と min については、戻り値が Option 型になる点に注意してください。これは、イテレータが空の場合は、最大値や最小値を返せないためです。

fold / rfold：畳み込み計算を行う

fold や rfold は、イテレータの要素を順番に取り出しながら 1 つの値にまとめるための消費アダプタです。fold は前から、rfold は後ろから計算する点に違いがあります。

基本的な構文は以下のような形となります。

iterator.fold(初期値, |累積値, 要素| 処理)

• 初期値：最初に累積する値
• 累積値：これまでの計算結果
• 要素：イテレータから取り出した要素

以降では、簡単な合計の例で fold と rfold の使い方を見てみましょう。なお、合計を例にするだけで、fold / rfold では任意の処理ができる点が非常に強力です。

fold（前から畳み込む）

fold は、イテレータの要素を前から順に処理しながら、1 つにまとめます。

合計 (sum) を fold で計算する例

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];

    // fold を使用して、イテレータの要素の合計を求める
    let sum = numbers.iter().fold(0, |acc, x| acc + x);

    // 結果を表示
    println!("sum: {}", sum);
}

【実行結果】
sum: 15

例では、「初期値: 0」「0 + 1 = 1」「1 + 2 = 3」…「10 + 5 = 15」のように計算が繰り返し進んで 1 つの合計結果にまとまります。この例から、分かるように上記で紹介した sum や product などは、fold でも実現することができます。

任意の処理を定義可能

上記では分かりやすいように合計の例を紹介しましたが、fold は任意の処理を定義できます。以下は、文字列を連結する例です。

fn main() {
    let words = vec!["Hello", " ", "Rust", "!"];

    // fold を使用して、イテレータの要素を連結する
    let concatenated = words.iter().fold(String::new(), |acc, word| acc + word);

    // 結果を表示
    println!("{}", concatenated);
}

【実行結果】
Hello Rust!

このように、fold は文字列の結合などにも使えます。fold や後述する rfold は要素をどのように 1 つの値へまとめるかを柔軟に定義できる点が大きな特徴です。

rfold（後ろから畳み込む）

rfold は、fold と同じように値を 1 つにまとめますが、後ろから順に処理する点が異なります。数値計算だと計算順序が分かりにくいため、文字列結合で比較してみましょう。

fn main() {
    let words = vec!["a", "b", "c", "d"];

    // fold を使用して、前から順に要素を結合する
    let forward = words.iter().fold(String::new(), |acc, word| acc + word);

    // rfold を使用して、逆順に要素を結合する
    let backward = words.iter().rfold(String::new(), |acc, word| acc + word);

    // 結果を表示
    println!("forward: {}", forward);
    println!("backward: {}", backward);
}

【実行結果】
fold: abcd
rfold: dcba

例のように、fold では "abcd" のような順になりますが、rfold では、"dcba" のように処理の順序が逆になっています。数値計算などでも、処理の順序が変わる点は同様です。

その他の便利な消費アダプタ

その他の消費アダプタ一覧

上記で紹介した消費アダプタの他にも多くの消費アダプタがありますが、ここでは、代表的なものを一覧で簡単に紹介します。

まとめ

Rust の イテレータ（Iterator）に消費アダプタの基本について解説しました。

イテレータは next を使って順番に値を取り出す仕組みであり、その要素を最後まで、または途中まで使うことを「消費」と言います。消費アダプタは、そのイテレータを消費しながら最終的な結果を得るためのメソッドです。

この記事では、代表的な消費アダプタとして、次のようなものを紹介しました。

• collect：コレクションにまとめる
• count：件数を取得する
• sum / product：合計や積を計算する
• max / min：最大値や最小値を取得する
• fold / rfold：任意の処理で 1 つの値にまとめる

まずは collect、count、sum などの基本的な消費アダプタに慣れてもらい、そのうえで fold を理解すると、イテレータの仕組みをより深く理解できるようになります。

あわせて読みたい

Rust プログラミング入門

イテレータアダプタとは

イテレータ（Iterator）とは、値の列を生成する値で、要素を順番に取り出すことができる仕組みです。イテレータの基本は「イテレータ（Iterator）の基本を分かりやすく解説」を参考にしてください。この記事で、基本となる next や into_iter などについて解説しています。

イテレータには、要素を順番に取り出すだけでなく、要素を変換したり、条件に合うものだけを残したりする便利なメソッドが多数用意されています。これらをイテレータアダプタと言います。イテレータアダプタは、既存のイテレータをもとに、新しいイテレータを作り出します。

イテレータアダプタの重要な点は、その場ですぐに最終結果を作るのではなく、新しいイテレータを返すという点です。この仕組みは「遅延評価」と呼ばれ、要素が実際に取り出されるときに初めて処理が実行されます。そのため、必要な分だけ効率よく処理を行うことができます。

また、イテレータアダプタには、変換などの処理内容を指定するためにクロージャをよく使用します。なお、クロージャの代わりに通常関数を渡すことも可能ですが、外部変数を利用できる点からクロージャがよく使用されます。

この記事では、代表的なイテレータアダプタを紹介しつつ、イテレータアダプタの基本的な使い方を紹介していきます。

代表的なイテレータアダプタ

ここでは、基本としてよく使用するイテレータアダプタである map と filter を中心に使い方を見ていきましょう。

map：各要素に処理を適用し、別の値に変換する

map は、イテレータの各要素に対して指定した処理を適用し、その結果となるイテレータに変換するアダプタです。

fn main() {
    // 元データのベクタを作成
    let numbers = vec![1, 2, 3];

    // map を使用し、各要素を2倍にしたイテレータを作成
    // (この時点ではまだ計算されない)
    let doubled_iter = numbers.iter().map(|x| x * 2);

    // イテレータをベクタに収集 (ここで初めて計算が行われる)
    let result: Vec<_> = doubled_iter.collect();

    // 結果を表示
    println!("{:?}", result);
}

【実行結果】
[2, 4, 6]

map では、引数にクロージャ（または関数）を受け取りイテレータを返却します。上記で doubled_iter はイテレータです。この時点では、各要素を 2 倍にするという計算はまだされていません。collect や for 文で要素を取り出すときに、初めて計算が実行されます。これが「遅延評価」です。

result 変数に束縛する際に使用している collect という処理は、イテレータの要素をコレクションにまとめるメソッドです。collect は戻り値の型が一意には決まりません。例えば、Vec や HashSet などのさまざまなコレクションに変換できるためです。このため「let result: Vec<_>」のように型注釈をつけるか、collect::<Vec<_>>() のように、どの型に変換するかを明示する必要があります

なお、上記では map によるイテレータ生成から、collect による遅延評価での処理という流れを理解してもらうために丁寧に文を分けて記載しましたが、以下のように「.（ドット）」で処理を連結させることで簡潔に記載も可能です。以降では、この形式で紹介していきます。

fn main() {
    // 元データのベクタを作成
    let numbers = vec![1, 2, 3];

    // map を使用し、各要素を2倍にした結果を取得する
    let result: Vec<_> = numbers.iter().map(|x| x * 2).collect();

    // 結果を表示
    println!("{:?}", result);
}

filter：条件に一致する要素だけを残す

filter は、イテレータの各要素に対して条件による判定をし、条件に一致する要素だけを残したイテレータに変換するアダプタです。

fn main() {
    let numbers = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

    // filter を使用し、偶数のみを残す
    let even_numbers: Vec<_> = numbers.iter().filter(|x| **x % 2 == 0).collect();

    // 結果を表示
    println!("{:?}", even_numbers);
}

【実行結果】
[2, 4, 6, 8, 10]

filter では、クロージャが true を返した要素のみ残り、false の要素は除外されます。

例では、iter() を使用しているため要素は参照として扱われます。また、filter は要素をクロージャに渡して条件判定を行うため、この例では **x のように参照を外して値を取り出しています。（参照が重なっているため、2 回参照を外しています。）

map と filter を組み合わせて使う

イテレータアダプタは、「.（ドット）」でつなげることで複数の処理を連続して適用することで本領を発揮します。以下は、filter で偶数のみ残し、さらに map で 2 倍する例です。

fn main() {
    let numbers = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

    // filter と map を組み合わせて、偶数の2倍を計算する
    let even_doubles: Vec<_> = numbers
        .iter()
        .filter(|x| **x % 2 == 0)
        .map(|x| x * 2)
        .collect();

    // 結果を表示
    println!("{:?}", even_doubles);
}

【実行結果】
[4, 8, 12, 16, 20]

このように、イテレータアダプタを組み合わせて、データの処理を上から順に記述していくことで、可読性が高いコードを記述できることが特徴です。

その他の便利なイテレータアダプタ

map と filter はイテレータアダプタとして中心的なものです。他にも多くのイテレータアダプタがありますが、ここではよく使われるものをいくつか紹介します。

filter_map：変換を行い、成功（Option の Some）のみを残す

filter_map は、変換と絞り込みを同時に行うことができるアダプタで、変換を行い成功した値のみを残すことができます。

fn main() {
    let values = vec!["10", "abc", "20", "def", "30"];

    // filter_map を使用して、文字列を整数に変換し、成功したものだけを収集する
    let numbers: Vec<_> = values
        .iter()
        .filter_map(|s| s.parse::<i32>().ok())
        .collect();

    // 結果を表示
    println!("{:?}", numbers);
}

【実行結果】
[10, 20, 30]

この例では、文字列の Vec を整数に変換しています。指定したクロージャは、整数に変換できた場合は、Option 型の Some(v) を返し、変換できなかった場合は None を返します。

結果を見ると分かるように filter_map は、変換結果が Some(v) であれば中の値 v を結果に残し、None の場合はその値を除外します。

flat_map：各要素を複数の要素に展開し、1 つの列としてつなげる

flat_map は、各要素を複数の要素に展開し、1 つの列としてつなげるアダプタです。

fn main() {
    let numbers = vec![1, 2, 3];

    let result: Vec<_> = numbers.iter().flat_map(|x| vec![*x, *x * 10]).collect();

    // 結果を表示
    println!("{:?}", result);
}

【実行結果】
[1, 10, 2, 20, 3, 30]

この例で、指定したクロージャは与えられたイテレータの要素の値に対して、値と 10 倍の値のペアを生成しています。[1, 2, 3] がクロージャにより [[1, 10], [2, 20], [3, 30]] に展開され、flat_map により [1, 10, 2, 20, 3, 30] に 1 つの列につなげられているイメージを持ってもらうと分かりやすいかと思います。

その他のイテレータアダプタ一覧

上記で紹介したイテレータアダプタの他にも多くのイテレータアダプタがありますが、ここでは、代表的なものを一覧で簡単に紹介します。

まとめ

Rust の イテレータに用意されているイテレータアダプタの基本について解説しました。

イテレータアダプタは、既存のイテレータから新しいイテレータを作る仕組みです。代表的なイテレータアダプタである map と filter を用いて基本的な使い方を紹介しています。また、その他のイテレータアダプタについても簡単に紹介しました。

イテレータアダプタは、組み合わせて使用することで、処理の流れを非常に分かりやすく記述することができます。まずは、map と filter でしっかりと理解してもらうことが重要です。その上で、filter_map や flat_map などのさまざまなアダプタも徐々に使えるようになっていってください。

あわせて読みたい

Rust プログラミング入門

イテレータとは

イテレータ（Iterator）は、値の列を生成する値で、要素を順番に取り出すことができる仕組みです。Rust では、文字列や Vec などから要素を取り出して処理するイテレータが用意されています。他にも、様々な場面でイテレータの仕組みが利用されています。

Rust の for 文はイテレータにとって自然に扱える構文となっており、シンプルなプログラム例は以下のようなものです。

fn main() {
    let v = vec![1, 2, 3];

    for x in v {
        println!("{}", x);
    }
}

【実行結果】
1
2
3

Rust では、このような繰り返し処理の多くがイテレータを使って実装されており、Rust における重要な仕組みです。Rust のイテレータは、具体的には、Iterator トレイトや IntoIterator トレイトにより表現されています。

この記事では、Rust のイテレータ（Iterator）の基本を解説します。

イテレータの基本

イテレータを実現する中心的なトレイトは、Iterator トレイトと IntoIterator トレイトです。ここでは、それぞれの概要について紹介します。

Iterator トレイト

Iterator トレイトは、以下のように定義されています。

pub trait Iterator {
    type Item;

    // Required method
    fn next(&mut self) -> Option<Self::Item>;

    ...(他のメソッドは省略)...
}

Item という取り出す要素の型と next メソッドを持ちます。独自の型に Iterator トレイトを実装する際には next メソッドは必須のメソッドになります。他にもトレイトで定義されているメソッドはありますが、明確に定義しない場合はデフォルト実装が使用されます。

next メソッド

next メソッドは、イテレータの中心となる重要なメソッドです。

fn main() {
    let v = vec![1, 2, 3];
    let mut iter = v.iter();

    println!("{:?}", iter.next()); // Some(1)
    println!("{:?}", iter.next()); // Some(2)
    println!("{:?}", iter.next()); // Some(3)
    println!("{:?}", iter.next()); // None
}

【実行結果】
Some(1)
Some(2)
Some(3)
None

iter メソッドは、対象のイテレータを取得します。（iter については後ほど説明します。）

イテレータにおける next メソッドは、順に要素を取り出し、値 x がある場合は、Option 型の Some(x) を返却します。要素を取り出し続け、取り出す要素がなくなったら最後に None を返却します。 イテレータは、Option 型を使って処理の終了を表現していることがポイントです。

v は、イミュータブル（変更不可）ですが、iter は mut を付けてミュータブル（変更可能）にしています。これは、next() メソッドがイテレータ自身の状態を更新するためであり、イテレータは mut で宣言する必要があります。

IntoIterator トレイト

IntoIterator トレイトは、イテレータを生成できる型を表すトレイトで、以下のように定義されています。

pub trait IntoIterator {
    type Item;
    type IntoIter: Iterator<Item = Self::Item>;

    // Required method
    fn into_iter(self) -> Self::IntoIter;
}

IntoIterator を実装している型は、into_iter メソッドによってイテレータに変換することができます。

into_iter メソッド

into_iter メソッドは、値や参照からイテレータを生成するメソッドです。into_iter() で理解しておくべきことは以下の通りです。対象 v に対してそれぞれ呼ばれる実装が変わります。

• (&v).into_iter()：不変参照のイテレータを生成する
• (&mut v).into_iter()：可変参照のイテレータを生成する
• v.into_iter()：所有権を移動するイテレータを生成する

以下の例を見てみましょう。

fn main() {
    let v1 = vec![1, 2, 3];

    // 不変参照のイテレータを作成
    for x in (&v1).into_iter() {
        println!("{}", x);
    }

    let mut v2 = vec![4, 5, 6];

    // 可変参照のイテレータを作成
    for x in (&mut v2).into_iter() {
        *x += 1; // 各要素に1を加える
        println!("{}", x);
    }

    let v3 = vec![7, 8, 9];

    // 所有権を移動するイテレータを作成
    for x in v3.into_iter() {
        println!("{}", x);
    }

    // v3は所有権が移動したため、ここで使用できない
    // println!("{:?}", v3); // コンパイルエラー
}

【実行結果】
1
2
3
5
6
7
7
8
9

このように、into_iter() は同じ名前のメソッドであっても、値に対して呼ぶのか、参照に対して呼ぶのかで返すイテレータの型が異なります。この違いは、IntoIterator が「値」「不変参照」「可変参照」のそれぞれに対して実装されていることによるものです。そのため、要素の型も T / &T / &mut T のように変化します。なお、T は型パラメータです。

for 文と Iterator の関係

Rust の for 文は、IntoIterator トレイトを実装している型に対して使用できます。つまり、for 文は内部的に into_iter() を呼び出し、イテレータとして要素を取り出しています。

for 文で繰り返し処理を実装する場合は、明示的に into_iter() を書かなくても、以下のように不変参照で繰り返し処理を行うことができます。なお、可変参照や所有権移動の場合も同様に考えることができます。

for x in &v {
    println!("{}", x);
}

これは、内部的には、概ね次のような処理が行われていると考えることができます。

fn main() {
    let v = vec![1, 2, 3];

    let mut iter = (&v).into_iter();

    while let Some(x) = iter.next() {
        println!("{}", x);
    }
}

つまり、「for x in &v」は、(&v).into_iter() を使ってイテレータを生成し、next() で要素を順番に取り出して処理をしているというイメージです。

コレクションにおける iter や iter_mut メソッド

Vec などのコレクションでは、Iterator を返すメソッドとして、iter メソッドや iter_mut メソッドが提供されています。名称の通り、iter メソッドは不変参照のイテレータを、iter_mut メソッドは、可変参照のイテレータを返却します。

以下の例で見てみましょう。

fn main() {
    let mut v = vec![1, 2, 3];

    // iter メソッドで不変参照のイテレータを返却
    for x in v.iter() {
        println!("{}", x);

        // 不変参照なので、以下のように値を変更することはできない
        // *x += 1;
    }

    // iter_mut メソッドで可変参照のイテレータを返却
    for x in v.iter_mut() {
        *x += 1;
        println!("{}", x);
    }
}

【実行結果】
1
2
3
2
3
4

例えば、iter を使用すると要素への不変参照を順番に取り出すことができます。不変参照なので、値を変更しようとするとコンパイルエラーとなります。一方で、iter_mut を使用すると要素への可変参照を取得できるため、要素の値を書き換えることができます。

ポイント

多くのコレクションでは以下のような対応関係があります。

• v.iter() は (&v).into_iter() に対応
• v.iter_mut() は (&mut v).into_iter() に対応

つまり、iter や iter_mut は、参照に対する into_iter() をより分かりやすく使うためのメソッドと考えることができます。ただし、誤解しやすいポイントですが、iter や iter_mut は、Iterator トレイトや IntoIterator トレイトで定義されているメソッドではありません。

これらは、Rust の標準ライブラリにおいて、コレクションがイテレータを生成するための便利なメソッドとして提供しているものです。そのため、必ずしも上記対応が保証されているわけではありませんので注意してください。

Iterator トレイトの必須メソッドとされている next や IntoIterator トレイトの必須メソッドとされている into_iter とは位置づけが異なることを理解しておきましょう。

まとめ

Rust におけるイテレータ（Iterator）の基本を解説しました。

イテレータは、値の列を生成する値で、要素を順番に取り出すことができる仕組みで for 文などの繰り返し処理で利用されます。

イテレータの中心となるのが、Iterator トレイトと IntoIterator トレイトです。この記事では、それぞれの必須メソッドである next や into_iter メソッドの役割について説明しました。また、for 文との関係や、Rust のコレクションで提供される iter、iter_mut といったメソッドについても紹介しました。

イテレータは、Rust のデータ処理の中心的な仕組みです。基本の考え方をしっかりと理解しておきましょう。

あわせて読みたい

Rust プログラミング入門

Rust のクロージャの型とトレイト

Rust におけるクロージャ（Closure）とは、「その場で定義できる無名の関数のようなもの」のことです。クロージャの使い方の基本については「クロージャの基本と使い方を分かりやすく解説」を参考にしてください。

この記事では、基本からは一段深く、クロージャの「型」と「トレイト」について踏み込んで紹介します。

クロージャの型

まずは、クロージャーの本質について確認してみましょう。結論から述べるとクロージャは、コンパイラが生成する固有の型です。

記事冒頭で「その場で定義できる無名の関数のようなもの」と説明しましたが、実際には「関数」ではありません。ここではその違いを具体的なコードで確認します。

関数の型とクロージャの型は異なる

Rust のクロージャは、以下のように使用することができます。

fn main() {
    // クロージャで使用する外部変数
    let base = 1;

    // クロージャーを定義
    let add_one_closure = |x| x + base;
    println!("クロージャーを呼び出す: {}", add_one_closure(5));
}

【実行結果】
クロージャーを呼び出す: 6

この例では、base という外部変数をキャプチャしています。これにより add_one_closure は引数 x に与えられた値に base の値を加算する機能を提供します。

では、このクロージャが関数として扱えるかを試してみましょう。以下の call_function は関数を引数として受け取り呼び出すだけの関数です。比較のために add_one という通常の関数を用意しています。

// 関数を引数として受け取り、呼び出す関数
fn call_function(f: fn(i32) -> i32, x: i32) -> i32 {
    f(x)
}

// 1を加算する通常の関数
fn add_one(x: i32) -> i32 {
    x + 1
}

fn main() {
    // クロージャで使用する外部変数
    let base = 1;

    // クロージャーを定義
    let add_one_closure = |x| x + base;
    println!("クロージャーを呼び出す: {}", add_one_closure(5));

    // 通常の関数を呼び出す
    println!(
        "通常の関数を call_function 経由で呼び出す: {}",
        call_function(add_one, 5)
    );

    // クロージャーを call_function に渡す。（これはエラーとなる）
    // println!(
    //     "クロージャーを call_function 経由で呼び出す: {}",
    //     call_function(add_one_closure, 5)
    // );
}

例の call_function は、「fn(i32) -> i32」という型を受け取ります。この型は、関数ポインタ型と呼ばれ、「i32 型を受け取り i32 型の結果を返す」ことを意味しています。

通常関数の add_one も、クロージャである add_one_closure も「i32 型を受け取り i32 型の結果を返す」という形式に一致しています。しかし、例でコメントアウトしているクロージャー add_one_closure を call_function に渡している部分はコンパイルエラーとなります。

理由はシンプルで、クロージャーの型は「fn(i32) -> i32」ではないためです。この結果から分かりますが、クロージャは、コンパイラが生成する固有の型となっています。

トレイト境界でクロージャと関数を同様に扱う

上記で、通常関数とクロージャは型が異なることが分かりました。しかし、関数にクロージャを渡して実行したいケースは非常に多くあります。関数とクロージャーを同じように扱う方法はないのでしょうか？もちろんあります。ポイントとなるのが Fn トレイトです。

次の例のようにトレイト境界を用いた call_function を使用すれば、通常関数もクロージャも両方受け取ることができるようになります。Fn トレイトについては詳細は後述しますので、一旦ここでは、このようにすることで対応できると理解していただければと思います

// クロージャも引数として受け取ることができる関数
fn call_function_closure<F>(f: F, x: i32) -> i32
where
    F: Fn(i32) -> i32,
{
    f(x)
}

// 1を加算する通常の関数
fn add_one(x: i32) -> i32 {
    x + 1
}

fn main() {
    // クロージャで使用する外部変数
    let base = 1;

    // クロージャーを定義
    let add_one_closure = |x| x + base;
    println!("クロージャーを呼び出す: {}", add_one_closure(5));

    // 通常の関数を呼び出す
    println!(
        "通常の関数を call_function 経由で呼び出す: {}",
        call_function_closure(add_one, 5)
    );

    // クロージャーを call_function_closure に渡す
    println!(
        "クロージャーを call_function_closure 経由で呼び出す: {}",
        call_function_closure(add_one_closure, 5)
    );
}

このようにすることで「通常の関数」と「クロージャ」をどちらも同じように扱うことができます。これは、通常の関数もクロージャも、Fn トレイトを通じて扱うことができるためです。

実は、クロージャは、常に同じトレイトを実装するわけではありません。外部変数のキャプチャ方法（不変参照、可変参照、所有権移動）によって実装されるトレイトが変わります。以降では、クロージャのトレイトについて説明していきます。

クロージャのトレイト（Fn / FnMut / FnOnce）

Rust では、この違いを表現するために、以下の 3 つのトレイトが用意されています。

• Fn：不変参照
• FnMut：可変参照
• FnOnce：所有権の移動

これらは、クロージャが外部の変数をどのように扱うかによって使い分けられます。以降では、クロージャのトレイトの違いについて詳しく見ていきます。

クロージャの基本記事「クロージャの基本と使い方を分かりやすく解説」で紹介しているクロージャのキャプチャ方法は、この各トレイトに相当しています。基本記事で使用したコードを再掲しながら確認してみましょう。

Fn トレイト（不変参照）

Fn トレイトは、外部の変数を変更せずに利用するクロージャに対して実装されるトレイトです。つまり、キャプチャした変数を「読み取るだけ」の 場合に Fn が実装されます。

fn main() {
    // ===== 不変参照でのキャプチャ例
    let x = 10;
    // x は不変参照でキャプチャされる
    let f = |y| x + y;

    // クロージャの呼び出し
    println!("f(5) = {}", f(5));
    // xはまだ使用可能
    println!("x = {}", x);
}

例では、x をクロージャの中で参照しているだけで変更していません。そのため、このクロージャは Fn トレイトを実装します。Fn のクロージャは、状態を変更しないため何度でも安全に呼び出すことができます。

FnMut トレイト（可変参照）

FnMut トレイトは、キャプチャした変数を「変更する」クロージャに対して実装されるトレイトです。

fn main() {
    // ===== 可変参照でのキャプチャ例
    let mut count = 0;
    println!("count before: {}", count);
    // countは可変参照でキャプチャされる
    let mut g = || count += 1;

    // クロージャを呼び出すとcountが変更される
    g();
    // countは変更されている
    println!("count after: {}", count);
}

例では、クロージャの中で count を変更しています。そのため、このクロージャは FnMut トレイトを実装します。

FnMut のクロージャは、キャプチャした変数を変更する可能性があります。そのため、呼び出し時には、クロージャ自身が変更される可能性があるため、クロージャを変数に束縛するには「let mut g」のように mut をつける必要があります。

FnOnce トレイト（所有権の移動）

FnOnce トレイトは、「キャプチャした値の所有権を消費する」クロージャに対して実装されるトレイトです。

fn main() {
    // ===== move による所有権の移動でのキャプチャ例
    let s = String::from("Hello");
    // s は move で所有権がクロージャに移動される
    let h = move || println!("{s} World!");

    // 実行時に s は消費されて使用できなくなる
    h();
    // sはmoveで所有権が移動されているため以降は使用できない
    // println!("{s}"); // コンパイルエラー
}

例では、move を使用して s の所有権をクロージャに移動しています。このような場合、クロージャはキャプチャした値を消費する可能性があるため、1 回しか安全に呼び出すことができません。そのため、このようなクロージャは FnOnce トレイトを実装します。

let s = String::from("Hello");
let h = || drop(s);

Fn / FnMut / FnOnce の関係性

上記で紹介したトレイトは、次のような関係になっています。

Fn ⊂ FnMut ⊂ FnOnce

上記図は「Fn は FnMut のサブトレイト」「FnMut は FnOnce のサブトレイト」という意味を表しています。つまり、Fn を実装するクロージャは FnMut としても扱うことができ、FnMut を実装するクロージャは FnOnce としてもあつかえるという関係になっています。

記事の前半で Fn をトレイト境界に持つ関数の例を紹介しましたが、この call_function は、FnMut のクロージャを受け取ることができません。一方で、FnMut をトレイト境界に持つ関数は、Fn トレイトのクロージャを受け取ることが可能となります。

ここまでで紹介してきたように、Rust では、クロージャの振る舞いに応じて Fn / FnMut / FnOnce のトレイトが自動的に決定されます。このような仕組みとなっていることをしっかり理解していただければと思います。

まとめ

Rust におけるクロージャ（Closure）の型とトレイト（Fn / FnMut / FnOnce）について解説しました。

クロージャは、通常の関数とは異なり、コンパイラが生成する固有の型です。一方で、トレイト境界を使うことで通常の関数と同じように扱うことができます。

また、クロージャは、キャプチャする外部変数の扱い方に応じて、Fn / FnMut / FnOnce のいずれかのトレイトを実装します。これらの違いを理解しておくことで、クロージャを引数として受け取る関数や所有権が関わるコードをより正確に理解して実装ができるようになります。

あわせて読みたい

Rust プログラミング入門

クロージャ（Closure）とは

Rust におけるクロージャ（Closure）とは、「その場で定義できる無名の関数のようなもの」のことです。

通常の fn で定義する関数との大きな違いは、外部のスコープにある変数を利用できることです。この「外側の変数を取り込んで使う」ことを「キャプチャ（capture）」と呼びます。

共通的な変数をクロージャの中に取り込んでおくことで、他の可変な値と組み合わせながら、柔軟で再利用可能な処理を定義することができます。

この記事では、Rust におけるクロージャの基本的な使い方や考え方について紹介します。

クロージャの基本

クロージャの基本的な使い方

基本的なクロージャの使い方を紹介します。

|引数1, 引数2, ...| 式

クロージャの構文は非常にシンプルです。上記のように || 内に引数を列挙し、クロージャの返却値となる式をその後に記載します。引数なしのクロージャー (|| 式) でも問題ありません。

また、複数の文を書く場合は、以下のように {} のブロックを使用します。

|引数1, 引数2, ...| {
    文;
    ...;
    式
}

最後の式は、クロージャの戻り値になります。最後に ; (セミコロン) をつけると戻り値は () となります。

それでは、簡単な具体例で確認してみましょう。

単一式の例

fn main() {
    // ===== 単一の式のクロージャ例
    let add = |a, b| a + b;
    println!("add(2, 3) = {}", add(2, 3));
}

【実行結果】
add(2, 3) = 5

この例では、変数 a と b を受け取り a + b という単一の式を計算するクロージャを定義して add という変数名に束縛しています。a + b がクロージャの戻り値になります。

クロージャを使用する時には「add(2, 3)」のように使用します。もちろん、add(4, 5)、 …のように任意の引数での再利用が可能です。

単一の式の場合であれば、{} を使用しなくても上記のように簡潔に書くことができます。

引数なしの例

fn main() {
    // ===== 引数なしのクロージャ例
    let greet = || "Hello, Rust!";
    println!("greet() = {}", greet());
}

【実行結果】
greet() = Hello, Rust!

クロージャは、引数がなくても使用できます。引数がない場合、|| のように何も書かずに定義します。この例では、"Hello, Rust!" という文字列リテラルがそのまま戻り値になります。

ブロック形式の例

fn main() {
    // ===== ブロック形式のクロージャ例
    let multiply = |a, b| {
        println!("calculating {a} * {b} ...");
        // 最後の式がクロージャの戻り値になる
        a * b
    };
    println!("multiply(3, 5) = {}", multiply(3, 5));
}

【実行結果】
calculating 3 * 5 ...
multiply(3, 5) = 15

複数の文を実行したい場合には、{} ブロックを使用します。例では、計算前に println! でメッセージを表示し、その後に a * b を評価しています。

Rust では、ブロックの最後の式が戻り値になるというルールがあります。そのため、a * b に ; (セミコロン) をつけないことが重要です。; を付けた場合の返却値は () となります。

外側の変数をキャプチャする例

ここまでの例は、関数とほぼ同じような使い方でした。しかし、クロージャの本質は「外側の変数を利用できること」です。以下の例で、外側の変数をキャプチャする例を見てみましょう。

fn main() {
    // ===== 外側の変数をキャプチャするクロージャ例
    let base = 10;

    let add_to_base = |x| base + x;
    println!("add_to_base(5) = {}", add_to_base(5));
}

【実行結果】
add_to_base(5) = 15

この例では、base という変数をクロージャの外側で定義しています。add_to_base は、引数 x だけを受け取っていますが、計算で base も利用しています。このように add_to_base を用意しておくと、様々な x に対して base を足した結果を再利用して計算できます。

あたかも add_to_base が base 変数を捕捉した状態で使いまわせるため「キャプチャする」という表現が使われています。

このように、外側のスコープにある変数を取り込んで使用することができるのがクロージャの本質です。ここまでの例を振り返るとクロージャーは次のような特徴があることが分かります。

• 関数のように振る舞う
• fn を使わなくても、その場で定義することができる
• 外側の変数を利用することができる（キャプチャできる）

つまり、単なる無名関数というだけではなく、定義された環境設定ごと関数を扱える仕組みであることがクロージャの本当の価値です。

クロージャの型注釈と型推論

引数の型注釈

クロージャーは型推論がされるため、基本的には型注釈を入れる必要はありません。以下のように型注釈を入れたクロージャも使うことができます。

fn main() {
    // ===== 単一の式のクロージャ例 (型注釈あり)
    let subtract = |a: i32, b: i32| a - b;
    println!("subtract(5, 2) = {}", subtract(5, 2));
}

【実行結果】
subtract(5, 2) = 3

例のように a: i32, b: i32 といった形で型注釈を書くことができます。なお、戻り値については、let subtract = |a: i32, b: i32| -> i32 { a - b }; のように書くことも可能ですが、引数の型が決まれば、戻り値の型は式から自動推論できるため、通常は記載しません。

クロージャの型推論

クロージャは型推論をすると記載しましたが、どこで型が確定するかというと「最初にクロージャが使用されたときの型」で確定となります。そのため、先ほどの例で一度 add(2, 3) と使用した後に以下のように、floating-point で使用しようとするとコンパイルエラーとなります。

println!("add(1.0, 2.0) = {}", add(1.0, 2.0));

【エラー例】
error[E0308]: arguments to this function are incorrect
  --> rust-basic\closure-basic\examples\closure_basic.rs:28:36
   |
28 |     println!("add(1.0, 2.0) = {}", add(1.0, 2.0));
   |                                    ^^^ ---  --- expected integer, found floating-point number
   |                                        |
   |                                        expected integer, found floating-point number

クロージャのキャプチャの方法

ここでは、クロージャのキャプチャについて少し詳しく見てみましょう。キャプチャとは、クロージャが外側のスコープにある変数を取り込んで利用することでした。

Rust のクロージャでは、外側の変数をどのように扱うかに応じて、キャプチャ方法をコンパイラが自動で選択します。主なキャプチャの方法には以下の 3 種類です。

1. 不変参照でのキャプチャ
2. 可変参照でのキャプチャ
3. move による所有権の移動でのキャプチャ

不変参照でのキャプチャ

外側の変数を「読み取るだけ」であればクロージャは、変数を不変参照でキャプチャします。この場合、外側の変数は所有権を失わないため、クロージャ呼び出し後も引き続き利用できます。

fn main() {
    // ===== 不変参照でのキャプチャ例
    let x = 10;
    // x は不変参照でキャプチャされる
    let f = |y| x + y;

    // クロージャの呼び出し
    println!("f(5) = {}", f(5));
    // xはまだ使用可能
    println!("x = {}", x);
}

【実行結果】
f(5) = 15
x = 10

例のクロージャでは、x を不変参照しているだけで変更していません。そのため、クロージャを呼び出した後でも x は使用できます。

可変参照でのキャプチャ

クロージャの中で外側の変数を変更する場合、クロージャはその変数を可変参照でキャプチャします。以下は、count 変数をクロージャ内部でカウントアップしているような例です。

fn main() {
    // ===== 可変参照でのキャプチャ例
    let mut count = 0;
    println!("count before: {}", count);
    // countは可変参照でキャプチャされる
    let mut g = || count += 1;

    // クロージャを呼び出すとcountが変更される
    g();
    // countは変更されている
    println!("count after: {}", count);
}

【実行結果】
count before: 0
count after: 1

可変参照でキャプチャする場合は、外側の変数は let mut により、変更可能（ミュータブル）な変数として定義する必要があります。また、クロージャを変数（上記例では g）に束縛する場合は、g についても let mut で変更可能な形で定義する必要があります。

move による所有権の移動でのキャプチャ

これまでの例では、外側の変数は参照としてキャプチャされていました。以下のようにクロージャの定義の前に move をつけることで、外側の変数は所有権ごとクロージャに移動します。

fn main() {
    // ===== move による所有権の移動でのキャプチャ例
    let s = String::from("Hello");
    // s は move で所有権がクロージャに移動される
    let h = move || println!("{s} World!");

    // 実行時に s は消費されて使用できなくなる
    h();
    // sはmoveで所有権が移動されているため以降は使用できない
    // println!("{s}"); // コンパイルエラー
}

【実行結果】
Hello World!

【move 後のコメントアウト部分を外した場合のコンパイルエラー 一部抜粋】
error[E0382]: borrow of moved value: `s`
  --> rust-basic\closure-basic\examples\closure_capture.rs:31:16
   |
24 |     let s = String::from("Hello");
   |         - move occurs because `s` has type `String`, which does not implement the `Copy` trait
25 |     // s は move で所有権がクロージャに移動される
26 |     let h = move || println!("{s} World!");
   |             -------            - variable moved due to use in closure
   |             |
   |             value moved into closure here
...
31 |     println!("{s}"); // コンパイルエラー
   |                ^ value borrowed here after move

例のように、move を付けた時点で変数 s の所有権はクロージャに移動します。そのため、以降外側のスコープでは s は使用できません。使用しようとするとコンパイルエラーとなります。（例でコメントアウトしている部分を外して試してみてください。）

move は、外側の値の所有権をクロージャ側に移して、クロージャがその値を保持できるようにしたい場合に使います。（例：スレッドに渡す、関数の外へ変数を持ち出す など）

クロージャの型とトレイト

クロージャの基本的な使い方を紹介してきました。記事の冒頭で、クロージャは「その場で定義できる無名の関数のようなもの」という少し曖昧な表現をしました。これは、クロージャの型やトレイトをより理解すると、関数とは異なるということが分かるためです。

少し詳細な内容になるため、クロージャの型とトレイトについては「クロージャの型とトレイト（Fn / FnMut / FnOnce）」でまとめていますので参考にしてください。

まとめ

Rust におけるクロージャ（Closure）の基本を解説しました。

クロージャは 「 |引数1, 引数2, …| 式」の形式で、その場で定義できる無名の関数のような仕組みです。ブロック形式の場合は、最後の式が戻り値になります。また、型注釈は必要に応じて記載できますが、多くの場合は型推論に任せることができます。

さらに、クロージャの本質である「キャプチャ」について、不変参照・可変参照・move による所有権移動の 3 パターンを紹介しました。特に move を使うと、外側の値の所有権がクロージャに移動し、以降は外側のスコープでは利用できなくなる点が重要です。

クロージャは、その場で処理を定義できる非常に便利な機能で、Rust ではさまざまな場面で利用されます。まずは、基本的な書き方とキャプチャの考え方をしっかり押さえておきましょう。

あわせて読みたい

Rust プログラミング入門

anyhow クレートの概要

anyhow とは

Rust のエラー処理では、Result<T, E> 型を使用して「成功（Ok）」か「失敗（Err）」かを表現するのが基本となります。この時、E は、エラーを表す型の型パラメータです。

エラーの型は、各種外部のクレートなど様々な機能でも個別に用意されており、扱うエラー型は多岐に渡るため、すべてのエラー型を意識して厳密にエラーに対する処理を実装していくことは、多くの負担がかかってしまいます。

anyhow は、こうした「複数のエラーをまとめて扱いたい」場面で非常に便利なクレートです。anyhow::Error という汎用的なエラー型を用いることで、アプリケーション側のエラー処理を簡潔に表現して扱うことができます。

anyhow の特徴（複数のエラーをまとめて扱う）

anyhow を使用する最大のメリットは、エラー型を 1 つに統一できることです。

通常、Rust の ? 演算子は、エラーが一致 または 変換できる場合（From トレイトによる変換が可能な場合）にしか使用することができません。そのため、複数のエラー型が混ざる処理では、エラー変換を自前で実装したり、独自エラー型にまとめる必要性が出てきます。

anyhow を使用すると以下のような書き方ができるようになります。

なお、anyhow はエラーを握りつぶすためのものではありません。後ほど説明するようにエラーに追加の文脈情報（コンテキスト）を付与することで、原因調査をしやすくするための仕組みも提供します。

use anyhow::Result;

fn run() -> Result<()> {
    Ok()
}

anyhow の位置づけ（Result<T, E> や thiserror との関係性）

Rust のエラー処理では、基本的に Result<T, E> 型を利用してエラーを処理します。この E は、エラーのためのジェネリックな型パラメータで、任意の型を使用することができます。

anyhow を使用するということは、E に anyhow::Error を採用する設計を意味します。とにかくエラー型を統一して扱いたい場合には、anyhow は非常に向いています。

一方で、thiserror という独自エラー型を設計するクレートも非常によく使用されます。これは、自身で MyError 型を定義し、Result<T, MyError> のようにエラーの種類を明確に表現したい場合に向いています。クレートの位置づけを整理すると以下の通りです。

一般的には、ライブラリ側では thiserror、アプリケーション側では anyhow が使われることが多いです。ライブラリが用意している独自エラー型を、アプリケーション側が受け取った際には anyhow::Error に変換・統一して扱うという構成です。もちろん、独自エラーの情報を消してしまうわけではなく、元の独自エラーの情報を保持しつつ、anyhow::Error に統一します。

anyhow の基本

anyhow の導入方法

anyhow は、他クレートと同様に cargo add または Cargo.toml に追記することで利用できるようになります。

【cargo add で追加する場合】

cargo add anyhow

【Cargo.toml に追記する場合】

[dependencies]
anyhow = "1.0.101"

例での記載バージョンは、記事執筆・更新時点での最新バージョンで記載しているため、導入時には crates.io の anyhow のページを確認して指定してください。

? で複数のエラーをまとめて扱う基本的な使い方

anyhow を利用する最も大きなメリットの 1 つは、ライブラリなどの複数のエラーをまとめて扱うことができることです。代表的な使い方として ? 演算子により、From トレイトによる変換を通じて、外部エラーを anyhow::Error に変換して扱う方法を紹介します。

以下は、input_file.txt を読み込む際に、ファイルが存在しない場面と思ってください。

use anyhow::Result;
use std::fs;

fn main() -> Result<()> {
    let path = "input_file.txt";

    // エラーを anyhow::Error に変換して返す
    let content = fs::read_to_string(path)?;

    println!("{content}");

    Ok(())
}

【実行結果】
Error: 指定されたファイルが見つかりません。 (os error 2)
error: process didn't exit successfully: `D:\RustProject\rust-tech-sample-source\target\debug\examples\anyhow_basic.exe` (exit code: 1)  

例では、fs::read_to_string によって std::io::Error が発生しています。通常であれば、このエラー型にあわせて処理を実装する必要があります。

しかし、main 関数の戻り値は anyhow::Result<()>（= Result<(), anyhow::Error>）としているため、自動的に anyhow::Error に変換され、? 演算子により上位へ返却されます。このように、エラー型を意識せずに ? を使えることが、anyhow を使用する大きなメリットです。

context / with_context で文脈情報（コンテキスト）を追加する

? を使用したエラー伝播は非常に簡潔で便利ですが、そのままではどの処理で失敗したのかが分かりづらくなってしまう場合があります。このような場合に便利なのが、Context トレイトが提供する context および with_context です。

これらを使うことで、エラー発生時に追加の文脈情報（コンテキスト）を付与することができ、原因調査をしやすくなります。

context で固定のメッセージを追加する

context を使用することで以下のように固定のメッセージを追加することができます。

use anyhow::{Context, Result};
use std::fs;

fn main() -> Result<()> {
    let path = "input_file.txt";

    // コンテキスト情報を追加してエラーを返す
    let content =
        fs::read_to_string(path).context("[main] テキストファイルの読み込みに失敗しました。")?;

    println!("{content}");

    Ok(())
}

【実行結果】
Error: [main] テキストファイルの読み込みに失敗しました。

Caused by:
    指定されたファイルが見つかりません。 (os error 2)
error: process didn't exit successfully: `D:\RustProject\rust-tech-sample-source\target\debug\examples\anyhow_context.exe` (exit code: 1)

例のように context を使用すると、元のエラーに対して固定のメッセージを追加することができます。実行結果を見ると、最初に追加したメッセージが表示されており、その下の「Caused by:」以下に元のエラーが保持されていることが分かります。

このように、anyhow は元のエラー情報を失うことなく、追加の文脈情報（コンテキスト）を積み重ねて保持することができます。

with_context で動的にメッセージを生成して追加する

context は固定メッセージを追加する方法でしたが、with_context を使用すると、以下のように動的にメッセージを生成して追加することができます。

use anyhow::{Context, Result};
use std::fs;

fn main() -> Result<()> {
    let path = "input_file.txt";

    // クロージャーを使って動的にコンテキスト情報を追加してエラーを返す
    let content = fs::read_to_string(path)
        .with_context(|| format!("[main] テキストファイルの読み込みに失敗しました。path={path}"))?;

    println!("{content}");

    Ok(())
}

【実行結果】
Error: [main] テキストファイルの読み込みに失敗しました。path=input_file.txt

Caused by:
    指定されたファイルが見つかりません。 (os error 2)
error: process didn't exit successfully: `D:\RustProject\rust-tech-sample-source\target\debug\examples\anyhow_with_context.exe` (exit code: 1)

with_context は、クロージャーを受け取り、エラーが発生した場合にのみ処理を実行します。そのため、例のように format! マクロを使って変数を埋め込んだ動的なメッセージを生成したい場合などに向いています。

context と with_context は似ていますが、使い分けは以下のように整理できます。

• context：固定のメッセージを追加したい場合
• with_context：エラー発生時に処理を行い、動的なメッセージを生成したい場合

anyhow! / bail! マクロで自分でエラーを作る

これまでは、下位の処理が返却するエラーを ? 演算子で伝播する例を見てきました。一方で、アプリケーション側の条件チェックなどにより自分でエラーを生成したい場合もよくあります。

このような場合には、anyhow! マクロや bail! マクロの使用が便利です。

anyhow! マクロで anyhow::Error を生成する

anyhow! マクロを使用することで以下のように anyhow::Error を生成することができます。

use anyhow::{Result, anyhow};

fn main() -> Result<()> {
    let path = "";

    if path.is_empty() {
        // エラーを生成する
        let err = anyhow!("[main] パスが空です。");

        // エラーを返却する
        return Err(err);
    }

    Ok(())
}

【実行結果】
Error: [main] パスが空です。
error: process didn't exit successfully: `D:\RustProject\rust-tech-sample-source\target\debug\examples\anyhow_anyhow_macro.exe` (exit code: 1)

例のように、anyhow! マクロにより anyhow::Error 型の値を生成することができ、変数に代入して扱うことができます。これにより、ログ出力などの追加の処理をしてから「return Err(err)」のように返却するといったことが可能になります。

bail! マクロで anyhow::Error を生成し、即時返却する

anyhow! マクロでは一度変数に代入して扱いましたが、場合によってはエラー発生時に即時に return すればいい場合があります。このような場合には、bail! マクロを使用することでコードがより簡潔に書くことができます。

use anyhow::{Result, bail};

fn main() -> Result<()> {
    let path = "";

    if path.is_empty() {
        // エラーを生成して、即時に返却する
        bail!("[main] パスが空です。");
    }

    Ok(())
}

【実行結果】
Error: [main] パスが空です。
error: process didn't exit successfully: `D:\RustProject\rust-tech-sample-source\target\debug\examples\anyhow_bail_macro.exe` (exit code: 1)

例のように bail! マクロは anyhow::Error を生成し、その場で Err を返却しています。そのため、return の記載も必要なくなり非常に簡潔にコードを各ことができます。

まとめ

Rust で anyhow を用いて複数のエラーをまとめて扱う方法について解説しました。

anyhow を使用することでアプリケーション側ではエラー型を 1 つに統一し、? 演算子によるエラー伝播を簡潔に記述できます。

また、context / with_context を使用することでエラーに追加の文脈情報（コンテキスト）を追加することで原因調査もしやすくなります。さらに、anyhow! や bail! といったマクロを使うことで、自分でエラー生成をして扱うことも簡単です。

anyhow は、エラー型を厳密にするためのクレートではなく、アプリケーション側でのエラー運用をしやすくしてくれるクレートです。ライブラリ側では、thiserror による独自エラー型を設計し、アプリケーション側では anyhow を使って統一的にエラーを扱うという使い分けをすると非常に効率的に開発を進められると思います。

ぜひ、anyhow の使い方の基本をしっかりと覚えてもらえたらと思います。

あわせて読みたい

Rust プログラミング入門

thiserror クレートの概要

thiserror とは

Rust で独自のエラー型を定義する場合、std::error::Error トレイトや std::fmt::Display トレイトの実装が必要となり、エラーの種別が増えるほどボイラープレートコードという定型的なコードが増えていってしまいます。

thiserror は、独自のエラー型の実装を簡潔に書けるようにする便利なクレートです。

この記事では、thiserror を使った独自エラー型の定義方法の基本について紹介します。

thiserror の特徴（derive でエラー型の実装を簡素化する）

thiserror を使用する上で最低限理解したい内容としては以下です。

以降では、上記について例を用いて紹介していきます。

thiserror の位置づけ（Result<T, E> や anyhow との関係性）

Rust では、Result<T, E> という結果型を用いた明示的なエラー処理が基本です。T や E は、型パラメータであり、任意の型とすることができます。thiserror は、この E に使う「独自のエラー型」を定義しやすくするためのクレートです。

また、Rust のエラー処理では、anyhow というクレートもよく聞きます。各種クレートなどの様々な機能を使用する場合、それらの機能が独自に設計しているエラー型を扱う場合があります。この時、全てのエラー型を意識して実装するのは大変です。anyhow は、様々なエラー型をまとめて取り扱うことができます。

thiserror と anyhow の位置づけは以下のように理解しておいてもらうといいかと思います。

• thiserror：独自のエラー型を簡単に定義する。
• anyhow：様々なエラー型をまとめて取り扱うことができる。

一般的には、ライブラリ側では thiserror、アプリケーション側では anyhow が使われることが多いです。

thiserror の基本

thiserror の導入方法

thiserror は他クレート同様に cargo add または Cargo.toml に追記することで利用できるようになります。

【cargo add で追加する場合】

cargo add thiserror

【Cargo.toml に追記する場合】

[dependencies]
thiserror = "2.0.18"

例での記載バージョンは、記事執筆時点での最新バージョンで記載しているため、導入時には crates.io の thiserror のページを確認して指定してください。

独自エラー型の定義方法（基本）

thiserror の基本的な使い方を以下の例で見ていきましょう。以下の例では、独自の MyError というエラー型を作成しています。

use thiserror::Error;

// 独自エラー型の定義
#[derive(Error, Debug)]
enum MyError {
    #[error("不正な入力です。")]
    InvalidInput,

    #[error("権限がありません。")]
    PermissionDenied,
}

fn main() {
    // 不正な入力エラー
    let err = MyError::InvalidInput;
    println!("{err}");
    println!("{err:?}");

    // 権限拒否エラー
    let err = MyError::PermissionDenied;
    println!("{err}");
    println!("{err:?}");
}

【実行結果】
不正な入力です。
InvalidInput
権限がありません。
PermissionDenied

上記例の独自エラー型は列挙型（enum）で定義しており、不正な入力を意味する InvalidInput と権限がないことを意味する PermissionDenied というバリアントを持っている型です。

thiserror を使用するには、まず「use thiserror::Error」をスコープに取り込みます。独自のエラー型に #[derive(Error, Debug)] をつけることで独自の型に各種トレイトを自動実装しています。

#[derive(Error)] により、std::error::Error トレイトが実装され、各バリアントに記載された #[error("...")] のエラーメッセージに基づいて std::fmt::Display トレイトの自動実装も行われています。また、#[derive(Debug)] では、std::fmt::Debug トレイトの自動実装が行われています。

main 関数では、この独自エラー型を生成して表示してみていますが、Display トレイトが実装されることで、独自に作ったエラー表示ができていることが分かるかと思います。なお、Debug トレイトの自動実装では、バリアント名や保持している値が表示されるようになります。

引数によりエラーに情報を持たせる

thiserror を使って構築するエラー型では、エラーの原因を調査しやすくするために、エラーに関連するような情報を引数として渡して受け取ることができます。

use thiserror::Error;

// 独自エラー型の定義 引数付き
#[derive(Error, Debug)]
enum MyError {
    #[error("不正な入力です: {0}")]
    InvalidInput(String),

    #[error("権限がありません: ID {user_id}")]
    PermissionDenied { user_id: u32 },
}

fn main() {
    // 不正な入力エラー
    let err = MyError::InvalidInput("空の文字列".to_string());
    println!("{err}");
    println!("{err:?}");

    // 権限拒否エラー
    let err = MyError::PermissionDenied { user_id: 42 };
    println!("{err}");
    println!("{err:?}");
}

【実行結果】
不正な入力です: 空の文字列
InvalidInput("空の文字列")
権限がありません: ID 42
PermissionDenied { user_id: 42 }

例では、#[error("...")] 内で指定する文字列に、引数を埋め込むように指定することができます。引数の指定については、値を直接持たせる形式（tuple variant）とフィールド名付きの形式（struct variant）の大きく 2 種類があります。

値を直接持たせる形式（tuple variant）の場合には、エラー文字列の埋め込む位置に {0}, {1}, … のように記載し、引数として渡された順に値が埋め込まれます。複数の引数を渡す場合には「,」で列挙して渡します。

フィールド名付きの形式（struct variant）の場合には、エラー文字列の埋め込む位置に {user_id} のようにフィールド名を記載します。引数を渡す際には { user_id: 42 } のようにフィールドと値を設定して渡します。

#[from] によるエラー変換

独自のエラー型は、ある関数やメソッドの返却値として使用します。当該関数やメソッドで下位のモジュールを使用する場合、下位からもエラーが返却されることがあります。この場合、エラーをその場で処理せずに上位へ伝播する際に Rust では「?」をよく使用します。

この時に、下位のエラーを独自のエラー型に変換して伝播したい場合は、#[from] により独自エラー型へ型変換すると便利です。具体的には「impl From<std::io::Error> for MyError」が自動生成されます。

use std::fs;
use thiserror::Error;

#[derive(Error, Debug)]
enum MyError {
    // std::io::Error から自動的に変換されるエラー
    #[error("My I/Oエラーが発生: {0}")]
    Io(#[from] std::io::Error),
}

// ファイルを読み込む関数
fn my_read_file(path: &str) -> Result<String, MyError> {
    // fs::read_to_string は std::io::Error を返却するが、
    // #[from] により MyError に自動変換される
    let content = fs::read_to_string(path)?;
    Ok(content)
}

fn main() {
    match my_read_file("non_existent_file.txt") {
        Ok(content) => println!("ファイル内容: {content}"),
        Err(e) => {
            println!("エラー : {e}");
            println!("デバッグ情報: {e:?}");
        }
    }
}

【実行結果】
エラー : My I/Oエラーが発生: 指定されたファイルが見つかりません。 (os error 2)
デバッグ情報: Io(Os { code: 2, kind: NotFound, message: "指定されたファイルが見つかりません。" })

例では、my_read_file という関数でファイルを読み込もうとしていますが、ファイルが開けない場合などでは、std::io::Error が返却されてきます。

このエラーを独自エラー型に変換する場合は、「Io(#[from] std::io::Error)」の部分のように記載します。これは、Io バリアントに std::io::Error を詰めていることを表していて、#[error("...")] 内の {0} の部分には、std::io::Error のエラー表示が埋め込まれます。

このようにして、下位エラーを MyError に変換し、Result<T, MyError> の Err(...) として返却できるようになります。

#[error(transparent)] により透過的にエラーを扱う

上記の #[from] の例では、下位のモジュールのエラーを独自エラー型に変換しました。場合によっては、下位のモジュールのエラー内容をそのまま利用するだけで十分な場合があります。そのような場合は、以下のように「#[error(transparent)]」を使用するのが便利です。

use std::fs;
use thiserror::Error;

#[derive(Error, Debug)]
enum MyError {
    // 下位のエラーをそのまま伝搬させる
    #[error(transparent)]
    Io(#[from] std::io::Error),
}

// ファイルを読み込む関数
fn my_read_file(path: &str) -> Result<String, MyError> {
    let content = fs::read_to_string(path)?;
    Ok(content)
}

fn main() {
    match my_read_file("non_existent_file.txt") {
        Ok(content) => println!("ファイル内容: {content}"),
        Err(e) => {
            println!("エラー : {e}");
            println!("デバッグ情報: {e:?}");
        }
    }
}

【実行結果】
エラー : 指定されたファイルが見つかりません。 (os error 2)
デバッグ情報: Io(Os { code: 2, kind: NotFound, message: "指定されたファイルが見つかりません。" })

transparent とは「透明」という意味で、独自のエラーなのに下位のエラーが透過的にみえるというイメージを持ってもらうと分かりやすいかと思います。薄いラッパーのエラー型を作りたい場合には、非常によく使われる方法です。

まとめ

この記事では、Rust で thiserror を用いて独自のエラー型を実装する方法について、初心者向けに解説しました。

thiserror を使用することで独自エラー型を実装する際に発生しがちなボイラープレートコードを削減しつつ、Result<T, E> の E に適したエラー型を自然な形で設計できます。

thiserror の入門として最低限押さえておきたいポイントは以下の通りです。

また、エラー処理関連でよく紹介される anyhow については、一般的に以下のような使い分けがされます。

• ライブラリ／モジュール側：thiserror による独自エラー型を定義
• アプリケーション側：anyhow による複数エラーの統一的な取り扱い

ぜひ、thiserror をうまく活用して、扱いやすい独自エラー型を実装してみてください。

あわせて読みたい

Rust プログラミング入門

Rust のモジュールの可視性

Rust では、コードを整理して安全性を高めるために「モジュール」と「可視性（visibility）」という仕組みが用意されています。この仕組みの中でも「pub」は、モジュール間やクレート間での参照をうまく制御するための重要なキーワードです。

Rust は、安全性を高めるため「モジュール外から参照できる要素はデフォルトで非公開」となっているという特徴があります。そのため、外部に公開したいものには pub をつけて開発者が明示的に公開範囲を示す必要があります。

この記事では、Rust のモジュール構造を説明しながら、pub を中心とした可視性の仕組みを初心者にも分かりやすく紹介します。

Rust のモジュールとは

Rust では、コードを階層的に分割し、相互の機能を隠ぺい、公開するための強力なモジュールシステムがあります。モジュールは、関数、構造体、定数などを論理的にまとめることができ、mod キーワードを使って以下のように定義します。

// ファイル内でのモジュール定義例
mod sample_mod {
    // 公開関数
    pub fn hello() {
        println!("[sample_mod] 公開関数");
    }
}

fn main() {
    println!("===== ファイル内でのモジュール定義例 =====");
    sample_mod::hello();
}

この sample_mod モジュールは、main.rs のファイル内で定義されているモジュールであるとします。例では、sample_mod に hello() という関数が定義されていることを意味します。

pub による公開

Rust の大きな特徴として「モジュール外から参照できる要素はデフォルトで非公開」となっています。そのため、mod で定義したモジュール内の要素をスコープ外に公開したい場合には、pub キーワードをつけて公開（public）であることを明示します。

上記の例で「pub fn hello() { ... }」は、mod の {} で囲われたスコープの外に hello() 関数を公開していることを意味します。モジュール sample_mod は、名前空間として機能するため main.rs 内の関数（main 関数など）から、hello() 関数を使用するには、sample_mod::hello() のように「::」を使用して呼び出します。

デフォルトは非公開

Rust の大きな特徴として「すべての要素はデフォルトで private（非公開）」となっています。そのため、以下のように mod のスコープ外から内部で pub をつけずに定義した関数へアクセスしようとするとコンパイルエラーとなります。

// ファイル内でのモジュール定義例
mod sample_mod {
    // 公開関数
    pub fn hello() {
        println!("[sample_mod] 公開関数");
        private_hello();
    }

    // 非公開関数
    fn private_hello() {
        println!("[sample_mod] 非公開関数");
    }
}

fn main() {
    println!("===== ファイル内でのモジュール定義例 =====");
    sample_mod::hello();
    // 以下の非公開関数の呼び出しはエラーになる
    // sample_mod::private_hello();
}

例では、private_hello は、非公開関数であり、sample_mod モジュールの中でしか使用できません。そのため、スコープ外の main 関数から呼び出すとコンパイルエラーとなります。

一方で、hello 関数は、モジュール内の関数なので、この関数からは private_hello 関数へアクセスすることが可能です。このようにすることで、モジュールの外部に公開する関数を制御することが可能です。

モジュールの分割と管理方法

Rust では、モジュール定義を mod 宣言により行いますが、その実体をファイルやディレクトリに分割することができます。Rust でよく使われるモジュール分割方法には次のようなものがあります。

以降では、基本的な方法から順に説明していきます。

ファイル単位でモジュールを分割する方法

まずは、基本となるファイル単位でモジュールを分割する方法を説明します。以下のように main.rs とは別に module1.rs を用意した例で紹介します。

src/
├── main.rs      // エントリポイント
└── module1.rs   // module1 モジュール

以下のようなプログラムを用いて詳細を説明します。

[main.rs]

// モジュール読み込み
mod module1; // ファイルで分割

fn main() {
    println!("\n===== ファイルで分割する例 (module1) =====");
    module1::hello();
    // 以下の非公開関数の呼び出しはエラーになる
    // module1::private_hello();
    module1::submod::hello();
    module1::submod::nested::nested_hello();
}

[module1.rs]

// 公開関数
pub fn hello() {
    println!("[module1] 公開関数");
    private_hello();
    private_mod::hello();
}

// 非公開関数
fn private_hello() {
    println!("[module1] 非公開関数");
}

// 公開サブモジュール
pub mod submod {
    // サブモジュール内の公開関数
    pub fn hello() {
        println!("[module1::submod] サブモジュール内の公開関数");
        private_hello();
    }

    // サブモジュール内の非公開関数
    fn private_hello() {
        println!("[module1::submod] サブモジュール内の非公開関数");
    }

    // ネストされた公開サブモジュール
    pub mod nested {
        pub fn nested_hello() {
            println!("[module1::submod::nested] ネストされたサブモジュール内の公開関数");
        }
    }
}

// 非公開のサブモジュール
mod private_mod {
    pub fn hello() {
        println!("[module1::private_mod] 非公開のサブモジュール");
    }
}

main.rs で module1 を使用するには、ファイルの先頭で次のように宣言します。

mod module1;

この宣言により、module1.rs は module1 モジュールとして読み込まれて、module1::関数名 のように公開要素を利用できるようになります。

module1.rs 内では、複数の関数とサブモジュールを定義しています。hello 関数は、pub をつけて定義しているため、main.rs のような外部モジュールから呼び出すことができます。一方、private_hello 関数は pub をつけていないため、module1 の内部からのみ利用可能です。

また、モジュール内ではさらにサブモジュールを定義することができます。submod は、module1 の公開サブモジュールであり、外部からもアクセス可能です。さらに、その中に nested のようなネストしたサブモジュールを定義することもできます。

注意点として、サブモジュールも「pub mod」としない限り外部には公開されません。private_mod は、pub が付いていないため、module1 の内部からしか利用できないモジュールです。

このように、意味のある単位でモジュールを分割し、可視性を適切に制御することで、コードの構造を整理し、安全で見通しの良いプログラムを作成することができます。

ディレクトリでサブモジュールを管理する方法

プロジェクトが大きくなってきた際に、1 つのファイルにすべてのサブモジュールを定義すると構造が分かりにくくなります。そのような場合には、ディレクトリを使ってサブモジュールを分割すると構造が明確になり、保守性も向上します。

以下のような構成を考えます。

src/
├── main.rs      // エントリポイント
├── module2.rs   // module2 モジュール
└── module2/
    ├── submod_1.rs  // サブモジュール1
    └── submod_2.rs  // サブモジュール2

[main.rs]

// モジュール読み込み
mod module2; // ディレクトリでサブモジュールを管理する

fn main() {
    println!("\n===== ディレクトリでサブモジュールを管理する例 (module2) =====");
    module2::submod_1::hello();
    module2::submod_2::hello();
}

[module2.rs]

pub mod submod_1;
pub mod submod_2;

[submod_1.rs]

// 公開関数
pub fn hello() {
    println!("[module2::submod_1] 公開関数");
    private_hello();
}

// 非公開関数
fn private_hello() {
    println!("[module2::submod_1] 非公開関数");
}

[submod_2.rs]

// 公開関数
pub fn hello() {
    println!("[module2::submod_2] 公開関数");
    private_hello();
}

fn private_hello() {
    println!("[module2::submod_2] 非公開関数");
}

この構成では、module2.rs が module2 モジュールのエントリーポイントになります。module2 ディレクトリ配下に配置したファイルについては、module2.rs 内で mod 宣言することでサブモジュールとして読み込まれます。

なお、ディレクトリにファイルを配置しただけでは、自動的にモジュールにはなりません。親モジュール側（この例では、module2.rs）で mod 宣言する必要がある点に注意してください。

mod.rs を使用する従来の方法

以前の Rust では、ディレクトリをモジュールとして扱う場合、mod.rs を配置する方法が一般的でした。現在でも使用可能ですが、新規プロジェクトでは前述の「ファイル + ディレクトリ」を組み合わせた方法が使われることが多くなっています。

mod.rs は以下のようにモジュール名のディレクトリ配下に配置します。

src/
├── main.rs      // エントリポイント
└── module3/
    ├── mod.rs       // module3 モジュール
    ├── submod_1.rs  // サブモジュール1
    └── submod_2.rs  // サブモジュール2

[main.rs]

// モジュール読み込み
mod module3; // mod.rs を使用する従来の方法

fn main() {
    println!("\n===== mod.rs を使用する従来の方法例 (module3) =====");
    module3::submod_1::hello();
    module3::submod_2::hello();
}

[mod.rs]

pub mod submod_1;
pub mod submod_2;

submod_1.rs と submod_2.rs は先ほどの例と同様なので省略します。

use によるモジュールのスコープへの取り込み

これまでの例では、module::submodule::function のようにフルパスでモジュールの構成要素を呼び出していました。use を使うことで、指定した要素をスコープに取り込み、より簡潔に記述できます。

[main.rs]

// モジュール読み込み
mod module1; // ファイルで分割
mod module2; // ディレクトリでサブモジュールを管理する

// use 宣言でモジュールをスコープに取り込む
use module1::submod::hello;
use module2::submod_1::hello as hello_module2_submod_1;

fn main() {
    println!("\n===== use 宣言でスコープに取り込む例 =====");
    hello();
    hello_module2_submod_1();
}

同名の要素をスコープに取り込む場合には、as を使って別名をつける必要があります。

なお、use は名前解決を簡単にするための仕組みであり、可視性に直接かかわるものではありません。モジュールを使用するためには、mod でモジュールを取り込む必要があることに注意してください。

その他の pub の指定方法

これまでに紹介したように、基本的には pub を使った公開指定の方法とモジュール分割の方法を理解しておけば多くの場合では問題ありません。より細かく公開範囲を指定したい場合には、次のような指定方法も用意されています。

• pub(super)：親モジュールまで公開する
• pub(in path)：指定したモジュールパス (path) 内のみに公開

この記事では詳細な説明は省略しますが、公開範囲を段階的に制御できる仕組みがあるという点は押さえておいてください。

まとめ

Rust のモジュールの可視性の基本について解説しました。

Rust では、モジュール外から参照できる要素はデフォルトで非公開となっており、外部に公開したい関数や型には pub を付けて明示的に公開範囲を指定します。この仕組みにより、意図しない API の公開を防ぎ、安全で保守しやすいコードを書くことができます。

また、モジュールは mod 宣言を用いて定義し、その実体をファイルやディレクトリに分割して管理することが可能です。プロジェクトの規模に応じて、ファイル単位やディレクトリ単位でモジュールを整理すると、コードの見通しが良くなります。

さらに、use を使うことでモジュールの要素をスコープに取り込み、記述を簡潔にすることができます。ただし、use は可視性のルール自体を変更するものではない点には注意が必要です。

まずは、この記事で紹介した pub による公開と基本的なモジュール分割の方法をしっかり理解することで、Rust のモジュール設計の基礎を覚えていただければと思います。

あわせて読みたい

Rust プログラミング入門

Rust のクレート

クレートとは？

Rust におけるクレート（crate）とは、コンパイル可能な最小単位のコードのまとまりのことです。Rust のプログラムは、必ず 1 つ以上のクレートによって構成されており、Cargo を使用してプロジェクトを作成すると自動的にクレートが生成されます。

クレートの種類には「バイナリクレート」と「ライブラリクレート」の 2 種類があります。

バイナリクレート（binary crate）

実行可能なファイル（.exe など）を生成するためのクレートです。プログラムのエントリポイントである main 関数があり、cargo run で実行できるプログラムを作るときに使用します。

バイナリクレートでは、src/main.rs が存在し、main() 関数から処理が開始されます。

ライブラリクレート（library crate）

他のコードから再利用される関数や型を提供するためのクレートです。エントリーポイントはなく、公開した API を別のクレートから利用することができます。

ライブラリクレートでは、src/lib.rs が存在し、再利用を前提として設計されます。また、後述する crates.io に公開してライブラリを配布することも可能です。

クレートと Cargo プロジェクトの関係性

Cargo でプロジェクトを作成する際にバイナリクレートか、ライブラリクレートかを切り替えて作成することができます。

バイナリクレートの場合 --bin

バイナリクレートは、以下のように cargo new で作成します。

cargo new my_app

cargo new はデフォルトがバイナリクレートとなっています。なお、「--bin」を明示的に指定して実行することも可能です。

cargo new --bin my_app

バイナリクレートでは、main.rs が作成されます。

ライブラリクレートの場合 --lib

ライブラリクレートは、「--lib」を指定して cargo new で作成します。

cargo new --lib my_app

ライブラリクレートでは、lib.rs が作成されます。

crates.io

crates.io は、Rust の公式パッケージリポジトリです。Rust のライブラリ（クレート）を公開・共有するためのプラットフォームで、Python の PyPI (Python Package Index) や Node.js の npm (Node Package Manager) 等に相当します。

Rust のエコシステムは、crates.io を中心に発展してきており、開発者は必要なライブラリを crates.io で検索し、Cargo.toml に依存のあるクレートとして追加して簡単に利用できます。

Rust の依存関係（dependencies）

依存関係（dependencies）とは

Rust のプロジェクトでは、自身が開発したコードだけではなく、外部のクレートをプロジェクトに取り込むことで効率的に開発を進めることができます。この外部のクレートを管理する仕組みが Cargo には組み込まれており、Cargo.toml という設定ファイルで制御できます。

Cargo.toml の基本構造

Cargo で作成したプロジェクトには、必ず Cargo.toml というファイルが存在しており、プロジェクト名、バージョン、依存関係などが記載されます。

[package]
name = "my_app"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = "1.0.228"
rand = "0.9.2"

[package] セクションには、プロジェクトの名称やバージョン、Rust のエディションなどの情報が記載されます。

[dependencies] セクションに書かれているクレートが、Cargo によってダウンロード、ビルドといった管理がされるものです。

[dependencies] の役割

[dependencies] セクションは、プロジェクトが利用するクレートを宣言する部分です。キーにクレート名、値が指定するバージョンになります。

例の以下部分では、serde クレートのバージョン 1.0.228 を使用することを意味します。

[dependencies]
serde = "1.0.228"

セマンティックバージョニング

Rust では、バージョン番号はセマンティックバージョニング（SemVer）に従っています。セマンティックバージョニングは「MAJOR.MINOR.PATCH」の形で、バージョンを構成します。

• MAJOR（メジャー）：後方互換性のない変更を行った場合に数字を増やします。大きな機能追加や API の破壊的変更の場合に使用します。
• MINOR（マイナー）：後方互換性を保った機能追加を行った場合に数字を増やします。新機能や改善で既存利用者への影響が小さい変更の場合に使用します。
• PATCH（パッチ）：後方互換性のあるバグ修正を行った場合に数字を増やします。動作に変更はなく、不具合を修正する場合に使用します。

セマンティックバージョニングでは、自動バージョンアップ可能性についても指定ができます。例えば「^1.2.3」のように指定すると、MAJOR が同じであれば、MINOR/PATCH への自動更新は許可するといったことが指定できます。破壊的変更を避けつつ、適度に更新するといったことができるようになっています。

crates.io でのクレートの探し方

crates.io へのアクセス

Rust の公式パッケージリポジトリである crates.io には「https://crates.io/」からアクセスすることができます。検索バーに、クレート名やキーワードを入力することで簡単に目的のクレートを探すことができます。

クレート情報

特定のクレートを検索して情報を確認すると以下のような情報を確認できます。

• 最新バージョン：クレートの現在の安定バージョンが分かります。
• ダウンロード数：どれだけダウンロードされているかの人気の指標です。
• インストール方法：クレートのインストール方法が分かります。（詳細は後述）
• ドキュメント：docs.rs で生成された API ドキュメントへのリンクがあります。
• Readme：当該クレートの Readme 情報が表示されます。

その他にも、Homepage、GitHub へのリンクや各種メタ情報などを確認可能です。

クレート選びのポイント

Python では、長年の実績で迷ったらこれというような、事実上一択なライブラリが多くありますが、Rust は比較的新しい言語であることもあり、まだそのようなクレートは少ないです。

ただし、一部の分野ではほぼ共通で使われているようなクレートも存在します。例としては以下のようなものが有名かなと思います。

上記は有名どころのクレートであり、多くのプロジェクトでも使用されているため安心して利用できます。

他にもたくさんのクレートがありますので、使えるクレートはどんどん試していただければと思います。外部クレートを選ぶ際は、以下のような点を確認することがおすすめです。

• 最終更新日が新しいか
• ドキュメントが整備されているか
• ダウンロード数が多いか
• 依存関係が過剰に多くないか
• GitHub のアクティビティなどメンテナンスはどの程度されているか

依存クレートの追加と管理

依存関係は Cargo.toml の [dependencies] に直接記述することもできますが、cargo コマンドによる管理も可能です。各種コマンドについて紹介します。

cargo コマンドによるクレートの追加と管理

依存性の管理では、cargo コマンドを以下のように実行します。シリアライズ／デシリアライズのためのクレートである serde を例に紹介します。

クレートの追加

cargo add serde

バージョンを指定して追加

バージョンを指定する場合は、クレート名の後に @ でバージョン番号を指定します。

cargo add serde@1.0.228

クレートの依存関係の更新

cargo update

クレートの依存ツリーの確認

cargo tree

上記のようなコマンドを使うことで、プロジェクトの依存関係を管理、構造の確認といったことが容易にできます。

features の指定

クレートには、Feature と呼ばれる追加機能がある場合があります。Feature を有効化するには、以下のように cargo add にオプションとして追加できます。

cargo add serde --features derive

また、Cargo.toml で以下のように features を指定しても構いません。

serde = { version = "1.0.228", features = ["derive"] }

上記では、serde クレートで derive マクロが使えるように features を指定しています。どのような features があるかどうかは、各クレートのドキュメントなどを確認してください。

features を使用することで、必要な機能だけを有効化して不要な依存関係を避けることができます。Rust のクレート設計では、この features はよく使用されています。

まとめ

Rust におけるクレートと依存関係の管理について解説しました。

Rust におけるクレート（crate）とは、コンパイル可能な最小単位のコードのまとまりのことで、バイナリクレートとライブラリクレートといった種類があります。また、クレートには依存関係（dependencies）というものがあり、Cargo を用いて作成したプロジェクトでは依存関係を柔軟に管理することができます。

crates.io には、多くの便利なクレートが公開されて利用できるようになっています。ぜひ、色々なクレートを使用して効率的に Rust の開発をしていってください。

あわせて読みたい

Rust プログラミング入門

Rust の入出力

プログラミング言語において、ファイル入出力は非常に基本的で重要な処理です。Rust の入出力は、Read、BufRead、Write というトレイトを中心に構築されています。入出力という広い観点で見ると「ファイル」「標準入出力」「ネットワーク」など様々な対象がありますが、Rust では、いずれもこれらのトレイトを通じて扱うことができます。

この記事では、トレイトの細かなところまでは踏み込みませんが、テキストファイルの入出力を通じて Rust でのファイル入出力の基本を紹介します。

テキストファイルの入出力

テキストファイルの読み込み

ファイルを開いて全てのテキストを読み込む read_to_string

テキストファイルを開いて内容を読み込むには、read_to_string メソッドを使用します。

use std::fs;
use std::io::{self};

fn read_file(filepath: &str) -> io::Result<()> {
    // ファイルパスのデータを String 型で取得する
    let contents = fs::read_to_string(filepath)?;
    // 読み込んだ文字列を表示する
    println!("{}", contents);

    Ok(())
}

fn main() {
    // ファイルパスは任意のパスに変更してください
    let filepath = r"D:\RustProject\rust-tech-sample-source\rust-basic\file_input_output\examples\input_example.txt";

    // ファイル読み込み関数を呼び出し、エラーが発生した場合はエラーを表示する
    if let Err(e) = read_file(filepath) {
        println!("Error: {}", e);
    }
}

【実行結果】※ input_example.txt の内容
Rust Programming
ファイル入出力の基本
テキストファイルの入出力

「use std::fs;」とすることで、標準ライブラリ std 内の fs モジュールを使用します。read_to_string は fs モジュール内の関数で、ファイルパスを渡すことで、ファイルの中身を String 型で読み込むことができます。

この read_to_string 関数の返却値の型は、io::Result<String> 型になります。上記例の read_file 関数では、返却値を io::Result<()> として、? 演算子によりエラーが発生した場合や呼び出し元に移譲しています。

エラーの場合は、呼び出し元の main 関数内で if let により Err を補足してエラーを表示するようにしています。より丁寧にエラー処理をする場合は、match による処理ももちろん可能です。エラー処理の基本が分からない方は「エラー処理の基本を分かりやすく解説」も参考にしてください。

ファイルを開いてから読み込む

read_to_string 関数は、上記のようにファイルパスを指定して簡単にテキストファイルを読み込むことができますが、以下の例のように fs::File::open によりファイルを開いてから、読込先の String を渡して読み込むことも可能です。

use std::fs;
use std::io::{self, Read};

fn read_file(filepath: &str) -> io::Result<()> {
    let mut file = fs::File::open(filepath)?;
    let mut contents = String::new();

    // ファイルの内容を読み込み
    file.read_to_string(&mut contents)?;
    // 読み込んだ文字列を表示する
    println!("{contents}");

    Ok(())
}

この時、Read トレイトを use 指定する必要がある点に注意してください。先ほどまで使用していた fs::read_to_string は fs モジュール内に定義された関数でした。一方で、上記例は File 型にトレイトのメソッドとして定義した read_to_string を使用しているため、似ているように見えて全くの別物です。

トレイトで定義されるメソッドを使用する際には、use でトレイトを読み込む必要があるため、上記の例では Read トレイトの読み込みが必要となるわけです。

1行ずつ読み込む

ファイルを 1行ずつ読み込む場合には、BufReader により順次処理をすることが可能です。

use std::fs::File;
use std::io::{self, BufRead, BufReader};

fn read_lines(filepath: &str) -> io::Result<()> {
    let file = File::open(filepath)?;
    let reader = BufReader::new(file);

    // ファイルを1行ずつ読み込む
    for line in reader.lines() {
        // line は Result<String, Error> なので値を取り出す
        let line = line?;
        println!("{} :文字数({})", line, line.chars().count());
    }

    Ok(())
}

fn main() {
    // ファイルパスは任意のパスに変更してください
    let filepath = r"D:\RustProject\rust-tech-sample-source\rust-basic\file_input_output\examples\input_example.txt";

    // ファイル読み込み関数を呼び出し、エラーが発生した場合はエラーを表示する
    if let Err(e) = read_lines(filepath) {
        println!("Error: {}", e);
    }
}

【実行結果】
Rust Programming :文字数(16)
ファイル入出力の基本 :文字数(10)
テキストファイルの入出力 :文字数(12)

上記例では、まず File::open によりファイルを開き、BufReader の new 関数に渡すことで reader を生成します。reader.lines() により各行のデータを順に取得することができるため、for 文で line に値を入れつつ 1行ずつ処理をすることが可能です。

なお、BufRead トレイトと BufReader 型を use 指定する必要があるので注意してください。

取り出される line は、Result<String, Error> 型であるため、? 演算子により値を取り出してから使用しています。このようにすることで、1行ずつファイルを読み込み処理をすることができます。

テキストファイルの書き込み

入力は主に read_to_string などのメソッドを用いて行いましたが、書き込みでは write! マクロを使用します。

ファイルを作成して書き込む

ファイルの書き込みを行う場合には、OpenOptions 型を使用します。この型では、「.」でメソッドを連結することでファイルを開く際のオプションを指定することが可能になっています。

use std::fs::OpenOptions;
use std::io::{self, Write};

fn write_new_file(filepath: &str, text: &str) -> io::Result<()> {
    // ファイルを作成して開く
    let mut file = OpenOptions::new()
        .write(true)
        .create_new(true) // ファイルが存在するとエラー
        .open(filepath)?;

    // 文字列を書き込む
    writeln!(file, "{text}")?;

    Ok(())
}

fn main() {
    // ファイルパスは任意のパスに変更してください
    let filepath = r"D:\RustProject\rust-tech-sample-source\rust-basic\file_input_output\examples\output_example.txt";

    // 書き込み文字列を準備
    let write_str = "Rust Programming\nファイル入出力の基本\nテキストファイルの入出力";

    // ファイル書き込み関数を呼び出し、エラーが発生した場合はエラーを表示する
    if let Err(e) = write_new_file(filepath, write_str) {
        println!("Error: {e}");
    }
}

ファイルを書き込む際には「.write(true).create_new(true).open(filepath)」とすることで、指定したファイルパスでファイルを作成して、書き込みモードで開くことができます。この時ファイルが存在する場合は、エラーとなります。

ファイルを書き込む場合には、writeln! マクロを使用します。このマクロは、println! マクロとほとんど同じですが、第1引数に File 型のインスタンスを指定していることとが異なります。なお、改行を含まないように出力したい場合は write! マクロで対応可能です。

また、返却値として Result 型が返ってくる点も println! マクロとは異なるためエラー処理が必要です。上記例では ? 演算子により処理をしています。

ファイルを開いて追記する

ログファイルの出力など、ファイルを追記モードで開いて末尾に文字列を追記したくなることが良くあります。この場合は、以下のように「.append(true)」とすることで対応可能です。

use std::fs::OpenOptions;
use std::io::{self, Write};

fn write_append_file(filepath: &str, text: &str) -> io::Result<()> {
    // ファイルを追記モードで開く
    let mut file = OpenOptions::new()
        .append(true) // ファイルが存在しない場合、エラー
        .open(filepath)?;

    // 文字列を書き込む
    writeln!(file, "{text}")?;

    Ok(())
}

fn main() {
    let filepath = r"D:\RustProject\rust-tech-sample-source\rust-basic\file_input_output\examples\output_example.txt";

    // 追記する文字列を準備
    let append_str = "Rust 文字列の追記";

    // ファイル書き込み関数を呼び出し、エラーが発生した場合はエラーを表示する
    if let Err(e) = write_append_file(filepath, append_str) {
        println!("Error: {e}");
    }
}

この場合、ファイルが存在しない場合はエラーとなるので注意してください。

まとめ

Rust のファイル入出力の基本について解説しました。この記事では、テキストファイルの読み込み・書き込みを中心に紹介しています。

ファイル入出力は、どのようなプログラミング言語においても基本になります。Rust の I/O を理解することで、より安全でパフォーマンスの高いプログラムが書けるようになりましょう。

あわせて読みたい

Rust プログラミング入門