Result と Option

Option は値があるか、ないかを示します。Result<T, E> は操作の成功または失敗を示し、失敗時には E を保持します。これらにより、呼び出し元は型から処理すべき分岐を確認できます。「結果がないこと」が通常かどうかをまず決定し、その後型を選択します。存在しないオプショナル設定のクエリでは None を返すことができますが、ファイルの読み取りに失敗した場合は通常、Err を使用して理由を提供する必要があります。

Result を返すからといって、関数が絶対に panic しないわけではありません。それは、返り値を通じて報告される失敗のみを記述するものです。Result を使用しないと must_use 警告がトリガーされますが、これは回避不可能な強制処理ではなく、プログラムがエラーを正しく回復したことを証明するものではありません。Result

例：オプショナルなポート設定

欠落と無効の両方をデフォルト値に変換すると、誤った設定がこっそり有効になってしまいます。ここでは、欠落はデフォルトポートを使用するという約束事にしていますが、構文が無効であるか u16 の範囲を超えている場合はエラーを報告する必要があります。ポート 0 が許可されるかどうかは、別のビジネス検証ステップによって決定されます。

use std::num::ParseIntError;

fn optional_port(input: Option<&str>) -> Result<Option<u16>, ParseIntError> {
    input.map(str::parse::<u16>).transpose()
}

fn configured_port(input: Option<&str>) -> Result<u16, ParseIntError> {
    Ok(optional_port(input)?.unwrap_or(8080))
}

fn main() {
    assert_eq!(optional_port(None).unwrap(), None);
    assert_eq!(optional_port(Some("9000")).unwrap(), Some(9000));
    assert!(optional_port(Some("oops")).is_err());
    assert!(optional_port(Some("70000")).is_err());
    assert_eq!(configured_port(None).unwrap(), 8080);
    assert!(configured_port(Some("")).is_err());
}

map はまず Option<&str> を Option<Result<u16, E>> に変換し、transpose はさらに2つのコンテナの位置を調整します。3つの状態は依然として存在し、外側の Result により、呼び出し元はまず失敗を伝播し、その後欠落の処理方法を決定できます。Option::transpose

解析成功後、ビジネス範囲の検証も必要

u16 の表現可能な範囲と、サービスが許可する設定範囲は異なります。このサービスがポート 0 を明確に禁止していると仮定すると、構文エラーとビジネスエラーを別々にモデル化できます。ユーザーがエラー文字列からどちらのカテゴリなのかを推測する必要はありません。

use std::num::ParseIntError;
#[derive(Debug)]
enum PortError { Syntax(ParseIntError), Zero }
fn port(input: Option<&str>) -> Result<u16, PortError> {
    let parsed = input.map(str::parse::<u16>).transpose()
        .map_err(PortError::Syntax)?.unwrap_or(8080);
    if parsed == 0 { return Err(PortError::Zero); }
    Ok(parsed)
}
fn main() {
    assert_eq!(port(None).unwrap(), 8080);
    assert_eq!(port(Some("9000")).unwrap(), 9000);
    assert!(matches!(port(Some("0")), Err(PortError::Zero)));
    match port(Some("oops")) {
        Err(PortError::Syntax(source)) => assert!(!source.to_string().is_empty()),
        other => panic!("構文エラーを期待したが、実際は {other:?}"),
    }
}

ポート 0 は、一部のバインドインターフェースではシステムにポートの割り当てを要求する意味を持ちます。したがって、ここで拒否するのはサービスポリシーであり、Rust の数値解析ルールではありません。階層化された表現により、パーサーの再利用性を保ちつつ、アプリケーションが自らの制約を明確にできます。

transpose が保つ 3 つの場合

入れ替えは状態を統合せず、先に処理する層を変えます。3 種類を選ぶと、未指定と不正な文字列が別経路を通るため、? でエラーを伝播しつつ unwrap_or を正常な未指定にだけ適用できることが分かります。

合成メソッドはどの分岐で実行されるか

map のクロージャは通常の値を返しますが、and_then のクロージャは同じ種類のコンテナを返すため、不要なネストが形成されません。すべてのメソッドが「成功分岐のみを処理する」わけではありません。or_else は、欠落または失敗時に実行されます。

