Comprehensive Rust 🦀 へようこそ

This is a free Rust course developed by the Android team at Google. The course covers the full spectrum of Rust, from basic syntax to advanced topics like generics and error handling.

コースの最新バージョンは https://google.github.io/comprehensive-rust/ にあります。他の場所でお読みの場合は、そちらで最新情報をご確認ください。

The course is available in other languages. Select your preferred language in the top right corner of the page or check the Translations page for a list of all available translations.

The course is also available as a PDF.

本講座の目的は、Rustを教える事です。Rustに関する前提知識は不要としており、次の目標を設定しています：

• Rustの基本構文と言語についての理解を深める。
• 既存のプログラムを修正したり、新規プログラムをRustで書けるようにする。
• 一般的なRustのイディオムを紹介する。

コースの最初の4日間を「Rust の基礎」と呼びます。

Building on this, you're invited to dive into one or more specialized topics:

• Android: a half-day course on using Rust for Android platform development (AOSP). This includes interoperability with C, C++, and Java.
• Chromium: a half-day course on using Rust within Chromium based browsers. This includes interoperability with C++ and how to include third-party crates in Chromium.
• Bare-metal: a whole-day class on using Rust for bare-metal (embedded) development. Both microcontrollers and application processors are covered.
• Concurrency: a whole-day class on concurrency in Rust. We cover both classical concurrency (preemptively scheduling using threads and mutexes) and async/await concurrency (cooperative multitasking using futures).

本講座の対象外

Rustは非常に汎用性の高い言語であり、数日で全てを網羅する事はできません。本講座の目標として設定されていないものには、以下のようなものがあります：

• Learning how to develop macros: please see Chapter 19.5 in the Rust Book and Rust by Example instead.

前提知識

The course assumes that you already know how to program. Rust is a statically-typed language and we will sometimes make comparisons with C and C++ to better explain or contrast the Rust approach.

If you know how to program in a dynamically-typed language such as Python or JavaScript, then you will be able to follow along just fine too.

講座の運営について

このページは講師用です。

以下は、Google内での講座の運営方法に関する情報です。

クラスは通常午前9時から午後4時までで、途中で1時間の昼食休憩があります。つまり、午前のクラスが3時間、午後のクラスが3時間となります。どちらのセッションにも、休憩と、受講者が演習に取り組むための時間が複数回含まれています。

講座開始までに、以下にあげる準備を済ませておくと良いでしょう：

1. 資料に慣れておいてください。要点を強調するためにスピーカーノートが用意されています（内容の追加にご協力ください！）。プレゼン時には、スクリーンを見やすい状態で保つために、スピーカーノートはポップアップウィンドウで開いてください（スピーカーノートの横にある小さな矢印をクリック）。

2. Decide on the dates. Since the course takes four days, we recommend that you schedule the days over two weeks. Course participants have said that they find it helpful to have a gap in the course since it helps them process all the information we give them.

3. 十分な広さの部屋を確保しておいてください。15~25名程度のクラスを推奨しています。受講者にとって質問がしやすい人数であり、1人の講師が質問に答える時間も確保できる規模だからです。また、皆さんはPCで作業をする必要があるため、講師を含めた人数分の机を用意しておいてください。ライブコーディング形式での実施を想定しているため、講壇は不要です。

4. 当日は少し早めに到着して準備をしてください。自分のPCで実行するmdbook serveから直接プレゼンを行う事を推奨します（インストール手順はこちら）。これにより、ページ切り替え時に遅延なしで最適なパフォーマンスが得られます。また、PCを使用する事で、受講者や自分自身が見つけたタイプミスなども修正可能になります。

5. 練習問題は個人か小さいグループで解いてください。回答をレビューする時間も含め、各練習問題に30~45分を費やします。受講者が行き詰まっているかどうか、何か質問があるかなど確認してください。複数の受講者が同じ問題で詰まっている場合、クラス全体に対してそれを共有し、解決策を提供してください。例えば、探している情報が標準ライブラリのどこにあるかを示す、など。

以上です。運営頑張ってください！皆さんにとっても楽しい時間になりますように！

本講座の改善に向けてフィードバックをお願いします。うまくいった点や改善点について幅広くご意見お聞かせください。受講者からのフィードバックも歓迎しております！

講座の構成

このページは講師用です。

Rust の基礎

Rust の基礎 を構成する最初の 4 日間で、さまざまな項目を駆け足で学びます。

コースのスケジュール:

• Day 1 Morning (2 hours and 5 minutes, including breaks)

• Day 1 Afternoon (2 hours and 35 minutes, including breaks)

• Day 2 Morning (2 hours and 10 minutes, including breaks)

• Day 2 Afternoon (3 hours and 15 minutes, including breaks)

• Day 3 Morning (2 hours and 20 minutes, including breaks)

• Day 3 Afternoon (1 hour and 55 minutes, including breaks)

• Day 4 Morning (2 hours and 40 minutes, including breaks)

• Day 4 Afternoon (2 hours and 20 minutes, including breaks)

専門的なトピック

In addition to the 4-day class on Rust Fundamentals, we cover some more specialized topics:

Rust in Android

The Rust in Android deep dive is a half-day course on using Rust for Android platform development. This includes interoperability with C, C++, and Java.

AOSPのチェックアウトが必要です。同じ端末から講座のリポジトリをチェックアウトし、src/android/ディレクトリをAOSPチェックアウトのルートに移動してください。これにより、Androidビルドシステムがsrc/android/内のAndroid.bpを確認できるようになります。

エミュレータまたは実際のデバイスでadb syncが機能する事を確認し、src/android/build_all.shを使用して全てのAndroidの例を事前にビルドしてください。スクリプトを読んで実行コマンドを確認し、手動で実行した際に正常に動作する事を確認してください。

Rust in Chromium

Chromium での Rust は半日コースで、Chromium ブラウザの一部として Rust を使用する方法について詳しく説明します。Chromium の gn ビルドシステムで Rust を使用することで、サードパーティ ライブラリ（「クレート」）、および C++ との相互運用性を導入できます。

受講者は、Chromium をビルドできる必要があります。時間を短縮できるデバッグのコンポーネント ビルドを 推奨 しますが、どのようなビルドでも問題ありません。作成した Chromium ブラウザを実行できることを確認します。

Bare-Metal Rust

The Bare-Metal Rust deep dive is a full day class on using Rust for bare-metal (embedded) development. Both microcontrollers and application processors are covered.

マイクロコントローラの章では、事前にBBCmicro:bitv2開発ボードを購入する必要があります。また、welcomeページで説明されているように、複数のパッケージをインストールする必要があります。

Rustでの並行性

The Concurrency in Rust deep dive is a full day class on classical as well as async/await concurrency.

新規クレートの作成と、依存関係（dependencies）のダウンロードが必要です。その後、例をsrc/main.rsにコピペして実行する事ができます：

cargo init concurrency
cd concurrency
cargo add tokio --features full
cargo run

コースのスケジュール:

• Morning (3 hours and 20 minutes, including breaks)

• Afternoon (3 hours and 20 minutes, including breaks)

フォーマット

本講座はインタラクティブな形式で行います。積極的に質問して、Rustへの理解を深めてください！

キーボード ショートカット

mdBookには、便利なショートカットキーがいくつか存在します：

• Arrow-Left: Navigate to the previous page.
• Arrow-Right: Navigate to the next page.
• Ctrl + Enter: Execute the code sample that has focus.
• s: Activate the search bar.

翻訳

本資料は、ボランティアによって翻訳されています：

• ポルトガル語（ブラジル）: @rastringer、@hugojacob、@joaovicmendes、@henrif75
• Chinese (Simplified) by @suetfei, @wnghl, @anlunx, @kongy, @noahdragon, @superwhd, @SketchK, and @nodmp.
• 中国語（繁体字）: @hueich、@victorhsieh、@mingyc、@kuanhungchen、@johnathan79717
• Farsi by @DannyRavi, @javad-jafari, @Alix1383, @moaminsharifi , @hamidrezakp and @mehrad77.
• Japanese by @CoinEZ-JPN, @momotaro1105, @HidenoriKobayashi and @kantasv.
• Korean by @keispace, @jiyongp, @jooyunghan, and @namhyung.
• スペイン語: @deavid
• Ukrainian by @git-user-cpp, @yaremam and @reta.
• Farsi by @DannyRavi, @javad-jafari, @Alix1383, @moaminsharifi, @hamidrezakp and @mehrad77.

画面右上の言語切り替えボタンから、切り替えを行なってください。

Incomplete Translations

進行中の翻訳が多数あります。最新の翻訳へのリンクを以下に示します。

• Arabic by @younies
• ベンガル語: @raselmandol
• French by @KookaS, @vcaen and @AdrienBaudemont.
• ドイツ語: @Throvn、@ronaldfw
• Italian by @henrythebuilder and @detro.

The full list of translations with their current status is also available either as of their last update or synced to the latest version of the course.

この取り組みにご協力いただける場合は、our instructionsをご覧ください。翻訳はissue trackerで管理されています。

Cargoの使用

Rustを学び始めると、まもなくRustエコシステムで広く使われているビルドシステム兼パッケージマネージャであるCargoという標準ツールに出会います。ここでは、Cargoの概要や使用方法、そして本講座における重要性について簡単に説明します。

インストール

https://rustup.rs/ の手順に沿ってインストールしてください。

This will give you the Cargo build tool (cargo) and the Rust compiler (rustc). You will also get rustup, a command line utility that you can use to install to different compiler versions.

Rust をインストールしたら、Rust で動作するようにエディタまたは IDE を設定する必要があります。ほとんどのエディタでは、rust-analyzer と通信することでこれを行います。rust-analyzer は、VS Code、Emacs、Vim / Neovim など、多くのエディタ向けにオートコンプリート機能と「定義に移動」機能を提供します。RustRover という別の IDE も用意されています。

Rust エコシステム

Rustエコシステムの主要ツールは以下の通りです：

• rustc： Rustのコンパイラです。.rsファイルをバイナリや他の中間形式に変換します。

• cargo: the Rust dependency manager and build tool. Cargo knows how to download dependencies, usually hosted on https://crates.io, and it will pass them to rustc when building your project. Cargo also comes with a built-in test runner which is used to execute unit tests.

• rustup: the Rust toolchain installer and updater. This tool is used to install and update rustc and cargo when new versions of Rust are released. In addition, rustup can also download documentation for the standard library. You can have multiple versions of Rust installed at once and rustup will let you switch between them as needed.

講座のサンプルコード

本講座は、主にブラウザ内で実行可能な例を使います。こうする事で、セットアップが容易になり、一貫した開発環境の提供が可能となります。

ただし、できればCargoをインストールしてください： 練習問題で使えると便利です。また最終日に依存関係を扱う課題を扱いますが、そこではCargoが必要になります。

講座のコードブロックはインタラクティブです：

fn main() {
    println!("Edit me!");
}

You can use Ctrl + Enter to execute the code when focus is in the text box.

Cargoを使ってローカルで実行

コードをローカルで試したい場合、Rust Bookの手順に従ってRustをインストールしてください。正常にインストールされたら、rustcとcargoが使えるようになります。最新のstableリリースのバージョンは以下の通りです：

% rustc --version
rustc 1.69.0 (84c898d65 2023-04-16)
% cargo --version
cargo 1.69.0 (6e9a83356 2023-04-12)

Rust は下位互換性を維持しているため、新しいバージョンを使用することもできます。

With this in place, follow these steps to build a Rust binary from one of the examples in this training:

1. 「Copy to clipboard」でコードをコピー。

2. cargo new exerciseでexercise/ディレクトリを作成：

   $ cargo new exercise
        Created binary (application) `exercise` package
   

3. exercise/ディレクトリに移動し、cargo runでバイナリをビルドして実行：

   $ cd exercise
   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.75s
        Running `target/debug/exercise`
   Hello, world!
   

4. src/main.rsのボイラープレートコードを、コピーしたコードで置き換えてください。例えば、前のページの例を使った場合、src/main.rsは以下のようになります。

   fn main() {
       println!("Edit me!");
   }

5. cargo runで更新されたバイナリをビルドして実行：

   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.24s
        Running `target/debug/exercise`
   Edit me!
   

6. cargo checkでプロジェクトのエラーチェックを行い、cargo buildでコンパイルだけ（実行はせず）を行います。通常のデバッグビルドでは、生成されたファイルはtarget/debug/に格納されます。最適化されたリリースビルドにはcargo build —releaseを使い、ファイルはtarget/release/に格納されます。

7. プロジェクトに依存関係を追加するには、Cargo.tomlを編集します。その後、cargoコマンドを実行すると、自動的に不足している依存関係がダウンロードされてコンパイルされます。

Day 1へようこそ

This is the first day of Rust Fundamentals. We will cover a lot of ground today:

• Rustの基本的な構文： 変数、スカラー型と複合型、列挙型、構造体、参照、関数、メソッド。
• Types and type inference.
• 制御フローの構造: ループ、条件など。
• ユーザー定義型: 構造体と列挙型。
• パターン マッチング: 列挙型、構造体、配列の分解。

スケジュール

Including 10 minute breaks, this session should take about 2 hours and 5 minutes. It contains:

Hello, World

This segment should take about 15 minutes. It contains:

Rustとは？

Rustは2015年に1.0版がリリースされた新しいプログラミング言語です：

• RustはC++と同様に、静的にコンパイルされる言語です
  • rustcはバックエンドにLLVMを使用しています。
• Rustは多くのプラットフォームとアーキテクチャをサポートしています：
  • x86, ARM, WebAssembly, …
  • Linux, Mac, Windows, …
• Rustは様々なデバイスで使用されています：
  • ファームウェアやブートローダ、
  • スマートディスプレイ、
  • 携帯電話、
  • デスクトップ、
  • サーバ。

Rustのメリット

Rustのユニークなセールスポイントをいくつか紹介します：

• コンパイル時のメモリ安全性 - クラス全体のメモリのバグをコンパイル時に防止します。

  • 未初期化の変数がない。
  • 二重解放が起きない。
  • 解放済みメモリ使用（use-after-free）がない。
  • NULL（ヌル）ポインタがない。
  • ミューテックス（mutex）のロックの解除忘れがない。
  • スレッド間でデータ競合しない。
  • イテレータが無効化されない。

• 未定義のランタイム動作がない - Rust ステートメントで行われる処理が未規定のまま残ることはありません。

  • 配列へのアクセスには境界チェックが行われる。
  • Integer overflow is defined (panic or wrap-around).

• 最新の言語機能 - 高水準言語に匹敵する表現力があり、人間が使いやすい機能を備えています。

  • 列挙型とパターンマッチング
  • ジェネリクス
  • オーバーヘッドのないFFI
  • ゼロコスト抽象化
  • 優秀なコンパイルエラー。
  • 組み込みの依存関係マネージャ。
  • 組み込みのテストサポート。
  • Language Server Protocol（LSP）のサポート。

プレイグラウンド

このコースの例や演習には、短い Rust プログラムを簡単に実行できる Rust プレイグラウンド を使用します。最初の「hello-world」プログラムを実行してみましょう。次のような便利な機能があります。

• 「Tools」 にある rustfmt オプションを使用して、コードを「standard」の形式でフォーマットします。

• Rust には、コードを生成するための主要な「プロファイル」が 2 つあります。1 つは Debug（追加のランタイムチェックがあり、最適化が少ない）で、もう 1 つは Release（ランタイムチェックが少なく、最適化が多い）です。これらは上部の [Debug] からアクセスできます。

• 興味がある場合は、「...」 の下にある 「ASM」 を使用すると、生成されたアセンブリ コードを確認できます。

型と値

This segment should take about 40 minutes. It contains:

Hello, World

さっそく一番シンプルなプログラムである定番のHello Worldからみてみましょう：

fn main() {
    println!("Hello 🌍!");
}

プログラムの中身：

• 関数はfnで導入されます。
• CやC++と同様に、ブロックは波括弧で囲みます。
• main関数はプログラムのエントリーポイントになります。
• Rustには衛生的なマクロがあり、println!はその一例です。
• Rustの文字列はUTF-8でエンコードされ、どんなUnicode文字でも含む事ができます。

変数

Rust は静的型付けによって型安全性を提供します。変数のバインディングは let を使用して行います。

fn main() {
    let x: i32 = 10;
    println!("x: {x}");
    // x = 20;
    // println!("x: {x}");
}

値

基本的な組み込み型と、各型のリテラル値の構文を以下に示します。

各型の幅は次のとおりです。

• iN、uN、fN は N ビット幅です。
• isize と usize はポインタの幅です。
• char は 32 ビット幅です。
• bool は 8 ビット幅です。

算術

fn interproduct(a: i32, b: i32, c: i32) -> i32 {
    return a * b + b * c + c * a;
}

fn main() {
    println!("result: {}", interproduct(120, 100, 248));
}

型推論

Rust は、どのように変数が 使用されているか を確認することで、型を判別します。

fn takes_u32(x: u32) {
    println!("u32: {x}");
}

fn takes_i8(y: i8) {
    println!("i8: {y}");
}

fn main() {
    let x = 10;
    let y = 20;

    takes_u32(x);
    takes_i8(y);
    // takes_u32(y);
}

fn main() {
    let x = 3.14;
    let y = 20;
    assert_eq!(x, y);
    // エラー: `{float} == {integer}` の実装がありません
}

演習: フィボナッチ

The Fibonacci sequence begins with [0,1]. For n>1, the n'th Fibonacci number is calculated recursively as the sum of the n-1'th and n-2'th Fibonacci numbers.

n 番目のフィボナッチ数を計算する関数 fib(n) を記述します。この関数はいつパニックするでしょうか。

fn fib(n: u32) -> u32 {
    if n < 2 {
        // ベースケース。
        todo!("ここを実装してください")
    } else {
        // 再帰的なケース。
        todo!("ここを実装してください")
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

解答

fn fib(n: u32) -> u32 {
    if n < 2 {
        return n;
    } else {
        return fib(n - 1) + fib(n - 2);
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

制御フローの基本

This segment should take about 40 minutes. It contains:

if 式

Rust の if 式 は、他の言語における if 文と全く同じように使えます。

fn main() {
    let x = 10;
    if x == 0 {
        println!("zero!");
    } else if x < 100 {
        println!("biggish");
    } else {
        println!("huge");
    }
}

さらに、if を式としても用いることができます。それぞれのブロックにある最後の式が、if 式の値となります。

fn main() {
    let x = 10;
    let size = if x < 20 { "small" } else { "large" };
    println!("number size: {}", size);
}

ループ

Rust には、while、loop、for の 3 つのループ キーワードがあります。

while

while キーワード は、他の言語における while と非常によく似た働きをします。

fn main() {
    let mut x = 200;
    while x >= 10 {
        x = x / 2;
    }
    println!("Final x: {x}");
}

for

The for loop iterates over ranges of values or the items in a collection:

fn main() {
    for x in 1..5 {
        println!("x: {x}");
    }

    for elem in [1, 2, 3, 4, 5] {
        println!("elem: {elem}");
    }
}

loop

loop ステートメント は、break まで永久にループするだけです。

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        println!("{i}");
        if i > 100 {
            break;
        }
    }
}

break と continue

次のイテレーションをすぐさま開始したい場合は continue を使用してください。

If you want to exit any kind of loop early, use break. With loop, this can take an optional expression that becomes the value of the loop expression.

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        if i > 5 {
            break;
        }
        if i % 2 == 0 {
            continue;
        }
        println!("{}", i);
    }
}

Labels

continue と break はオプションでラベル引数を取ることができます。ラベルはネストしたループから抜け出すために使われます。

fn main() {
    let s = [[5, 6, 7], [8, 9, 10], [21, 15, 32]];
    let mut elements_searched = 0;
    let target_value = 10;
    'outer: for i in 0..=2 {
        for j in 0..=2 {
            elements_searched += 1;
            if s[i][j] == target_value {
                break 'outer;
            }
        }
    }
    print!("elements searched: {elements_searched}");
}

ブロックとスコープ

コードブロック

A block in Rust contains a sequence of expressions, enclosed by braces {}. Each block has a value and a type, which are those of the last expression of the block:

fn main() {
    let z = 13;
    let x = {
        let y = 10;
        println!("y: {y}");
        z - y
    };
    println!("x: {x}");
}

最後の式が ; で終了した場合、ブロック全体の値と型は () になります。

スコープとシャドーイング

変数のスコープは、囲まれたブロック内に限定されます。

外側のスコープの変数と、同じスコープの変数の両方をシャドーイングできます。

fn main() {
    let a = 10;
    println!("before: {a}");
    {
        let a = "hello";
        println!("inner scope: {a}");

        let a = true;
        println!("shadowed in inner scope: {a}");
    }

    println!("after: {a}");
}

関数

fn gcd(a: u32, b: u32) -> u32 {
    if b > 0 {
        gcd(b, a % b)
    } else {
        a
    }
}

fn main() {
    println!("gcd: {}", gcd(143, 52));
}

マクロ

マクロはコンパイル時に Rust コードに展開され、可変長引数を取ることができます。これらは末尾の ! で区別されます。Rust 標準ライブラリには、各種の便利なマクロが含まれています。

• println!(format, ..): std::fmt で説明されている書式を適用して、1 行を標準出力に出力します。
• format!(format, ..): println! と同様に機能しますが、結果を文字列として返します。
• dbg!(expression): 式の値をログに記録して返します。
• todo!(): 一部のコードに未実装のマークを付けます。実行するとパニックが発生します。
• unreachable!(): コードの一部をアクセス不能としてマークします。実行するとパニックが発生します。

fn factorial(n: u32) -> u32 {
    let mut product = 1;
    for i in 1..=n {
        product *= dbg!(i);
    }
    product
}

fn fizzbuzz(n: u32) -> u32 {
    todo!()
}

fn main() {
    let n = 4;
    println!("{n}! = {}", factorial(n));
}

演習: コラッツ数列

The Collatz Sequence is defined as follows, for an arbitrary n₁ greater than zero:

