reqwest クレートの概要

reqwest とは

reqwest は、Rust で HTTP 通信を行うための代表的なクレートです。GET や POST などの HTTP リクエストを簡潔なコードで記述でき、JSON の送受信、認証ヘッダーの付与、タイムアウト設定なども柔軟に対応しています。

Rust の標準ライブラリには、HTTP クライアント機能は含まれていないため、Web API との通信が必要な場面では、reqwest がデファクトスタンダードとして広く使用されています。

この記事では、reqwest の基本的な使い方を紹介します。

非同期モードと同期モード

reqwest には、非同期モードと同期モードの 2 種類があります。reqwest は、非同期処理ランタイムの tokio をベースに構築されており、デフォルトは非同期モードです。

• 非同期モード（デフォルト）：async / await を使用して非同期でリクエストを送信します。非同期処理ランタイムである tokio が必要です。
• 同期モード：reqwest::blocking モジュールを使うことで、通常の同期コードとして HTTP リクエストを書くことができます。使用する場合には、blocking feature を有効にする必要があります。

この記事では、実務上よく使われる非同期モードを中心に解説します。同期モード（reqwest::blocking）については、後半で簡単に触れます。

reqwest を使用した HTTP 通信の基本

reqwest の導入方法

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

cargo add で追加する場合

cargo add reqwest --features json,query
cargo add tokio --features full

Cargo.toml に追記する場合

[dependencies]
reqwest = { version = "0.13", features = ["json", "query"] }
tokio = { version = "1", features = ["full"] }

feature について

reqwest の json feature を有効にすることで、json メソッドが使えるようになります。これにより、リクエストボディへの JSON 埋め込みや、レスポンスの JSON デシリアライズを簡単に行うことができます。JSON を扱う場合には、必ず指定するようにしましょう。また、以降で使用する query メソッドも使えるように query feature も有効にします。

tokio の full feature は、tokio が提供するすべての機能を有効にしておきます。

導入時には crates.io の reqwest や tokio のページを確認してください。なお、実際にインストールされたバージョンは Cargo.lock ファイルで確認できます。

テスト用サービス httpbin.org

HTTP リクエストとレスポンスをテストする

HTTP リクエストとレスポンスのテストをするためには、API を提供するサーバーが必要になります。今回は「httpbin.org」を使用します。

httpbin.org は、HTTP リクエストとレスポンスのテストに使用される人気のオンラインサービスで、開発者が HTTP リクエストを送信し、レスポンスを確認することができます。

httpbin.org は、WebAPI 開発や HTTP クライアントのライブラリ、フレームワークのテストなどに広く使用されています。

Docker 環境の利用

httpbin.org は、通信タイミングによってサービスが不安定なことがあります。httpbin.org のサービスは、Docker 環境が用意されているため、Docker 環境が手元にある場合には、以下のコマンドでローカル実行してテストする方が安定的に動作の確認が可能です。

docker run --rm -p 8080:80 kennethreitz/httpbin

上記コマンドを実行すると「kennethreitz/httpbin」というコンテナ環境をインストールし、起動します。--rm オプションは、終了時にコンテナを削除するコマンドで、-p 8080:80 はポートの接続設定です。ローカル環境からは 8080 ポートを使用してコンテナにアクセスします。

なお、httpbin.org にアクセスする場合は、https で SSL可能ですが、ローカルの Docker 環境は SSL 通信は対応していないので http でアクセスする必要があります。

以降のサンプルコードでは、https://httpbin.org への URL を記載しています。ローカルの Docker 環境を使う場合は http://localhost:8080 に切り替えて試してください。

各 HTTP メソッドでリクエストを送信する
（GET / POST/ PUT / DELETE）

基本的な使い方の流れ

reqwest を用いて HTTP 通信をする際の基本的な流れは以下の通りです。

以降では、上記の流れで各 HTTP メソッドを使用する例を順番に紹介します。

GET リクエストでレスポンスを取得する

基本的な使い方

基本的な GET リクエストを送ってレスポンスを取得する例から見ていきましょう。

use std::error::Error;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // httpbin.org から取得する
    let url = "https://httpbin.org/get";
    // Docker を使用する場合は、以下のように URL を変更してください
    // let url = "http://localhost:8080/get";

    // ClientBuilder でタイムアウトなどを設定する
    let client_builder = reqwest::Client::builder().timeout(Duration::from_secs(10));

    // ClientBuilder から Client を作成する
    let client = client_builder.build()?;

    // RequestBuilder を作成する
    let request_builder = client.get(url);

    // レスポンスを取得する
    let response = request_builder.send().await?;

    // ステータスコードを取得する
    let status = response.status();
    println!("ステータスコード:\n{status}\n");

    // レスポンスボディを文字列として取得する
    let text = response.text().await?;
    println!("応答の文字列形式:\n{text}");

    Ok(())
}

【実行結果】
ステータスコード:
200 OK

応答の文字列形式:
{
  "args": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-6a49b680-6c650d0050fcf1c707d6e742"
  }, 
  "origin": "xxx.xxx.xxx.xxx", 
  "url": "https://httpbin.org/get"
}

#[tokio::main] は、main 関数を非同期関数として実行するためのものです。reqwest の非同期モードでは、tokio のランタイムが必要なため、この指定が必要です。

まず、reqwest::Client::builder() で ClientBuilder を生成し、timeout() で通信タイムアウトを設定しています。

次に、client.get(url) で、RequestBuilder を生成し、send().await でリクエストを送信します。このとき、await で非同期処理の完了を待ち、? 演算子でエラーを呼び出し元に伝播しています。

レスポンスからは、status() でステータスコードを取得でき、ボディの文字列を取得する際には、text().await を使用します。text() は非同期処理のため、await が必要な点に注意してください。

クエリパラメータを指定する

GET リクエストを送る際に、検索の条件となるクエリパラメータを指定する場合には、query メソッドを使用します。

use std::error::Error;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    ...(Client 作成までは同様なので省略)...

    // RequestBuilder を作成する
    // query() でクエリパラメータを付与することができる
    let queries = [("key1", "value1"), ("key2", "value2")];
    let request_builder = client.get(url).query(&queries);

    // レスポンスを取得する
    let response = request_builder.send().await?;

    ...(ステータスコード表示とボディの表示は同様なので省略)...
}

【実行結果】
ステータスコード:
200 OK

応答の文字列形式:
{
  "args": {
    "key1": "value1", 
    "key2": "value2"
  }, 
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-6a49b7d7-169234f062f0d8bb46cea5c2"
  }, 
  "origin": "xxx.xxx.xxx.xxx", 
  "url": "https://httpbin.org/get?key1=value1&key2=value2"
}

query メソッドにキーと値を持った配列を渡すことで、クエリパラメータを設定できます。具体的な URL としては、https://httpbin.org/get?key1=value1&key2=value2 のように送信されることになります。

ヘッダーを扱う

リクエストの際にはヘッダー情報を指定する場合や、レスポンスのヘッダーを確認することがよくあります。ヘッダーの扱いについても以下で確認しましょう。

use std::error::Error;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    ...(Client 作成までは同様なので省略)...

    // RequestBuilder を作成する
    // header() でリクエストヘッダーを付与することができる
    // API キーを送信する場合によく使われる例
    let request_builder = client.get(url).header("X-API-Key", "sample-api-key");

    // レスポンスを取得する
    let response = request_builder.send().await?;

    // ステータスコードを取得する
    let status = response.status();
    println!("ステータスコード:\n{status}\n");

    // ヘッダーを取得する
    let headers = response.headers();
    println!("ヘッダー:\n{headers:?}\n");

    // ヘッダーから特定の項目だけを取り出す例
    // ヘッダーは HeaderMap 型で取得されるので、get() メソッドで取り出す
    // 値の型は HeaderValue なので、文字列に変換する必要がある
    let content_type = headers
        .get("content-type")
        .ok_or("content-type ヘッダーが見つかりません")?
        .to_str()?;
    println!("content-type ヘッダー: {content_type}\n");

    // レスポンスボディを文字列として取得する
    let text = response.text().await?;
    println!("応答の文字列形式:\n{text}");

    Ok(())
}

