本文へ移動
Senu English

はじめての Rust の関数

約 7 分で読めます

記事のページには、タイトルの下に「約 1 分で読めます」のような読む時間の目安が出ています。この章では、それを計算している Rust の関数をテストから先に作り直し、ノートのページで結果を確かめます。必要な Rust は、入力する前にすべて説明します。

関数のある場所

Rust のコードは src フォルダーにあります。何かを変える前に、エディターで src/reading.rs を開いて読んでみてください。.rs のファイルはそれぞれモジュール、つまりほかのファイルから使えるコードのまとまりです。src/lib.rs は pub mod reading; のような行で Senu のモジュールを並べています。pub (public) は JavaScript の export によく似ています。別のモジュールは use crate::reading::reading_minutes; でこの関数を取り込みます。これは import { readingMinutes } from "./reading.js" によく似ています。このようなパスは、外側から順に部分を並べた名前で、フォルダーを / で区切るように :: で区切ります。crate は Senu 自身のコードのいちばん上、reading はモジュール、reading_minutes は関数です。

Senu はページを作るとき、ノートのコードの枠の外にある語を数え、それが何分かかるかを reading_minutes に尋ねます。目安はわざと単純にしてあり、1 分に 200 語として切り上げるので、短いノートは 1 分になります。日本語は語と語のあいだに空白がないので、日本語のノートでは 2 文字を 1 語として数えます。その分、英語よりさらに大まかな目安です。

この章で使う Rust

テストは、自分のコードを呼んで答えを確かめる小さな関数です。関数の上に #[test] と書くとテストの印になり、assert_eq!(left, right) は二つの値が等しいかを確かめて、等しくなければメッセージを出してテストを止めます。! はマクロの印で、Rust が代わりに展開してくれるコードです。ここでは普通の関数呼び出しとして読んでかまいません。

テストはふつうファイルの最後に、専用の小さなモジュールとして置きます。mod tests { ... } の上の #[cfg(test)] は、このモジュールがテストを実行するときだけビルドされるという意味です。その中の use super::reading_minutes; は、super、つまりこのモジュールを囲むモジュール (ここでは src/reading.rs の残りの部分) から関数を取り込みます。

Red: 最初の試み

src/reading.rs の中身をすべて、次の最初の試みに置き換えてください。四つの例を確かめるテストが一つと、割り算をするだけの関数があります。

// Turns a word count into the minutes shown under an article's title.

const WORDS_PER_MINUTE: usize = 200;

pub fn reading_minutes(words: usize) -> usize {
    words / WORDS_PER_MINUTE
}

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

    #[test]
    fn rounds_up_to_whole_minutes() {
        assert_eq!(reading_minutes(0), 0);
        assert_eq!(reading_minutes(1), 1);
        assert_eq!(reading_minutes(200), 1);
        assert_eq!(reading_minutes(201), 2);
    }
}

このモジュールのテストを実行します。--lib は Senu のライブラリー部分を指し、reading:: は完全な名前がそれで始まるテストを選びます。

cargo test --quiet --lib reading::

running 1 test
reading::tests::rounds_up_to_whole_minutes --- FAILED

failures:

---- reading::tests::rounds_up_to_whole_minutes stdout ----

thread 'reading::tests::rounds_up_to_whole_minutes' (ID) panicked at src/reading.rs:16:9:
assertion `left == right` failed
  left: 0
 right: 1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    reading::tests::rounds_up_to_whole_minutes

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 148 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

テストが失敗しました。これは狙いどおりで、テストが間違いを見つけられることを示しています。失敗しているテストを red と呼びます。メッセージは src/reading.rs の assert_eq!(reading_minutes(1), 1) を指しています。1 / 200 は 0 なので、テストが 1 (right) を期待したところで関数は 0 (left) を返しました。1 語でも読むのに 1 分はかかります。テスト名の後ろの括弧の中の番号 (ここでは (ID) と書いています) は、実行するたびに変わります。

Green: 切り上げる

余った語があれば 1 分足すように関数を変えます。もう一度 src/reading.rs を置き換えてください。

// Turns a word count into the minutes shown under an article's title.

const WORDS_PER_MINUTE: usize = 200;

pub fn reading_minutes(words: usize) -> usize {
    let full_minutes = words / WORDS_PER_MINUTE;
    let leftover_words = words % WORDS_PER_MINUTE;
    if leftover_words > 0 {
        full_minutes + 1
    } else {
        full_minutes
    }
}

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

    #[test]
    fn rounds_up_to_whole_minutes() {
        assert_eq!(reading_minutes(0), 0);
        assert_eq!(reading_minutes(1), 1);
        assert_eq!(reading_minutes(200), 1);
        assert_eq!(reading_minutes(201), 2);
    }
}
cargo test --quiet --lib reading::

running 1 test
.
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 148 filtered out; finished in 0.00s

四つの例がすべて通りました。通っているテストを green と呼びます。

ページで確かめる

