[Rust] Option メソッド まとめ

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

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

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

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

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

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

0. まとめ

用途別:

• 生成
  • default
  • from
• 値を取得
  • is_some
  • is_none
  • is_some_and
  • unwrap_or, unwrap_or_else
  • unwrap_or_default
  • ok_or, ok_or_else
• 値を取得 (unsafe)
  • unwrap_unchecked
• 値を取得 (パニックを起こす)
  • unwrap
  • expect
• 値を取得および値に関数を適用
  • map_or, map_or_else
• 値に関数を適用
  • map
• フィルタ
  • filter
• 値を変更 (変更前の値を取得)
  • take
  • replace
• 値を変更 (変更後の値の参照を取得)
  • insert
  • get_or_insert, get_or_insert_with
• 値を結合
  • flatten
• 値同士を結合
  • and, and_then
  • or, or_else
  • xor
• タプル
  • zip
  • unzip
• 参照
  • as_ref, as_deref, as_mut, as_deref_mut
  • as_pin_ref, as_pin_mut
• 複製
  • copied
  • cloned
  • clone, clone_from
• イテレータ
  • from_iter
  • into_iter
  • iter, iter_mut
• たたみ込み
  • sum
  • product
• 転置
  • transpose

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

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

参考「Option in std::option - Rust」

1. 生成

戻り値	メソッド	概要
Option<T>	default	デフォルト値 None (Default トレイト実装メソッド)

引数	戻り値	メソッド	概要
T	Option<T>	from	引数の型から戻り値の型に変換 ※動作は引数 val: T に対して Some(val) と同じ (From トレイト実装メソッド)
&Option<T>	Option<&T>	from	引数の型から戻り値の型に変換 ※動作は <Option<T>>::as_ref と同じ (From トレイト実装メソッド)
&mut Option<T>	Option<&mut T>	from	引数の型から戻り値の型に変換 ※動作は <Option<T>>::as_mut と同じ (From トレイト実装メソッド)

2. 値を取得

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

2.1. 基本

self	戻り値	メソッド	概要
&Option<T>	bool	is_some	Some かどうか確認する
&Option<T>	bool	is_none	None かどうか確認する

self	引数	戻り値	メソッド	概要
Option<T>	impl FnOnce(T) -> bool	bool	is_some_and	Some かつ関数 impl FnOnce(T) -> bool が真を返すかどうか確認する

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

self	戻り値	メソッド	概要
Option<T>	T	unwrap_or_default	Some を取得する None ならデフォルト値 <T as Default>::default() にする

self	引数	戻り値	メソッド	概要
Option<T>	E	Result<T, E>	ok_or	Option を Result に変換する None なら err: E の値にする ※動作は ok_or_else と同じ ※ err: E の値に関数の戻り値を使う場合は ok_or_else で遅延評価することを推奨
Option<T>	F: FnOnce() -> E	Result<T, E>	ok_or_else	Option を Result に変換する None なら関数 F の戻り値にする

2.2. unsafe メソッド

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

self	戻り値	メソッド	概要
Option<T>	T	unwrap_unchecked	Some を取得する None なら未定義動作 ※バージョン 1.73.0 現在、const として扱う機能は不安定

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

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

self	戻り値	メソッド	概要
Option<T>	T	unwrap	Some を取得する None ならパニックを起こす ※バージョン 1.73.0 現在、const として扱う機能は不安定

self	引数	戻り値	メソッド	概要
Option<T>	&str	T	expect	Some を取得する None なら msg: &str の値でパニックを起こす Some であることを期待する ※バージョン 1.73.0 現在、const として扱う機能は不安定

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

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

4. 値に関数を適用

self	引数	戻り値	メソッド	概要
Option<T>	F: FnOnce(T) -> U	Option<U>	map	Some なら関数 F の変換をする

5. フィルタ

self	引数	戻り値	メソッド	概要
Option<T>	P: FnOnce(&T) -> bool	Option<T>	filter	Some かつ関数 F の戻り値が true なら Some Some から None への変換もできる

6. 値を変更

6.1. 変更前の値を取得