【実行結果】
ステータスコード:
200 OK

ヘッダー:
{"date": "Sun, 05 Jul 2026 02:06:48 GMT", "content-type": "application/json", "content-length": "257", "server": "gunicorn/19.9.0", "access-control-allow-origin": "*", "access-control-allow-credentials": "true"}

content-type ヘッダー: application/json

応答の文字列形式:
{
  "args": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-6a49bc38-646f78d43467315669dd0b4a", 
    "X-Api-Key": "sample-api-key"
  }, 
  "origin": "xxx.xxx.xxx.xxx", 
  "url": "https://httpbin.org/get"
}

リクエストのヘッダーに固有のヘッダを付与したい場合には、RequestBuilder で、header メソッドを使用します。例の「header("X-API-Key", "sample-api-key")」のような指定は、外部サービスの REST API を使用する際に固有の認証キーを使う際によく利用されます。

レスポンスのヘッダー情報は、headers メソッドで全体を取得できます。ヘッダーは、HeaderMap 型であり、特定の項目を取り出す際は、get() でアクセスします。取得される値は HeaderValue 型のため、最後に to_str で文字列に変換します。

JSON レスポンスを構造体にデシリアライズする

Web API では JSON 形式のレスポンスを受け取るケースが多くあります。reqwest では serde と組み合わせることで、JSON レスポンスを構造体に直接デシリアライズできます。デシリアライズするためには serde が必要です。cargo addで追加しておいてください。

cargo add serde --features derive

use serde::Deserialize;
use std::collections::HashMap;
use std::error::Error;
use std::time::Duration;

// url と headers だけを保持する構造体
#[derive(Debug, Deserialize)]
struct HttpBinResponse {
    url: String,
    headers: HashMap<String, String>,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    ...(Client 作成までは同様なので省略)...

    // RequestBuilder を作成する
    let request_builder = client.get(url);

    // レスポンスを取得する
    let response = request_builder.send().await?;

    // json() で構造体にデシリアライズする
    let data: HttpBinResponse = response.json().await?;

    // url と headers を取り出す
    println!("url: {}", data.url);
    println!("headers: {:?}", data.headers);

    Ok(())
}

【実行結果】
url: https://httpbin.org/get
headers: {"X-Amzn-Trace-Id": "Root=1-6a498cbb-25fe1cde73cbb10827f0d817", "Accept": "*/*", "Host": "httpbin.org"}

json().await で、レスポンスボディを指定した型に直接デシリアライズできます。受け取る変数には「let data: HttpBinResponse」のように型を明示する必要があります。また、JSON で取り込む構造体は、#[derive(Deserialize)]を付けて定義する必要があります。

JSON のフィールドと構造体のフィールドが一致しない場合や、型が合わない場合にはエラーとなります。存在しない場合があるフィールドは Option<T> にしておくと安全です。

POST リクエストで JSON を送信する

JSON データを含めて POST リクエストを送信する例を見てみましょう。POST でデータを登録する場合には、対象サービスのエンドポイントが用意されます。

今回は、https://httpbin.org/anything/users というエンドポイントがユーザー登録のためのエンドポイントとして例を紹介します。なお、httpbin.org で /anything や /anything/<任意パス> は、HTTPメソッドを問わず、リクエスト内容をそのまま返却するようなエンドポイントです。今回は、users というユーザー登録のエンドポイント例の代替として使用します。

use std::error::Error;
use std::time::Duration;

use serde::Serialize;

// リクエストボディとして送信するデータ
// user_id はサーバー側で採番される想定とする
#[derive(Serialize)]
struct User {
    name: String,
    age: u32,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // httpbin.org へ送信する
    // ユーザー登録エンドポイントを呼び出す
    let url = "https://httpbin.org/anything/users";
    // Docker を使用する場合は、以下のように URL を変更してください
    // let url = "http://localhost:8080/anything/users";

    // ClientBuilder でタイムアウトなどを設定する
    let client_builder = reqwest::Client::builder().timeout(Duration::from_secs(10));

    // ClientBuilder から Client を作成する
    let client = client_builder.build()?;

    // 送信するデータ
    let user = User {
        name: "Taro".to_string(),
        age: 30,
    };

    // RequestBuilder を作成する
    // json() でリクエストボディを JSON として送信する
    let request_builder = client.post(url).json(&user);

    // レスポンスを取得する
    let response = request_builder.send().await?;

    // ステータスコードを取得する
    let status = response.status();
    println!("ステータスコード:\n{status}\n");

    // レスポンスボディを文字列として取得する
    let text = response.text().await?;
    println!("応答の文字列形式:\n{text}");

    Ok(())
}

【実行結果】
ステータスコード:
200 OK

応答の文字列形式:
{
  "args": {}, 
  "data": "{\"name\":\"Taro\",\"age\":30}", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "24", 
    "Content-Type": "application/json", 
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-6a49c912-2d1d37541f89dcbd32a31524"
  }, 
  "json": {
    "age": 30, 
    "name": "Taro"
  }, 
  "method": "POST", 
  "origin": "xxx.xxx.xx.xxx", 
  "url": "https://httpbin.org/anything/users"
}

client.post(url) で POST リクエストの RequestBuilder を作成し、json(&user) で送信したい構造体のデータを設定します。

送信するデータの構造体には #[derive(Serialize)] を付与しておく必要があります。なお、json() は内部で Content-Type: application/json ヘッダーも自動付与してくれます。

PUT リクエストでデータを更新する

PUT リクエストについても考えましょう。今回の例では、既に user_id が POST により登録されており、https://httpbin.org/anything/users/u1001 というユーザー ID のエンドポイントを PUT で呼び出すと考えます。

REST API では、このようにエンドポイントで対象となる ID をパスパラメータとして指定できるように作られることが一般的です。

use std::error::Error;
use std::time::Duration;

use serde::Serialize;

// リクエストボディとして送信するデータ
// user_id は URL のパスパラメータで指定するため、ボディには含めない
#[derive(Serialize)]
struct User {
    name: String,
    age: u32,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // 更新対象の user_id
    let user_id = "u1001";

    // httpbin.org へ送信する
    // user_id をパスパラメータとして URL に含める
    let url = format!("https://httpbin.org/anything/users/{user_id}");
    // Docker を使用する場合は、以下のように URL を変更してください
    // let url = format!("http://localhost:8080/anything/users/{user_id}");

    ...(Client 作成までは同様なので省略)...

    // 更新後のデータ
    let user = User {
        name: "Miki".to_string(),
        age: 25,
    };

    // RequestBuilder を作成する
    // put() で PUT リクエストを送信する
    let request_builder = client.put(url).json(&user);

    // レスポンスを取得する
    let response = request_builder.send().await?;

    // ステータスコードを取得する
    let status = response.status();
    println!("ステータスコード:\n{status}\n");

    // レスポンスボディを文字列として取得する
    let text = response.text().await?;
    println!("応答の文字列形式:\n{text}");

    Ok(())
}

【実行結果】
ステータスコード:
200 OK

応答の文字列形式:
{
  "args": {}, 
  "data": "{\"name\":\"Miki\",\"age\":25}", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "24", 
    "Content-Type": "application/json", 
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-6a49c11f-39b3368462de6e1f2244052c"
  }, 
  "json": {
    "age": 25, 
    "name": "Miki"
  }, 
  "method": "PUT", 
  "origin": "xxx.xxx.xxx.xxx", 
  "url": "https://httpbin.org/anything/users/u1001"
}

対象とする ID 情報は、例のように format! を用いて埋め込むのが簡単です。それ以降の処理の流れは、post が put に変わるだけで同様の流れとなります。

DELETE リクエストでデータを削除する

