はじめての 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
fn reading_minutes(words: usize) -> usize { ... }はfunction readingMinutes(words) { ... }に当たります。Rust では、引数ごとにコロンの後ろに型を書き、結果の型を->の後ろに書きます。usizeは負にならない整数の型です。0、1、2 と続き、usize::MAXというとても大きな最大値まであります。usizeが来るべきところに文字列や負の数を渡すコードを、Rust はビルドしません。const WORDS_PER_MINUTE: usize = 200;は、ファイル全体で使う決まった値に名前を付けます。let full_minutes = words / WORDS_PER_MINUTE;は JavaScript のconst fullMinutes = ...に当たります。Rust のletは、あとから値を変えられません。/は整数どうしで割り算をして余りを捨てるので、201 / 200は1です。%はその余りを返すので、201 % 200も1です。if leftover_words > 0 { a } else { b }は JavaScript のifと同じように働きますが、aかbの値にもなります。関数の最後の行をセミコロンなしで書くと、その値が関数の戻り値になります。前にreturnが付いているのと同じです。
テストは、自分のコードを呼んで答えを確かめる小さな関数です。関数の上に #[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 に最初から入っているファイルとまったく同じになりました。プログラムの本物の一部を作り直したことになります。
うまくいかないとき
error[Eで始まる行と「could not compile」: テストの失敗ではなく、コンパイルのエラーです。メッセージがファイル、行、桁を示しているので、そこで;や}の抜けやつづりの間違いを探し、上の枠と見比べてください。- 「running 0 tests」: 絞り込みに何も合いませんでした。
reading::のコロンが二つあるか確かめてください。 - ページの読む時間が古いまま: ノートを変えたときと同じく、Rust のコードを変えたあとも Senu を再起動します。
次へ: 作ったものと、この先の学び方