サイトも同じ関数を呼んでいるので、Senu を再起動して自分の版でビルドします。Senu のターミナルで Ctrl+C を押し、いつものコマンドを実行してください。

cargo run --quiet -- site
senu: listening on http://127.0.0.1:3000

http://127.0.0.1:3000/ja/my-first-note を開いてください。ノートは 200 語よりずっと短いので、1 分と表示されます。二つ目のターミナルでも確かめます。grep -A1 は、一致した行とその次の行を表示します。ここでは題名と、その下の読了時間です。

curl -s http://127.0.0.1:3000/ja/my-first-note | grep -A1 '<h1>'
<h1>最初のノート</h1>
<p class="text-sm text-gray-600">約 1 分で読めます</p>

演習: いちばん大きな数

語の数がいちばん大きな値、usize::MAX のときはどうなるでしょう。最初のテストの下に二つ目のテストを足して、src/reading.rs を次のようにしてください。

// Turns a word count into the minutes shown under an article's title.

const WORDS_PER_MINUTE: usize = 200;

pub fn reading_minutes(words: usize) -> usize {
    let full_minutes = words / WORDS_PER_MINUTE;
    let leftover_words = words % WORDS_PER_MINUTE;
    if leftover_words > 0 {
        full_minutes + 1
    } else {
        full_minutes
    }
}

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

    #[test]
    fn rounds_up_to_whole_minutes() {
        assert_eq!(reading_minutes(0), 0);
        assert_eq!(reading_minutes(1), 1);
        assert_eq!(reading_minutes(200), 1);
        assert_eq!(reading_minutes(201), 2);
    }

    #[test]
    fn the_largest_count_does_not_overflow() {
        assert_eq!(reading_minutes(usize::MAX), usize::MAX / 200 + 1);
    }
}
cargo test --quiet --lib reading::

running 2 tests
..
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 148 filtered out; finished in 0.00s

(words + 199) / WORDS_PER_MINUTE でも切り上げになるので、短い式のほうが魅力的に見えます。試してみましょう。関数の本体を置き換えて、src/reading.rs を次のようにしてください。

// Turns a word count into the minutes shown under an article's title.

const WORDS_PER_MINUTE: usize = 200;

pub fn reading_minutes(words: usize) -> usize {
    (words + 199) / WORDS_PER_MINUTE
}

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

    #[test]
    fn rounds_up_to_whole_minutes() {
        assert_eq!(reading_minutes(0), 0);
        assert_eq!(reading_minutes(1), 1);
        assert_eq!(reading_minutes(200), 1);
        assert_eq!(reading_minutes(201), 2);
    }

    #[test]
    fn the_largest_count_does_not_overflow() {
        assert_eq!(reading_minutes(usize::MAX), usize::MAX / 200 + 1);
    }
}

新しいテストだけを実行します。一つのテスト名にだけ合う絞り込みを使うと、出力が短くなります。

cargo test --quiet --lib overflow

running 1 test
reading::tests::the_largest_count_does_not_overflow --- FAILED

failures:

---- reading::tests::the_largest_count_does_not_overflow stdout ----

thread 'reading::tests::the_largest_count_does_not_overflow' (ID) panicked at src/reading.rs:6:5:
attempt to add with overflow
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    reading::tests::the_largest_count_does_not_overflow

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 149 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

何が起きたのでしょう。最初の版にこの問題がないのはなぜでしょう。

解答. words が usize::MAX のとき、words + 199 は usize の最大値より大きくなるので、足し算がオーバーフローします。結果が収まらないのです。テスト用のビルドでは、Rust は間違った数のまま進まずに「attempt to add with overflow」(足し算でオーバーフローしようとした) と言って止まります。先に割り算をすれば数が大きくなることはなく、usize::MAX / 200 + 1 は余裕で収まるので、商と余りを使う版はどんな入力でも動きます。元に戻して、src/reading.rs を次のようにしてください。

// Turns a word count into the minutes shown under an article's title.

const WORDS_PER_MINUTE: usize = 200;

pub fn reading_minutes(words: usize) -> usize {
    let full_minutes = words / WORDS_PER_MINUTE;
    let leftover_words = words % WORDS_PER_MINUTE;
    if leftover_words > 0 {
        full_minutes + 1
    } else {
        full_minutes
    }
}

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

    #[test]
    fn rounds_up_to_whole_minutes() {
        assert_eq!(reading_minutes(0), 0);
        assert_eq!(reading_minutes(1), 1);
        assert_eq!(reading_minutes(200), 1);
        assert_eq!(reading_minutes(201), 2);
    }

    #[test]
    fn the_largest_count_does_not_overflow() {
        assert_eq!(reading_minutes(usize::MAX), usize::MAX / 200 + 1);
    }
}
cargo test --quiet --lib reading::

running 2 tests
..
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 148 filtered out; finished in 0.00s

これで src/reading.rs は、Senu に最初から入っているファイルとまったく同じになりました。プログラムの本物の一部を作り直したことになります。

うまくいかないとき

次へ: 作ったものと、この先の学び方