DELETE リクエストも、PUT と同様に https://httpbin.org/anything/users/u1001 に対して DELETE のリクエストを送信する例を考えます。

use std::error::Error;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // 削除対象の user_id
    let user_id = "u1001";

    // httpbin.org へ送信する
    // user_id をパスパラメータとして URL に含める
    let url = format!("https://httpbin.org/anything/users/{user_id}");
    // Docker を使用する場合は、以下のように URL を変更してください
    // let url = format!("http://localhost:8080/anything/users/{user_id}");

    ...(Client 作成までは同様なので省略)...

    // RequestBuilder を作成する
    // delete() で DELETE リクエストを送信する
    let request_builder = client.delete(url);

    // レスポンスを取得する
    let response = request_builder.send().await?;

    // ステータスコードを取得する
    let status = response.status();
    println!("ステータスコード:\n{status}\n");

    // レスポンスボディを文字列として取得する
    let text = response.text().await?;
    println!("応答の文字列形式:\n{text}");

    Ok(())
}

【実行結果】
ステータスコード:
200 OK

応答の文字列形式:
{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "X-Amzn-Trace-Id": "Root=1-6a49c102-51e1f4260751237d2a3ea3c7"
  }, 
  "json": null, 
  "method": "DELETE", 
  "origin": "xxx.xxx.xxx.xxx", 
  "url": "https://httpbin.org/anything/users/u1001"
}

DELETE の場合は、対象が識別できればいいので、エンドポイントを指定して delete メソッドを呼び出しているだけになります。プログラムの構成としては、PUT と同様です。

エラー情報に対処する

各 HTTP メソッドの使い方を見てきました。これまでの例は、成功ステータスの例のみでしたが、実開発では、エラーステータスコードの場合、適切な処理が必要です。4xx、5xx 番はエラーとして扱いますが、これまで紹介したメソッドは、レスポンスが返ってくれば 4xx や 5xx でも Ok 扱いとなります。

そのため、エラーステータスを判断して処理をしたい場合は、レスポンスの error_for_status メソッドを使用します。このメソッドは、4xx、5xx の場合に、Err を返すため、? 演算子と組み合わせるなど状況に応じて適切にエラー処理ができます。

httpbin.org には、特定のエラーコードを返却するエンドポイントが用意されているので、今回は、ステータスコード 400 が返ってくる場合の対処例を紹介します。

use std::error::Error;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // httpbin.org から取得する
    let url = "https://httpbin.org/status/400";
    // Docker を使用する場合は、以下のように URL を変更してください
    // let url = "http://localhost:8080/status/400";

    // ClientBuilder でタイムアウトなどを設定する
    let client_builder = reqwest::Client::builder().timeout(Duration::from_secs(10));

    // ClientBuilder から Client を作成する
    let client = client_builder.build()?;

    // ケース1: HTTP レベルのエラー(ステータスコードが 4xx や 5xx)
    // 通信自体は成功しているため、send() は Ok(Response) を返す
    let response = client.get(url).send().await?;
    println!("ステータスコード: {}\n", response.status());

    // error_for_status() を使うと、4xx・5xx のステータスコードを Err に変換できる
    match response.error_for_status() {
        Ok(response) => println!("成功として扱われました: {}", response.status()),
        Err(error) => println!("error_for_status() でエラーになりました: {error}"),
    }
    println!();

    // ケース2: 通信レベルのエラー
    // 存在しないホスト名のため、DNS 解決に失敗して send() 自体が Err を返す
    let invalid_url = "https://this-host-does-not-exist.com";
    match client.get(invalid_url).send().await {
        Ok(response) => println!("ステータスコード: {}", response.status()),
        Err(error) => println!("send() でエラーになりました: {error}"),
    }

    Ok(())
}

【実行結果】
ステータスコード: 400 Bad Request