unwrap_or(expensive()) の引数は、すでに値がある場合でも呼び出し前に評価されます。unwrap_or_else(|| expensive()) は必要な場合にのみクロージャを実行します。デフォルト値は欠落またはエラー状態を飲み込んでしまうため、明示的な戦略であるべきであり、match を少しくらい書かないようにするための手段であってはなりません。Option

呼び出し回数から遅延評価を見る

use std::cell::Cell;
fn main() {
    let calls = Cell::new(0);
    let fallback = || { calls.set(calls.get() + 1); 8080u16 };
    let present = Some(9000u16);
    assert_eq!(present.unwrap_or(fallback()), 9000);
    assert_eq!(calls.get(), 1);
    assert_eq!(present.unwrap_or_else(fallback), 9000);
    assert_eq!(calls.get(), 1);
    assert_eq!(None::<u16>.unwrap_or_else(fallback), 8080);
    assert_eq!(calls.get(), 2);
}

この違いは ok_or と ok_or_else、or と or_else にも適用されます。代替分岐に割り当て、ログ出力、または設定の読み取りが含まれている場合、事前評価は作業の無駄となり、予期しない副作用を生む可能性があります。単純な定数のデフォルト値であれば、形式の統一のためにクロージャに変更する必要はありません。

? は現在の返却境界で早期終了する

Result<T, E> を返す通常の関数において、Result に対して ? を使用すると、Ok が取り出され、Err は適用可能な From 変換を経て早期返却されます。これは、回復戦略を一つずつ試すものではなく、エラーを自動的にログに記録するものでもありません。

Option を返す関数の場合、None は None として早期返却されます。Result を返す関数内で Option に対して直接 ? を使用することはできません。まず ok_or または ok_or_else を使用して「欠落がどのエラーに対応するか」を指定する必要があります。逆方向に .ok() を呼び出すと、エラーの原因が破棄されます。

? のより一般的な言語メカニズムは、残余値の伝播によって表現され、? をサポートするすべての型を Result の From 変換と理解してはいけません。日常的には、Result と Option の具体的なルールを理解していれば十分です。

早期返却は、現在のスコープ内で破棄が必要なローカル値を正常に解放しますが、送信済みのリクエスト、書き込まれたファイル内容、またはコミットされたトランザクションを元に戻すものではありません。アトミックな更新が必要な場合は、別途コミットプロトコルを設計する必要があります。

クロージャ内の ? はまずクロージャの呼び出し元に返る

use std::num::ParseIntError;
fn prepare(input: &str) -> Result<u32, ParseIntError> {
    let run = || -> Result<u32, ParseIntError> {
        let value = input.parse::<u32>()?;
        Ok(value)
    };
    let result = run();
    // ここでもまだ実行される。クロージャの返り値の処理方法は外側で決定される。
    result.map(|value| value.saturating_add(1))
}
fn main() {
    assert_eq!(prepare("7").unwrap(), 8);
    assert_eq!(prepare("4294967295").unwrap(), u32::MAX);
    assert!(prepare("bad").is_err());
}

map のクロージャが Result を返す場合、外側にはさらに1層のコンテナが追加されます。本当に必要なのは「失敗する可能性のある結果を保存すること」か、and_then を使用して同種の失敗を連鎖させて伝播することかを確認してください。インデントだけを頼りに、? がどの関数またはクロージャを終了させるかを判断しないでください。

早期返却は既存のオブジェクトへの修正を元に戻さない

use std::num::ParseIntError;
fn append_incrementally(target: &mut Vec<u32>, input: &[&str])
    -> Result<(), ParseIntError>
{
    for text in input { target.push(text.parse()?); }
    Ok(())
}
fn append_after_validation(target: &mut Vec<u32>, input: &[&str])
    -> Result<(), ParseIntError>
{
    let parsed: Result<Vec<u32>, _> = input.iter().map(|text| text.parse()).collect();
    target.extend(parsed?);
    Ok(())
}
fn main() {
    let mut first = vec![9];
    assert!(append_incrementally(&mut first, &["1", "bad"]).is_err());
    assert_eq!(first, [9, 1]);
    let mut second = vec![9];
    assert!(append_after_validation(&mut second, &["1", "bad"]).is_err());
    assert_eq!(second, [9]);
    append_after_validation(&mut second, &["1", "2"]).unwrap();
    assert_eq!(second, [9, 1, 2]);
}