• If n_i is 1, then the sequence terminates at n_i.
• If n_i is even, then n_i+1 = n_i / 2.
• If n_i is odd, then n_i+1 = 3 * n_i + 1.

For example, beginning with n₁ = 3:

• 3 is odd, so n₂ = 3 * 3 + 1 = 10;
• 10 is even, so n₃ = 10 / 2 = 5;
• 5 is odd, so n₄ = 3 * 5 + 1 = 16;
• 16 is even, so n₅ = 16 / 2 = 8;
• 8 is even, so n₆ = 8 / 2 = 4;
• 4 is even, so n₇ = 4 / 2 = 2;
• 2 is even, so n₈ = 1; and
• 数列は終了します。

任意の初期値 n に対するコラッツ数列の長さを計算する関数を作成します。

/// `n` から始まるコラッツ数列の長さを決定。
fn collatz_length(mut n: i32) -> u32 {
  todo!("ここを実装してください")
}

#[test]
fn test_collatz_length() {
    assert_eq!(collatz_length(11), 15);
}

fn main() {
    println!("Length: {}", collatz_length(11));
}

解答

/// `n` から始まるコラッツ数列の長さを決定。
fn collatz_length(mut n: i32) -> u32 {
    let mut len = 1;
    while n > 1 {
        n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 };
        len += 1;
    }
    len
}

#[test]
fn test_collatz_length() {
    assert_eq!(collatz_length(11), 15);
}

fn main() {
    println!("Length: {}", collatz_length(11));
}

おかえり

Including 10 minute breaks, this session should take about 2 hours and 35 minutes. It contains:

タプルと配列

This segment should take about 35 minutes. It contains:

配列

fn main() {
    let mut a: [i8; 10] = [42; 10];
    a[5] = 0;
    println!("a: {a:?}");
}

タプル

fn main() {
    let t: (i8, bool) = (7, true);
    println!("t.0: {}", t.0);
    println!("t.1: {}", t.1);
}

配列のイテレート

for ステートメントでは、配列の反復処理がサポートされています（タプルはサポートされていません）。

fn main() {
    let primes = [2, 3, 5, 7, 11, 13, 17, 19];
    for prime in primes {
        for i in 2..prime {
            assert_ne!(prime % i, 0);
        }
    }
}

パターンとデストラクト

When working with tuples and other structured values it's common to want to extract the inner values into local variables. This can be done manually by directly accessing the inner values:

fn print_tuple(tuple: (i32, i32)) {
    let left = tuple.0;
    let right = tuple.1;
    println!("left: {left}, right: {right}");
}

However, Rust also supports using pattern matching to destructure a larger value into its constituent parts:

fn print_tuple(tuple: (i32, i32)) {
    let (left, right) = tuple;
    println!("left: {left}, right: {right}");
}

演習: ネストされた配列

配列には他の配列を含めることができます。

#![allow(unused)]
fn main() {
let array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
}

What is the type of this variable?

上記のような配列を使用して、行列を転置（行を列に変換）する transpose 関数を記述します。

Copy the code below to https://play.rust-lang.org/ and implement the function. This function only operates on 3x3 matrices.

// TODO: 実装が完了したら、これを削除します。
#![allow(unused_variables, dead_code)]

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    unimplemented!()
}

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- このコメントにより rustfmt で改行を追加
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("matrix: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("transposed: {:#?}", transposed);
}

解答

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    let mut result = [[0; 3]; 3];
    for i in 0..3 {
        for j in 0..3 {
            result[j][i] = matrix[i][j];
        }
    }
    result
}

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], // <-- このコメントにより rustfmt で改行を追加
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("matrix: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("transposed: {:#?}", transposed);
}

参照

This segment should take about 55 minutes. It contains:

共有参照

A reference provides a way to access another value without taking ownership of the value, and is also called "borrowing". Shared references are read-only, and the referenced data cannot change.

fn main() {
    let a = 'A';
    let b = 'B';
    let mut r: &char = &a;
    println!("r: {}", *r);
    r = &b;
    println!("r: {}", *r);
}

型 T への共有参照の型は &T です。参照値は & 演算子で作成されます。* 演算子は参照を「逆参照」し、その値を生成します。

Rust はダングリング参照を静的に禁止します。

fn x_axis(x: &i32) -> &(i32, i32) {
    let point = (*x, 0);
    return &point;
}

排他参照

排他参照は可変参照とも呼ばれ、参照先の値を変更できます。型は &mut T です。

fn main() {
    let mut point = (1, 2);
    let x_coord = &mut point.0;
    *x_coord = 20;
    println!("point: {point:?}");
}

Slices

スライスは、より大きなコレクションに対するビューを提供します。

fn main() {
    let mut a: [i32; 6] = [10, 20, 30, 40, 50, 60];
    println!("a: {a:?}");

    let s: &[i32] = &a[2..4];

    println!("s: {s:?}");
}

• スライスは、スライスされた型からデータを借用します。

文字列

We can now understand the two string types in Rust:

• &str is a slice of UTF-8 encoded bytes, similar to &[u8].
• String is an owned buffer of UTF-8 encoded bytes, similar to Vec<T>.

fn main() {
    let s1: &str = "World";
    println!("s1: {s1}");

    let mut s2: String = String::from("Hello ");
    println!("s2: {s2}");
    s2.push_str(s1);
    println!("s2: {s2}");

    let s3: &str = &s2[s2.len() - s1.len()..];
    println!("s3: {s3}");
}

演習: ジオメトリ

ここでは、点を [f64;3] として表現する 3 次元ジオメトリのユーティリティ関数をいくつか作成します。関数シグネチャは任意で指定してください。

// 座標の二乗を合計して平方根を取り、
// ベクターの大きさを計算します。`sqrt()` メソッドを使用して、`v.sqrt()` と同様に
// 平方根を計算します。


fn magnitude(...) -> f64 {
    todo!()
}

// 大きさを計算し、すべての座標をその大きさで割ることで
// ベクターを正規化します。


fn normalize(...) {
    todo!()
}

// 次の `main` を使用して処理をテストします。

fn main() {
    println!("Magnitude of a unit vector: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitude of {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitude of {v:?} after normalization: {}", magnitude(&v));
}

解答

/// 指定されたベクターの大きさを計算します。
fn magnitude(vector: &[f64; 3]) -> f64 {
    let mut mag_squared = 0.0;
    for coord in vector {
        mag_squared += coord * coord;
    }
    mag_squared.sqrt()
}

/// 向きを変えずにベクターの大きさを 1.0 に変更します。
fn normalize(vector: &mut [f64; 3]) {
    let mag = magnitude(vector);
    for item in vector {
        *item /= mag;
    }
}

fn main() {
    println!("Magnitude of a unit vector: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("Magnitude of {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("Magnitude of {v:?} after normalization: {}", magnitude(&v));
}

ユーザー定義型

This segment should take about 50 minutes. It contains:

名前付き構造体

C や C++ と同様に、Rust はカスタム構造体をサポートしています。

struct Person {
    name: String,
    age: u8,
}

fn describe(person: &Person) {
    println!("{} is {} years old", person.name, person.age);
}

fn main() {
    let mut peter = Person { name: String::from("Peter"), age: 27 };
    describe(&peter);

    peter.age = 28;
    describe(&peter);

    let name = String::from("Avery");
    let age = 39;
    let avery = Person { name, age };
    describe(&avery);

    let jackie = Person { name: String::from("Jackie"), ..avery };
    describe(&jackie);
}

タプル構造体

フィールド名が重要でない場合は、タプル構造体を使用できます。

struct Point(i32, i32);

fn main() {
    let p = Point(17, 23);
    println!("({}, {})", p.0, p.1);
}

これは多くの場合、単一フィールド ラッパー（ニュータイプと呼ばれます）に使用されます。

struct PoundsOfForce(f64);
struct Newtons(f64);

fn compute_thruster_force() -> PoundsOfForce {
    todo!("Ask a rocket scientist at NASA")
}

fn set_thruster_force(force: Newtons) {
    // ...
}

fn main() {
    let force = compute_thruster_force();
    set_thruster_force(force);
}

列挙型（enums）

enum キーワードを使用すると、いくつかの異なるバリアントを持つ型を作成できます。

#[derive(Debug)]
enum Direction {
    Left,
    Right,
}

#[derive(Debug)]
enum PlayerMove {
    Pass,                        // 単純なバリアント
    Run(Direction),              // Tuple variant
    Teleport { x: u32, y: u32 }, // 構造体バリアント
}

fn main() {
    let player_move: PlayerMove = PlayerMove::Run(Direction::Left);
    println!("On this turn: {player_move:?}");
}

const

Constants are evaluated at compile time and their values are inlined wherever they are used:

const DIGEST_SIZE: usize = 3;
const ZERO: Option<u8> = Some(42);

fn compute_digest(text: &str) -> [u8; DIGEST_SIZE] {
    let mut digest = [ZERO.unwrap_or(0); DIGEST_SIZE];
    for (idx, &b) in text.as_bytes().iter().enumerate() {
        digest[idx % DIGEST_SIZE] = digest[idx % DIGEST_SIZE].wrapping_add(b);
    }
    digest
}

fn main() {
    let digest = compute_digest("Hello");
    println!("digest: {digest:?}");
}

Rust RFC Book によると、定数変数は使用時にインライン化されます。

コンパイル時に const 値を生成するために呼び出せるのは、const とマークされた関数のみです。ただし、const 関数は実行時に呼び出すことができます。

static

静的変数はプログラムの実行全体を通じて存続するため、移動しません。

static BANNER: &str = "Welcome to RustOS 3.14";

fn main() {
    println!("{BANNER}");
}

Rust RFC Book で説明されているように、静的変数は使用時にインライン化されず、実際の関連するメモリ位置に存在します。これは安全でないコードや埋め込みコードに有用であり、変数はプログラムの実行全体を通じて存続します。グローバル スコープの値にオブジェクト ID が必要ない場合は、一般的に const が使用されます。

型エイリアス

型エイリアスは、別の型の名前を作成します。この 2 つの型は同じ意味で使用できます。

enum CarryableConcreteItem {
    Left,
    Right,
}

type Item = CarryableConcreteItem;

// エイリアスは長くて複雑な型に使用すると便利です。
use std::cell::RefCell;
use std::sync::{Arc, RwLock};
type PlayerInventory = RwLock<Vec<Arc<RefCell<Item>>>>;

演習: エレベーターでのイベント

エレベーター制御システムでイベントを表すデータ構造を作成します。さまざまなイベントを構築するための型と関数を自由に定義して構いません。#[derive(Debug)] を使用して、型を {:?} でフォーマットできるようにします。

この演習に必要なのは、main がエラーなしで実行されるように、データ構造を作成して入力することだけです。このコースの次のパートでは、これらの構造からデータを取得する方法を説明します。

#[derive(Debug)]
/// コントローラが反応する必要があるエレベーター システム内のイベント。
enum Event {
    // TODO: 必要なバリアントを追加する
}

/// 運転方向。
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// かごが所定の階に到着した。
fn car_arrived(floor: i32) -> Event {
    todo!()
}

/// かごのドアが開いた。
fn car_door_opened() -> Event {
    todo!()
}

/// かごのドアが閉まった。
fn car_door_closed() -> Event {
    todo!()
}

/// 所定の階のエレベーター ロビーで方向ボタンが押された。
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    todo!()
}

/// エレベーターのかごの階数ボタンが押された。
fn car_floor_button_pressed(floor: i32) -> Event {
    todo!()
}

fn main() {
    println!(
        "A ground floor passenger has pressed the up button: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("The car has arrived on the ground floor: {:?}", car_arrived(0));
    println!("The car door opened: {:?}", car_door_opened());
    println!(
        "A passenger has pressed the 3rd floor button: {:?}",
        car_floor_button_pressed(3)
    );
    println!("The car door closed: {:?}", car_door_closed());
    println!("The car has arrived on the 3rd floor: {:?}", car_arrived(3));
}

解答

#[derive(Debug)]
/// コントローラが反応する必要があるエレベーター システム内のイベント。
enum Event {
    /// ボタンが押された。
    ButtonPressed(Button),

    /// 車両が所定の階に到着した。
    CarArrived(Floor),

    /// かごのドアが開いた。
    CarDoorOpened,

    /// かごのドアが閉まった。
    CarDoorClosed,
}

/// 階は整数として表される。
type Floor = i32;

/// 運転方向。
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// ユーザーがアクセスできるボタン。
#[derive(Debug)]
enum Button {
    /// 所定の階のエレベーター ロビーにあるボタン。
    LobbyCall(Direction, Floor),

    /// かご内の階数ボタン。
    CarFloor(Floor),
}

/// かごが所定の階に到着した。
fn car_arrived(floor: i32) -> Event {
    Event::CarArrived(floor)
}

/// かごのドアが開いた。
fn car_door_opened() -> Event {
    Event::CarDoorOpened
}

/// かごのドアが閉まった。
fn car_door_closed() -> Event {
    Event::CarDoorClosed
}

/// 所定の階のエレベーター ロビーで方向ボタンが押された。
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    Event::ButtonPressed(Button::LobbyCall(dir, floor))
}

/// エレベーターのかごの階数ボタンが押された。
fn car_floor_button_pressed(floor: i32) -> Event {
    Event::ButtonPressed(Button::CarFloor(floor))
}

fn main() {
    println!(
        "A ground floor passenger has pressed the up button: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("The car has arrived on the ground floor: {:?}", car_arrived(0));
    println!("The car door opened: {:?}", car_door_opened());
    println!(
        "A passenger has pressed the 3rd floor button: {:?}",
        car_floor_button_pressed(3)
    );
    println!("The car door closed: {:?}", car_door_closed());
    println!("The car has arrived on the 3rd floor: {:?}", car_arrived(3));
}

2日目の講座へようこそ

Rust についてかなり多くのことを学んできましたが、今日は Rust の型システムに焦点を当てます。

• パターン マッチング: 構造からのデータの抽出。
• メソッド: 関数と型の関連付け。
• トレイト: 複数の型で共有される挙動。
• ジェネリクス: 他の型での型のパラメータ化。
• 標準ライブラリの型とトレイト: Rust の豊富な標準ライブラリの紹介。

スケジュール

Including 10 minute breaks, this session should take about 2 hours and 10 minutes. It contains:

パターンマッチング

This segment should take about 1 hour. It contains:

Matching Values

match キーワードを使用すると、1 つ以上のパターンに対して値を照合できます。上から順に照合が行われ、最初に一致したパターンのみが実行されます。

C や C++ の switch と同様に、パターンには単純な値を指定できます。

#[rustfmt::skip]
fn main() {
    let input = 'x';
    match input {
        'q'                       => println!("Quitting"),
        'a' | 's' | 'w' | 'd'     => println!("Moving around"),
        '0'..='9'                 => println!("Number input"),
        key if key.is_lowercase() => println!("Lowercase: {key}"),
        _                         => println!("Something else"),
    }
}

The _ pattern is a wildcard pattern which matches any value. The expressions must be exhaustive, meaning that it covers every possibility, so _ is often used as the final catch-all case.

一致を式として使用できます。if と同様に、各マッチアームは同じ型にする必要があります。型は、ブロックの最後の式です（存在する場合）。上記の例では、型は () です。

パターンの変数（この例では key）により、マッチアーム内で使用できるバインディングが作成されます。

マッチガードにより、条件が true の場合にのみアームが一致します。

構造体（structs）

Like tuples, Struct can also be destructured by matching:

struct Foo {
    x: (u32, u32),
    y: u32,
}

#[rustfmt::skip]
fn main() {
    let foo = Foo { x: (1, 2), y: 3 };
    match foo {
        Foo { x: (1, b), y } => println!("x.0 = 1, b = {b}, y = {y}"),
        Foo { y: 2, x: i }   => println!("y = 2, x = {i:?}"),
        Foo { y, .. }        => println!("y = {y}, other fields were ignored"),
    }
}

列挙型（enums）

Like tuples, enums can also be destructured by matching:

パターンは、変数を値の一部にバインドするためにも使用できます。以下のようにして、型の構造を調べることができます。単純な enum から始めましょう。

enum Result {
    Ok(i32),
    Err(String),
}

fn divide_in_two(n: i32) -> Result {
    if n % 2 == 0 {
        Result::Ok(n / 2)
    } else {
        Result::Err(format!("cannot divide {n} into two equal parts"))
    }
}

fn main() {
    let n = 100;
    match divide_in_two(n) {
        Result::Ok(half) => println!("{n} divided in two is {half}"),
        Result::Err(msg) => println!("sorry, an error happened: {msg}"),
    }
}

ここでは、アーム（arm, パターンを並べたもの）を使用して Result 値の分解を行っています。最初のアームでは、half は Ok バリアント内の値にバインドされます。2 つ目のアームでは msg がエラー メッセージにバインドされます。

Let制御フロー

Rust には、他の言語とは異なる制御フロー構造がいくつかあります。これらはパターン マッチングに使用されます。

• if let 式
• let else 式
• while let 式

if let 式

if let 式 を使用すると、値がパターンに一致するかどうかに応じて異なるコードを実行できます。

use std::time::Duration;

fn sleep_for(secs: f32) {
    if let Ok(duration) = Duration::try_from_secs_f32(secs) {
        std::thread::sleep(duration);
        println!("slept for {duration:?}");
    }
}

fn main() {
    sleep_for(-10.0);
    sleep_for(0.8);
}

let else 式

パターンをマッチして関数から戻るという一般的なケースでは、let else を使用します。「else」ケースは発散する必要があります（return、break、パニックなど、ブロックから抜けるもの以外のすべて）。

fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    if let Some(s) = maybe_string {
        if let Some(first_byte_char) = s.chars().next() {
            if let Some(digit) = first_byte_char.to_digit(16) {
                Ok(digit)
            } else {
                return Err(String::from("not a hex digit"));
            }
        } else {
            return Err(String::from("got empty string"));
        }
    } else {
        return Err(String::from("got None"));
    }
}

fn main() {
    println!("result: {:?}", hex_or_die_trying(Some(String::from("foo"))));
}

if let に似た while let 派生物もあります。これは、パターンに照らして値をテストします。

fn main() {
    let mut name = String::from("Comprehensive Rust 🦀");
    while let Some(c) = name.pop() {
        println!("character: {c}");
    }
    // (There are more efficient ways to reverse a string!)
}

ここで String::pop は、文字列が空になるまで Some(c) を返し、その後 None を返します。while let を使用すると、すべてのアイテムに対して反復処理を続行できます。

#![allow(unused)]
fn main() {
fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let Some(s) = maybe_string else {
        return Err(String::from("got None"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("got empty string"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("not a hex digit"));
    };

    return Ok(digit);
}
}

演習: 式の評価

演算式用の簡単な再帰エバリュエータを作成してみましょう。

An example of a small arithmetic expression could be 10 + 20, which evaluates to 30. We can represent the expression as a tree:

A bigger and more complex expression would be (10 * 9) + ((3 - 4) * 5), which evaluate to 85. We represent this as a much bigger tree:

In code, we will represent the tree with two types:

#![allow(unused)]
fn main() {
/// 2 つのサブ式に対して実行する演算。
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// ツリー形式の式。
#[derive(Debug)]
enum Expression {
    /// 2 つのサブ式に対する演算。
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// リテラル値
    Value(i64),
}
}

ここでの Box 型はスマート ポインタです。詳細はこの講座で後ほど説明します。テストで見られるように、式は Box::new で「ボックス化」できます。ボックス化された式を評価するには、逆参照演算子（*）を使用して「ボックス化解除」します（eval(*boxed_expr)）。

一部の式は評価できず、エラーが返されます。標準の Result<Value, String> 型は、成功した値（Ok(Value)）またはエラー（Err(String)）のいずれかを表す列挙型です。この型については、後ほど詳しく説明します。

コードをコピーして Rust プレイグラウンドに貼り付け、eval の実装を開始します。完成したエバリュエータはテストに合格する必要があります。todo!() を使用して、テストを 1 つずつ実施することをおすすめします。#[ignore] を使用して、テストを一時的にスキップすることもできます。

#[test]
#[ignore]
fn test_value() { .. }

#![allow(unused)]
fn main() {
/// 2 つのサブ式に対して実行する演算。
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// ツリー形式の式。
#[derive(Debug)]
enum Expression {
    /// 2 つのサブ式に対する演算。
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// リテラル値
    Value(i64),
}

fn eval(e: Expression) -> Result<i64, String> {
    todo!()
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(19));
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        Ok(30)
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        Ok(85)
    );
}

#[test]
fn test_zeros() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        Ok(0)
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Mul,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        Ok(0)
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        Ok(0)
    );
}

#[test]
fn test_error() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(99)),
            right: Box::new(Expression::Value(0)),
        }),
        Err(String::from("division by zero"))
    );
}
}

解答

/// 2 つのサブ式に対して実行する演算。
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// ツリー形式の式。
#[derive(Debug)]
enum Expression {
    /// 2 つのサブ式に対する演算。
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// リテラル値
    Value(i64),
}

fn eval(e: Expression) -> Result<i64, String> {
    match e {
        Expression::Op { op, left, right } => {
            let left = match eval(*left) {
                Ok(v) => v,
                Err(e) => return Err(e),
            };
            let right = match eval(*right) {
                Ok(v) => v,
                Err(e) => return Err(e),
            };
            Ok(match op {
                Operation::Add => left + right,
                Operation::Sub => left - right,
                Operation::Mul => left * right,
                Operation::Div => {
                    if right == 0 {
                        return Err(String::from("division by zero"));
                    } else {
                        left / right
                    }
                }
            })
        }
        Expression::Value(v) => Ok(v),
    }
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(19));
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        Ok(30)
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        Ok(85)
    );
}

#[test]
fn test_zeros() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        Ok(0)
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Mul,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        Ok(0)
    );
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(0)),
            right: Box::new(Expression::Value(0))
        }),
        Ok(0)
    );
}

