[Rust] Result メソッド まとめ

※ 2023-11-11: 記事を全体的に修整。

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

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

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

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

参考「[Rust] Option メソッド まとめ - Qiita」

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」

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 を取得する Err ならデフォルト値 <T as Default>::default() にする

1.2. unsafe メソッド

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

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

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

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

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

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

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

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

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

4. 値同士を結合

self	引数	戻り値	メソッド	概要
Result<T, E>	Result<U, E>	Result<U, E>	and	両方とも Ok なら Ok ※動作は and_then と同じ ※引数に関数の戻り値を使う場合は and_then で遅延評価することを推奨
Result<T, E>	F: FnOnce(T) -> Result<U, E>	Result<U, E>	and_then	Ok なら関数 F の変換をする Ok から Err への変換もできる
Result<T, E>	Result<T, F>	Result<T, F>	or	どちらかが Ok なら Ok ※動作は or_else と同じ ※引数に関数の戻り値を使う場合は or_else で遅延評価することを推奨
Result<T, E>	O: FnOnce(E) -> Result<T, F>	Result<T, F>	or_else	Err なら関数 O の変換をする 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 を可変参照にする ※バージョン 1.73.0 現在、const として扱う機能は不安定
&mut Result<T, E>	Result<&mut <T as Deref>::Target, &mut E>	as_deref_mut	T と E を可変参照にし、さらに T を deref_mut する (※ 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 を複製 (クローン) する (Clone トレイト実装メソッド)

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

7. イテレータ

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

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

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

8. たたみ込み

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

9. 転置

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

10. 終了

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

11. 関連記事

参考「[Rust] Result 型から Result 型への変換 - Qiita」