2番目の実装は、解析エラーが発生した場合に target を変更しないことを約束し、この動作のために追加の一時ストレージを使用します。これは汎用データベーストランザクションではなく、割り当て失敗やプロセスのクラッシュなどを回復可能なエラーに変換するものでもありません。関数のドキュメントには、「Result を返す」だけでなく、失敗後の状態を正確に記述すべきです。

コンテナの借用により、不要なムーブを避ける

多くの合成メソッドは self を値で取得します。後で元のコンテナを使用する必要がある場合は、as_ref を使用して Option<&T> または Result<&T, &E> を取得できます。Option::as_deref を使用すると Option<&str> が得られ、所有する文字列を読み取り専用パーサーに渡すのに適しています。

fn main() {
    let setting = Some(String::from("9000"));
    let borrowed: Option<&str> = setting.as_deref();
    assert_eq!(borrowed, Some("9000"));
    assert_eq!(setting.as_ref().unwrap().len(), 4);
    assert_eq!(setting.unwrap(), "9000"); // ここで初めてコンテナが消費される
}

一括処理：失敗で停止するか、収集するか

fn main() {
    let values = ["1", "bad", "3"];
    let parsed: Result<Vec<u32>, _> = values.iter().map(|s| s.parse()).collect();
    assert!(parsed.is_err());
}

collect::<Result<Vec<_>, _>>() は、最初の Err に遭遇するとショートサーキットし、収集済みの成功接頭辞は返しません。各行のエラーを表示する必要がある場合は、Result を個々に保存し、入力位置を記録する必要があります。filter_map(|s| s.parse().ok()) は失敗した項目をすべて直接破棄するため、「無効な入力が明確に無視可能である場合」にのみ適しています。

行番号を保持して、失敗を入力者に返す

use std::num::ParseIntError;
fn main() {
    let input = ["1", "bad", "70000", "3"];
    let results: Vec<(usize, Result<u16, ParseIntError>)> = input.iter()
        .enumerate().map(|(index, text)| (index + 1, text.parse())).collect();
    let errors: Vec<usize> = results.iter()
        .filter_map(|(line, result)| result.as_ref().err().map(|_| *line)).collect();
    assert_eq!(errors, [2, 3]);
    assert_eq!(results[0].1.as_ref().unwrap(), &1);
    assert_eq!(results[3].1.as_ref().unwrap(), &3);
}

この filter_map は、完全な結果をすでに保持した後にエラー行番号のリストを生成するだけであり、元のエラーを破棄することはありません。複数のフィールド検証を一度に表示する必要がある場合は、通常、独立したエラーを収集すべきです。ただし、フィールド B の検証がフィールド A の成功に依存している場合、デフォルト値を使用して誤解を招く連鎖エラーを生成しないようにする必要があります。

非常に大きな入力の場合、各項目の結果を保存するには追加のメモリが必要です。診断を逐次出力するか、エラー数を制限するか、またはサマリーと入力位置を保存することができます。最初のエラーで停止、完全なレポート、部分的な成功インポートは異なる製品動作であり、インターフェース層で明確な選択を行う必要があります。

main のエラー報告

main は Result<(), E> を返すことができます。ここで E は Debug を満たす必要があります。標準ライブラリの Termination 実装は、Err に対してデバッグ表現を出力し、失敗終了コードを返します。このインターフェースのクロスプラットフォーム契約を数値 1 と固定して記述しないでください。安定したユーザープロンプトと細分化された終了コードが必要な場合は、明示的な match を使用して ExitCode を返します。Termination

unwrap/expect はテストアサートまたは証明可能な不変条件に適しており、通常の外部入力エラーを一律に panic に変えるものではありません。E の設計方法、原因の保持、ビジネスコンテキストの追加については、Error trait とエコシステム を参照してください。