#[test]
fn test_error() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(99)),
            right: Box::new(Expression::Value(0)),
        }),
        Err(String::from("division by zero"))
    );
}

fn main() {
    let expr = Expression::Op {
        op: Operation::Sub,
        left: Box::new(Expression::Value(20)),
        right: Box::new(Expression::Value(10)),
    };
    println!("expr: {expr:?}");
    println!("result: {:?}", eval(expr));
}

Methods and Traits

This segment should take about 50 minutes. It contains:

メソッド

Rust を使用すると、関数を新しい型に関連付けることができます。これは impl ブロックで実行します。

#[derive(Debug)]
struct Race {
    name: String,
    laps: Vec<i32>,
}

impl Race {
    // レシーバなし、静的メソッド
    fn new(name: &str) -> Self {
        Self { name: String::from(name), laps: Vec::new() }
    }

    // 自身に対する排他的な読み取り / 書き込み借用アクセス
    fn add_lap(&mut self, lap: i32) {
        self.laps.push(lap);
    }

    // 自身に対する共有および読み取り専用の借用アクセス
    fn print_laps(&self) {
        println!("Recorded {} laps for {}:", self.laps.len(), self.name);
        for (idx, lap) in self.laps.iter().enumerate() {
            println!("Lap {idx}: {lap} sec");
        }
    }

    // Exclusive ownership of self (covered later)
    fn finish(self) {
        let total: i32 = self.laps.iter().sum();
        println!("Race {} is finished, total lap time: {}", self.name, total);
    }
}

fn main() {
    let mut race = Race::new("Monaco Grand Prix");
    race.add_lap(70);
    race.add_lap(68);
    race.print_laps();
    race.add_lap(71);
    race.print_laps();
    race.finish();
    // race.add_lap(42);
}

self 引数は、「レシーバ」、つまりメソッドが操作するオブジェクトを指定します。メソッドの一般的なレシーバは次のとおりです。

• &self: 共有の不変参照を使用して、呼び出し元からオブジェクトを借用します。このオブジェクトは後で再び使用できます。
• &mut self: 一意の可変参照を使用して、呼び出し元からオブジェクトを借用します。このオブジェクトは後で再び使用できます。
• self: オブジェクトの所有権を取得し、呼び出し元から遠ざけます。メソッドがオブジェクトの所有者になります。所有権が明示的に送信されない限り、メソッドが戻ると、オブジェクトは破棄（デアロケート）されます。完全な所有権は、必ずしも可変性を意味するわけではありません。
• mut self: 上記と同じですが、メソッドはオブジェクトを変更できます。
• レシーバなし: 構造体の静的メソッドになります。通常は、new と呼ばれるコンストラクタを作成するために使用されます。

トレイト（trait）

Rustでは、型に関しての抽象化をトレイトを用いて行うことができます。トレイトはインターフェースに似ています：

trait Pet {
    /// Return a sentence from this pet.
    fn talk(&self) -> String;

    /// Print a string to the terminal greeting this pet.
    fn greet(&self);
}

トレイトの実装

trait Pet {
    fn talk(&self) -> String;

    fn greet(&self) {
        println!("Oh you're a cutie! What's your name? {}", self.talk());
    }
}

struct Dog {
    name: String,
    age: i8,
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Woof, my name is {}!", self.name)
    }
}

fn main() {
    let fido = Dog { name: String::from("Fido"), age: 5 };
    fido.greet();
}

スーパートレイト

A trait can require that types implementing it also implement other traits, called supertraits. Here, any type implementing Pet must implement Animal.

trait Animal {
    fn leg_count(&self) -> u32;
}

trait Pet: Animal {
    fn name(&self) -> String;
}

struct Dog(String);

impl Animal for Dog {
    fn leg_count(&self) -> u32 {
        4
    }
}

impl Pet for Dog {
    fn name(&self) -> String {
        self.0.clone()
    }
}

fn main() {
    let puppy = Dog(String::from("Rex"));
    println!("{} has {} legs", puppy.name(), puppy.leg_count());
}

関連型

Associated types are placeholder types which are supplied by the trait implementation.

#[derive(Debug)]
struct Meters(i32);
#[derive(Debug)]
struct MetersSquared(i32);

trait Multiply {
    type Output;
    fn multiply(&self, other: &Self) -> Self::Output;
}

impl Multiply for Meters {
    type Output = MetersSquared;
    fn multiply(&self, other: &Self) -> Self::Output {
        MetersSquared(self.0 * other.0)
    }
}

fn main() {
    println!("{:?}", Meters(10).multiply(&Meters(20)));
}

導出

サポートされているトレイトは、次のようにカスタム型に自動的に実装できます。

#[derive(Debug, Clone, Default)]
struct Player {
    name: String,
    strength: u8,
    hit_points: u8,
}

fn main() {
    let p1 = Player::default(); // デフォルト トレイトで `default` コンストラクタを追加します。
    let mut p2 = p1.clone(); // クローン トレイトで `clone` メソッドを追加します。
    p2.name = String::from("EldurScrollz");
    // デバッグ トレイトで、`{:?}` を使用した出力のサポートを追加します。
    println!("{p1:?} vs. {p2:?}");
}

Exercise: Logger Trait

トレイト Logger と log メソッドを使用して、シンプルなロギングユーティリティを設計してみましょう。進行状況をログに記録するコードは、その後に &impl Logger を受け取ることができます。この場合、テストではテストログファイルにメッセージが書き込まれますが、本番環境ビルドではログサーバーにメッセージが送信されます。

However, the StdoutLogger given below logs all messages, regardless of verbosity. Your task is to write a VerbosityFilter type that will ignore messages above a maximum verbosity.

これは一般的なパターンです。つまり、トレイト実装をラップして同じトレイトを実装し、その過程で挙動を追加していく構造体です。ロギングユーティリティでは他にどのような種類のラッパーが役立つでしょうか。

pub trait Logger {
    /// 指定された詳細度レベルでメッセージをログに記録します。
    fn log(&self, verbosity: u8, message: &str);
}

struct StdoutLogger;

impl Logger for StdoutLogger {
    fn log(&self, verbosity: u8, message: &str) {
        println!("verbosity={verbosity}: {message}");
    }
}

// TODO: `VerbosityFilter` を定義して実装します。

fn main() {
    let logger = VerbosityFilter { max_verbosity: 3, inner: StdoutLogger };
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

解答

pub trait Logger {
    /// 指定された詳細度レベルでメッセージをログに記録します。
    fn log(&self, verbosity: u8, message: &str);
}

struct StdoutLogger;

impl Logger for StdoutLogger {
    fn log(&self, verbosity: u8, message: &str) {
        println!("verbosity={verbosity}: {message}");
    }
}

/// 指定された詳細度レベルまでのメッセージのみをログに記録。
struct VerbosityFilter {
    max_verbosity: u8,
    inner: StdoutLogger,
}

impl Logger for VerbosityFilter {
    fn log(&self, verbosity: u8, message: &str) {
        if verbosity <= self.max_verbosity {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let logger = VerbosityFilter { max_verbosity: 3, inner: StdoutLogger };
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

おかえり

Including 10 minute breaks, this session should take about 3 hours and 15 minutes. It contains:

ジェネリクス（generics）

This segment should take about 45 minutes. It contains:

ジェネリック関数

Rust supports generics, which lets you abstract algorithms or data structures (such as sorting or a binary tree) over the types used or stored.

/// `n` の値に応じて `even` または `odd` を選択します。
fn pick<T>(n: i32, even: T, odd: T) -> T {
    if n % 2 == 0 {
        even
    } else {
        odd
    }
}

fn main() {
    println!("picked a number: {:?}", pick(97, 222, 333));
    println!("picked a string: {:?}", pick(28, "dog", "cat"));
}

ジェネリックデータ型

ジェネリクスを使って、具体的なフィールドの型を抽象化することができます：

#[derive(Debug)]
struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn coords(&self) -> (&T, &T) {
        (&self.x, &self.y)
    }

    fn set_x(&mut self, x: T) {
        self.x = x;
    }
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
    println!("{integer:?} and {float:?}");
    println!("coords: {:?}", integer.coords());
}

ジェネリックトレイト

Traits can also be generic, just like types and functions. A trait's parameters get concrete types when it is used.

#[derive(Debug)]
struct Foo(String);

impl From<u32> for Foo {
    fn from(from: u32) -> Foo {
        Foo(format!("Converted from integer: {from}"))
    }
}

impl From<bool> for Foo {
    fn from(from: bool) -> Foo {
        Foo(format!("Converted from bool: {from}"))
    }
}

fn main() {
    let from_int = Foo::from(123);
    let from_bool = Foo::from(true);
    println!("{from_int:?}, {from_bool:?}");
}

トレイト制約

ジェネリクスを用いるとき、あるトレイトのメソッドを呼び出せるように、型がそのトレイトを実装していることを要求したいことがよくあります。（脚注：本教材では"Trait bounds"を「トレイト制約」と翻訳しましたが、Rustの日本語翻訳コミュニティでは「トレイト境界」と呼ぶ流派もあり、どちらの翻訳を採用するかについては議論がなされています。）

You can do this with T: Trait:

fn duplicate<T: Clone>(a: T) -> (T, T) {
    (a.clone(), a.clone())
}

// struct NotCloneable;

fn main() {
    let foo = String::from("foo");
    let pair = duplicate(foo);
    println!("{pair:?}");
}

impl Trait

トレイト境界と似たように、構文 impl Traitは関数の引数と返り値においてのみ利用可能です：

// 以下の糖衣構文:
//   fn add_42_millions<T: Into<i32>>(x: T) -> i32 {
fn add_42_millions(x: impl Into<i32>) -> i32 {
    x.into() + 42_000_000
}

fn pair_of(x: u32) -> impl std::fmt::Debug {
    (x + 1, x - 1)
}

fn main() {
    let many = add_42_millions(42_i8);
    println!("{many}");
    let many_more = add_42_millions(10_000_000);
    println!("{many_more}");
    let debuggable = pair_of(27);
    println!("debuggable: {debuggable:?}");
}

dyn Trait

In addition to using traits for static dispatch via generics, Rust also supports using them for type-erased, dynamic dispatch via trait objects:

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Woof, my name is {}!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

// Uses generics and static dispatch.
fn generic(pet: &impl Pet) {
    println!("Hello, who are you? {}", pet.talk());
}

// Uses type-erasure and dynamic dispatch.
fn dynamic(pet: &dyn Pet) {
    println!("Hello, who are you? {}", pet.talk());
}

fn main() {
    let cat = Cat { lives: 9 };
    let dog = Dog { name: String::from("Fido"), age: 5 };

    generic(&cat);
    generic(&dog);

    dynamic(&cat);
    dynamic(&dog);
}

演習: ジェネリックな min

In this short exercise, you will implement a generic min function that determines the minimum of two values, using the Ord trait.

use std::cmp::Ordering;

// TODO: `main` で使用する `min` 関数を実装します。

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("hello", "goodbye"), "goodbye");
    assert_eq!(min("bat", "armadillo"), "armadillo");
}

解答

use std::cmp::Ordering;

fn min<T: Ord>(l: T, r: T) -> T {
    match l.cmp(&r) {
        Ordering::Less | Ordering::Equal => l,
        Ordering::Greater => r,
    }
}

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("hello", "goodbye"), "goodbye");
    assert_eq!(min("bat", "armadillo"), "armadillo");
}

標準ライブラリ内の型

This segment should take about 1 hour. It contains:

標準ライブラリ

Rust には、Rust のライブラリとプログラムで使用される一般的な型のセットを確立するのに役立つ標準ライブラリが付属しています。2 つのライブラリをスムーズに連携させることができるのは、このように両方とも同じ String 型を使用しているためです。

実際、Rust には標準ライブラリ（core、alloc、std）の複数のレイヤが含まれています。

• core には、libc やアロケータ、さらにはオペレーティング システムの存在にも依存しない、最も基本的な型と関数が含まれます。
• alloc には、Vec、Box、Arc など、グローバルヒープアロケータを必要とする型が含まれます。
• 多くの場合、埋め込みの Rust アプリは core のみを使用し、場合によっては alloc を使用します。

ドキュメント

Rust には詳細なドキュメントが用意されています。次に例を示します。

• All of the details about loops.
• u8 のようなプリミティブ型。
• Option や BinaryHeap などの標準ライブラリ型。

Use rustup doc --std or https://std.rs to view the documentation.

実際、独自のコードにドキュメントをつけることができます。

/// 最初の引数が 2 番目の引数で割り切れるかどうかを判定します。
///
/// 2 番目の引数がゼロの場合、結果は false になります。
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

コンテンツはマークダウンとして扱われます。公開されたすべての Rust ライブラリ クレートは、rustdoc ツールを使用して、docs.rs で自動的にドキュメントがまとめられます。このパターンを使用して、すべての公開アイテムを API でドキュメント化するのが慣用的です。

アイテム内（モジュール内など）からアイテムをドキュメント化するには、「内部ドキュメントのコメント」と呼ばれる //! または /*! .. */ を使用します。

//! このモジュールには、整数の整除に関連する機能が含まれています。

Option

Option<T> の使用方法についてはすでにいくつか見てきましたが、これは型 T の値を格納するか、何も格納しません。たとえば、String::find は Option<usize> を返します。

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    println!("find returned {position:?}");
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    println!("find returned {position:?}");
    assert_eq!(position.expect("Character not found"), 0);
}

Result

Result is similar to Option, but indicates the success or failure of an operation, each with a different enum variant. It is generic: Result<T, E> where T is used in the Ok variant and E appears in the Err variant.

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Dear diary: {contents} ({bytes} bytes)");
            } else {
                println!("Could not read file content");
            }
        }
        Err(err) => {
            println!("The diary could not be opened: {err}");
        }
    }
}

String

String is a growable UTF-8 encoded string:

fn main() {
    let mut s1 = String::new();
    s1.push_str("Hello");
    println!("s1: len = {}, capacity = {}", s1.len(), s1.capacity());

    let mut s2 = String::with_capacity(s1.len() + 1);
    s2.push_str(&s1);
    s2.push('!');
    println!("s2: len = {}, capacity = {}", s2.len(), s2.capacity());

    let s3 = String::from("🇨🇭");
    println!("s3: len = {}, number of chars = {}", s3.len(), s3.chars().count());
}

String は Deref<Target = str> を実装します。つまり、String のすべての str メソッドを呼び出すことができます。

Vec

Vec は、サイズ変更可能な標準のヒープ割り当てバッファです。

fn main() {
    let mut v1 = Vec::new();
    v1.push(42);
    println!("v1: len = {}, capacity = {}", v1.len(), v1.capacity());

    let mut v2 = Vec::with_capacity(v1.len() + 1);
    v2.extend(v1.iter());
    v2.push(9999);
    println!("v2: len = {}, capacity = {}", v2.len(), v2.capacity());

    // 要素でベクターを初期化する正規マクロ。
    let mut v3 = vec![0, 0, 1, 2, 3, 4];

    // 偶数要素のみを保持します。
    v3.retain(|x| x % 2 == 0);
    println!("{v3:?}");

    // 連続する重複を削除します。
    v3.dedup();
    println!("{v3:?}");
}

Vec は Deref<Target = [T]> を実装しているため、Vec でスライス メソッドを呼び出すことができます。

HashMap

HashDoS 攻撃から保護する標準のハッシュマップ:

use std::collections::HashMap;

fn main() {
    let mut page_counts = HashMap::new();
    page_counts.insert("Adventures of Huckleberry Finn", 207);
    page_counts.insert("Grimms' Fairy Tales", 751);
    page_counts.insert("Pride and Prejudice", 303);

    if !page_counts.contains_key("Les Misérables") {
        println!(
            "We know about {} books, but not Les Misérables.",
            page_counts.len()
        );
    }

    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        match page_counts.get(book) {
            Some(count) => println!("{book}: {count} pages"),
            None => println!("{book} is unknown."),
        }
    }

    // 何も見つからなかった場合は、.entry() メソッドを使用して値を挿入します。
    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        let page_count: &mut i32 = page_counts.entry(book).or_insert(0);
        *page_count += 1;
    }

    println!("{page_counts:#?}");
}

演習: カウンター

この演習では、非常にシンプルなデータ構造を汎用的なものにします。std::collections::HashMap を使用して、どの値が確認され、各値が何回出現したかを追跡します。

Counter の初期バージョンは、u32 の値でのみ機能するようにハードコードされています。追跡する値の型に対して構造体とそのメソッドをジェネリック化します。これにより、Counter であらゆる型の値を追跡できます。

早めに終わった場合は、entry メソッドを使用して、count メソッドの実装に必要なハッシュ ルックアップの回数を半分にしてみましょう。

use std::collections::HashMap;

/// カウンタは型 T の各値が確認された回数をカウントします。
struct Counter {
    values: HashMap<u32, u64>,
}

impl Counter {
    /// 新しいカウンタを作成します。
    fn new() -> Self {
        Counter {
            values: HashMap::new(),
        }
    }

    /// 指定された値の発生をカウントします。
    fn count(&mut self, value: u32) {
        if self.values.contains_key(&value) {
            *self.values.get_mut(&value).unwrap() += 1;
        } else {
            self.values.insert(value, 1);
        }
    }

    /// 指定された値が確認された回数を返します。
    fn times_seen(&self, value: u32) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("saw {} values equal to {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("got {} apples", strctr.times_seen("apple"));
}

解答

use std::collections::HashMap;
use std::hash::Hash;

/// カウンタは型 T の各値が確認された回数をカウントします。
struct Counter<T> {
    values: HashMap<T, u64>,
}

impl<T: Eq + Hash> Counter<T> {
    /// 新しいカウンタを作成します。
    fn new() -> Self {
        Counter { values: HashMap::new() }
    }

    /// 指定された値の発生をカウントします。
    fn count(&mut self, value: T) {
        *self.values.entry(value).or_default() += 1;
    }

    /// 指定された値が確認された回数を返します。
    fn times_seen(&self, value: T) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("saw {} values equal to {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("got {} apples", strctr.times_seen("apple"));
}

標準ライブラリ内のトレイト

This segment should take about 1 hour and 10 minutes. It contains:

他の言語との比較

これらのトレイトは値の比較をサポートします。すべてのトレイトは、これらのトレイトを実装するフィールドを含む型用に導出できます。

PartialEq と Eq

PartialEq は、必須のメソッド eq と指定されたメソッド ne を持つ部分的な等価関係です。== 演算子と != 演算子は、これらのメソッドを呼び出します。

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq for Key {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

Eq は完全な等価関係（反射的、対称的、推移的）であり、PartialEq を意味します。完全な等価関係を必要とする関数は、トレイト境界として Eq を使用します。

PartialOrd と Ord

PartialOrd は partial_cmp メソッドを使って部分的な順序を定義します。これは、<、<=、>=、> 演算子を実装するために使用されます。

use std::cmp::Ordering;
#[derive(Eq, PartialEq)]
struct Citation {
    author: String,
    year: u32,
}
impl PartialOrd for Citation {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        match self.author.partial_cmp(&other.author) {
            Some(Ordering::Equal) => self.year.partial_cmp(&other.year),
            author_ord => author_ord,
        }
    }
}

Ord は全順序を示し、cmp は Ordering を返します。

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq<u32> for Key {
    fn eq(&self, other: &u32) -> bool {
        self.id == *other
    }
}

演算子

演算子のオーバーロードは、std::ops 内のトレイトを介して実装されます。

#[derive(Debug, Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

impl std::ops::Add for Point {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        Self { x: self.x + other.x, y: self.y + other.y }
    }
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let p2 = Point { x: 100, y: 200 };
    println!("{p1:?} + {p2:?} = {:?}", p1 + p2);
}

From と Into

Types implement From and Into to facilitate type conversions. Unlike as, these traits correspond to lossless, infallible conversions.

fn main() {
    let s = String::from("hello");
    let addr = std::net::Ipv4Addr::from([127, 0, 0, 1]);
    let one = i16::from(true);
    let bigger = i32::from(123_i16);
    println!("{s}, {addr}, {one}, {bigger}");
}

From が実装されると、Into が自動的に実装されます。

fn main() {
    let s: String = "hello".into();
    let addr: std::net::Ipv4Addr = [127, 0, 0, 1].into();
    let one: i16 = true.into();
    let bigger: i32 = 123_i16.into();
    println!("{s}, {addr}, {one}, {bigger}");
}

キャスト

Rust には 暗黙的 な型変換はありませんが、as による明示的なキャストはサポートされています。これらのキャストは通常、それらが定義されている C セマンティクスに従います。

fn main() {
    let value: i64 = 1000;
    println!("as u16: {}", value as u16);
    println!("as i16: {}", value as i16);
    println!("as u8: {}", value as u8);
}

as の結果は Rust で 常に 定義され、プラットフォーム間で一貫しています。これは、正負の符号を変えたり、より小さな型にキャストしたりする際に得られる直感に反しているかもしれません。ドキュメントを確認し、明確にするためにコメントを記述してください。

as を使用したキャストは比較的扱いにくく、誤って使用することが少なくありません。また、将来のメンテナンス作業で、使用される型や型の値の範囲が変更された際に、わかりにくいバグが発生する可能性があります。キャストは、無条件の切り捨てを示すことを目的としている場合にのみ、最適に使用されます（たとえば、上位ビットの内容に関係なく、as u32 で u64 の下位 32 ビットを選択する場合）。

絶対に正しいキャスト（例: u32 から u64 へのキャスト）では、キャストが実際に完璧であることを確認するために、as ではなく From または Into を使用することをおすすめします。正しくない可能性があるキャストについては、絶対に正しいキャストとは異なる方法でそれらを処理したい場合に、TryFrom と TryInto を使用できます。

Read と Write

Read と BufRead を使用することで、u8 ソースを抽象化できます。

use std::io::{BufRead, BufReader, Read, Result};

fn count_lines<R: Read>(reader: R) -> usize {
    let buf_reader = BufReader::new(reader);
    buf_reader.lines().count()
}

fn main() -> Result<()> {
    let slice: &[u8] = b"foo\nbar\nbaz\n";
    println!("lines in slice: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("lines in file: {}", count_lines(file));
    Ok(())
}

同様に、Write を使用すると、u8 シンクを抽象化できます。

use std::io::{Result, Write};

fn log<W: Write>(writer: &mut W, msg: &str) -> Result<()> {
    writer.write_all(msg.as_bytes())?;
    writer.write_all("\n".as_bytes())
}

fn main() -> Result<()> {
    let mut buffer = Vec::new();
    log(&mut buffer, "Hello")?;
    log(&mut buffer, "World")?;
    println!("Logged: {buffer:?}");
    Ok(())
}

Default トレイト

Default トレイトは、型のデフォルト値を生成します。

#[derive(Debug, Default)]
struct Derived {
    x: u32,
    y: String,
    z: Implemented,
}

#[derive(Debug)]
struct Implemented(String);

impl Default for Implemented {
    fn default() -> Self {
        Self("John Smith".into())
    }
}

fn main() {
    let default_struct = Derived::default();
    println!("{default_struct:#?}");

    let almost_default_struct =
        Derived { y: "Y is set!".into(), ..Derived::default() };
    println!("{almost_default_struct:#?}");

    let nothing: Option<Derived> = None;
    println!("{:#?}", nothing.unwrap_or_default());
}

クロージャ

クロージャやラムダ式には、名前を付けることができない型があります。ただし、これらは特別な Fn、FnMut、FnOnce トレイトを備えています。

fn apply_and_log(func: impl FnOnce(i32) -> i32, func_name: &str, input: i32) {
    println!("Calling {func_name}({input}): {}", func(input))
}

fn main() {
    let n = 3;
    let add_3 = |x| x + n;
    apply_and_log(&add_3, "add_3", 10);
    apply_and_log(&add_3, "add_3", 20);

    let mut v = Vec::new();
    let mut accumulate = |x: i32| {
        v.push(x);
        v.iter().sum::<i32>()
    };
    apply_and_log(&mut accumulate, "accumulate", 4);
    apply_and_log(&mut accumulate, "accumulate", 5);

    let multiply_sum = |x| x * v.into_iter().sum::<i32>();
    apply_and_log(multiply_sum, "multiply_sum", 3);
}

fn make_greeter(prefix: String) -> impl Fn(&str) {
    return move |name| println!("{} {}", prefix, name);
}

fn main() {
    let hi = make_greeter("Hi".to_string());
    hi("Greg");
}

演習: ROT13暗号

この例では、古典的な 「ROT13」暗号を実装します。このコードをプレイグラウンドにコピーし、欠落しているビットを実装してください。結果が有効な UTF-8 のままになるように、ASCII アルファベット文字のみをローテーションします。

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

// `RotDecoder` の `Read` トレイトを実装します。

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

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

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

それぞれが 13 文字ずつローテーションされる 2 つの RotDecoder インスタンスを連結するとどうなるでしょうか。

解答

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

impl<R: Read> Read for RotDecoder<R> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        let size = self.input.read(buf)?;
        for b in &mut buf[..size] {
            if b.is_ascii_alphabetic() {
                let base = if b.is_ascii_uppercase() { 'A' } else { 'a' } as u8;
                *b = (*b - base + self.rot) % 26 + base;
            }
        }
        Ok(size)
    }
}

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

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

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