error_for_status() でエラーになりました: HTTP status client error (400 Bad Request) for url (https://httpbin.org/status/400)

send() でエラーになりました: error sending request for url (https://this-host-does-not-exist.com/)

ケース1 は、通信は通っているものの適切なリクエストの仕方ではなかったため、400 番のレスポンスがあった場合です。一方で、ケース2 の方は、そもそも通信レベルのエラーの場合です。例では存在しない URL へアクセスしようとして通信が返ってきません。この時は、send の時点で Err が返ってきます。どちらのケースのエラーであるのかを判断できるようにコーディングするようにしましょう。

汎用メソッド request を使用する

これまで、get、post、put、delete と各 HTTP メソッドごとの専用メソッドを使ってきました。reqwest には、HTTP メソッドを動的に指定できる request という汎用メソッドも用意されています。

use std::error::Error;
use std::time::Duration;

use reqwest::Method;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // ClientBuilder でタイムアウトなどを設定する
    let client_builder = reqwest::Client::builder().timeout(Duration::from_secs(10));

    // ClientBuilder から Client を作成する
    let client = client_builder.build()?;

    // 対象の user_id
    let user_id = "u1001";

    // request() を使うと、get()・post()・put()・delete() のような専用メソッドの代わりに、
    // Method を指定して同じ内容のリクエストを送信できる
    let requests = [
        (
            "GET",
            Method::GET,
            "https://httpbin.org/anything/users".to_string(),
        ),
        (
            "POST",
            Method::POST,
            "https://httpbin.org/anything/users".to_string(),
        ),
        (
            "PUT",
            Method::PUT,
            format!("https://httpbin.org/anything/users/{user_id}"),
        ),
        (
            "DELETE",
            Method::DELETE,
            format!("https://httpbin.org/anything/users/{user_id}"),
        ),
    ];

    for (label, method, url) in requests {
        // RequestBuilder を作成する
        let request_builder = client.request(method, url);

        // レスポンスを取得する
        let response = request_builder.send().await?;

        // ステータスコードを取得する
        let status = response.status();
        println!("[{label}] {status}");
    }

    Ok(())
}

【実行結果】
[GET] 200 OK
[POST] 200 OK
[PUT] 200 OK
[DELETE] 200 OK

request では、例えば、GET であれば、client.request(Method::GET, url) のように reqwest::Method 型を指定することで HTTP メソッドを切り替えます。client.get() などの個別メソッドは、内部的にはこの client.request() を呼び出すラッパーになっています。

呼び出されるメソッドが明確な場合は、各専用メソッドを用いる方が可読性の観点で優れています。一方で、ライブラリなどで動的に呼び出すメソッドを変更したい場合には、request を使って実装するのがおすすめです。

同期通信 reqwest::blocking

この記事の冒頭で説明した通り、reqwest は、非同期モードがデフォルトになっています。同期的に使用したい場合には、reqwest::blocking を使用します。 blocking はデフォルトでは無効なので「cargo add reqwest --features json,query,blocking」のように blocking feature を有効にするようにしてください。

use std::error::Error;
use std::time::Duration;

// blocking::Client を使うと、async/await を使わずに同期的に通信できる
// tokio::main は不要で、通常の fn main で実行できる
fn main() -> Result<(), Box<dyn Error>> {
    // httpbin.org から取得する
    let url = "https://httpbin.org/get";
    // Docker を使用する場合は、以下のように URL を変更してください
    // let url = "http://localhost:8080/get";

    // ClientBuilder でタイムアウトなどを設定する
    let client_builder = reqwest::blocking::Client::builder().timeout(Duration::from_secs(10));

    // ClientBuilder から Client を作成する
    let client = client_builder.build()?;

    // 同じ Client で複数回リクエストを送る
    for count in 1..=3 {
        // RequestBuilder を作成する
        let request_builder = client.get(url);

        // レスポンスを取得する(await が不要)
        let response = request_builder.send()?;

        // ステータスコードを取得する
        let status = response.status();
        println!("{count}回目 ステータスコード: {status}");
    }

    Ok(())
}

【実行結果】
1回目 ステータスコード: 200 OK
2回目 ステータスコード: 200 OK
3回目 ステータスコード: 200 OK

非同期との違いは、まず、main 関数が同期関数となっている点です。#[tokio::main] の付いた関数の中で reqwest::blocking を使うと実行時に panic となるので、非同期との併用は不可である点は注意してください。

また、使い方では、ClientBuilder 生成で reqwest::blocking::Client::builder() を使用する点が異なります。それ以外の使い方はほとんど同様ですが、同期実行であるため、send の際に await は不要となります。

まとめ

Rust で HTTP 通信を行うためのクレートである reqwest の基本的な使い方について、解説しました。

GET・POST・PUT・DELETE といった基本的な HTTP メソッドの使い方から、クエリパラメータやヘッダーの指定、JSON のシリアライズ・デシリアライズ、エラー処理の考え方まで、実務でよく使う内容を中心に紹介しました。

また、汎用メソッドの request や、同期的に扱える reqwest::blocking についても紹介しました。基本の使い方をしっかり押さえておくことで、外部 API との連携など、様々な場面で活用できるようになります。ぜひ、基本的な使い方を理解してください。

あわせて読みたい

Rust プログラミング入門

serde クレートの概要

serde とは

Web API のレスポンスや設定ファイルなど、開発現場では、JSON 形式のデータを扱うことが多くあります。プログラム内の型のデータを JSON のような文字列形式に変換することを「シリアライズ（serialize）」、逆に JSON 文字列を型のデータに変換することを「デシリアライズ（deserialize）」と言います。

Rust では、このシリアライズ・デシリアライズで serde （サード、サーディと読みます）というクレートを使用します。この記事では、serde を使った JSON の基本的な扱い方について紹介します。

この記事で理解してもらいたい内容は以下の通りです。

• serde は、シリアライズ・デシリアライズの共通の仕組みを提供する。
• JSON を扱うには serde_json と組み合わせて使う。
• #[derive(Serialize)] で型をJSONに変換でき、#[derive(Deserialize)] で JSON を型に変換できる。
• ネストした型や、Vec<T>、Option<T> などを含む型もそのまま扱える。

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

serde と serde_json

serde 本体は、特定のデータ形式（フォーマット）に依存しない共通の仕組みです。そのため、serde 自体には、「JSON に変換する」「JSON から変換する」といった具体的な処理はありません。

実際に、JSON を扱うためには、JSON フォーマットに対応した serde_json というクレートを組み合わせて使用します。このクレートは、serde の仕組みを利用して、JSON フォーマットの読み書きを実装しています。

このように serde は形式に依存しない設計になっているおかげで、JSON 以外にも YAML (serde_yaml) や TOML (toml) など、各フォーマットに対応するクレートを使って同じ書き方で使用することができます。この記事では、最もよく使われる JSON を例に紹介します。

serde を使用した JSON 操作の基本

serde の導入方法

serde と serde_json は、他のクレートと同様に cargo add または Cargo.toml に追記することで利用できます。

cargo add で追加する場合

cargo add serde --features derive
cargo add serde_json

Cargo.toml に追記する場合

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

例では、メジャーバージョンとして "1" を指定しています。これにより、互換性のある範囲で最新のバージョンが使用されます。もちろん特定のバージョンを指定しても構いません。

導入時には crates.io の serde や serde_json のページを確認してください。なお、実際にインストールされたバージョンは Cargo.lock ファイルで確認できます。

型を JSON に変換する（Serialize）

基本的な方法

構造体 (struct) を JSON 文字列に変換するシリアライズ (Serialize) から見ていきましょう。対象の型に #[derive(Serialize)] を付与し、serde_json::to_string 関数を使用することで、JSON 形式の文字列に変換することができます。

以下の例では、User という型を定義し、JSON 文字列に変換しています。

use serde::Serialize;

// 構造体を定義し、Serialize トレイトを derive することで
// 構造体を JSON にシリアライズできるようにする
#[derive(Serialize, Debug)]
struct User {
    name: String,
    age: u32,
}

fn main() -> Result<(), serde_json::Error> {
    let user = User {
        name: String::from("Alice"),
        age: 30,
    };

    // 構造体を JSON 文字列に変換（シリアライズ）
    let json = serde_json::to_string(&user)?;
    println!("{json}");

    Ok(())
}

【実行結果】
{"name":"Alice","age":30}

定義した型に対して #[derive(Serialize)] を付けておくことで、serde_json::to_string にわたすだけで JSON 文字列に変換できていることが分かります。

なお、serde_json::to_string は変換に失敗する可能性があることから、戻り値は Result 型となります。今回の例では、? 演算子を使ってエラー (serde_json::Error) を上位へ伝播しています。もちろん match を用いて処理する方法も適切ですので設計に応じて検討しましょう。

改行やインデントを入れて整形する方法

改行やインデントを入れて整形した、人間が読みやすい形式の JSON 文字列にしたい場合は、serde_json::to_string_pretty を使用します。

use serde::Serialize;

#[derive(Serialize, Debug)]
struct User {
    name: String,
    age: u32,
}

fn main() -> Result<(), serde_json::Error> {
    let user = User {
        name: String::from("Alice"),
        age: 30,
    };

    // 読みやすいように改行・インデント付きの JSON 文字列に変換する
    let json = serde_json::to_string_pretty(&user)?;
    println!("{json}");

    Ok(())
}

【実行結果】
{
  "name": "Alice",
  "age": 30
}

設定ファイルの出力やデバッグ時など、見やすさを重視したい場合には、serde_json::to_string_pretty を使用するのが便利です。

JSON を型に変換する（Deserialize）

次に、JSON 文字列を構造体 (struct) に変換するデシリアライズ (Deserialize) を見ていきましょう。対象の型に #[derive(Deserialize)] を付与し、serde_json::from_str 関数を使用することで、JSON 形式の文字列から構造体に変換することができます。

use serde::Deserialize;

// 構造体を定義し、Deserialize トレイトを derive することで
// JSON 文字列を構造体にデシリアライズできるようにする
#[derive(Deserialize, Debug)]
struct User {
    name: String,
    age: u32,
}

fn main() -> Result<(), serde_json::Error> {
    let json = r#"{"name":"Alice","age":30}"#;

    // JSON 文字列を構造体に変換（デシリアライズ）
    let user: User = serde_json::from_str(json)?;
    println!("{user:?}");

    Ok(())
}

【実行結果】
User { name: "Alice", age: 30 }

定義した型 (User)に対して #[derive(Deserialize)] を付けておき、serde_json::from_str に JSON 文字列を渡せば User 構造体に変換できます。なお、「let user: User」 のように変換先の型注釈を明示している点に注意してください。serde_json::from_str は様々な型に変換できる関数のため、どの型に変換するのかを伝える必要があります。

また、serde_json::from_str も変換に失敗する可能性があることから、戻り値は Result 型となります。例えば、フィールドが一致しない場合や、型が合わない場合にエラーとなります。

Serialize と Deserialize を同時に使用する

実際の開発では、ある型に対してシリアライズとデシリアライズを両方行えるようにするケースがほとんどです。その場合には、#[derive(Serialize, Deserialize)] のように両方をまとめて指定します。

use serde::{Deserialize, Serialize};

// Serialize と Deserialize の両方を derive することで
// シリアライズとデシリアライズの両方に対応できる
#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    age: u32,
}

fn main() -> Result<(), serde_json::Error> {
    let user = User {
        name: String::from("Alice"),
        age: 30,
    };

    // 構造体を JSON 文字列に変換（シリアライズ）
    let json = serde_json::to_string(&user)?;
    println!("{json}");

    // JSON 文字列を構造体に変換（デシリアライズ）
    let deserialized_user: User = serde_json::from_str(&json)?;
    println!("{deserialized_user:?}");

    Ok(())
}

【実行結果】
{"name":"Alice","age":30}
User { name: "Alice", age: 30 }

以降では、いくつかよく使用するパターンを紹介します。その際には、#[derive(Serialize, Deserialize)] のように両方を付けた形で紹介していきます。

よく使用するパターン

ネストした型を含む場合

