[Rust] Option メソッド まとめ

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

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

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

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

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

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

# 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](https://doc.rust-lang.org/std/option/enum.Option.html)」

# 1. 生成

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

|引数|戻り値|メソッド|概要|
|-|-|-|-|
|`T`|`Option<T>`|`from`|引数の型から戻り値の型に変換<br>※動作は引数 `val: T` に対して `Some(val)` と同じ<br>(`From` トレイト実装メソッド)|
|`&Option<T>`|`Option<&T>`|`from`|引数の型から戻り値の型に変換<br>※動作は `<Option<T>>::as_ref` と同じ<br>(`From` トレイト実装メソッド)|
|`&mut Option<T>`|`Option<&mut T>`|`from`|引数の型から戻り値の型に変換<br>※動作は `<Option<T>>::as_mut` と同じ<br>(`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` を取得する<br>`None` ならデフォルト値 `default: T` にする<br>※動作は `unwrap_or_else` と同じ<br>**※デフォルト値に関数の戻り値を使う場合は `unwrap_or_else` で遅延評価することを推奨**|
|`Option<T>`|`F: FnOnce() -> T`|`T`|`unwrap_or_else`|`Some` を取得する<br>`None` なら関数 `F` の戻り値を取得する|

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

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

## 2.2. `unsafe` メソッド

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

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

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

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

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

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

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

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

# 6. 値を変更

## 6.1. 変更前の値を取得

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

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`&mut Option<T>`|`T`|`Option<T>`|`replace`|`self` の値を `value: T` を含む `Some` に変更し、変更前の値を取得<br>※ `None` を指定すると `take` と同じ動作<br>※バージョン 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` なら可変参照を取得<br>`None` なら `self` の値を `value: T` を含む `Some` に変更し、可変参照を取得<br>※動作は `get_or_insert_with` と同じ<br>**※ `insert` する値に関数の戻り値を使う場合は `get_or_insert_with` で遅延評価することを推奨**|
|`&mut Option<T>`|`F: FnOnce() -> T`|`&mut T`|`get_or_insert_with`|`Some` なら可変参照を取得<br>`None` なら `self` の値を関数 `F` の戻り値を含む `Some` に変更し、可変参照を取得|

# 7. 値を結合

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

# 8. 値同士を結合

|`self`|引数|戻り値|メソッド|概要|
|-|-|-|-|-|
|`Option<T>`|`Option<U>`|`Option<U>`|`and`|両方とも `Some` なら `Some`<br>※動作は `and_then` と同じ<br>**※引数に関数の戻り値を使う場合は `or_else` で遅延評価することを推奨**|
|`Option<T>`|`F: FnOnce(T) -> Option<U>`|`Option<U>`|`and_then`|`Some` なら関数 `F` の変換をする<br>`Some` から `None` への変換もできる|
|`Option<T>`|`Option<T>`|`Option<T>`|`or`|どちらかが `Some` なら `Some`<br>※動作は `or_else` と同じ<br>**※引数に関数の戻り値を使う場合は `or_else` で遅延評価することを推奨**|
|`Option<T>`|`F: FnOnce() -> Option<T>`|`Option<T>`|`or_else`|`None` なら関数 `F` の戻り値にする<br>`None` から `Some` への変換もできる|
|`Option<T>`|`Option<T>`|`Option<T>`|`xor`|`Some` と `None` またはその逆なら `Some` にする<br>`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` を可変参照にする<br>※バージョン 1.73.0 現在、`const` として扱う機能は不安定|
|`&mut Option<T>`|`Option<&mut <T as Deref>::Target>`|`as_deref_mut`|`T` を可変参照にし、さらに `deref_mut` する<br>(※ `DerefMut` は `Deref` のサブトレイトで、`deref_mut` の戻り値の型は `<T as Deref>::Target` で正しいです。`<T as DerefMut>::Target` ではありません)|

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

# 11. 複製

## 11.1. `Some`

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

## 11.2. `Some` および `None`

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

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

# 12. イテレータ

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

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

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

# 13. たたみ込み

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

# 14. 転置

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