3 日目のトレーニングにようこそ

本日の内容:

• メモリ管理、ライフタイム、借用チェッカー: Rust がメモリの安全性を確保する仕組み。
• スマートポインタ: 標準ライブラリのポインタ型。

スケジュール

Including 10 minute breaks, this session should take about 2 hours and 20 minutes. It contains:

メモリ管理

This segment should take about 1 hour. It contains:

プログラム メモリの見直し

プログラムは、次の 2 つの方法でメモリを割り当てます。

• スタック: ローカル変数用の連続したメモリ領域。

  • 値のサイズは固定されており、コンパイル時に判明しています。
  • 非常に高速: スタック ポインタを移動するだけです。
  • 関数呼び出しによって行われるため、管理が容易です。
  • メモリ局所性に優れています。

• ヒープ: 関数呼び出しに依存しない値の保持領域。

  • 値のサイズは動的で、実行時に決定されます。
  • スタックよりやや低速で、何らかののブックキーピングが必要です。
  • メモリの局所性が保証されません。

例

String を作成すると、スタックには固定サイズのメタデータが配置され、ヒープにはサイズが動的に決定されるデータ（実際の文字列）が配置されます。

fn main() {
    let s1 = String::from("Hello");
}

fn main() {
    let mut s1 = String::from("Hello");
    s1.push(' ');
    s1.push_str("world");
    // 自宅では行わないでください。これは説明のみを目的としています。
    // String はそのレイアウトを保証しないため、未定義の動作が
    // 発生する可能性があります。
    unsafe {
        let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);
        println!("capacity = {capacity}, ptr = {ptr:#x}, len = {len}");
    }
}

メモリ管理のアプローチ

伝統的に、言語は大きく 2 つのカテゴリに分類されます。

• 手動でのメモリ管理による完全な制御: C、C++、Pascal など
  • プログラマーがヒープメモリを割り当てまたは解放するタイミングを決定します。
  • プログラマーは、ポインタがまだ有効なメモリを指しているかどうかを判断する必要があります。
  • 調査によると、プログラマーは判断を誤ることがあります。
• 実行時の自動メモリ管理による完全な安全性: Java、Python、Go、Haskell など
  • ランタイム システムにより、メモリは参照できなくなるまで解放されません。
  • Typically implemented with reference counting or garbage collection.

Rust ではこの 2 つを融合することで、新たに以下の特徴を提供します。

コンパイル時の適切なメモリ管理の適用による、完全な制御と安全性。

これは、明示的な所有権の概念によって実現されます。

所有権

すべての変数バインディングには有効なスコープがあり、スコープ外で変数を使用するとエラーになります。

struct Point(i32, i32);

fn main() {
    {
        let p = Point(3, 4);
        println!("x: {}", p.0);
    }
    println!("y: {}", p.1);
}

これを、変数が値を 所有 していると表現します。すべての Rustの値所有者は常に 1 人です。

スコープから外れると変数が破棄 (drop) され、データが解放されます。ここでデストラクタを実行してリソースを解放できます。

ムーブセマンティクス

代入すると、変数間で 所有権 が移動します。

fn main() {
    let s1: String = String::from("Hello!");
    let s2: String = s1;
    println!("s2: {s2}");
    // println!("s1: {s1}");
}

• s1 を s2 に代入すると、所有権が移動します。
• s1 がスコープ外になると、何も所有してないからです（何も所有しません）。
• s2 がスコープ外になると、文字列データは解放されます。

s2 に移動する前:

s2 に移動した後:

次の例のように、関数に値を渡すと、その値は関数パラメータに代入されます。これにより、所有権が移動します。

fn say_hello(name: String) {
    println!("Hello {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name);
    // say_hello(name);
}

std::string s1 = "Cpp";
std::string s2 = s1;  // s1 にデータを複製します。

Clone

値のコピーを作成したい場合は、Clone トレイトを使用できます。

fn say_hello(name: String) {
    println!("Hello {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name.clone());
    say_hello(name);
}

Copy 型

言語としてのデフォルトはムーブセマンティクスですが、特定の型ではデフォルトでコピーが行われます。

fn main() {
    let x = 42;
    let y = x;
    println!("x: {x}"); // would not be accessible if not Copy
    println!("y: {y}");
}

これらの型は Copy トレイトを実装しているからです。

あなたが定義した独自の型のデフォルトをコピーセマンティクスにすることが出来ます。

#[derive(Copy, Clone, Debug)]
struct Point(i32, i32);

fn main() {
    let p1 = Point(3, 4);
    let p2 = p1;
    println!("p1: {p1:?}");
    println!("p2: {p2:?}");
}

• 代入後は、p1 と p2 の両方が独自のデータを所有します。
• p1.clone() を使用してデータを明示的にコピーすることもできます。

Drop トレイト

Drop を実装している値では、スコープから外れるときに実行するコードを指定できます。

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Dropping {}", self.name);
    }
}

fn main() {
    let a = Droppable { name: "a" };
    {
        let b = Droppable { name: "b" };
        {
            let c = Droppable { name: "c" };
            let d = Droppable { name: "d" };
            println!("Exiting block B");
        }
        println!("Exiting block A");
    }
    drop(a);
    println!("Exiting main");
}

演習: ビルダー型

この例では、すべてのデータを持つ複雑なデータ型を実装します。「ビルダー パターン」で便利な関数を使用して、新しい値を 1 つずつ構築できるようにします。

抜けている部分を記入してください。

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// ソフトウェア パッケージの表現。
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// このパッケージの表現を依存関係として返し、
    /// 他のパッケージのビルドに使用します。
    fn as_dependency(&self) -> Dependency {
        todo!("1")
    }
}

/// パッケージのビルダー。`build()` を使用して `Package` 自体を作成します。
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        todo!("2")
    }

    /// パッケージのバージョンを設定します。
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// パッケージ作成者を設定します。
    fn authors(mut self, authors: Vec<String>) -> Self {
        todo!("3")
    }

    /// 依存関係を追加します。
    fn dependency(mut self, dependency: Dependency) -> Self {
        todo!("4")
    }

    /// 言語を設定します。設定しない場合、言語はデフォルトで None になります。
    fn language(mut self, language: Language) -> Self {
        todo!("5")
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

解答

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// ソフトウェア パッケージの表現。
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// このパッケージの表現を依存関係として返し、
    /// 他のパッケージのビルドに使用します。
    fn as_dependency(&self) -> Dependency {
        Dependency {
            name: self.name.clone(),
            version_expression: self.version.clone(),
        }
    }
}

/// パッケージのビルダー。`build()` を使用して `Package` 自体を作成します。
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        Self(Package {
            name: name.into(),
            version: "0.1".into(),
            authors: vec![],
            dependencies: vec![],
            language: None,
        })
    }

    /// パッケージのバージョンを設定します。
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// パッケージ作成者を設定します。
    fn authors(mut self, authors: Vec<String>) -> Self {
        self.0.authors = authors;
        self
    }

    /// 依存関係を追加します。
    fn dependency(mut self, dependency: Dependency) -> Self {
        self.0.dependencies.push(dependency);
        self
    }

    /// 言語を設定します。設定しない場合、言語はデフォルトで None になります。
    fn language(mut self, language: Language) -> Self {
        self.0.language = Some(language);
        self
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

スマートポインタ

This segment should take about 55 minutes. It contains:

Box<T>

Box は、ヒープ上のデータへの所有ポインタです。

fn main() {
    let five = Box::new(5);
    println!("five: {}", *five);
}

Box<T> は Deref<Target = T> を実装しているため、Box<T> に対して T のメソッドを直接呼び出すことができます。

Recursive data types or data types with dynamic sizes cannot be stored inline without a pointer indirection. Box accomplishes that indirection:

#[derive(Debug)]
enum List<T> {
    /// 空でないリスト: 最初の要素とリストの残り。
    Element(T, Box<List<T>>),
    /// 空のリスト。
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

Rc

Rc は、参照カウントされた共有ポインタです。複数の場所から同じデータを参照する必要がある場合に使用します。

use std::rc::Rc;

fn main() {
    let a = Rc::new(10);
    let b = Rc::clone(&a);

    println!("a: {a}");
    println!("b: {b}");
}

• See Arc and Mutex if you are in a multi-threaded context.
• 共有ポインタを Weak ポインタにダウングレード (downgrade) すると、ドロップされるサイクルを作成できます。

所有されたトレイトオブジェクト

We previously saw how trait objects can be used with references, e.g &dyn Pet. However, we can also use trait objects with smart pointers like Box to create an owned trait object: Box<dyn Pet>.

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Woof, my name is {}!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

fn main() {
    let pets: Vec<Box<dyn Pet>> = vec![
        Box::new(Cat { lives: 9 }),
        Box::new(Dog { name: String::from("Fido"), age: 5 }),
    ];
    for pet in pets {
        println!("Hello, who are you? {}", pet.talk());
    }
}

petsを割り当てた後のメモリレイアウト：

演習: バイナリツリー

バイナリツリーは、すべてのノードに 2 つの子（左と右）があるツリー型のデータ構造です。ここでは、各ノードが値を格納するツリーを作成します。ある特定のノード N について、N の左側のサブツリー内のすべてのノードにはより小さい値が含まれ、N の右側のサブツリー内のすべてのノードにはより大きい値が含まれます。

次の型を実装して、指定されたテストが通るようにします。

追加の実習: バイナリツリーに値を順番に返すイテレータを実装します。

/// バイナリツリーのノード。
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// 空の可能性のあるサブツリー。
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// バイナリツリーを使用して一連の値を格納するコンテナ。
///
/// 同じ値が複数回追加された場合、その値は 1 回だけ格納される。
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

// Implement `new`, `insert`, `len`, and `has` for `Subtree`.

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

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // 固有のアイテムではない
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

解答

use std::cmp::Ordering;

/// バイナリツリーのノード。
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// 空の可能性のあるサブツリー。
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// バイナリツリーを使用して一連の値を格納するコンテナ。
///
/// 同じ値が複数回追加された場合、その値は 1 回だけ格納される。
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

impl<T: Ord> Subtree<T> {
    fn new() -> Self {
        Self(None)
    }

    fn insert(&mut self, value: T) {
        match &mut self.0 {
            None => self.0 = Some(Box::new(Node::new(value))),
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.insert(value),
                Ordering::Equal => {}
                Ordering::Greater => n.right.insert(value),
            },
        }
    }

    fn has(&self, value: &T) -> bool {
        match &self.0 {
            None => false,
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.has(value),
                Ordering::Equal => true,
                Ordering::Greater => n.right.has(value),
            },
        }
    }

    fn len(&self) -> usize {
        match &self.0 {
            None => 0,
            Some(n) => 1 + n.left.len() + n.right.len(),
        }
    }
}

impl<T: Ord> Node<T> {
    fn new(value: T) -> Self {
        Self { value, left: Subtree::new(), right: Subtree::new() }
    }
}

fn main() {
    let mut tree = BinaryTree::new();
    tree.insert("foo");
    assert_eq!(tree.len(), 1);
    tree.insert("bar");
    assert!(tree.has(&"foo"));
}

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

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // 固有のアイテムではない
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

おかえり

Including 10 minute breaks, this session should take about 1 hour and 55 minutes. It contains:

借用

This segment should take about 55 minutes. It contains:

値の借用

前に説明したように、関数を呼び出すときに所有権を移動する代わりに、関数で値を借用できます。

#[derive(Debug)]
struct Point(i32, i32);

fn add(p1: &Point, p2: &Point) -> Point {
    Point(p1.0 + p2.0, p1.1 + p2.1)
}

fn main() {
    let p1 = Point(3, 4);
    let p2 = Point(10, 20);
    let p3 = add(&p1, &p2);
    println!("{p1:?} + {p2:?} = {p3:?}");
}

• add 関数は 2 つのポイントを 借用 し、新しいポイントを返します。
• 呼び出し元は入力の所有権を保持します。

借用チェック

Rust の 借用チェッカー は、値を借用する方法に制限を設けます。任意の値に対して、常に次の制限が課されます。

• 値への共有参照を 1 つ以上持つことが出来ます。または、
• 値への排他参照を 1 つだけ持つことが出来ます。

fn main() {
    let mut a: i32 = 10;
    let b: &i32 = &a;

    {
        let c: &mut i32 = &mut a;
        *c = 20;
    }

    println!("a: {a}");
    println!("b: {b}");
}

Borrow Errors

As a concrete example of how these borrowing rules prevent memory errors, consider the case of modifying a collection while there are references to its elements:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    let elem = &vec[2];
    vec.push(6);
    println!("{elem}");
}

Similarly, consider the case of iterator invalidation:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    for elem in &vec {
        vec.push(elem * 2);
    }
}

内部可変性

場合によっては、共有（読み取り専用）参照の背後にあるデータを変更する必要があります。たとえば、共有データ構造に内部キャッシュがあり、そのキャッシュを読み取り専用メソッドから更新する必要がある場合があります。

「内部可変性」パターンは、共有参照を通した排他的（可変）アクセスを可能にします。標準ライブラリには、これを安全に行うための方法がいくつか用意されており、通常はランタイム チェックを実行することで安全性を確保します。

Cell

Cell wraps a value and allows getting or setting the value using only a shared reference to the Cell. However, it does not allow any references to the inner value. Since there are no references, borrowing rules cannot be broken.

use std::cell::Cell;

fn main() {
    // Note that `cell` is NOT declared as mutable.
    let cell = Cell::new(5);

    cell.set(123);
    println!("{}", cell.get());
}

RefCell

RefCell allows accessing and mutating a wrapped value by providing alternative types Ref and RefMut that emulate &T/&mut T without actually being Rust references.

These types perform dynamic checks using a counter in the RefCell to prevent existence of a RefMut alongside another Ref/RefMut.

By implementing Deref (and DerefMut for RefMut), these types allow calling methods on the inner value without allowing references to escape.

use std::cell::RefCell;

fn main() {
    // Note that `cell` is NOT declared as mutable.
    let cell = RefCell::new(5);

    {
        let mut cell_ref = cell.borrow_mut();
        *cell_ref = 123;

        // This triggers an error at runtime.
        // let other = cell.borrow();
        // println!("{}", *other);
    }

    println!("{cell:?}");
}

演習: 健康に関する統計

健康管理システムの実装の一環として、ユーザーの健康に関する統計情報を追跡する必要があります。

impl ブロックのスタブ関数と、User 構造体の定義がある状態から開始します。User 構造体の impl ブロックにおいてスタブ化された関数を実装することです。

以下のコードを https://play.rust-lang.org/ にコピーし、実体がないメソッドの中身を実装します。

// TODO: 実装が完了したら、これを削除します。
#![allow(unused_variables, dead_code)]


#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        todo!("Update a user's statistics based on measurements from a visit to the doctor")
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("I'm {} and my age is {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);
    assert!((report.height_change - 0.9).abs() < 0.00001);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
    assert_eq!(report.height_change, 0.0);
}

解答

#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        self.visit_count += 1;
        let bp = measurements.blood_pressure;
        let report = HealthReport {
            patient_name: &self.name,
            visit_count: self.visit_count as u32,
            height_change: measurements.height - self.height,
            blood_pressure_change: match self.last_blood_pressure {
                Some(lbp) => {
                    Some((bp.0 as i32 - lbp.0 as i32, bp.1 as i32 - lbp.1 as i32))
                }
                None => None,
            },
        };
        self.height = measurements.height;
        self.last_blood_pressure = Some(bp);
        report
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("I'm {} and my age is {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);
    assert!((report.height_change - 0.9).abs() < 0.00001);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
    assert_eq!(report.height_change, 0.0);
}

ライフタイム

This segment should take about 50 minutes. It contains:

関数とライフタイム

参照にはライフタイムがあり、これは参照する値よりも「長く存続」してはなりません。これは借用チェッカーによって検証されます。

これまで見てきたとおり、ライフタイムは暗黙に扱えますが、&'a Point、&'document str のように明示的に指定することもできます。ライフタイムは ' で始まり、'a が一般的なデフォルト名です。&'a Point は、「少なくともライフタイム a の間は有効な、借用した Point」とと解釈します。

ライフタイムは常にコンパイラによって推測されます。自分でライフタイムを割り当てることはできません。明示的なライフタイム アノテーションを使用すると、あいまいなところに制約を課すことができます。それに対し、コンパイラはその制約を満たすライフタイムを設定できることを検証します。

関数に値を渡し、関数から値を返すことを考慮する場合、ライフタイムはより複雑になります。

#[derive(Debug)]
struct Point(i32, i32);

fn left_most(p1: &Point, p2: &Point) -> &Point {
    if p1.0 < p2.0 {
        p1
    } else {
        p2
    }
}

fn main() {
    let p1: Point = Point(10, 10);
    let p2: Point = Point(20, 20);
    let p3 = left_most(&p1, &p2); // p3 のライフタイムは？
    println!("p3: {p3:?}");
}

fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {

関数とライフタイム

関数の引数や戻り値のライフタイムは完全に指定する必要がありますが、Rust ではほとんどの場合、いくつかの簡単なルールにより、ライフタイムを省略できます。これは推論ではなく、構文の省略形にすぎません。

• ライフタイム アノテーションが付いていない各引数には、1 つのライフタイムが与えられます。
• 引数のライフタイムが 1 つしかない場合、アノテーションのない戻り値すべてにそのライフタイムが与えられます。
• 引数のライフタイムが複数あり、最初のライフタイムが self である場合、アノテーションのない戻り値すべてにそのライフタイムが与えられます。

#[derive(Debug)]
struct Point(i32, i32);

fn cab_distance(p1: &Point, p2: &Point) -> i32 {
    (p1.0 - p2.0).abs() + (p1.1 - p2.1).abs()
}

fn nearest<'a>(points: &'a [Point], query: &Point) -> Option<&'a Point> {
    let mut nearest = None;
    for p in points {
        if let Some((_, nearest_dist)) = nearest {
            let dist = cab_distance(p, query);
            if dist < nearest_dist {
                nearest = Some((p, dist));
            }
        } else {
            nearest = Some((p, cab_distance(p, query)));
        };
    }
    nearest.map(|(p, _)| p)
}

fn main() {
    let points = &[Point(1, 0), Point(1, 0), Point(-1, 0), Point(0, -1)];
    println!("{:?}", nearest(points, &Point(0, 2)));
}

fn nearest<'a, 'q>(points: &'a [Point], query: &'q Point) -> Option<&'q Point> {

データ構造とライフタイム

データ型が借用データを内部に保持する場合、ライフタイムアノテーションを付ける必要があります。

#[derive(Debug)]
struct Highlight<'doc>(&'doc str);