型を定義する際に、構造体のフィールドに別の構造体を持たせることはよくあります。このような場合に、シリアライズ・デシリアライズをする場合には両方に #[derive(Serialize, Deserialize)] を付けて定義しておく必要があることに注意してください。

以下の例では、User 構造体のフィールドとして Address 構造体を持っています。

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct Address {
    city: String,
    zip: String,
}

#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    address: Address,
}

fn main() -> Result<(), serde_json::Error> {
    let user = User {
        name: String::from("Alice"),
        address: Address {
            city: String::from("Tokyo"),
            zip: String::from("100-0001"),
        },
    };

    // 構造体を JSON 文字列に変換（シリアライズ）
    let json = serde_json::to_string_pretty(&user)?;
    println!("{json}");

    // JSON 文字列を構造体に変換（デシリアライズ）
    let deserialized_user: User = serde_json::from_str(&json)?;
    println!("{deserialized_user:?}");

    Ok(())
}

【実行結果】
{
  "name": "Alice",
  "address": {
    "city": "Tokyo",
    "zip": "100-0001"
  }
}
User { name: "Alice", address: Address { city: "Tokyo", zip: "100-0001" } }

例のようにネストした構造体を含めて JSON 文字列に変換できていることが分かります。また、デシリアライズでも、ネストした JSON をそのまま User 構造体に変換できています。

Vec<T> や配列のフィールドを含む場合

複数の値を持つコレクションである Vec<T> についても特別な対応をすることなく、そのまま扱うことが可能です。Vec<T> は JSON の配列に対応します。

以下の例では、先ほどの例における Address を Vec<Address> として表現しています。

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct Address {
    city: String,
    zip: String,
}

#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    addresses: Vec<Address>,
}

fn main() -> Result<(), serde_json::Error> {
    let user = User {
        name: String::from("Alice"),
        addresses: vec![
            Address {
                city: String::from("Tokyo"),
                zip: String::from("100-0001"),
            },
            Address {
                city: String::from("Osaka"),
                zip: String::from("530-0001"),
            },
        ],
    };

    // 構造体を JSON 文字列に変換（シリアライズ）
    let json = serde_json::to_string_pretty(&user)?;
    println!("{json}");

    // JSON 文字列を構造体に変換（デシリアライズ）
    let deserialized_user: User = serde_json::from_str(&json)?;
    println!("{deserialized_user:?}");

    Ok(())
}

【実行結果】
{
  "name": "Alice",
  "addresses": [
    {
      "city": "Tokyo",
      "zip": "100-0001"
    },
    {
      "city": "Osaka",
      "zip": "530-0001"
    }
  ]
}
User { name: "Alice", addresses: [Address { city: "Tokyo", zip: "100-0001" }, Address { city: "Osaka", zip: "530-0001" }] }

Vec<Address> が JSON の配列として表現されていることが分かります。例は、作成した構造体に対してですが、Vec<i32> や Vec<String> のように基本的な型の場合も同様です。

なお、[T; N] のような固定長配列も同様に扱えますが、デシリアライズ時に要素数が一致しないとエラーになります。実用上は要素数を柔軟に扱える Vec<T> を使うことがほとんどです。

Option<T> のフィールドを含む場合

値が存在する場合と存在しない場合がある場合には、Option<T> を使用します。serde では、Option<T> も自然に扱うことができます。

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    email: Option<String>,
}

fn main() -> Result<(), serde_json::Error> {
    let user1 = User {
        name: String::from("Alice"),
        email: Some(String::from("alice@example.com")),
    };
    let user2 = User {
        name: String::from("Bob"),
        email: None,
    };

    // 構造体を JSON 文字列に変換（シリアライズ）
    let json1 = serde_json::to_string(&user1)?;
    let json2 = serde_json::to_string(&user2)?;
    println!("{json1}");
    println!("{json2}");

    // JSON 文字列を構造体に変換（デシリアライズ）
    let deserialized_user1: User = serde_json::from_str(&json1)?;
    let deserialized_user2: User = serde_json::from_str(&json2)?;
    println!("{deserialized_user1:?}");
    println!("{deserialized_user2:?}");

    Ok(())
}

【実行結果】
{"name":"Alice","email":"alice@example.com"}
{"name":"Bob","email":null}
User { name: "Alice", email: Some("alice@example.com") }
User { name: "Bob", email: None }

Option<T> を使用する場合、None は null として JSON 文字列に出力されます。デシリアライズの場合は、JSON 文字列に当該キーが存在しないか、null であれば None に、値があれば Some(値) という形に変換されます。

null を出力せずキー自体を出力したくない場合

Option 型の値が None の際に、null を出力するのではなく、キー自体を出力したくないような場合には、#[serde(skip_serializing_if = "Option::is_none")] を対象のフィールドに付与します。

...(省略)...

#[derive(Serialize, Deserialize, Debug)]
struct User {
    name: String,
    // None の場合はキーごと出力しない
    #[serde(skip_serializing_if = "Option::is_none")]
    email: Option<String>,
}
...(省略)...

【実行結果】
{"name":"Alice","email":"alice@example.com"}
{"name":"Bob"}
User { name: "Alice", email: Some("alice@example.com") }
User { name: "Bob", email: None }

例の結果のようにキー自体が出力されなくなったことが分かります。

まとめ

Rust で serde を用いて JSON を扱う方法について解説しました。serde の入門として最低限理解してほしい内容を中心に説明し、よくある使用例なども紹介しました。

serde は、外部 API との通信や設定ファイルの読み書きなど、様々な場面で利用される非常に重要なクレートで、Rust の学習時に代表例としてよく出てくるものです。今回紹介した基本をしっかりと押さえておくことで今後の様々なクレートの活用にもつながります。

あわせて読みたい

Rust プログラミング入門

HashSet<T> 型

Rust には、同じ型のデータをまとめて管理するための「コレクション（Collections）」が用意されています。コレクションは、実行中に要素数を変更できる柔軟なデータ構造です。

この記事では、コレクション型の代表例である HashSet<T> 型について解説します。

HashSet<T> 型とは

HashSet<T> 型は重複しない値の集合を管理するためのコレクション型です。

HashSet には、次のような特徴があります。

• 重複した要素を保持できない
• 要素の順序は保証されない
• 要素の検索が高速

例えば、「ユーザーIDの重複チェック」「タグ一覧の管理」「特定の値の存在確認」などの目的のためにデータの集合として利用できます。

HashSet の生成方法

HashSet を使う準備

HashSet は標準ライブラリの std::collections モジュールで提供されています。利用するには以下のようにインポートします。

use std::collections::HashSet;

以降で紹介する各プログラムでも先頭でインポートしています。

関連関数 HashSet::new() を使用する

HashSet を生成する最も基本的な方法は、new メソッドを使用する方法です。値を追加するには、insert メソッドを使用します。

use std::collections::HashSet;

fn main() {
    // HashSet を生成する
    let mut set = HashSet::new();

    // 値を追加する
    set.insert(String::from("Alice"));
    set.insert(String::from("Bob"));
    set.insert(String::from("Charlie"));

    println!("{:?}", set);
}

【実行結果】
{"Alice", "Charlie", "Bob"}

なお、HashSet は要素の追加順序を保証しません。そのため、実行により表示順序が異なる場合があります。以降の例についても同様です。

配列から HashSet を生成する

HashSet は配列から生成することも可能です。into_iter().collect() を使うことで配列から HashSet を生成できます。

use std::collections::HashSet;

fn main() {
    // 配列から HashSet を生成する
    let set: HashSet<_> = [1, 2, 3, 4].into_iter().collect();

    println!("生成された HashSet : {set:?}");
}

【実行結果】
生成された HashSet : {3, 1, 4, 2}

Vec から HashSet を生成する

配列同様に Vec から HashSet を生成することもできます。なお、重複した値が Vec に含まれている場合は、自動的に除かれます。