self	戻り値	メソッド	概要
&mut Option<T>	Option<T>	take	self の値を <Option<T> as Default>::default() すなわち None に変更し、変更前の値を取得する ※ replace で None を指定するのと同じ動作 ※バージョン 1.73.0 現在、const として扱う機能は不安定

self	引数	戻り値	メソッド	概要
&mut Option<T>	T	Option<T>	replace	self の値を value: T を含む Some に変更し、変更前の値を取得 ※ None を指定すると take と同じ動作 ※バージョン 1.73.0 現在、const として扱う機能は不安定

6.2. 変更後の値の参照を取得

self	引数	戻り値	メソッド	概要
&mut Option<T>	T	&mut T	insert	self の値を value: T を含む Some に変更し、可変参照を取得
&mut Option<T>	T	&mut T	get_or_insert	Some なら可変参照を取得 None なら self の値を value: T を含む Some に変更し、可変参照を取得 ※動作は get_or_insert_with と同じ ※ insert する値に関数の戻り値を使う場合は get_or_insert_with で遅延評価することを推奨
&mut Option<T>	F: FnOnce() -> T	&mut T	get_or_insert_with	Some なら可変参照を取得 None なら self の値を関数 F の戻り値を含む Some に変更し、可変参照を取得

7. 値を結合

self	戻り値	メソッド	概要
Option<Option<T>>	Option<T>	flatten	入れ子になった Option を一段階平らにする ※再帰的に何段階も平らにされるわけでない ※バージョン 1.73.0 現在、const として扱う機能は不安定

8. 値同士を結合

self	引数	戻り値	メソッド	概要
Option<T>	Option<U>	Option<U>	and	両方とも Some なら Some ※動作は and_then と同じ ※引数に関数の戻り値を使う場合は or_else で遅延評価することを推奨
Option<T>	F: FnOnce(T) -> Option<U>	Option<U>	and_then	Some なら関数 F の変換をする Some から None への変換もできる
Option<T>	Option<T>	Option<T>	or	どちらかが Some なら Some ※動作は or_else と同じ ※引数に関数の戻り値を使う場合は or_else で遅延評価することを推奨
Option<T>	F: FnOnce() -> Option<T>	Option<T>	or_else	None なら関数 F の戻り値にする None から Some への変換もできる
Option<T>	Option<T>	Option<T>	xor	Some と None またはその逆なら Some にする Some 同士や None 同士なら None にする

9. タプル

self	引数	戻り値	メソッド	概要
Option<T>	Option<T>	Option<(T, U)>	zip	両方とも Some ならタプルの Some

self	戻り値	メソッド	概要
Option<(T, U)>	(Option<T>, Option<U>)	unzip	タプルの Option を Option のタプルにする

10. 参照

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

self	戻り値	メソッド	概要
Pin<&Option<T>>	Option<Pin<&T>>	as_pin_ref	T を参照にする ※バージョン 1.73.0 現在、const として扱う機能は不安定
Pin<&mut Option<T>>	Option<Pin<&mut T>>	as_pin_mut	T を可変参照にする ※バージョン 1.73.0 現在、const として扱う機能は不安定

11. 複製

11.1. Some

self	戻り値	メソッド	概要
Option<&T>	Option<T>	copied	T を複製 (コピー) する ※バージョン 1.73.0 現在、const として扱う機能は不安定
Option<&T>	Option<T>	cloned	T を複製 (クローン) する
Option<&mut T>	Option<T>	copied	T を複製 (コピー) する ※バージョン 1.73.0 現在、const として扱う機能は不安定
Option<&mut T>	Option<T>	cloned	T を複製 (クローン) する

11.2. Some および None

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

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

12. イテレータ

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

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

self	戻り値	メソッド	概要
&Option<T>	Iter<T>	iter	参照のイテレータに変換する type Item = &T; ※バージョン 1.73.0 現在、const として扱う機能は不安定
&mut Option<T>	IterMut<T>	iter_mut	可変参照のイテレータに変換する type Item = &mut T;

13. たたみ込み

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

14. 転置

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