fn erase(text: String) {
    println!("Bye {text}!");
}

fn main() {
    let text = String::from("The quick brown fox jumps over the lazy dog.");
    let fox = Highlight(&text[4..19]);
    let dog = Highlight(&text[35..43]);
    // 消去（テキスト）;
    println!("{fox:?}");
    println!("{dog:?}");
}

演習: Protobufの解析

この演習では、protobuf バイナリ エンコード用のパーサーを作成します。見かけよりも簡単ですので、心配はいりません。これは、データのスライスを渡す一般的な解析パターンを示しています。基になるデータ自体がコピーされることはありません。

protobuf メッセージを完全に解析するには、フィールド番号でインデックス付けされたフィールドの型を知る必要があります。これは通常、proto ファイルで提供されます。この演習では、フィールドごとに呼び出される関数の match ステートメントに、その情報をエンコードします。

次の proto を使用します。

message PhoneNumber {
  optional string number = 1;
  optional string type = 2;
}

message Person {
  optional string name = 1;
  optional int32 id = 2;
  repeated PhoneNumber phones = 3;
}

proto メッセージは、連続するフィールドとしてエンコードされます。それぞれが後ろに値を伴う「タグ」として実装されます。タグにはフィールド番号（例: Person メッセージの id フィールドには 2）と、バイト ストリームからペイロードがどのように決定されるかを定義するワイヤータイプが含まれます。

タグを含む整数は、VARINT と呼ばれる可変長エンコードで表されます。幸いにも、parse_varint は以下ですでに定義されています。また、このコードでは、Person フィールドと PhoneNumber フィールドを処理し、メッセージを解析してこれらのコールバックに対する一連の呼び出しに変換するコールバックも定義しています。

残る作業は、parse_field 関数と、Person および PhoneNumber の ProtoMessage トレイトを実装するだけです。

/// ワイヤー上で見えるワイヤータイプ。
enum WireType {
    /// Varint WireType は、値が単一の VARINT であることを示します。
    Varint,
    /// The I64 WireType indicates that the value is precisely 8 bytes in
    /// little-endian order containing a 64-bit signed integer or double type.
    //I64,  -- not needed for this exercise
    /// The Len WireType indicates that the value is a length represented as a
    /// VARINT followed by exactly that number of bytes.
    Len,
    // The I32 WireType indicates that the value is precisely 4 bytes in
    // little-endian order containing a 32-bit signed integer or float type.
    //I32,  -- not needed for this exercise
}

#[derive(Debug)]
/// ワイヤータイプに基づいて型指定されたフィールドの値。
enum FieldValue<'a> {
    Varint(u64),
    //I64（i64）、  -- この演習では不要
    Len(&'a [u8]),
    //I32(i32),  -- not needed for this exercise
}

#[derive(Debug)]
/// フィールド番号とその値を含むフィールド。
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64、  -- この演習では不要
            2 => WireType::Len,
            //5 => WireType::I32,  -- not needed for this exercise
            _ => panic!("Invalid wire type: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Expected string to be a `Len` field");
        };
        std::str::from_utf8(data).expect("Invalid string")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Expected bytes to be a `Len` field");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Expected `u64` to be a `Varint` field");
        };
        *value
    }
}

/// VARINT を解析し、解析した値と残りのバイトを返します。
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Not enough bytes for varint");
        };
        if b & 0x80 == 0 {
            // これは VARINT の最後のバイトであるため、
            // u64 に変換して返します。
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // 7 バイトを超える値は無効です。
    panic!("Too many bytes for varint");
}

/// タグをフィールド番号と WireType に変換します。
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}


/// フィールドを解析して残りのバイトを返します。
fn parse_field(data: &[u8]) -> (Field, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        _ => todo!("ワイヤータイプに応じて、フィールドを構築し、必要な量のバイトを消費します。")
    };
    todo!("フィールドと、未消費のバイトを返します。")
}

/// 指定されたデータ内のメッセージを解析し、メッセージのフィールドごとに
/// `T::add_field` を呼び出します。
///
/// 入力全体が消費されます。
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

// TODO: Person と PhoneNumber の ProtoMessage を実装します。

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    println!("{:#?}", person);
}

解答

/// ワイヤー上で見えるワイヤータイプ。
enum WireType {
    /// Varint WireType は、値が単一の VARINT であることを示します。
    Varint,
    /// The I64 WireType indicates that the value is precisely 8 bytes in
    /// little-endian order containing a 64-bit signed integer or double type.
    //I64,  -- not needed for this exercise
    /// The Len WireType indicates that the value is a length represented as a
    /// VARINT followed by exactly that number of bytes.
    Len,
    // The I32 WireType indicates that the value is precisely 4 bytes in
    // little-endian order containing a 32-bit signed integer or float type.
    //I32,  -- not needed for this exercise
}

#[derive(Debug)]
/// ワイヤータイプに基づいて型指定されたフィールドの値。
enum FieldValue<'a> {
    Varint(u64),
    //I64（i64）、  -- この演習では不要
    Len(&'a [u8]),
    //I32(i32),  -- not needed for this exercise
}

#[derive(Debug)]
/// フィールド番号とその値を含むフィールド。
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64、  -- この演習では不要
            2 => WireType::Len,
            //5 => WireType::I32,  -- not needed for this exercise
            _ => panic!("Invalid wire type: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("Expected string to be a `Len` field");
        };
        std::str::from_utf8(data).expect("Invalid string")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("Expected bytes to be a `Len` field");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("Expected `u64` to be a `Varint` field");
        };
        *value
    }
}

/// VARINT を解析し、解析した値と残りのバイトを返します。
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("Not enough bytes for varint");
        };
        if b & 0x80 == 0 {
            // これは VARINT の最後のバイトであるため、
            // u64 に変換して返します。
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // 7 バイトを超える値は無効です。
    panic!("Too many bytes for varint");
}

/// タグをフィールド番号と WireType に変換します。
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}

/// フィールドを解析して残りのバイトを返します。
fn parse_field(data: &[u8]) -> (Field, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        WireType::Varint => {
            let (value, remainder) = parse_varint(remainder);
            (FieldValue::Varint(value), remainder)
        }
        WireType::Len => {
            let (len, remainder) = parse_varint(remainder);
            let len: usize = len.try_into().expect("len not a valid `usize`");
            if remainder.len() < len {
                panic!("Unexpected EOF");
            }
            let (value, remainder) = remainder.split_at(len);
            (FieldValue::Len(value), remainder)
        }
    };
    (Field { field_num, value: fieldvalue }, remainder)
}

/// 指定されたデータ内のメッセージを解析し、メッセージのフィールドごとに
/// `T::add_field` を呼び出します。
///
/// 入力全体が消費されます。
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}

#[derive(PartialEq)]
#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(PartialEq)]
#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

impl<'a> ProtoMessage<'a> for Person<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.name = field.value.as_str(),
            2 => self.id = field.value.as_u64(),
            3 => self.phone.push(parse_message(field.value.as_bytes())),
            _ => {} // それ以外をすべてスキップ
        }
    }
}

impl<'a> ProtoMessage<'a> for PhoneNumber<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.number = field.value.as_str(),
            2 => self.type_ = field.value.as_str(),
            _ => {} // それ以外をすべてスキップ
        }
    }
}

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    println!("{:#?}", person);
}

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

    #[test]
    fn test_id() {
        let person_id: Person = parse_message(&[0x10, 0x2a]);
        assert_eq!(person_id, Person { name: "", id: 42, phone: vec![] });
    }

    #[test]
    fn test_name() {
        let person_name: Person = parse_message(&[
            0x0a, 0x0e, 0x62, 0x65, 0x61, 0x75, 0x74, 0x69, 0x66, 0x75, 0x6c, 0x20,
            0x6e, 0x61, 0x6d, 0x65,
        ]);
        assert_eq!(
            person_name,
            Person { name: "beautiful name", id: 0, phone: vec![] }
        );
    }

    #[test]
    fn test_just_person() {
        let person_name_id: Person =
            parse_message(&[0x0a, 0x04, 0x45, 0x76, 0x61, 0x6e, 0x10, 0x16]);
        assert_eq!(person_name_id, Person { name: "Evan", id: 22, phone: vec![] });
    }

    #[test]
    fn test_phone() {
        let phone: Person = parse_message(&[
            0x0a, 0x00, 0x10, 0x00, 0x1a, 0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x33,
            0x34, 0x2d, 0x37, 0x37, 0x37, 0x2d, 0x39, 0x30, 0x39, 0x30, 0x12, 0x04,
            0x68, 0x6f, 0x6d, 0x65,
        ]);
        assert_eq!(
            phone,
            Person {
                name: "",
                id: 0,
                phone: vec![PhoneNumber { number: "+1234-777-9090", type_: "home" },],
            }
        );
    }
}

4 日目のトレーニングにようこそ

本日は、Rust での大規模なソフトウェアのビルドに関連するトピックを取り上げます。

• イテレータ: Iterator トレイトの詳細。
• モジュールと可視性。
• Testing.
• エラー処理: パニック、Result、try 演算子 ?。
• アンセーフRust: 安全な Rust では記述できない場合の回避策。

スケジュール

Including 10 minute breaks, this session should take about 2 hours and 40 minutes. It contains:

イテレータ

This segment should take about 45 minutes. It contains:

Iterator

Iterator トレイトは、コレクション内の一連の要素に対して順番に処理を適用することを可能にします。このトレイトはnextメソッドを必要とし、それにより多くのメソッドを提供します。多くの標準ライブラリ型で Iterator が実装されていますが、自分で実装することもできます。

struct Fibonacci {
    curr: u32,
    next: u32,
}

impl Iterator for Fibonacci {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        let new_next = self.curr + self.next;
        self.curr = self.next;
        self.next = new_next;
        Some(self.curr)
    }
}

fn main() {
    let fib = Fibonacci { curr: 0, next: 1 };
    for (i, n) in fib.enumerate().take(5) {
        println!("fib({i}): {n}");
    }
}

IntoIterator

Iterator トレイトは、イテレータを作成した後に反復処理を行う方法を示します。関連するトレイト IntoIterator は、ある型に対するイテレータを作成する方法を定義します。これは for ループによって自動的に使用されます。

struct Grid {
    x_coords: Vec<u32>,
    y_coords: Vec<u32>,
}

impl IntoIterator for Grid {
    type Item = (u32, u32);
    type IntoIter = GridIter;
    fn into_iter(self) -> GridIter {
        GridIter { grid: self, i: 0, j: 0 }
    }
}

struct GridIter {
    grid: Grid,
    i: usize,
    j: usize,
}

impl Iterator for GridIter {
    type Item = (u32, u32);

    fn next(&mut self) -> Option<(u32, u32)> {
        if self.i >= self.grid.x_coords.len() {
            self.i = 0;
            self.j += 1;
            if self.j >= self.grid.y_coords.len() {
                return None;
            }
        }
        let res = Some((self.grid.x_coords[self.i], self.grid.y_coords[self.j]));
        self.i += 1;
        res
    }
}

fn main() {
    let grid = Grid { x_coords: vec![3, 5, 7, 9], y_coords: vec![10, 20, 30, 40] };
    for (x, y) in grid {
        println!("point = {x}, {y}");
    }
}

FromIterator

FromIterator を使用すると、Iterator からコレクションを作成できます。

fn main() {
    let primes = vec![2, 3, 5, 7];
    let prime_squares = primes.into_iter().map(|p| p * p).collect::<Vec<_>>();
    println!("prime_squares: {prime_squares:?}");
}

fn collect<B>(self) -> B
where
    B: FromIterator<Self::Item>,
    Self: Sized

演習: イテレータのメソッドチェーン

この演習では、複雑な計算を実装するためにIterator トレイトで提供されているメソッドをいくつかを探して使用する必要があります。

次のコードを https://play.rust-lang.org/ にコピーし、テストが通るようにしてください。イテレータ式を使用し、その結果をcollectすることで戻り値を生成します。

#![allow(unused)]
fn main() {
/// `values`において、`offset`だけ離れた要素間の差を計算します。
/// なお、`values`の末尾要素の次は先頭へ戻ることとします。
///
/// 結果の要素 `n` は `values[(n+offset)%len] - values[n]` です。
fn offset_differences(offset: usize, values: Vec<i32>) -> Vec<i32> {
    unimplemented!()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}
}

解答

/// `values`において、`offset`だけ離れた要素間の差を計算します。
/// なお、`values`の末尾要素の次は先頭へ戻ることとします。
///
/// 結果の要素 `n` は `values[(n+offset)%len] - values[n]` です。
fn offset_differences(offset: usize, values: Vec<i32>) -> Vec<i32> {
    let a = (&values).into_iter();
    let b = (&values).into_iter().cycle().skip(offset);
    a.zip(b).map(|(a, b)| *b - *a).collect()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}

fn main() {}

モジュール

This segment should take about 40 minutes. It contains:

モジュール

impl ブロックで関数を型の名前空間に所属させる方法はすでに見てきました。

同様に、mod を使用して型と関数の名前空間を指定できます。

mod foo {
    pub fn do_something() {
        println!("In the foo module");
    }
}

mod bar {
    pub fn do_something() {
        println!("In the bar module");
    }
}

fn main() {
    foo::do_something();
    bar::do_something();
}

ファイルシステム階層

モジュールの定義内容を省略すると、Rust はそれを別のファイルで探します。

mod garden;

This tells Rust that the garden module content is found at src/garden.rs. Similarly, a garden::vegetables module can be found at src/garden/vegetables.rs.

crate ルートは以下の場所にあります。

• src/lib.rs（ライブラリ クレートの場合）
• src/main.rs（バイナリ クレートの場合）

ファイルで定義されたモジュールに対して、「内部ドキュメント用コメント」を使用して説明を加えることもできます。これらのコメントは、それが含まれるアイテム（この場合はモジュール）に対する説明になります。

//! このモジュールは畑を実装します（パフォーマンスの高い発芽の
//! 実装を含む）。

// このモジュールから型を再エクスポートします。
pub use garden::Garden;
pub use seeds::SeedPacket;

/// 指定された種をまきます。
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// 十分に実っている畑で作物を収穫します。
pub fn harvest(garden: &mut Garden) {
    todo!()
}

可視性

モジュールはプライバシーの境界です。

• モジュール アイテムはデフォルトでプライベートです（実装の詳細は表示されません）。
• 親アイテムと兄弟アイテムは常に見えます。
• 言い換えれば、あるアイテムがモジュール foo から見える場合、そのアイテムは foo のすべての子孫から見えます。

mod outer {
    fn private() {
        println!("outer::private");
    }

    pub fn public() {
        println!("outer::public");
    }

    mod inner {
        fn private() {
            println!("outer::inner::private");
        }

        pub fn public() {
            println!("outer::inner::public");
            super::private();
        }
    }
}

fn main() {
    outer::public();
}

use、super、self

モジュールは、use を使用して別のモジュールのシンボルをスコープに取り込むことができます。次のような記述はモジュールの先頭においてよく見られます。

use std::collections::HashSet;
use std::process::abort;

パス

パスは次のように解決されます。

1. 相対パスの場合:

   • foo または self::foo は、現在のモジュール内の foo を参照します。
   • super::foo は、親モジュール内の foo を参照します。

2. 絶対パスの場合:

   • crate::foo は、現在のクレートのルート内の foo を参照します。
   • bar::foo は、bar クレート内の foo を参照します。

演習: GUI ライブラリのモジュール

この演習では、小規模な GUI ライブラリ実装を再編成します。このライブラリでは、Widget トレイト、そのトレイトのいくつかの実装、main 関数を定義しています。

通常は、各型または密接に関連する型のセットを個別のモジュールに配置するので、ウィジェット タイプごとに独自のモジュールを用意する必要があります。

Cargo Setup

Rust プレイグラウンドは 1 つのファイルしかサポートしていないため、ローカル ファイル システムで Cargo プロジェクトを作成する必要があります。

cargo init gui-modules
cd gui-modules
cargo run

生成された src/main.rs を編集して mod ステートメントを追加し、src ディレクトリにファイルを追加します。

ソース

GUI ライブラリの単一モジュール実装は次のとおりです。

pub trait Widget {
    /// `self` の自然な幅。
    fn width(&self) -> usize;

    /// ウィジェットをバッファに描画します。
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// ウィジェットを標準出力に描画します。
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub struct Label {
    label: String,
}

impl Label {
    fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

pub struct Button {
    label: Label,
}

impl Button {
    fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // 枠線用に 4 つのパディングを追加します。
        self.inner_width() + 4
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: Result<(), std::fmt::Error> を返すように draw_into を変更します。次に、.unwrap() の代わりに
        // ? 演算子を使用します。
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        self.label.width() + 8 // パディングを少し追加します。
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

fn main() {
    let mut window = Window::new("Rust GUI Demo 1.23");
    window.add_widget(Box::new(Label::new("This is a small text GUI demo.")));
    window.add_widget(Box::new(Button::new("Click me!")));
    window.draw();
}

解答

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// ---- src/widgets.rs ----
mod button;
mod label;
mod window;

pub trait Widget {
    /// `self` の自然な幅。
    fn width(&self) -> usize;

    /// ウィジェットをバッファに描画します。
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// ウィジェットを標準出力に描画します。
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub use button::Button;
pub use label::Label;
pub use window::Window;

// ---- src/widgets/label.rs ----
use super::Widget;

pub struct Label {
    label: String,
}

impl Label {
    pub fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        // ANCHOR_END: Label-width
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    // ANCHOR: Label-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Label-draw_into
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

// ---- src/widgets/button.rs ----
use super::{Label, Widget};

pub struct Button {
    label: Label,
}

impl Button {
    pub fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        // ANCHOR_END: Button-width
        self.label.width() + 8 // パディングを少し追加します。
    }

    // ANCHOR: Button-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Button-draw_into
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

// ---- src/widgets/window.rs ----
use super::Widget;

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    pub fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    pub fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // ANCHOR_END: Window-width
        // 枠線に 4 つのパディングを追加します。
        self.inner_width() + 4
    }

    // ANCHOR: Window-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Window-draw_into
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: エラー処理について学習した後で、
        // Result<(), std::fmt::Error> を返すように draw_into を変更できます。次に、ここで
        // .unwrap() の代わりに ? 演算子を使用します。
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

// ---- src/main.rs ----
mod widgets;

use widgets::Widget;

fn main() {
    let mut window = widgets::Window::new("Rust GUI Demo 1.23");
    window
        .add_widget(Box::new(widgets::Label::new("This is a small text GUI demo.")));
    window.add_widget(Box::new(widgets::Button::new("Click me!")));
    window.draw();
}

テスト

This segment should take about 45 minutes. It contains:

ユニットテスト

Rust と Cargo には、シンプルな単体テスト フレームワークが付属しています。

• 単体テストはコードのあらゆる場所に記述可能です。

• 統合テストはtests/ディレクトリ内に記述します。

テストには #[test] のマークが付きます。多くの場合、単体テストは通常ネストされたtestsモジュールに配置され、#[cfg(test)]によりテストのビルド時にのみコンパイルされるようになります。

fn first_word(text: &str) -> &str {
    match text.find(' ') {
        Some(idx) => &text[..idx],
        None => &text,
    }
}

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

    #[test]
    fn test_empty() {
        assert_eq!(first_word(""), "");
    }

    #[test]
    fn test_single_word() {
        assert_eq!(first_word("Hello"), "Hello");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word("Hello World"), "Hello");
    }
}

• これにより、プライベート ヘルパーの単体テストを行えます。
• #[cfg(test)] 属性が付与されたコードは cargo test の実行時にのみ有効になります。

他のタイプのテスト

インテグレーションテスト

ライブラリをクライアントとしてテストする場合は、統合テストを使用します。

tests/ の下に .rs ファイルを作成します。

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

これらのテストでは、クレートの公開 API にのみアクセスできます。

ドキュメンテーションテスト

Rust には、ドキュメントのテストに関する機能が組み込まれています。

#![allow(unused)]
fn main() {
/// 指定した長さに文字列を短縮します。
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Hello World", 5), "Hello");
/// assert_eq!(shorten_string("Hello World", 20), "Hello World");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• /// コメント内のコードブロックは、自動的に Rust コードとみなされます。
• コードは cargo test の一環としてコンパイルされ、実行されます。
• コードに # を追加すると、ドキュメントには表示されなくなりますが、コンパイルと実行は引き続き行われます。
• Rust プレイグラウンド で上記のコードをテストします。

コンパイラの Lints と Clippy

Rust コンパイラは、読みやすいエラーおよびlintメッセージを生成します。Clippy では、さらに多くの lint がグループにまとめられており、プロジェクトごとに有効にできます。

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!("X probably fits in a u16, right? {}", x as u16);
}

演習: Luhnアルゴリズム

Luhn アルゴリズム は、クレジット カード番号の検証に使用されます。このアルゴリズムは文字列を入力として受け取り、以下の処理を行ってクレジット カード番号を検証します。

• Ignore all spaces. Reject numbers with fewer than two digits.

• 右から左に見ていきながら、それぞれ2桁目の数字を 2 倍にします。数値 1234 の場合、3 と 1 を 2 倍にします。数値 98765 の場合、6 と 8 を 2 倍にします。

• 桁を 2 倍にした後、結果が 9 より大きい場合はその桁を合計します。したがって、7 を 2 倍すると 14 になり、1 + 4 = 5 になります。

• 2 倍にしていない数字と 2 倍にした数字をすべて合計します。

• クレジット カード番号は、合計が 0 で終わる場合に有効です。

The provided code provides a buggy implementation of the luhn algorithm, along with two basic unit tests that confirm that most of the algorithm is implemented correctly.

以下のコードを https://play.rust-lang.org/ にコピーし、提供された実装のバグを発見するための追加のテストを記述し、見つけたバグを修正してください。

#![allow(unused)]
fn main() {
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

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

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }
}
}

解答

// これは問題に記述されているバグのあるバージョンです。
#[cfg(never)]
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

