[Rust] Result メソッド まとめ

<font color="#ff8080">※ 2023-11-11: 記事を全体的に修整。</font>

Rust で `Result` や `Option` を扱う場合、`if let` や `match` を使うよりもメソッドを使用した方が簡潔に書ける場合があります。

変換前の型と変換後の型からメソッドを探せるようにするため、型を基準にまとめた表にしました。

※バージョン 1.73.0 現在、安定化されているメソッドのみ記載。
※ `#[derive]` によるトレイト実装メソッドは詳細略。
※ライフタイムは省略。
※基本的に `Self` 型が含むジェネリクスのトレイト境界は省略。
※特に注記がないものは固有メソッド、トレイト実装メソッドは各概要欄に記載。
※ **`self` の型が参照で `&`, `&mut` が付いている場合**でも、Rust の機能であるメソッド呼び出し時の**自動参照**によって、**参照が付いていない型の値も呼ぶことができます**。

`Option` に関しては別記事にしました。

参考「[[Rust] Option メソッド まとめ - Qiita](https://qiita.com/kerupani129/items/a45c614279e7fc58f129)」

# 0. まとめ

用途別:

- 値を取得
    - `is_ok`
    - `is_err`
    - `is_ok_and`
    - `is_err_and`
    - `ok`, `unwrap_or_default`
    - `err`
- 値を取得 (`unsafe`)
    - `unwrap_unchecked`
    - `unwrap_err_unchecked`
- 値を取得 (パニックを起こす)
    - `unwrap`
    - `unwrap_err`
    - `expect`
    - `expect_err`
- 値を取得および値に関数を適用
    - `unwrap_or`, `unwrap_or_else`
    - `map_or`, `map_or_else`
- 値に関数を適用
    - `map`
    - `map_err`
- 値同士を結合
    - `and`, `and_then`
    - `or`, `or_else`
- 参照
    - `as_ref`, `as_deref`, `as_mut`, `as_deref_mut`
- 複製
    - `copied`
    - `cloned`
    - `clone`, `clone_from`
- イテレータ
    - `from_iter`
    - `into_iter`
    - `iter`, `iter_mut`
- たたみ込み
    - `sum`
    - `product`
- 転置
    - `transpose`
- 終了
    - `report`

その他、`#[derive]` による実装トレイト別:

- `Copy`
- `PartialEq`
    - `eq`, `ne`
- `PartialOrd`
    - `partial_cmp`
    - `lt`, `le`, `gt`, `ge`
- `Eq`
- `Ord`
    - `cmp`
    - `max`, `min`, `clamp`
- `Debug`
    - `fmt`
- `Hash`
    - `hash`, `hash_slice`

参考「[Result in std::result - Rust](https://doc.rust-lang.org/std/result/enum.Result.html)」

# 1. 値を取得

※値を取得するメソッドはパニックを起こすものがあります。

## 1.1. 基本

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`&Result<T, E>`|`bool`|`is_ok`|`Ok` かどうか確認する|
|`&Result<T, E>`|`bool`|`is_err`|`Err` かどうか確認する|

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Result<T, E>`|`impl FnOnce(T) -> bool`|`bool`|`is_ok_and`|`Ok` かつ関数 `impl FnOnce(T) -> bool` が真を返すかどうか確認する|
|`Result<T, E>`|`impl FnOnce(E) -> bool`|`bool`|`is_err_and`|`Err` かつ関数 `impl FnOnce(E) -> bool` が真を返すかどうか確認する|

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<T, E>`|`Option<T>`|`ok`|`Ok` を `Option` で取得する|
|`Result<T, E>`|`Option<E>`|`err`|`Err` を `Option` で取得する|

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<T, E>`|`T`|`unwrap_or_default`|`Ok` を取得する<br>`Err` ならデフォルト値 `<T as Default>::default()` にする|

## 1.2. `unsafe` メソッド

※ `unsafe` メソッドは明確な理由がなければ使わないべきです。

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<T, E>`|`T`|`unwrap_unchecked`|`Ok` を取得する<br>`Err` なら未定義動作|
|`Result<T, E>`|`E`|`unwrap_err_unchecked`|`Err` を取得する<br>`Ok` なら未定義動作|

## 1.3. パニックを起こすメソッド

※パニックを起こすメソッドは、Rust の内部的なコードやサンプルコード、テストコード等で良く用いられますが、テストコード以外ではなるべく使わないべきです。
※ `expect` や `expect_err` メソッドは戻り値を得るためだけでなく、テストコード中で「パニックが起きない」ことを確認する目的でも使用されます。

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<T, E>`|`T`|`unwrap`|`Ok` を取得する<br>`Err` なら `Err` が持つ値でパニックを起こす|
|`Result<T, E>`|`E`|`unwrap_err`|`Err` を取得する<br>`Ok` なら `Ok` が持つ値でパニックを起こす|

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Result<T, E>`|`&str`|`T`|`expect`|`Ok` を取得する<br>`Err` なら `msg: &str` の値でパニックを起こす<br>`Ok` であることを期待する|
|`Result<T, E>`|`&str`|`E`|`expect_err`|`Err` を取得する<br>`Ok` なら `msg: &str` の値でパニックを起こす<br>`Err` であることを期待する|

# 2. 値を取得および値に関数を適用

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Result<T, E>`|`T`|`T`|`unwrap_or`|`Ok` を取得する<br>`Err` ならデフォルト値 `default: T` にする<br>※動作は `unwrap_or_else` と同じ<br>**※デフォルト値に関数の戻り値を使う場合は `unwrap_or_else` で遅延評価することを推奨**|
|`Result<T, E>`|`F: FnOnce(E) -> T`|`T`|`unwrap_or_else`|`Ok` を取得する<br>`Err` なら関数 `F` の変換をして取得する|

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Result<T, E>`|`U`,<br>`F: FnOnce(T) -> U`|`U`|`map_or`|`Ok` なら関数 `F` の変換をして取得する<br>`Err` ならデフォルト値 `default: U` にする<br>※動作は `map_or_else` と同じ<br>**※デフォルト値に関数の戻り値を使う場合は `map_or_else` で遅延評価することを推奨**|
|`Result<T, E>`|`D: FnOnce(E) -> U`,<br>`F: FnOnce(T) -> U`|`U`|`map_or_else`|`Ok` なら関数 `F` の変換をして取得する<br>`Err` なら関数 `D` の変換をして取得する|

# 3. 値に関数を適用

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Result<T, E>`|`F: FnOnce(T) -> U`|`Result<U, E>`|`map`|`Ok` なら関数 `F` の変換をする|
|`Result<T, E>`|`O: FnOnce(E) -> F`|`Result<T, F>`|`map_err`|`Err` なら関数 `O` の変換をする|

ちなみに `map_or` か `map_or_else` メソッドで `type U = Result<V, G>;` とすることで、`Ok` と `Err` の両方の型を変換することができます。

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Result<T, E>`|`Result<V, G>`,<br>`F: FnOnce(T) -> Result<V, G>`|`Result<V, G>`|`map_or`|`Ok` なら関数 `F` の変換をして取得する<br>`Ok` から `Err` への変換もできる<br>`Err` ならデフォルト値 `default: Result<V, G>` にする<br>`Err` から `Ok` への変換もできる<br>※動作は `map_or_else` と同じ<br>**※デフォルト値に関数の戻り値を使う場合は `map_or_else` で遅延評価することを推奨**|
|`Result<T, E>`|`D: FnOnce(E) -> Result<V, G>`,<br>`F: FnOnce(T) -> Result<V, G>`|`Result<V, G>`|`map_or_else`|`Ok` なら関数 `F` の変換をして取得する<br>`Ok` から `Err` への変換もできる<br>`Err` なら関数 `D` の変換をして取得する<br>`Err` から `Ok` への変換もできる|

# 4. 値同士を結合

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Result<T, E>`|`Result<U, E>`|`Result<U, E>`|`and`|両方とも `Ok` なら `Ok`<br>※動作は `and_then` と同じ<br>**※引数に関数の戻り値を使う場合は `and_then` で遅延評価することを推奨**|
|`Result<T, E>`|`F: FnOnce(T) -> Result<U, E>`|`Result<U, E>`|`and_then`|`Ok` なら関数 `F` の変換をする<br>`Ok` から `Err` への変換もできる|
|`Result<T, E>`|`Result<T, F>`|`Result<T, F>`|`or`|どちらかが `Ok` なら `Ok`<br>※動作は `or_else` と同じ<br>**※引数に関数の戻り値を使う場合は `or_else` で遅延評価することを推奨**|
|`Result<T, E>`|`O: FnOnce(E) -> Result<T, F>`|`Result<T, F>`|`or_else`|`Err` なら関数 `O` の変換をする<br>`Err` から `Ok` への変換もできる|

# 5. 参照

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`&Result<T, E>`|`Result<&T, &E>`|`as_ref`|`T` と `E` を参照にする|
|`&Result<T, E>`|`Result<&<T as Deref>::Target, &E>`|`as_deref`|`T` と `E` を参照にし、さらに `T` を `deref` する|
|`&mut Result<T, E>`|`Result<&mut T, &mut E>`|`as_mut`|`T` と `E` を可変参照にする<br>※バージョン 1.73.0 現在、`const` として扱う機能は不安定|
|`&mut Result<T, E>`|`Result<&mut <T as Deref>::Target, &mut E>`|`as_deref_mut`|`T` と `E` を可変参照にし、さらに `T` を `deref_mut` する<br>(※ `DerefMut` は `Deref` のサブトレイトで、`deref_mut` の戻り値の型は `<T as Deref>::Target` で正しいです。`<T as DerefMut>::Target` ではありません)|

# 6. 複製

## 6.1. `Ok`

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<&T, E>`|`Result<T, E>`|`copied`|`Ok` を複製 (コピー) する|
|`Result<&T, E>`|`Result<T, E>`|`cloned`|`Ok` を複製 (クローン) する|
|`Result<&mut T, E>`|`Result<T, E>`|`copied`|`Ok` を複製 (コピー) する|
|`Result<&mut T, E>`|`Result<T, E>`|`cloned`|`Ok` を複製 (クローン) する|

## 6.2. `Ok` および `Err`

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`&Result<T, E>`|`Result<T, E>`|`clone`|`self` を複製 (クローン) する<br>(`Clone` トレイト実装メソッド)|

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`&mut Result<T, E>`|`&Result<T, E>`|`()`|`clone_from`|`self` に `source: &Result<T, E>` を複製 (クローン) する<br>(`Clone` トレイト実装メソッド)|

# 7. イテレータ

|引数|戻り値|メソッド|概要|
|-|-|-|-|
|`I: IntoIterator<Item = Result<A, E>>`|`Result<V, E>`<br>`where V: FromIterator<A>`|`from_iter`|イテレータに変換可能な型 (イテレータ型も含む) から `Result` 型に変換する<br>ただし、戻り値の `Ok` が持つ値はイテレータから変換可能な型でなければならない<br>(`FromIterator` トレイト実装メソッド)|

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<T, E>`|`IntoIter<T>`|`into_iter`|`Ok` をイテレータに変換する<br>`type Item = T;`<br>(`IntoIterator` トレイト実装メソッド)|
|`&Result<T, E>`|`Iter<T>`|`into_iter`|`Ok` を参照のイテレータに変換する<br>`type Item = &T;`<br>※動作は `<Result<T, E>>::iter` と同じ<br>(`IntoIterator` トレイト実装メソッド)|
|`&mut Result<T, E>`|`IterMut<T>`|`into_iter`|`Ok` を可変参照のイテレータに変換する<br>`type Item = &mut T;`<br>※動作は `<Result<T, E>>::iter_mut` と同じ<br>(`IntoIterator` トレイト実装メソッド)|

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`&Result<T, E>`|`Iter<T>`|`iter`|`Ok` を参照のイテレータに変換する<br>`type Item = &T;`|
|`&mut Result<T, E>`|`IterMut<T>`|`iter_mut`|`Ok` を可変参照のイテレータに変換する<br>`type Item = &mut T;`|

# 8. たたみ込み

|引数|戻り値|メソッド|概要|
|-|-|-|-|
|`I: Iterator<Item = Result<U, E>>`|`Result<T, E>`<br>`where T: Sum<U>`|`sum`|イテレータの全要素が `Ok` ならそれらを加算した値を `Ok` で取得する<br>ただし、戻り値の `Ok` が持つ値はイテレータの要素を加算した結果の型でなければならない<br>`Err` が要素に含まれていたら `Err` を返す<br>イテレータが空の場合、`T` 型によって異なるが、基本的には `Ok(0)` 等が返り、`Err` にならない<br>(`Sum` トレイト実装メソッド)|
|`I: Iterator<Item = Result<U, E>>`|`Result<T, E>`<br>`where T: Product<U>`|`product`|イテレータの全要素が `Ok` ならそれらを乗算した値を `Ok` で取得する<br>ただし、戻り値の `Ok` が持つ値はイテレータの要素を乗算した結果の型でなければならない<br>`Err` が要素に含まれていたら `Err` を返す<br>イテレータが空の場合、`T` 型によって異なるが、基本的には `Ok(1)` 等が返り、`Err` にならない<br>(`Product` トレイト実装メソッド)|

# 9. 転置

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<Option<T>, E>`|`Option<Result<T, E>>`|`transpose`|`Result` と `Option` を入れ替える<br>`Ok(Some(_)) -> Some(Ok(_))`,<br>`Ok(None) -> None`,<br>`Err(_) -> Some(Err(_))`<br>※バージョン 1.73.0 現在、`const` として扱う機能は不安定|

# 10. 終了

|`self`|戻り値|メソッド|概要|
|-|-|-|-|
|`Result<T, E>`|`ExitCode`|`report`|`self` を `ExitCode` に変換する<br>(`Termination` トレイト実装メソッド)|

# 11. 関連記事

参考「[[Rust] Result<T, E> 型から Result<U, F> 型への変換 - Qiita](https://qiita.com/kerupani129/items/4c3d040c7f40a90c790a)」