use std::collections::HashSet;

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

    // Vec から HashSet を生成する（重複は自動で除かれる）
    let set: HashSet<_> = numbers.into_iter().collect();

    println!("元の Vec : [1, 2, 2, 3, 3, 4]");
    println!("生成された HashSet : {set:?}");
}

【実行結果】
元の Vec : [1, 2, 2, 3, 3, 4]
生成された HashSet : {1, 2, 4, 3}

上記のように、重複していた 2 と 3 は除かれてユニークな要素のみ保持できていることが確認できます。

use std::collections::HashSet;

fn main() {
    let set: HashSet<_> = [3, 1, 4, 2].into_iter().collect();

    // HashSet から Vec に変換する
    let mut numbers: Vec<_> = set.into_iter().collect();

    // HashSet は順序を持たないため、見やすいように並べ替える
    numbers.sort();

    println!("変換後の Vec : {numbers:?}");
}

【実行結果】
変換後の Vec : [1, 2, 3, 4]

HashSet の操作（要素の取得・追加・削除など）

HashSet 型では、要素の取得・追加・削除などの各種メソッドが用意されています。

要素の取得

HashSet の要素値を取得するには、get メソッドにより取得する値を指定します。

use std::collections::HashSet;

fn main() {
    let mut names = HashSet::new();

    names.insert(String::from("Alice"));
    names.insert(String::from("Bob"));

    // 要素を取得する
    let alice = names.get("Alice");
    match alice {
        Some(name) => println!("取得できた要素 : {name}"),
        None => println!("要素が見つかりませんでした。"),
    }

    let charlie = names.get("Charlie");
    match charlie {
        Some(name) => println!("取得できた要素 : {name}"),
        None => println!("Charlie は存在しません。"),
    }
}

【実行結果】
取得できた要素 : Alice
Charlie は存在しません。

get は、Option<&T> 型 を返却するため、match を使って値の有無を確認して安全に処理することが可能です。指定した値が存在しない場合には、None となります。

要素の追加

新しい要素の追加や更新には、insert メソッドを使用します。例のように、既に同じ値が存在する場合は、追加されず HashSet の内容は変化しません。

use std::collections::HashSet;

fn main() {
    let mut names = HashSet::new();

    println!("追加前 : {names:?}");

    // 要素を追加する
    names.insert(String::from("Alice"));
    names.insert(String::from("Bob"));

    println!("追加後 : {names:?}");

    // 同じ値を追加しても重複しない
    names.insert(String::from("Alice"));

    println!("同じ値を再追加した後 : {names:?}");
}

【実行結果】
追加前 : {}
追加後 : {"Alice", "Bob"}
同じ値を再追加した後 : {"Alice", "Bob"}

要素の削除

要素を削除する場合には、remove メソッドを使用します。存在しない値を削除しようとしても何も起こりません。

use std::collections::HashSet;

fn main() {
    let mut names = HashSet::new();

    names.insert(String::from("Alice"));
    names.insert(String::from("Bob"));
    names.insert(String::from("Charlie"));

    println!("削除前 : {names:?}");

    // 要素を削除する
    names.remove("Alice");

    println!("Alice 削除後 : {names:?}");

    // 存在しない要素を削除しても変化しない
    names.remove("Dave");

    println!("Dave 削除後（変化なし） : {names:?}");
}

【実行結果】
削除前 : {"Bob", "Charlie", "Alice"}
Alice 削除後 : {"Bob", "Charlie"}
Dave 削除後（変化なし） : {"Bob", "Charlie"}

要素数の取得

HashSet に含まれる要素数を取得するには、len メソッドを使用します。

use std::collections::HashSet;

fn main() {
    let mut names = HashSet::new();

    let len = names.len();
    println!("初期状態の要素数 : {len}");

    names.insert(String::from("Alice"));
    names.insert(String::from("Bob"));

    let len = names.len();
    println!("追加後の要素数 : {len}");

    names.remove("Alice");

    let len = names.len();
    println!("削除後の要素数 : {len}");
}

【実行結果】
初期状態の要素数 : 0
追加後の要素数 : 2
削除後の要素数 : 1

要素の存在確認

HashSet に指定した値が存在するかどうかを確認するには、contains メソッドを使用します。指定値が存在するかは bool 型の返却値として確認できます。

use std::collections::HashSet;

fn main() {
    let mut names = HashSet::new();

    names.insert(String::from("Alice"));
    names.insert(String::from("Bob"));

    // 要素の存在を確認する
    let contains_alice = names.contains("Alice");
    let contains_charlie = names.contains("Charlie");
    println!("Alice は存在するか : {contains_alice}");
    println!("Charlie は存在するか : {contains_charlie}");
}

【実行結果】
Alice は存在するか : true
Charlie は存在するか : false

繰り返し処理（for）での利用方法

HashSet は複数の要素を管理するため、for を利用した繰り返し処理を行うことがよくあります。Rust の繰り返しでは、イテレータを取得して動作します。

参照のみの繰り返し処理

HashSet の要素を 1 つずつ取り出して参照するだけの繰り返しの場合には、以下のように不変参照 (&) を使って for を使用します。ループ後も元の HashSet を引き続き利用できます。

use std::collections::HashSet;

fn main() {
    let mut names = HashSet::new();

    names.insert(String::from("Alice"));
    names.insert(String::from("Bob"));
    names.insert(String::from("Charlie"));

    // 所有権を移動せず、参照としてループする
    for name in &names {
        println!("名前 : {name}");
    }

    // ループ後も names を使える
    println!("ループ後の要素数 : {}", names.len());
}

【実行結果】
名前 : Charlie
名前 : Bob
名前 : Alice
ループ後の要素数 : 3

なお、HashSet は要素がキーなので、要素を直接変更するという考え方が基本的にありません。そのため、HashMap ではあった値を変更を伴う繰り返し (iter_mut) はありません。

所有権を移動する繰り返し処理

HashSet の所有権を移動して繰り返し処理をする場合には、以下のように in の部分に HashSet の変数を直接指定します。所有権を移動する繰り返し処理をした場合には、繰り返し後には変数を使うことができなくなる点に注意が必要です。

use std::collections::HashSet;