// これは解答で、以下のすべてのテストに合格します。
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;
    let mut digits = 0;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            digits += 1;
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else if c.is_whitespace() {
            // New: accept whitespace.
            continue;
        } else {
            // New: reject all other characters.
            return false;
        }
    }

    // New: check that we have at least two digits
    digits >= 2 && sum % 10 == 0
}

fn main() {
    let cc_number = "1234 5678 1234 5670";
    println!(
        "Is {cc_number} a valid credit card number? {}",
        if luhn(cc_number) { "yes" } else { "no" }
    );
}

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

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }

    #[test]
    fn test_non_digit_cc_number() {
        assert!(!luhn("foo"));
        assert!(!luhn("foo 0 0"));
    }

    #[test]
    fn test_empty_cc_number() {
        assert!(!luhn(""));
        assert!(!luhn(" "));
        assert!(!luhn("  "));
        assert!(!luhn("    "));
    }

    #[test]
    fn test_single_digit_cc_number() {
        assert!(!luhn("0"));
    }

    #[test]
    fn test_two_digit_cc_number() {
        assert!(luhn(" 0 0 "));
    }
}

おかえり

Including 10 minute breaks, this session should take about 2 hours and 20 minutes. It contains:

エラー処理

This segment should take about 1 hour and 5 minutes. It contains:

パニック（panic）

Rust は「パニック」を使用して致命的なエラーを処理します。

実行時に致命的なエラーが発生すると、Rust はパニックをトリガーします。

fn main() {
    let v = vec![10, 20, 30];
    println!("v[100]: {}", v[100]);
}

• パニックは、回復不能なエラーや予期しないエラーに使用するためのものです。
  • パニックはプログラムにバグがあることの兆候です。
  • ランタイム エラー（境界チェックの失敗など）は、パニックになる場合があります。
  • アサーション（assert! など）は失敗時にパニックになります。
  • 特定の目的でパニックさせてあい場合には、panic! マクロを使用できます。
• パニックが発生すると、スタックが「アンワインド」され、関数がリターンされたかのように値がドロップされます。
• クラッシュが許容されない場合は、パニックが発生しない API（Vec::get など）を使用します。

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "No problem here!");
    println!("{result:?}");

    let result = panic::catch_unwind(|| {
        panic!("oh no!");
    });
    println!("{result:?}");
}

Result

Our primary mechanism for error handling in Rust is the Result enum, which we briefly saw when discussing standard library types.

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Dear diary: {contents} ({bytes} bytes)");
            } else {
                println!("Could not read file content");
            }
        }
        Err(err) => {
            println!("The diary could not be opened: {err}");
        }
    }
}

Try演算子

connection-refused や file-not-found などのランタイム エラーは Result 型で処理されますが、すべての呼び出しでこの型を照合するのは面倒な場合があります。try 演算子 ? は、呼び出し元にエラーを返すのに使用されます。これにより、一般的な以下のコードを、はるかにシンプルなコードに変換できます。

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

変換後のコード:

some_expression?

この演算子を使用することで、エラー処理コードを簡素化できます。

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

fn read_username(path: &str) -> Result<String, io::Error> {
    let username_file_result = fs::File::open(path);
    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(err) => return Err(err),
    };

    let mut username = String::new();
    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(err) => Err(err),
    }
}

fn main() {
    //fs::write("config.dat", "alice").unwrap();
    let username = read_username("config.dat");
    println!("username or error: {username:?}");
}

Try変換

? を実際に展開すると、前述のコードよりも少し複雑なコードになります。

expression?

上のコードは、以下と同じように動作します。

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

ここでの From::from 呼び出しは、エラー型を関数が返す型に変換しようとしていることを意味します。これにより、エラーを上位レベルのエラーに簡単にカプセル化できます。

例

use std::error::Error;
use std::io::Read;
use std::{fmt, fs, io};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername(String),
}

impl Error for ReadUsernameError {}

impl fmt::Display for ReadUsernameError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            Self::IoError(e) => write!(f, "I/O error: {e}"),
            Self::EmptyUsername(path) => write!(f, "Found no username in {path}"),
        }
    }
}

impl From<io::Error> for ReadUsernameError {
    fn from(err: io::Error) -> Self {
        Self::IoError(err)
    }
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //std::fs::write("config.dat", "").unwrap();
    let username = read_username("config.dat");
    println!("username or error: {username:?}");
}

動的なエラー型

さまざまな可能性をカバーする独自の列挙型を記述することなく、あらゆる種類のエラーを返せるようにしたい場合があります。std::error::Error トレイトを使用すると、あらゆるエラーを含めることができるトレイト オブジェクトを簡単に作成できます。

use std::error::Error;
use std::fs;
use std::io::Read;

fn read_count(path: &str) -> Result<i32, Box<dyn Error>> {
    let mut count_str = String::new();
    fs::File::open(path)?.read_to_string(&mut count_str)?;
    let count: i32 = count_str.parse()?;
    Ok(count)
}

fn main() {
    fs::write("count.dat", "1i3").unwrap();
    match read_count("count.dat") {
        Ok(count) => println!("Count: {count}"),
        Err(err) => println!("Error: {err}"),
    }
}

thiserror

The thiserror crate provides macros to help avoid boilerplate when defining error types. It provides derive macros that assist in implementing From<T>, Display, and the Error trait.

use std::io::Read;
use std::{fs, io};
use thiserror::Error;

#[derive(Debug, Error)]
enum ReadUsernameError {
    #[error("I/O error: {0}")]
    IoError(#[from] io::Error),
    #[error("Found no username in {0}")]
    EmptyUsername(String),
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Username: {username}"),
        Err(err) => println!("Error: {err:?}"),
    }
}

anyhow

The anyhow crate provides a rich error type with support for carrying additional contextual information, which can be used to provide a semantic trace of what the program was doing leading up to the error.

This can be combined with the convenience macros from thiserror to avoid writing out trait impls explicitly for custom error types.

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("Found no username in {0}")]
struct EmptyUsernameError(String);

fn read_username(path: &str) -> Result<String> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)
        .with_context(|| format!("Failed to open {path}"))?
        .read_to_string(&mut username)
        .context("Failed to read")?;
    if username.is_empty() {
        bail!(EmptyUsernameError(path.to_string()));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Username: {username}"),
        Err(err) => println!("Error: {err:?}"),
    }
}

演習: Result を使用した書き換え

The following implements a very simple parser for an expression language. However, it handles errors by panicking. Rewrite it to instead use idiomatic error handling and propagate errors to a return from main. Feel free to use thiserror and anyhow.

Hint: start by fixing error handling in the parse function. Once that is working correctly, update Tokenizer to implement Iterator<Item=Result<Token, TokenizerError>> and handle that in the parser.

use std::iter::Peekable;
use std::str::Chars;

/// 算術演算子。
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// 式言語のトークン
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// 式言語の式
#[derive(Debug, PartialEq)]
enum Expression {
    /// 変数への参照。
    Var(String),
    /// リテラル数値。
    Number(u32),
    /// バイナリ演算。
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Token;

    fn next(&mut self) -> Option<Token> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(self.collect_number(c)),
            'a'..='z' => Some(self.collect_identifier(c)),
            '+' => Some(Token::Operator(Op::Add)),
            '-' => Some(Token::Operator(Op::Sub)),
            _ => panic!("Unexpected character {c}"),
        }
    }
}

fn parse(input: &str) -> Expression {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(tokens: &mut Tokenizer<'a>) -> Expression {
        let Some(tok) = tokens.next() else {
            panic!("Unexpected end of input");
        };
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse().expect("Invalid 32-bit integer");
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => panic!("Unexpected token {tok:?}"),
        };
        // バイナリ演算が存在する場合はパースします。
        match tokens.next() {
            None => expr,
            Some(Token::Operator(op)) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)),
            ),
            Some(tok) => panic!("Unexpected token {tok:?}"),
        }
    }

    parse_expr(&mut tokens)
}

fn main() {
    let expr = parse("10+foo+20-30");
    println!("{expr:?}");
}

解答

use thiserror::Error;
use std::iter::Peekable;
use std::str::Chars;

/// 算術演算子。
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// 式言語のトークン
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// 式言語の式
#[derive(Debug, PartialEq)]
enum Expression {
    /// 変数への参照。
    Var(String),
    /// リテラル数値。
    Number(u32),
    /// バイナリ演算。
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

#[derive(Debug, Error)]
enum TokenizerError {
    #[error("Unexpected character '{0}' in input")]
    UnexpectedCharacter(char),
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Result<Token, TokenizerError>;

    fn next(&mut self) -> Option<Result<Token, TokenizerError>> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(Ok(self.collect_number(c))),
            'a'..='z' | '_' => Some(Ok(self.collect_identifier(c))),
            '+' => Some(Ok(Token::Operator(Op::Add))),
            '-' => Some(Ok(Token::Operator(Op::Sub))),
            _ => Some(Err(TokenizerError::UnexpectedCharacter(c))),
        }
    }
}

#[derive(Debug, Error)]
enum ParserError {
    #[error("Tokenizer error: {0}")]
    TokenizerError(#[from] TokenizerError),
    #[error("Unexpected end of input")]
    UnexpectedEOF,
    #[error("Unexpected token {0:?}")]
    UnexpectedToken(Token),
    #[error("Invalid number")]
    InvalidNumber(#[from] std::num::ParseIntError),
}

fn parse(input: &str) -> Result<Expression, ParserError> {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(
        tokens: &mut Tokenizer<'a>,
    ) -> Result<Expression, ParserError> {
        let tok = tokens.next().ok_or(ParserError::UnexpectedEOF)??;
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse()?;
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => return Err(ParserError::UnexpectedToken(tok)),
        };
        // バイナリ演算が存在する場合はパースします。
        Ok(match tokens.next() {
            None => expr,
            Some(Ok(Token::Operator(op))) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)?),
            ),
            Some(Err(e)) => return Err(e.into()),
            Some(Ok(tok)) => return Err(ParserError::UnexpectedToken(tok)),
        })
    }

    parse_expr(&mut tokens)
}

fn main() -> anyhow::Result<()> {
    let expr = parse("10+foo+20-30")?;
    println!("{expr:?}");
    Ok(())
}

Unsafe Rust

This segment should take about 1 hour and 5 minutes. It contains:

Unsafe Rust

Rust 言語は 2 つの部分で構成されています。

• 安全な Rust: メモリセーフで、未定義の動作は起こりえません。
• アンセーフRust: 前提条件に違反した場合、未定義の動作がトリガーされる可能性があります。

このコースでは主に安全な Rust を見てきましたが、安全でない Rust とは何かを理解しておくことが重要です。

アンセーフなコードは通常、小規模で分離されており、その正確性は慎重に文書化されている必要があります。通常は安全な抽象化レイヤでラップされています。

アンセーフRustでは、次の 5 つの新機能を利用できます。

• 生ポインタの参照外し。
• 可変の静的変数へのアクセスまたは変更。
• union フィールドへのアクセス。
• extern 関数を含む unsafe 関数の呼び出し。
• unsafe トレイトの実装。

次に、安全でない機能について簡単に説明します。詳しくは、Rust Book の第 19.1 章と、Rustonomicon をご覧ください。

生ポインタの参照外し

ポインタの作成は安全ですが、参照外しには unsafe が必要です。

fn main() {
    let mut s = String::from("careful!");

    let r1 = &raw mut s;
    let r2 = r1 as *const String;

    // SAFETY: r1 and r2 were obtained from references and so are guaranteed to
    // be non-null and properly aligned, the objects underlying the references
    // from which they were obtained are live throughout the whole unsafe
    // block, and they are not accessed either through the references or
    // concurrently through any other pointers.
    unsafe {
        println!("r1 is: {}", *r1);
        *r1 = String::from("uhoh");
        println!("r2 is: {}", *r2);
    }

    // 安全でないため、NOT SAFE。このような記述をしないでください。
    /*
    let r3: &String = unsafe { &*r1 };
    drop(s);
    println!("r3 is: {}", *r3);
    */
}

可変なstatic変数

不変の静的変数は安全に読み取ることができます。

static HELLO_WORLD: &str = "Hello, world!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

ただし、データ競合が発生する可能性があるため、可変静的変数の読み取りと書き込みは安全ではありません。

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    // SAFETY: There are no other threads which could be accessing `COUNTER`.
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    // SAFETY: There are no other threads which could be accessing `COUNTER`.
    unsafe {
        println!("COUNTER: {COUNTER}");
    }
}

共用体

共用体は列挙型に似ていますが、アクティブ フィールドを自分でトラッキングする必要があります。

#[repr(C)]
union MyUnion {
    i: u8,
    b: bool,
}

fn main() {
    let u = MyUnion { i: 42 };
    println!("int: {}", unsafe { u.i });
    println!("bool: {}", unsafe { u.b }); // 未定義の動作
}

Unsafe関数の呼び出し

Unsafe関数の呼び出し

未定義の動作を回避するために満たす必要がある追加の前提条件がある関数またはメソッドは、unsafe とマークできます。

extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let emojis = "🗻∈🌏";

    // SAFETY: The indices are in the correct order, within the bounds of the
    // string slice, and lie on UTF-8 sequence boundaries.
    unsafe {
        println!("emoji: {}", emojis.get_unchecked(0..4));
        println!("emoji: {}", emojis.get_unchecked(4..7));
        println!("emoji: {}", emojis.get_unchecked(7..11));
    }

    println!("char count: {}", count_chars(unsafe { emojis.get_unchecked(0..7) }));

    // SAFETY: `abs` doesn't deal with pointers and doesn't have any safety
    // requirements.
    unsafe {
        println!("Absolute value of -3 according to C: {}", abs(-3));
    }

    // UTF-8 エンコード要件を満たさない場合、メモリの安全性が損なわれます。
    // println!("emoji: {}", unsafe { emojis.get_unchecked(0..3) });
    // println!("char count: {}", count_chars(unsafe {
    // emojis.get_unchecked(0..3) }));
}

fn count_chars(s: &str) -> usize {
    s.chars().count()
}

Unsafe関数の書き方

未定義の動作を回避するために特定の条件が必要な場合は、独自の関数を unsafe とマークできます。

/// 指定されたポインタが指す値をスワップします。
///
/// # Safety
///
/// ポインタが有効で、適切にアラインされている必要があります。
unsafe fn swap(a: *mut u8, b: *mut u8) {
    let temp = *a;
    *a = *b;
    *b = temp;
}

fn main() {
    let mut a = 42;
    let mut b = 66;

    // SAFETY: ...
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

Unsafeなトレイトの実装

関数と同様に、未定義の動作を回避するために実装で特定の条件を保証する必要がある場合は、トレイトを unsafe としてマークできます。

For example, the zerocopy crate has an unsafe trait that looks something like this:

use std::{mem, slice};

/// ...
/// # Safety
/// 型には定義された表現が必要で、パディングがあってはなりません。
pub unsafe trait IntoBytes {
    fn as_bytes(&self) -> &[u8] {
        let len = mem::size_of_val(self);
        unsafe { slice::from_raw_parts((&raw const self).cast::<u8>(), len) }
    }
}

// SAFETY: `u32` has a defined representation and no padding.
unsafe impl IntoBytes for u32 {}

安全なFFIラッパ

Rust は、外部関数インターフェース（FFI）を介した関数呼び出しを強力にサポートしています。これを使用して、ディレクトリ内のファイル名を読み取るために Cプログラムで使用する libc 関数の安全なラッパーを作成します。

以下のマニュアル ページをご覧ください。

• opendir(3)
• readdir(3)
• closedir(3)

std::ffi モジュールも参照してください。ここには、この演習で必要な文字列型が多数掲載されています。

以下のすべての型間で変換を行います。

• &str から CString: 末尾の \0 文字にも領域を割り当てる必要があります。
• CString から *const i8: C 関数を呼び出すためのポインタが必要です。
• *const i8 から &CStr: 末尾の \0 文字を検出できるものが必要です。
• &CStr から &[u8]: バイトのスライスは「不明なデータ」用の汎用的な インターフェースです。
• &[u8] から &OsStr: &OsStr は OsString に変換するための中間ステップであり、OsStrExt を使用して作成します。
• &OsStr内のデータを返し、さらに再びreaddirを呼び出せるようにするためには&OsStr内のデータをクローンする必要があります。

Nomicon にも、FFI に関する有益な章があります。

以下のコードを https://play.rust-lang.org/ にコピーし、不足している関数とメソッドを記入します。

// TODO: 実装が完了したら、これを削除します。
#![allow(unused_imports, unused_variables, dead_code)]

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // オペーク型。https://doc.rust-lang.org/nomicon/ffi.html をご覧ください。
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // readdir(3) の Linux マニュアル ページに沿ったレイアウト。ino_t と
    // off_t は
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h} の定義に従って解決されます。
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // macOSマニュアル ページのdir(5)に沿ったレイアウト。
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    unsafe extern "C" {
        pub unsafe fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub unsafe fn readdir(s: *mut DIR) -> *const dirent;

        // https://github.com/rust-lang/libc/issues/414、および  macOS 版マニュアル ページのstat(2)における
        // _DARWIN_FEATURE_64_BIT_INODE に関するセクションをご覧ください。
        //
        // 「これらのアップデートが利用可能になる前に存在していたプラットフォーム("Platforms that existed before these updates were available")」とは、
        // Intel および PowerPC 上の macOS（iOS / wearOS などではない）を指します。
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub unsafe fn readdir(s: *mut DIR) -> *const dirent;

        pub unsafe fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // opendir を呼び出し、成功した場合は Ok 値を返し、
        // それ以外の場合はメッセージとともに Err を返します。
        unimplemented!()
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // NULL ポインタが返されるまで readdir を呼び出し続けます。
        unimplemented!()
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // 必要に応じて closedir を呼び出します。
        unimplemented!()
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

解答

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // オペーク型。https://doc.rust-lang.org/nomicon/ffi.html をご覧ください。
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // readdir(3) の Linux マニュアル ページに沿ったレイアウト。ino_t と
    // off_t は
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h} の定義に従って解決されます。
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // macOSマニュアル ページのdir(5)に沿ったレイアウト。
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    unsafe extern "C" {
        pub unsafe fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub unsafe fn readdir(s: *mut DIR) -> *const dirent;

        // https://github.com/rust-lang/libc/issues/414、および  macOS 版マニュアル ページのstat(2)における
        // _DARWIN_FEATURE_64_BIT_INODE に関するセクションをご覧ください。
        //
        // 「これらのアップデートが利用可能になる前に存在していたプラットフォーム("Platforms that existed before these updates were available")」とは、
        // Intel および PowerPC 上の macOS（iOS / wearOS などではない）を指します。
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub unsafe fn readdir(s: *mut DIR) -> *const dirent;

        pub unsafe fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // opendir を呼び出し、成功した場合は Ok 値を返し、
        // それ以外の場合はメッセージとともに Err を返します。
        let path =
            CString::new(path).map_err(|err| format!("Invalid path: {err}"))?;
        // SAFETY: path.as_ptr()がNULLであることはありません。
        let dir = unsafe { ffi::opendir(path.as_ptr()) };
        if dir.is_null() {
            Err(format!("Could not open {path:?}"))
        } else {
            Ok(DirectoryIterator { path, dir })
        }
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // NULL ポインタが返されるまで readdir を呼び出し続けます。
        // SAFETY: self.dir は決して NULL になりません。
        let dirent = unsafe { ffi::readdir(self.dir) };
        if dirent.is_null() {
            // ディレクトリの最後に到達しました。
            return None;
        }
        // 安全: dirent は NULL ではなく、dirent.d_name は NUL
        // 文字終端されています。
        let d_name = unsafe { CStr::from_ptr((*dirent).d_name.as_ptr()) };
        let os_str = OsStr::from_bytes(d_name.to_bytes());
        Some(os_str.to_owned())
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Call closedir as needed.
        // SAFETY: self.dir is never NULL.
        if unsafe { ffi::closedir(self.dir) } != 0 {
            panic!("Could not close {:?}", self.path);
        }
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

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

    #[test]
    fn test_nonexisting_directory() {
        let iter = DirectoryIterator::new("no-such-directory");
        assert!(iter.is_err());
    }

    #[test]
    fn test_empty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Non UTF-8 character in path")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", ".."]);
        Ok(())
    }

    #[test]
    fn test_nonempty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        std::fs::write(tmp.path().join("foo.txt"), "The Foo Diaries\n")?;
        std::fs::write(tmp.path().join("bar.png"), "<PNG>\n")?;
        std::fs::write(tmp.path().join("crab.rs"), "//! Crab\n")?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Non UTF-8 character in path")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", "..", "bar.png", "crab.rs", "foo.txt"]);
        Ok(())
    }
}

Android での Rust へようこそ

Rust は Android のシステム ソフトウェアでサポートされています。つまり、新しいサービス、ライブラリ、ドライバ、さらにはファームウェアを Rust で作成できます（または、必要に応じて既存のコードを改善できます）。

セットアップ

コードのテストのためにCuttlefish Android Virtual Device を使用します。既存のDeviceがあればそれにアクセスできることを確認し、そうでなければ以下のコマンドにより作成しておいてください。

source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create

詳しくは、Android デベロッパー Codelab をご覧ください。

The code on the following pages can be found in the src/android/ directory of the course material. Please git clone the repository to follow along.

ビルドのルール

Android ビルドシステム（Soong）は、さまざまなモジュールを通じて Rust をサポートしています。

次に rust_binary と rust_library を見ていきます。

Rust バイナリ

簡単なアプリから始めましょう。AOSP チェックアウトのルートで、次のファイルを作成します。

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/main.rs"],
}

hello_rust/src/main.rs:

//! Rust のデモ。

/// 挨拶を標準出力に出力します。
fn main() {
    println!("Hello from Rust!");
}

これで、バイナリをビルド、push、実行できます。

m hello_rust
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust" /data/local/tmp
adb shell /data/local/tmp/hello_rust