fn main() {
    let mut names = HashSet::new();

    names.insert(String::from("Alice"));
    names.insert(String::from("Bob"));
    names.insert(String::from("Charlie"));

    // 所有権を移動してループする
    for name in names {
        println!("名前 : {name}");
    }

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

【実行結果】
名前 : Charlie
名前 : Bob
名前 : Alice

この方法は、ループ後に元の HashSet を使わない場合や、大きいサイズの HashSet であるためループ終了にあわせてメモリ解放したい場合などに利用できます。

集合演算と包含関係の判定

集合演算

HashSet には、数学の集合演算に対応した各種メソッドが用意されています。

積集合

積集合を計算するには、intersection メソッドを使用します。積集合では、両方の集合に含まれる要素を取得できます。

use std::collections::HashSet;

fn main() {
    let set_a: HashSet<_> = [1, 2, 3, 4].into_iter().collect();
    let set_b: HashSet<_> = [3, 4, 5, 6].into_iter().collect();

    // 積集合（両方に含まれる要素）
    let intersection: HashSet<_> = set_a.intersection(&set_b).copied().collect();

    println!("A: {set_a:?}");
    println!("B: {set_b:?}");
    println!("A ∩ B: {intersection:?}");
}

【実行結果】
A: {3, 4, 2, 1}
B: {3, 4, 5, 6}
A ∩ B: {4, 3}

intersection などの集合演算メソッドは、元の集合の要素への参照を返すイテレータになっています。例の i32 のように Copy トレイトを実装している場合は、copied() を呼ぶことで参照 (&i32) を値 (i32) にコピーし、collect により HashSet<i32> として集約できます。

なお、所有権を持つ String のような Copy トレイトを実装していない型の場合は、cloned() を使用するか、参照のままの HashSet<&String> として扱うことになります。

和集合

和集合を計算するには、union メソッドを使用します。和集合では、どちらかの集合に含まれる要素が取得され、重複要素は自動で除かれます。

use std::collections::HashSet;

fn main() {
    let set_a: HashSet<_> = [1, 2, 3].into_iter().collect();
    let set_b: HashSet<_> = [3, 4, 5].into_iter().collect();

    // 和集合（どちらかに含まれる要素）
    let union: HashSet<_> = set_a.union(&set_b).copied().collect();

    println!("A: {set_a:?}");
    println!("B: {set_b:?}");
    println!("A ∪ B: {union:?}");
}

【実行結果】
A: {1, 2, 3}
B: {3, 4, 5}
A ∪ B: {1, 3, 5, 2, 4}

差集合

差集合を計算するには、differenceメソッドを使用します。差集合の場合は、順序が重要になり、以下の例で A - B の場合は、A にのみ含まれる要素を取得できます。一方で、B - A の場合は、B にのみ含まれる要素を取得できます。

use std::collections::HashSet;

fn main() {
    let set_a: HashSet<_> = [1, 2, 3, 4].into_iter().collect();
    let set_b: HashSet<_> = [3, 4, 5].into_iter().collect();

    // 差集合（A にだけ含まれる要素）
    let difference_a_b: HashSet<_> = set_a.difference(&set_b).copied().collect();

    // 差集合（B にだけ含まれる要素）
    let difference_b_a: HashSet<_> = set_b.difference(&set_a).copied().collect();

    println!("A: {set_a:?}");
    println!("B: {set_b:?}");
    println!("A - B: {difference_a_b:?}");
    println!("B - A: {difference_b_a:?}");
}

【実行結果】
A: {4, 2, 1, 3}
B: {3, 4, 5}
A - B: {1, 2}
B - A: {5}

排他的論理和

排他的論理和を計算するには、symmetric_difference メソッドを使用します。排他的論理和では、どちらか一方にのみ含まれる要素を取得します。

use std::collections::HashSet;

fn main() {
    let set_a: HashSet<_> = [1, 2, 3, 4].into_iter().collect();
    let set_b: HashSet<_> = [3, 4, 5, 6].into_iter().collect();

    // 排他的論理和（片方にだけ含まれる要素）
    let symmetric_difference: HashSet<_> = set_a.symmetric_difference(&set_b).copied().collect();

    println!("A: {set_a:?}");
    println!("B: {set_b:?}");
    println!("A △ B: {symmetric_difference:?}");
}

【実行結果】
A: {1, 4, 3, 2}
B: {4, 5, 6, 3}
A △ B: {6, 1, 2, 5}

集合の包含関係の判定方法

HashSet には、集合同士の包含関係を判定するメソッドも各種用意されています。

集合が等しいかどうかの判定

集合が等しいかを判定するには、== 演算子を使用します。要素の順序は関係ありません。

use std::collections::HashSet;

fn main() {
    let set_a: HashSet<_> = ["Alice", "Bob", "Charlie"].into_iter().collect();
    let set_b: HashSet<_> = ["Charlie", "Alice", "Bob"].into_iter().collect();
    let set_c: HashSet<_> = ["Alice", "Bob"].into_iter().collect();

    // 集合が等しいか判定する
    let eq_ab = set_a == set_b;
    let eq_ac = set_a == set_c;
    println!("A と B は等しいか : {eq_ab}");
    println!("A と C は等しいか : {eq_ac}");
}

【実行結果】
A と B は等しいか : true
A と C は等しいか : false

set_a と set_b は順序は異なっていますが、含まれる要素が同じため true となります。

上位集合の判定

ある集合が別の集合の全要素を含む場合を上位集合と言います。上位集合かどうかを判定するには、is_superset メソッドを使用します。

use std::collections::HashSet;

fn main() {
    let all_members: HashSet<_> = ["Alice", "Bob", "Charlie"].into_iter().collect();
    let team_a: HashSet<_> = ["Alice", "Bob"].into_iter().collect();

    // 上位集合かどうかを判定する
    let is_superset_all = all_members.is_superset(&team_a);
    let is_superset_team = team_a.is_superset(&all_members);
    println!("all_members は team_a の上位集合か : {is_superset_all}");
    println!("team_a は all_members の上位集合か : {is_superset_team}");
}

【実行結果】
all_members は team_a の上位集合か : true
team_a は all_members の上位集合か : false

部分集合の判定

ある集合が別の集合に完全に含まれる場合を部分集合と言います。部分集合かどうかを判定するには、is_subset メソッドを使用します。

use std::collections::HashSet;

fn main() {
    let all_members: HashSet<_> = ["Alice", "Bob", "Charlie"].into_iter().collect();
    let team_a: HashSet<_> = ["Alice", "Bob"].into_iter().collect();

    // 部分集合かどうかを判定する
    let is_subset_team = team_a.is_subset(&all_members);
    let is_subset_all = all_members.is_subset(&team_a);
    println!("team_a は all_members の部分集合か : {is_subset_team}");
    println!("all_members は team_a の部分集合か : {is_subset_all}");
}

【実行結果】
team_a は all_members の部分集合か : true
all_members は team_a の部分集合か : false

共通要素の有無の判定

2 つの集合に共通する要素が存在しないかどうかを判定するには、is_disjoint メソッドを使います。共通要素がなければ true、1 つでもあれば false が返ります。

use std::collections::HashSet;

fn main() {
    let set_a: HashSet<_> = [1, 2, 3].into_iter().collect();
    let set_b: HashSet<_> = [4, 5, 6].into_iter().collect();
    let set_c: HashSet<_> = [3, 7, 8].into_iter().collect();

    // 共通要素がないかどうかを判定する
    let is_disjoint_ab = set_a.is_disjoint(&set_b);
    let is_disjoint_ac = set_a.is_disjoint(&set_c);
    println!("A と B に共通要素はない : {is_disjoint_ab}");
    println!("A と C に共通要素はない : {is_disjoint_ac}");
}

【実行結果】
A と B に共通要素はない : true
A と C に共通要素はない : false

intersection を使って確認することも可能ですが、単純に共通要素の有無だけを確認したい場合は、is_disjoint を使うと簡潔に記載できます。

まとめ

Rust で重複しない要素の集合を管理するための HashSet 型の基本を解説しました。

HashSet は、重複しない要素の集合を管理するためのコレクション型です。要素の追加・削除、存在確認といった基本操作に加えて、積集合・和集合・差集合などの集合演算や包含関係判定などについて紹介しました。

重複削除や高速な存在確認が必要な場面では、Vec や HashMap の代わりに HashSet の利用を検討してみてください。

あわせて読みたい

Rust プログラミング入門

HashMap<K, V> 型

Rust には、同じ型のデータをまとめて管理するための「コレクション（Collections）」が用意されています。コレクションは、実行中に要素数を変更できる柔軟なデータ構造です。

この記事では、コレクション型の代表例である HashMap<K, V> 型について解説します。

HashMap<K, V> 型とは

HashMap<K, V> 型は、キー（Key）と値（Value）のペアでデータを管理するためのコレクション型です。

Vec<T> 型がインデックスで要素にアクセスするのに対して、HashMap はキーを使って値を取得します。コレクション型は、内部でヒープ領域を利用してデータを管理するため、プログラム実行時のデータ長の変更や大きなサイズのデータの扱いに適します。

例えば、「ユーザー ID からユーザー名を取得する」「商品 ID から価格を取得する」というような場合を扱う際のデータ管理に非常に適しています。

HashMap の生成方法

HashMap を使う準備

HashMap は標準ライブラリの std::collections モジュールで提供されています。利用するには以下のようにインポートします。

use std::collections::HashMap;

以降で紹介する各プログラムでも先頭でインポートをしています。

関連関数 HashMap::new() を使用する

HashMap 型を生成する最も基本的な方法は、new メソッドを使用する方法です。キーや値を追加するには、insert メソッドを使用します。

use std::collections::HashMap;

fn main() {
    // HashMap を生成する
    let mut scores = HashMap::new();

    // キー、値を追加する
    scores.insert(String::from("Alice"), 80);
    scores.insert(String::from("Bob"), 100);

    println!("{:?}", scores);
}

【実行結果】
{"Alice": 80, "Bob": 100}

なお、HashMap は要素の順序を保証しません。そのため、実行により表示順序が異なる場合があります。

collect メソッドを使用する

HashMap は、イテレータから collect メソッドを使用して生成することも可能です。

use std::collections::HashMap;

fn main() {
    let keys = vec![String::from("Alice"), String::from("Bob")];
    let values = vec![80, 10];

    let scores: HashMap<String, i32> = keys.into_iter().zip(values.into_iter()).collect();

    println!("{:?}", scores);
}

【実行結果】
{"Alice": 80, "Bob": 10}

上記例では、keys と values という Vec 型の変数を用意し、zip によりペアを生成して collect により HashMap 型に集約しています。collect メソッドは任意のコレクションにまとめることができるため、型注釈をつけるようにしてください。

HashMap 要素の取得・追加・更新・削除

要素の取得

HashMap の要素値を取得するには、get メソッドによりキーを指定します。

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();

    // Alice のスコアを追加
    scores.insert(String::from("Alice"), 80);

    // Alice のスコアを取得
    let alice_score = scores.get("Alice");
    match alice_score {
        Some(score) => println!("Alice のスコア : {}", score),
        None => println!("Alice のスコアが見つかりませんでした。"),
    }

    // Bob のスコアを取得（存在しないキー）
    let bob_score = scores.get("Bob");
    match bob_score {
        Some(score) => println!("Bob のスコア : {}", score),
        None => println!("Bob のスコアが見つかりませんでした。"),
    }
}