Hello from Rust!

Rust ライブラリ

rust_library を使用して、Android 用の新しい Rust ライブラリを作成します。

ここでは、2 つのライブラリへの依存関係を宣言します。

• libgreeting: 以下で定義します。
• libtextwrap: すでにexternal/rust/crates/ に取り込まれているクレートです。

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust_with_dep",
    crate_name: "hello_rust_with_dep",
    srcs: ["src/main.rs"],
    rustlibs: [
        "libgreetings",
        "libtextwrap",
    ],
    prefer_rlib: true, // ダイナミック リンク エラーを回避するために必要です。
}

rust_library {
    name: "libgreetings",
    crate_name: "greetings",
    srcs: ["src/lib.rs"],
}

hello_rust/src/main.rs:

//! Rust のデモ。

use greetings::greeting;
use textwrap::fill;

/// 挨拶を標準出力に出力します。
fn main() {
    println!("{}", fill(&greeting("Bob"), 24));
}

hello_rust/src/lib.rs:

//! 挨拶ライブラリ。

/// `name` に挨拶します。
pub fn greeting(name: &str) -> String {
    format!("Hello {name}, it is very nice to meet you!")
}

前と同じようにバイナリをビルド、push、実行します。

m hello_rust_with_dep
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_with_dep" /data/local/tmp
adb shell /data/local/tmp/hello_rust_with_dep

Hello Bob, it is very
nice to meet you!

AIDL（Androidインターフェイス定義言語）

Rust では Android インターフェース定義言語（AIDL） がサポートされています。

• Rust コードは既存の AIDL サーバーを呼び出すことができます。
• Rust では新しい AIDL サーバーを作成できます。

誕生日サービスのチュートリアル

To illustrate how to use Rust with Binder, we're going to walk through the process of creating a Binder interface. We're then going to both implement the described service and write client code that talks to that service.

AIDL インターフェース

サービスの API を宣言するには、AIDL インターフェースを使用します。

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

package com.example.birthdayservice;

/** 誕生日サービスのインターフェース。*/
interface IBirthdayService {
    /** 「お誕生日おめでとう」というメッセージを生成します。*/
    String wishHappyBirthday(String name, int years);
}

birthday_service/aidl/Android.bp:

aidl_interface {
    name: "com.example.birthdayservice",
    srcs: ["com/example/birthdayservice/*.aidl"],
    unstable: true,
    backend: {
        rust: { // Rust はデフォルトでは無効です。
            enabled: true,
        },
    },
}

Generated Service API

Binder generates a trait corresponding to the interface definition. trait to talk to the service.

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** 誕生日サービスのインターフェース。*/
interface IBirthdayService {
    /** 「お誕生日おめでとう」というメッセージを生成します。*/
    String wishHappyBirthday(String name, int years);
}

Generated trait:

trait IBirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String>;
}

Your service will need to implement this trait, and your client will use this trait to talk to the service.

サービスの実装

次に、AIDL サービスを実装します。

birthday_service/src/lib.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

/// `IBirthdayService` の実装。
pub struct BirthdayService;

impl binder::Interface for BirthdayService {}

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String> {
        Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
    }
}

birthday_service/Android.bp:

rust_library {
    name: "libbirthdayservice",
    srcs: ["src/lib.rs"],
    crate_name: "birthdayservice",
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
}

AIDL サーバー

次に、サービスを公開するサーバーを作成します。

birthday_service/src/server.rs:

//! 誕生日サービス。
use birthdayservice::BirthdayService;
use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::BnBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// 誕生日サービスのエントリ ポイント。
fn main() {
    let birthday_service = BirthdayService;
    let birthday_service_binder = BnBirthdayService::new_binder(
        birthday_service,
        binder::BinderFeatures::default(),
    );
    binder::add_service(SERVICE_IDENTIFIER, birthday_service_binder.as_binder())
        .expect("Failed to register service");
    binder::ProcessState::join_thread_pool();
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_server",
    crate_name: "birthday_server",
    srcs: ["src/server.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
        "libbirthdayservice",
    ],
    prefer_rlib: true, // ダイナミック リンク エラーを回避するためです。
}

デプロイ

次に、サービスをビルド、push、開始します。

m birthday_server
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_server" /data/local/tmp
adb root
adb shell /data/local/tmp/birthday_server

別のターミナルで、サービスが実行されていることを確認します。

adb shell service check birthdayservice

Service birthdayservice: found

service call を使用してサービスを呼び出すこともできます。

adb shell service call birthdayservice 1 s16 Bob i32 24

Result: Parcel(
  0x00000000: 00000000 00000036 00610048 00700070 '....6...H.a.p.p.'
  0x00000010: 00200079 00690042 00740072 00640068 'y. .B.i.r.t.h.d.'
  0x00000020: 00790061 00420020 0062006f 0020002c 'a.y. .B.o.b.,. .'
  0x00000030: 006f0063 0067006e 00610072 00750074 'c.o.n.g.r.a.t.u.'
  0x00000040: 0061006c 00690074 006e006f 00200073 'l.a.t.i.o.n.s. .'
  0x00000050: 00690077 00680074 00740020 00650068 'w.i.t.h. .t.h.e.'
  0x00000060: 00320020 00200034 00650079 00720061 ' .2.4. .y.e.a.r.'
  0x00000070: 00210073 00000000                   's.!.....        ')

AIDL クライアント

ようやくここで、新しいサービス用の Rust クライアントを作成します。

birthday_service/src/client.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// 誕生日サービスを呼び出します。
fn main() -> Result<(), Box<dyn Error>> {
    let name = std::env::args().nth(1).unwrap_or_else(|| String::from("Bob"));
    let years = std::env::args()
        .nth(2)
        .and_then(|arg| arg.parse::<i32>().ok())
        .unwrap_or(42);

    binder::ProcessState::start_thread_pool();
    let service = binder::get_interface::<dyn IBirthdayService>(SERVICE_IDENTIFIER)
        .map_err(|_| "Failed to connect to BirthdayService")?;

    // Call the service.
    let msg = service.wishHappyBirthday(&name, years)?;
    println!("{msg}");
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_client",
    crate_name: "birthday_client",
    srcs: ["src/client.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
    prefer_rlib: true, // ダイナミック リンク エラーを回避するためです。
}

クライアントが libbirthdayservice に依存していないことに注目してください。

デバイスでクライアントをビルド、push、実行します。

m birthday_client
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_client" /data/local/tmp
adb shell /data/local/tmp/birthday_client Charlie 60

Happy Birthday Charlie, congratulations with the 60 years!

APIの変更

APIを拡張して、クライアントが誕生日カードに追加する複数行のメッセージを指定できるようにします。

package com.example.birthdayservice;

/** 誕生日サービスのインターフェース。*/
interface IBirthdayService {
    /** 「お誕生日おめでとう」というメッセージを生成します。*/
    String wishHappyBirthday(String name, int years, in String[] text);
}

This results in an updated trait definition for IBirthdayService:

trait IBirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String>;
}

Updating Client and Service

Update the client and server code to account for the new API.

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String> {
        let mut msg = format!(
            "Happy Birthday {name}, congratulations with the {years} years!",
        );

        for line in text {
            msg.push('\n');
            msg.push_str(line);
        }

        Ok(msg)
    }
}

birthday_service/src/client.rs:

let msg = service.wishHappyBirthday(
    &name,
    years,
    &[
        String::from("Habby birfday to yuuuuu"),
        String::from("And also: many more"),
    ],
)?;

Working With AIDL Types

AIDL types translate into the appropriate idiomatic Rust type:

• Primitive types map (mostly) to idiomatic Rust types.
• Collection types like slices, Vecs and string types are supported.
• References to AIDL objects and file handles can be sent between clients and services.
• File handles and parcelables are fully supported.

Primitive Types

Primitive types map (mostly) idiomatically:

配列型

The array types (T[], byte[], and List<T>) get translated to the appropriate Rust array type depending on how they are used in the function signature:

オブジェクトの送信

AIDL objects can be sent either as a concrete AIDL type or as the type-erased IBinder interface:

birthday_service/aidl/com/example/birthdayservice/IBirthdayInfoProvider.aidl:

package com.example.birthdayservice;

interface IBirthdayInfoProvider {
    String name();
    int years();
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.IBirthdayInfoProvider;

interface IBirthdayService {
    /** The same thing, but using a binder object. */
    String wishWithProvider(IBirthdayInfoProvider provider);

    /** The same thing, but using `IBinder`. */
    String wishWithErasedProvider(IBinder provider);
}

birthday_service/src/client.rs:

/// Rust struct implementing the `IBirthdayInfoProvider` interface.
struct InfoProvider {
    name: String,
    age: u8,
}

impl binder::Interface for InfoProvider {}

impl IBirthdayInfoProvider for InfoProvider {
    fn name(&self) -> binder::Result<String> {
        Ok(self.name.clone())
    }

    fn years(&self) -> binder::Result<i32> {
        Ok(self.age as i32)
    }
}

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    // Create a binder object for the `IBirthdayInfoProvider` interface.
    let provider = BnBirthdayInfoProvider::new_binder(
        InfoProvider { name: name.clone(), age: years as u8 },
        BinderFeatures::default(),
    );

    // Send the binder object to the service.
    service.wishWithProvider(&provider)?;

    // Perform the same operation but passing the provider as an `SpIBinder`.
    service.wishWithErasedProvider(&provider.as_binder())?;
}

Parcelables

Binder for Rust supports sending parcelables directly:

birthday_service/aidl/com/example/birthdayservice/BirthdayInfo.aidl:

package com.example.birthdayservice;

parcelable BirthdayInfo {
    String name;
    int years;
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.BirthdayInfo;

interface IBirthdayService {
    /** The same thing, but with a parcelable. */
    String wishWithInfo(in BirthdayInfo info);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    let info = BirthdayInfo { name: "Alice".into(), years: 123 };
    service.wishWithInfo(&info)?;
}

Sending Files

Files can be sent between Binder clients/servers using the ParcelFileDescriptor type:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

interface IBirthdayService {
    /** The same thing, but loads info from a file. */
    String wishFromFile(in ParcelFileDescriptor infoFile);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    // Open a file and put the birthday info in it.
    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
    writeln!(file, "{name}")?;
    writeln!(file, "{years}")?;

    // Create a `ParcelFileDescriptor` from the file and send it.
    let file = ParcelFileDescriptor::new(file);
    service.wishFromFile(&file)?;
}

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishFromFile(
        &self,
        info_file: &ParcelFileDescriptor,
    ) -> binder::Result<String> {
        // Convert the file descriptor to a `File`. `ParcelFileDescriptor` wraps
        // an `OwnedFd`, which can be cloned and then used to create a `File`
        // object.
        let mut info_file = info_file
            .as_ref()
            .try_clone()
            .map(File::from)
            .expect("Invalid file handle");

        let mut contents = String::new();
        info_file.read_to_string(&mut contents).unwrap();

        let mut lines = contents.lines();
        let name = lines.next().unwrap();
        let years: i32 = lines.next().unwrap().parse().unwrap();

        Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
    }
}

Testing in Android

Building on Testing, we will now look at how unit tests work in AOSP. Use the rust_test module for your unit tests:

testing/Android.bp:

rust_library {
    name: "libleftpad",
    crate_name: "leftpad",
    srcs: ["src/lib.rs"],
}

rust_test {
    name: "libleftpad_test",
    crate_name: "leftpad_test",
    srcs: ["src/lib.rs"],
    host_supported: true,
    test_suites: ["general-tests"],
}

testing/src/lib.rs:

#![allow(unused)]
fn main() {
//! Left-padding library.

/// Left-pad `s` to `width`.
pub fn leftpad(s: &str, width: usize) -> String {
    format!("{s:>width$}")
}

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

    #[test]
    fn short_string() {
        assert_eq!(leftpad("foo", 5), "  foo");
    }

    #[test]
    fn long_string() {
        assert_eq!(leftpad("foobar", 6), "foobar");
    }
}
}

You can now run the test with

atest --host libleftpad_test

The output looks like this:

INFO: Elapsed time: 2.666s, Critical Path: 2.40s
INFO: 3 processes: 2 internal, 1 linux-sandbox.
INFO: Build completed successfully, 3 total actions
//comprehensive-rust-android/testing:libleftpad_test_host            PASSED in 2.3s
    PASSED  libleftpad_test.tests::long_string (0.0s)
    PASSED  libleftpad_test.tests::short_string (0.0s)
Test cases: finished with 2 passing and 0 failing out of 2 test cases

Notice how you only mention the root of the library crate. Tests are found recursively in nested modules.

GoogleTest

GoogleTest クレートにより、マッチャーを使用した柔軟なテスト アサーションが可能になります。

use googletest::prelude::*;

#[googletest::test]
fn test_elements_are() {
    let value = vec!["foo", "bar", "baz"];
    expect_that!(value, elements_are!(eq(&"foo"), lt(&"xyz"), starts_with("b")));
}

最後の要素を "!" に変更すると、テストは失敗し、エラー箇所を示す構造化されたエラー メッセージが表示されます。

---- test_elements_are stdout ----
Value of: value
Expected: has elements:
  0. is equal to "foo"
  1. is less than "xyz"
  2. starts with prefix "!"
Actual: ["foo", "bar", "baz"],
  where element #2 is "baz", which does not start with "!"
  at src/testing/googletest.rs:6:5
Error: See failure output above

#[test]
fn test_multiline_string_diff() {
    let haiku = "Memory safety found,\n\
                 Rust's strong typing guides the way,\n\
                 Secure code you'll write.";
    assert_that!(
        haiku,
        eq("Memory safety found,\n\
            Rust's silly humor guides the way,\n\
            Secure code you'll write.")
    );
}

    Value of: haiku
Expected: is equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Actual: "Memory safety found,\nRust's strong typing guides the way,\nSecure code you'll write.",
  which isn't equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Difference(-actual / +expected):
 Memory safety found,
-Rust's strong typing guides the way,
+Rust's silly humor guides the way,
 Secure code you'll write.
  at src/testing/googletest.rs:17:5

モック

モックには、Mockall というライブラリが広く使用されています。トレイトを使用するようにコードをリファクタリングする必要があります。これにより、すぐにモックできるようになります。

use std::time::Duration;

#[mockall::automock]
pub trait Pet {
    fn is_hungry(&self, since_last_meal: Duration) -> bool;
}

#[test]
fn test_robot_dog() {
    let mut mock_dog = MockPet::new();
    mock_dog.expect_is_hungry().return_const(true);
    assert_eq!(mock_dog.is_hungry(Duration::from_secs(10)), true);
}

#[test]
fn test_robot_cat() {
    let mut mock_cat = MockPet::new();
    mock_cat
        .expect_is_hungry()
        .with(mockall::predicate::gt(Duration::from_secs(3 * 3600)))
        .return_const(true);
    mock_cat.expect_is_hungry().return_const(false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(1 * 3600)), false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(5 * 3600)), true);
}

ログ出力

log クレートを使用して、自動的に （デバイス上では）logcat または （ホスト上では）stdoutにログを記録するようにします。

hello_rust_logs/Android.bp:

rust_binary {
    name: "hello_rust_logs",
    crate_name: "hello_rust_logs",
    srcs: ["src/main.rs"],
    rustlibs: [
        "liblog_rust",
        "liblogger",
    ],
    host_supported: true,
}

hello_rust_logs/src/main.rs:

//! Rust ロギングのデモ。

use log::{debug, error, info};

/// 挨拶をログに記録します。
fn main() {
    logger::init(
        logger::Config::default()
            .with_tag_on_device("rust")
            .with_max_level(log::LevelFilter::Trace),
    );
    debug!("Starting program.");
    info!("Things are going fine.");
    error!("Something went wrong!");
}

デバイスでバイナリをビルド、push、実行します。

m hello_rust_logs
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_logs" /data/local/tmp
adb shell /data/local/tmp/hello_rust_logs

adb logcat でログを表示できます。

adb logcat -s rust

09-08 08:38:32.454  2420  2420 D rust: hello_rust_logs: Starting program.
09-08 08:38:32.454  2420  2420 I rust: hello_rust_logs: Things are going fine.
09-08 08:38:32.454  2420  2420 E rust: hello_rust_logs: Something went wrong!

相互運用性

Rust は他の言語との相互運用性に優れているため、次のことが可能です。

• 他の言語から Rust 関数を呼び出す。
• Rust から他の言語で記述された関数を呼び出す。

他の言語の関数を呼び出す場合は、外部関数インターフェース（FFI: foreign function interface）を使用します。

C との相互運用性

Rust は、C の呼び出し規則によるオブジェクト ファイルのリンクを完全にサポートしています。同様に、Rust 関数をエクスポートして C から呼び出すことができます。

これは手動で行うこともできます。

unsafe extern "C" {
    safe fn abs(x: i32) -> i32;
}

fn main() {
    let x = -42;
    let abs_x = abs(x);
    println!("{x}, {abs_x}");
}

We already saw this in the Safe FFI Wrapper exercise.

これは、ターゲット プラットフォームを完全に理解していることを前提としています。本番環境での使用推奨されません。

次に、より良い選択肢を見ていきます。

Bindgen の使用

bindgen ツールを使用すると、C ヘッダー ファイルからバインディングを自動生成できます。

まず、小さな C ライブラリを作成します。

interoperability/bindgen/libbirthday.h:

typedef struct card {
  const char* name;
  int years;
} card;

void print_card(const card* card);

interoperability/bindgen/libbirthday.c:

#include <stdio.h>
#include "libbirthday.h"

void print_card(const card* card) {
  printf("+--------------\n");
  printf("| Happy Birthday %s!\n", card->name);
  printf("| Congratulations with the %i years!\n", card->years);
  printf("+--------------\n");
}

これを Android.bp ファイルに追加します。

interoperability/bindgen/Android.bp:

cc_library {
    name: "libbirthday",
    srcs: ["libbirthday.c"],
}

ライブラリのラッパー ヘッダー ファイルを作成します（この例では必須ではありません）。

interoperability/bindgen/libbirthday_wrapper.h:

#include "libbirthday.h"

これで、バインディングを自動生成できます。

interoperability/bindgen/Android.bp:

rust_bindgen {
    name: "libbirthday_bindgen",
    crate_name: "birthday_bindgen",
    wrapper_src: "libbirthday_wrapper.h",
    source_stem: "bindings",
    static_libs: ["libbirthday"],
}

これで、Rust プログラムでバインディングを使用できます。

interoperability/bindgen/Android.bp:

rust_binary {
    name: "print_birthday_card",
    srcs: ["main.rs"],
    rustlibs: ["libbirthday_bindgen"],
}

interoperability/bindgen/main.rs:

//! Bindgen のデモ。

use birthday_bindgen::{card, print_card};

fn main() {
    let name = std::ffi::CString::new("Peter").unwrap();
    let card = card { name: name.as_ptr(), years: 42 };
    // SAFETY: The pointer we pass is valid because it came from a Rust
    // reference, and the `name` it contains refers to `name` above which also
    // remains valid. `print_card` doesn't store either pointer to use later
    // after it returns.
    unsafe {
        print_card(&card as *const card);
    }
}

デバイスでバイナリをビルド、push、実行します。

m print_birthday_card
adb push "$ANDROID_PRODUCT_OUT/system/bin/print_birthday_card" /data/local/tmp
adb shell /data/local/tmp/print_birthday_card

これで、自動生成されたテストを実行して、バインディングが機能していることを確認できます。

interoperability/bindgen/Android.bp:

rust_test {
    name: "libbirthday_bindgen_test",
    srcs: [":libbirthday_bindgen"],
    crate_name: "libbirthday_bindgen_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,
    clippy_lints: "none", // 生成されたファイル、lint チェックをスキップ
    lints: "none",
}

atest libbirthday_bindgen_test

Rust の呼び出し

Rust の関数と型は、C に簡単にエクスポートできます。

interoperability/rust/libanalyze/analyze.rs

//! Rust FFI のデモ。
#![deny(improper_ctypes_definitions)]

use std::os::raw::c_int;

/// Analyze the numbers.
// SAFETY: There is no other global function of this name.
#[unsafe(no_mangle)]
pub extern "C" fn analyze_numbers(x: c_int, y: c_int) {
    if x < y {
        println!("x ({x}) is smallest!");
    } else {
        println!("y ({y}) is probably larger than x ({x})");
    }
}

interoperability/rust/libanalyze/analyze.h

#ifndef ANALYSE_H
#define ANALYSE_H

void analyze_numbers(int x, int y);

#endif

interoperability/rust/libanalyze/Android.bp

rust_ffi {
    name: "libanalyze_ffi",
    crate_name: "analyze_ffi",
    srcs: ["analyze.rs"],
    include_dirs: ["."],
}

これで、これを C バイナリから呼び出せるようになりました。

interoperability/rust/analyze/main.c

#include "analyze.h"

int main() {
  analyze_numbers(10, 20);
  analyze_numbers(123, 123);
  return 0;
}

interoperability/rust/analyze/Android.bp

cc_binary {
    name: "analyze_numbers",
    srcs: ["main.c"],
    static_libs: ["libanalyze_ffi"],
}

デバイスでバイナリをビルド、push、実行します。

m analyze_numbers
adb push "$ANDROID_PRODUCT_OUT/system/bin/analyze_numbers" /data/local/tmp
adb shell /data/local/tmp/analyze_numbers

C++

CXX クレートを使用すると、Rust と C++ の間で安全な相互運用性を確保できます。

全体的なアプローチは次のようになります。

ブリッジモジュール

CXX は、各言語から他の言語に公開される関数シグネチャの記述に依存します。この記述は、#[cxx::bridge] 属性マクロでアノテーションされた Rust モジュール内の extern ブロックを使用して指定します。

#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    // 両方の言語からアクセスできるフィールドを持つ共有構造体。
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    // C++ に公開される Rust の型とシグネチャ。
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    // Rust に公開される C++ の型とシグネチャ。
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

Rust のブリッジ宣言

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MyType; // オペーク型
        fn foo(&self); // `MyType` のメソッド
        fn bar() -> Box<MyType>; // Free function
    }
}

struct MyType(i32);

impl MyType {
    fn foo(&self) {
        println!("{}", self.0);
    }
}

fn bar() -> Box<MyType> {
    Box::new(MyType(123))
}

生成された C++

#[cxx::bridge]
mod ffi {
    // C++ に公開される Rust の型とシグネチャ。
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }
}

おおよそ次のような C++ が生成されます。

struct MultiBuf final : public ::rust::Opaque {
  ~MultiBuf() = delete;

private:
  friend ::rust::layout;
  struct layout {
    static ::std::size_t size() noexcept;
    static ::std::size_t align() noexcept;
  };
};

::rust::Slice<::std::uint8_t const> next_chunk(::org::blobstore::MultiBuf &buf) noexcept;

C++ のブリッジ宣言

#[cxx::bridge]
mod ffi {
    // Rust に公開される C++ の型とシグネチャ。
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

おおよそ次のような Rust が生成されます。

#[repr(C)]
pub struct BlobstoreClient {
    _private: ::cxx::private::Opaque,
}

pub fn new_blobstore_client() -> ::cxx::UniquePtr<BlobstoreClient> {
    extern "C" {
        #[link_name = "org$blobstore$cxxbridge1$new_blobstore_client"]
        fn __new_blobstore_client() -> *mut BlobstoreClient;
    }
    unsafe { ::cxx::UniquePtr::from_raw(__new_blobstore_client()) }
}

impl BlobstoreClient {
    pub fn put(&self, parts: &mut MultiBuf) -> u64 {
        extern "C" {
            #[link_name = "org$blobstore$cxxbridge1$BlobstoreClient$put"]
            fn __put(
                _: &BlobstoreClient,
                parts: *mut ::cxx::core::ffi::c_void,
            ) -> u64;
        }
        unsafe {
            __put(self, parts as *mut MultiBuf as *mut ::cxx::core::ffi::c_void)
        }
    }
}

// ...

共有の型

#[cxx::bridge]
mod ffi {
    #[derive(Clone, Debug, Hash)]
    struct PlayingCard {
        suit: Suit,
        value: u8,  // A=1、J=11、Q=12、K=13
    }

    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

共有の列挙型

#[cxx::bridge]
mod ffi {
    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

生成された Rust:

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(transparent)]
pub struct Suit {
    pub repr: u8,
}

#[allow(non_upper_case_globals)]
impl Suit {
    pub const Clubs: Self = Suit { repr: 0 };
    pub const Diamonds: Self = Suit { repr: 1 };
    pub const Hearts: Self = Suit { repr: 2 };
    pub const Spades: Self = Suit { repr: 3 };
}
}

生成された C++:

enum class Suit : uint8_t {
  Clubs = 0,
  Diamonds = 1,
  Hearts = 2,
  Spades = 3,
};

Rustのエラー処理

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn fallible(depth: usize) -> anyhow::Result<String> {
    if depth == 0 {
        return Err(anyhow::Error::msg("fallible1 requires depth > 0"));
    }

    Ok("Success!".into())
}

C++のエラー処理

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/example.h");
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn main() {
    if let Err(err) = ffi::fallible(99) {
        eprintln!("Error: {}", err);
        process::exit(1);
    }
}

その他の型

Building in Android

cc_library_static を作成して、CXX で生成されたヘッダーとソースファイルを含む C++ ライブラリをビルドします。

cc_library_static {
    name: "libcxx_test_cpp",
    srcs: ["cxx_test.cpp"],
    generated_headers: [
        "cxx-bridge-header",
        "libcxx_test_bridge_header"
    ],
    generated_sources: ["libcxx_test_bridge_code"],
}

Building in Android

genrule を 2 つ作成します。1 つは CXX ヘッダーの生成用、もう 1 つは CXX ソースファイルの生成用です。これらは cc_library_static への入力として使用されます。

// lib.rs にある Rustからエクスポートされた関数に対する
// C++ バインディングを含む C++ ヘッダーを生成します。
genrule {
    name: "libcxx_test_bridge_header",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) --header > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.h"],
}

// Rust が呼び出す C++ コードを生成します。
genrule {
    name: "libcxx_test_bridge_code",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.cc"],
}

Building in Android

libcxx と cc_library_staticに依存する rust_binary を作成します。

rust_binary {
    name: "cxx_test",
    srcs: ["lib.rs"],
    rustlibs: ["libcxx"],
    static_libs: ["libcxx_test_cpp"],
}

Java との相互運用性

Java では、Java Native Interface（JNI） を介して共有オブジェクトを読み込むことができます。jni クレート を使用すると、互換性のあるライブラリを作成できます。

まず、Java にエクスポートする Rust 関数を作成します。

interoperability/java/src/lib.rs:

#![allow(unused)]
fn main() {
//! Rust <-> Java FFI のデモ。

use jni::objects::{JClass, JString};
use jni::sys::jstring;
use jni::JNIEnv;

/// HelloWorld::hello method implementation.
// SAFETY: There is no other global function of this name.
#[unsafe(no_mangle)]
pub extern "system" fn Java_HelloWorld_hello(
    mut env: JNIEnv,
    _class: JClass,
    name: JString,
) -> jstring {
    let input: String = env.get_string(&name).unwrap().into();
    let greeting = format!("Hello, {input}!");
    let output = env.new_string(greeting).unwrap();
    output.into_raw()
}
}

interoperability/java/Android.bp:

rust_ffi_shared {
    name: "libhello_jni",
    crate_name: "hello_jni",
    srcs: ["src/lib.rs"],
    rustlibs: ["libjni"],
}

次に、Java からこの関数を呼び出します。

interoperability/java/HelloWorld.java:

class HelloWorld {
    private static native String hello(String name);

    static {
        System.loadLibrary("hello_jni");
    }

    public static void main(String[] args) {
        String output = HelloWorld.hello("Alice");
        System.out.println(output);
    }
}

interoperability/java/Android.bp:

java_binary {
    name: "helloworld_jni",
    srcs: ["HelloWorld.java"],
    main_class: "HelloWorld",
    required: ["libhello_jni"],
}

最後に、バイナリをビルド、同期、実行します。

m helloworld_jni
adb sync  # requires adb root && adb remount
adb shell /system/bin/helloworld_jni

Chromium の Rust へようこそ

Rust は Chromium のサードパーティ ライブラリでサポートされています。Rust と既存の Chromium C++ コードを接続するには、ファースト パーティのグルーコードを使用します。

本日は、Rust で文字列を使って面白いことをしたいと思います。もし自分の担当部分にUTF8 文字列を表示するコードがある場合は、ここで述べた部分ではなく、自分のコードに対してこの手順を実行して構いません。

セットアップ

Chromium をビルドして実行できることを確認します。コードが比較的最近のもの（2023 年 11 月に対応するコミット位置 1223636 以降）であれば、任意のプラットフォームとビルドフラグのセットで問題ありません。

gn gen out/Debug
autoninja -C out/Debug chrome
out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium

（反復処理の時間を最短にするには、コンポーネントのデバッグビルドをおすすめします。これがデフォルトです）

まだ確認していない場合は、Chromium のビルド方法 を確認してください。なお、Chromium をビルドするためのセットアップには時間がかかります。

また、Visual Studio Code をインストールしておくことをおすすめします。

演習について

コースのこのパートには、相互に関連した一連の演習があります。コースの最後だけでなく、全体を通して演習を行います。特定のパートを完了する時間がない場合も、後で追いつけばよいため心配はいりません。

Chromium と Cargo のエコシステムの比較

The Rust community typically uses cargo and libraries from crates.io. Chromium is built using gn and ninja and a curated set of dependencies.

Rust でコードを記述する際は、次の選択肢があります。

• //build/rust/*.gni のテンプレート（例: 後で説明する rust_static_library）を参考にして、gn と ninja を使用します。これには、Chromium の監査済みのツールチェーンとクレートが使用されます。
• cargo を使用しますが、実際の利用をChromium の監査済みのツールチェーンとクレートに制限します。
• cargo を使用し、ツールチェーン や インターネットからダウンロードしたクレート を信頼します。

ここからは、gn と ninja に焦点を当てます。これらを使用することで、Chromium ブラウザに Rust コードを組み込むことができます。それとは別に、Cargo は Rust エコシステムの重要な部分であり、使いこなせるようになっているべきです。

Mini exercise

少人数のグループに分け、以下を行います。

• cargo がメリットをもたらす可能性のあるシナリオをブレインストーミングし、それらのシナリオのリスク プロファイルを評価します。
• gn や ninja、オフラインの cargo などを使用する際に、どのツール、ライブラリ、人々を信頼しなければならないかについて話し合います。

Chromium の Rust ポリシー

Chromium では、Chromium の エリア テクニカル リード によって承認されているまれなケースを除き、ファースト パーティでのRust使用はまだ許可されていません。

サードパーティ ライブラリに関する Chromium のポリシーについては、こちら をご覧ください。Rust は、パフォーマンスやセキュリティを高めるうえで最適な選択肢である場合を含め、さまざまな状況でサードパーティ ライブラリに使用することが許可されています。

C / C++ API を直接公開する Rust ライブラリはほとんどないため、こうしたライブラリのほぼすべてで、少量のファースト パーティ グルーコードが必要になります。

特定のサードパーティ クレート用のファースト パーティ Rust グルーコードは通常、third_party/rust/<crate>/<version>/wrapper に置かれるべきです。

以上の理由から、本日のコースでは以下に焦点を当てます。

• サードパーティの Rust ライブラリ（「クレート」）を導入する。
• Chromium C++ からクレートを使用できるようにグルーコードを記述する。

このポリシーが変更された場合は、それに合わせてコースも変更されます。

Build rules

Rust コードは通常、cargo を使用してビルドされます。Chromium は効率を高めるために gn と ninjaを使用してビルドされますが、その静的ルールによって最大限の並列処理が可能になります。Rust も例外ではありません。

Chromium に Rust コードを追加する

Chromium の既存の BUILD.gn ファイルで、rust_static_library を宣言します。

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

他の Rust ターゲットに deps を追加することもできます。後でこれを使用して、サードパーティのコードへの依存を設定します。

unsafe Rust コードの追加

安全でない Rust コードはデフォルトでは rust_static_library で禁止されており、コンパイルできません。安全でない Rust コードが必要な場合は、gn ターゲットに allow_unsafe = true を追加します（これが必要になる状況については、このコースの後半で説明します）。

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [
    "lib.rs",
    "hippopotamus.rs"
  ]
  allow_unsafe = true
}

Chromium C++からRustのコードに依存させる

上記のターゲットをいくつかの Chromium C++ ターゲットの deps に追加するだけです。

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

# または source_set、static_library など
component("preexisting_cpp") {
  deps = [ ":my_rust_lib" ]
}

Visual Studio Code

Rust コードでは型が省略されているため、優れた IDE は C++ の場合よりもさらに有用です。Visual Studio Code は Chromium の Rust で適切に機能します。Visual Studio Code を使用するにあたり、以下の点を確認してください。

• VSCode に、以前の形式の Rust サポートではなく、rust-analyzer 拡張機能があることを確認
• gn gen out/Debug --export-rust-project（またはあなたのプロジェクトにおける同様の出力ディレクトリ）
• ln -s out/Debug/rust-project.json rust-project.json

Build rules exercise

Chromium のビルドで、以下を含む新しい Rust ターゲットを //ui/base/BUILD.gn に追加します。

#![allow(unused)]
fn main() {
// SAFETY: There is no other global function of this name.
#[unsafe(no_mangle)]
pub extern "C" fn hello_from_rust() {
    println!("Hello from Rust!")
}
}

Important: note that no_mangle here is considered a type of unsafety by the Rust compiler, so you'll need to allow unsafe code in your gn target.

この新しい Rust ターゲットを //ui/base:base の依存関係として追加します。この関数を ui/base/resource/resource_bundle.cc の先頭で宣言します（後ほど、バインディング生成ツールでこれを自動化する方法を説明します）。

extern "C" void hello_from_rust();

この関数を ui/base/resource/resource_bundle.cc 内のどこかから呼び出します。おすすめはResourceBundle::MaybeMangleLocalizedString の先頭から呼び出すことです。Chromium をビルドして実行し、"Hello from Rust!" が何度も出力されていることを確認します。

VSCode を使用している場合は、VSCode で適切に動作するように Rust を設定します。これは、後続の演習で役立ちます。設定が完了したら、println! で "Go to definition" を右クリックで利用できるようになります。

参考情報

• rust_static_library gn テンプレート で使用できるオプション
• Information about #[unsafe(no_mangle)]
• extern "C" に関する情報
• gn の --export-rust-project スイッチに関する情報
• VSCode に rust-analyzer をインストールする方法

テスト

Rust コミュニティは通常、テスト対象のコードと同じソースファイルに配置されたモジュールで単体テストを作成します。これは本コースの 前の部分 で説明しており、以下のようになります。

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    #[test]
    fn my_test() {
        todo!()
    }
}
}

Chromium では単体テストを別のソースファイルに配置しており、Rust でもこの方針を継続します。これにより、テストが常に検出可能になり、2 度目に（test 構成で）.rs ファイルを再ビルドする必要がなくなります。

その結果、Chromium で Rust コードをテストするための次の選択肢が提供されます。

• ネイティブ Rust テスト（例: #[test]）。//third_party/rust 以外では推奨されません。
• C++ で作成され、FFI 呼び出しを介して Rust を実行する gtest テスト。Rust コードが単なる薄いFFI レイヤであり、既存の単体テストで今後この機能が漏れなくカバーされる場合には十分です。
• Rust で作成され、公開 API を介してテスト対象のクレートを使用する gtest テスト（必要に応じて pub mod for_testing { ... } を使用）。これについては、次の数枚のスライドで説明します。

rust_gtest_interop ライブラリ

rust_gtest_interop ライブラリを使用すると、次のことができます。

• Rust 関数を gtest テストケースとして使用する（#[gtest(...)] 属性を使用）。
• expect_eq! などのマクロを使用する（assert_eq!と似ていますが、アサーションが失敗してもパニックせず、テストを終了しません）。

Example:

use rust_gtest_interop::prelude::*;

#[gtest(MyRustTestSuite, MyAdditionTest)]
fn test_addition() {
    expect_eq!(2 + 2, 4);
}

Rust テスト用の GN ルール

Rust の gtest テストをビルドする最も簡単な方法は、C++ で作成されたテストがすでに含まれている既存のテストバイナリに追加することです。次に例を示します。

test("ui_base_unittests") {
  ...
  sources += [ "my_rust_lib_unittest.rs" ]
  deps += [ ":my_rust_lib" ]
}

別途、static_library で Rust テストを作成することも可能ですが、サポート ライブラリへの依存関係を手動で宣言する必要があります。

rust_static_library("my_rust_lib_unittests") {
  testonly = true
  is_gtest_unittests = true
  crate_root = "my_rust_lib_unittest.rs"
  sources = [ "my_rust_lib_unittest.rs" ]
  deps = [
    ":my_rust_lib",
    "//testing/rust_gtest_interop",
  ]
}

test("ui_base_unittests") {
  ...
  deps += [ ":my_rust_lib_unittests" ]
}

chromium::import! マクロ

GN の deps に :my_rust_lib を追加した後も、my_rust_lib_unittest.rs から my_rust_lib をインポートして使用する方法について学ぶ必要があります。my_rust_lib には明示的な crate_name が指定されていないため、クレート名はターゲットのフルパスと名前に基づいて生成されます。幸い、自動的にインポートされる chromium クレートから chromium::import! マクロを使用すれば、このような扱いにくい名前の使用を回避できます。

chromium::import! {
    "//ui/base:my_rust_lib";
}

use my_rust_lib::my_function_under_test;

内部で、マクロは次のように展開されます。

extern crate ui_sbase_cmy_urust_ulib as my_rust_lib;

use my_rust_lib::my_function_under_test;

詳しくは、chromium::import マクロの ドキュメント コメント をご覧ください。

Testing exercise

新たな演習の時間です！

Chromium ビルドで以下を行ってください。

• hello_from_rust の横にテスト可能な関数を追加します。たとえば、引数として受け取った 2 つの整数を追加する、n 番目のフィボナッチ数を計算する、スライス内の整数を合計する、などが考えられます。
• 新しい関数のテストを含む別個の ..._unittest.rs ファイルを追加します。
• 新しいテストを BUILD.gn に追加します。
• テストをビルドして実行し、新しいテストが機能することを確認します。

C++との相互運用性

Rust コミュニティには C++ と Rust の相互運用のためのオプションが複数用意されており、絶えず新しいツールが開発されています。現在のところ、Chromium では CXX というツールを使用しています。

言語境界全体をインターフェース定義言語（Rust によく似ています）で記述すると、CXX ツールが Rust と C++ の両方で関数と型の宣言を生成します。

CXX の詳細な使用例については、CXX チュートリアル をご覧ください。

バインディングの例

CXX では、C++ と Rust の境界全体を .rs ソースコード内の cxx::bridge モジュールで宣言する必要があります。

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        include!("example/include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: &BlobstoreClient, buf: &mut MultiBuf) -> Result<u64>;
    }
}

// Rust の型と関数の定義をここに記述します。

CXXの限界

CXX を使用するときに最も役立つページは、型リファレンス です。

CXX は基本的に、次のようなケースに適しています。

• Rust-C++ インターフェースが十分にシンプルで、すべてを宣言できる場合。
• すでに CXX でネイティブにサポートされている型のみを使用している場合（例: std::unique_ptr、std::string、&[u8]）。

Rust の Option 型がサポートされていないなど、CXX には多くの制限があります。

こうした制限により、Chromium では 任意の Rust と C++ の相互運用は行われず、Rustの使用は十分に独立したコードに限定されています。Chromium での Rust のユースケースを検討する際は、まず、言語境界の CXX バインディングの下書きを作成して、シンプルに見えるかどうかを確認することをおすすめします。

CXXにおけるエラー処理

CXX の Result<T,E> のサポート は、C++ 例外に依存しているため、Chromium では使用できません。以下の代替手段があります。

• Result<T, E> の T の部分:

  • out パラメータを介して返すことができます（例: &mut T）。そのためには、T を FFI の境界を越えて渡せる必要があります。たとえば、T には以下を指定する必要があります。
    • プリミティブ型（u32、usize など）
    • (Box<T> とは異なり)適切なデフォルト値を持つcxx でネイティブにサポートされている型（UniquePtr<T> など）。
  • Rust 側で保持し、参照を介して公開できます。これは、T が Rust 型の場合に必要になることがあります。Rust 型は FFI の境界を超えて渡すことができず、UniquePtr<T> に格納することもできません。

• Result<T, E> の E の部分:

  • ブール値として返すことができます（たとえば、true は成功、false は失敗を表します）。
  • 理論上はエラーの詳細を保持できますが、これまでは実際に必要になることはありませんでした。

CXX Error Handling: QR Example

QR コード生成ツールは、ブール値が成功または失敗を伝達し、成功の結果を FFI の境界を超えて受け渡すことができる 一例 です。

#[cxx::bridge(namespace = "qr_code_generator")]
mod ffi {
    extern "Rust" {
        fn generate_qr_code_using_rust(
            data: &[u8],
            min_version: i16,
            out_pixels: Pin<&mut CxxVector<u8>>,
            out_qr_size: &mut usize,
        ) -> bool;
    }
}

CXX Error Handling: PNG Example

PNG デコーダのプロトタイプは、成功した結果を FFI の境界を越えて渡せない場合に何ができるかを示しています。

#[cxx::bridge(namespace = "gfx::rust_bindings")]
mod ffi {
    extern "Rust" {
        /// これは `Result<PngReader<'a>,()>` と同等の FFI 対応の結果を
        /// 返します。
        fn new_png_reader<'a>(input: &'a [u8]) -> Box<ResultOfPngReader<'a>>;

        /// `crate::png::ResultOfPngReader` 型の C++ バインディング
        type ResultOfPngReader<'a>;
        fn is_err(self: &ResultOfPngReader) -> bool;
        fn unwrap_as_mut<'a, 'b>(
            self: &'b mut ResultOfPngReader<'a>,
        ) -> &'b mut PngReader<'a>;

        /// `crate::png::PngReader` 型の C++ バインディング
        type PngReader<'a>;
        fn height(self: &PngReader) -> u32;
        fn width(self: &PngReader) -> u32;
        fn read_rgba8(self: &mut PngReader, output: &mut [u8]) -> bool;
    }
}

Chromium で cxx を使用する

Chromium では、Rust を使用するリーフノードごとに独立した #[cxx::bridge] mod を定義します。通常は、rust_static_library ごとに 1 つずつになります。

cxx_bindings = [ "my_rust_file.rs" ]
   # すべてのソースファイルではなく、#[cxx::bridge] を含むファイルのリスト
allow_unsafe = true

上記のコードを、crate_root や sourcesと並んで、既存の rust_static_library ターゲットに追加するだけです。

C++ ヘッダーは適切な場所で生成されるため、次のようにインクルードできます。

#include "ui/base/my_rust_file.rs.h"

//base には、Chromium C++ 型から CXX Rust 型（およびその逆方向）への変換を行うためのユーティリティ関数がいくつかあります（例: SpanToRustSlice）。

Exercise: Interoperability with C++

パート 1

• 先ほど作成した Rust ファイルに、C++ から呼び出す単一の関数を示す #[cxx::bridge] を追加します。これは hello_from_rust という関数で、パラメータを受け取らず、値も返しません。
• Modify your previous hello_from_rust function to remove extern "C" and #[unsafe(no_mangle)]. This is now just a standard Rust function.
• gn ターゲットを変更して、これらのバインディングをビルドします。
• C++ コードで、hello_from_rust の前方宣言を削除し、代わりに生成されたヘッダー ファイルをインクルードします。
• ビルドして実行します。