【実行結果】
Alice のスコア : 80
Bob のスコアが見つかりませんでした。

get は、Option<&V> 型 を返却するため、match を使って値の有無を確認して安全に処理することが可能です。キーが存在しない場合には、None となります。

要素の追加・更新

新しい要素の追加や更新には、insert メソッドを使用します。例のように、同じキーに対して insert を実行すると更新となる点に注意してください。

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();

    println!("初期状態 : {:?}", scores);

    // スコアを追加する
    scores.insert(String::from("Alice"), 80);
    scores.insert(String::from("Bob"), 100);

    println!("追加後 : {:?}", scores);

    // Alice のスコアを更新する（上書き）
    scores.insert(String::from("Alice"), 95);

    println!("更新後 : {:?}", scores);
}

【実行結果】
初期状態 : {}
追加後 : {"Bob": 100, "Alice": 80}
更新後 : {"Bob": 100, "Alice": 95}

なお、String のような所有権を持つ型の場合、変数を使用している場合は、insert 時に所有権が移動し、元の変数は使えなくなるので注意しましょう。

let name = String::from("Alice");

scores.insert(name, 80);

// 所有権が移動するためエラーとなる。
// println!("{name}");

要素の削除

要素を削除する場合には、remove メソッドを使用します。存在しないキーを削除しても何も起こりません。

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();

    scores.insert(String::from("Alice"), 80);
    scores.insert(String::from("Bob"), 100);
    scores.insert(String::from("Charlie"), 70);

    println!("削除前 : {:?}", scores);

    // キーを指定して削除する
    scores.remove("Alice");

    println!("Alice 削除後 : {:?}", scores);

    // 存在しないキーを削除しても何も起きない
    scores.remove("Dave");

    println!("Dave 削除後（変化なし） : {:?}", scores);
}

【実行結果】
削除前 : {"Bob": 100, "Charlie": 70, "Alice": 80}
Alice 削除後 : {"Bob": 100, "Charlie": 70}
Dave 削除後（変化なし） : {"Bob": 100, "Charlie": 70}

存在しない場合のみ値を追加する場合（Entry API）

HashMap にキーが存在しない場合にのみ値を追加したい場合は、Entry API を使用するのが便利です。entry により対象を取得し、or_insert で値を追加することで、存在しない場合にのみ値を追加することができます。

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();

    scores.insert(String::from("Alice"), 80);

    println!("初期状態 : {:?}", scores);

    // Alice はすでに存在するので更新されない
    scores.entry(String::from("Alice")).or_insert(0);

    // Bob は存在しないので追加される
    scores.entry(String::from("Bob")).or_insert(100);

    println!("or_insert 後 : {:?}", scores);
}

【実行結果】
初期状態 : {"Alice": 80}
or_insert 後 : {"Bob": 100, "Alice": 80}

繰り返し処理（for）での利用方法

HashMap は複数の要素を管理するため、for を利用した繰り返し処理を行うことがよくあります。Rust の繰り返しでは、イテレータを取得して動作します。

参照のみの繰り返し処理

HashMap の要素を 1 つずつ取り出して参照するだけの繰り返しの場合には、以下のように不変参照 (&) を使って for を使用します。ループ後も元の HashMap を引き続き利用できます。

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();

    scores.insert(String::from("Alice"), 80);
    scores.insert(String::from("Bob"), 100);
    scores.insert(String::from("Charlie"), 70);

    // 所有権を移動せず参照としてループする
    for (name, score) in &scores {
        println!("{name} のスコア : {score}");
    }

    // ループ後も scores を使用できる
    println!("ループ後のエントリ数 : {}", scores.len());
}

【実行結果】
Bob のスコア : 100
Alice のスコア : 80
Charlie のスコア : 70
ループ後のエントリ数 : 3

キーと値は、(name, score) にそれぞれ 1 要素ずつ取り出して繰り返し処理が進みます。

値の変更を伴う繰り返し処理

HashMap の要素を繰り返しの中で変更する場合には、以下のように可変参照 (&mut) を使って for を使用します。

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();

    scores.insert(String::from("Alice"), 80);
    scores.insert(String::from("Bob"), 100);
    scores.insert(String::from("Charlie"), 70);

    println!("更新前 : {:?}", scores);

    // 可変参照でループし、全員のスコアに 10 を加算する
    for (_name, score) in &mut scores {
        *score += 10;
    }

    println!("更新後 : {:?}", scores);
}

【実行結果】
更新前 : {"Alice": 80, "Bob": 100, "Charlie": 70}
更新後 : {"Alice": 90, "Bob": 110, "Charlie": 80}

値を変更する場合には、*score のように参照を外して変更することが可能です。

所有権の移動を伴う繰り返し処理

HashMap の所有権を移動して繰り返し処理をする場合には、以下のように in の部分に HashMap の変数を直接指定します。所有権を移動する繰り返し処理をした場合には、繰り返し後には変数を使うことができなくなる点に注意が必要です。

use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();

    scores.insert(String::from("Alice"), 80);
    scores.insert(String::from("Bob"), 100);
    scores.insert(String::from("Charlie"), 70);

    // 所有権を移動させてループする
    for (name, score) in scores {
        println!("{name} のスコア : {score}");
    }

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

【実行結果】
Charlie のスコア : 70
Bob のスコア : 100
Alice のスコア : 80

この方法は、ループ後に元の HashMap を使わない場合や、大きいサイズの HashMap であるためループ終了にあわせてメモリ解放したい場合などに利用できます。

まとめ

Rust でデータをキーと値のペアで管理するための HashMap 型の基本を解説しました。

HashMap<K, V> 型は、キーと値のペアでデータを管理するためのコレクション型です。ユーザー ID とユーザー名、商品 ID と価格など、対応関係を持つデータを効率的に管理できます。

この記事では、HashMap の生成方法から要素の取得・追加・更新・削除、Entry API を利用した値の追加方法、for を使った繰り返し処理まで紹介しました。

HashMap は Rust のプログラムで非常によく利用されるコレクション型です。Vec 型とあわせて使う機会も多いため、この記事で紹介した基本操作をしっかり身につけておきましょう。

あわせて読みたい

Rust プログラミング入門

イテレータの消費とは

イテレータ（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 プログラミング入門