FirstAsync

1. 概要

FirstAsync は、Observable シーケンスの最初の要素、または条件を満たす最初の要素を取り出し、その結果を Task<T> として返すオペレーターです。対象の要素を受信した時点で即座に結果を返し、購読を解除します。該当する要素がないままシーケンスが完了した場合は InvalidOperationException をスローします。

2. シグネチャ

最初の要素を取得

public static Task<T> FirstAsync<T>(
    this Observable<T> source,
    CancellationToken cancellationToken = default)

シーケンスの最初の要素を返します。シーケンスが空の場合は例外をスローします。最初の要素を受信した時点で短絡評価を行います。

条件を満たす最初の要素を取得

public static Task<T> FirstAsync<T>(
    this Observable<T> source,
    Func<T, Boolean> predicate,
    CancellationToken cancellationToken = default)

predicate が true を返す最初の要素を返します。条件を満たす要素を受信した時点で短絡評価を行います。シーケンスが完了しても条件を満たす要素が見つからなかった場合は例外をスローします。

オーバーロードの使い分け

オーバーロード	用途
条件なし	シーケンスの先頭要素を取得する
条件あり	条件を満たす最初の要素を取得する

3. マーブルダイアグラム

ソースシーケンスの最初の要素が受信された時点で、その値が Task の結果として返され、購読が解除されます。

4. サンプルコード

// 最初の要素を取得
var source = new[] { 10, 20, 30 }.ToObservable();

int first = await source.FirstAsync();
Console.WriteLine(first); // 10

// 条件を満たす最初の要素を取得
var source = new[] { 10, 15, 20, 25 }.ToObservable();

int first = await source.FirstAsync(x => x > 18);
Console.WriteLine(first); // 20

// 空のシーケンスでは例外がスローされる
var empty = Observable.Empty<int>();

try
{
    int value = await empty.FirstAsync();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex.Message); // シーケンスに要素がありません
}

5. 補足

• 空のシーケンスで例外を避けたい場合は FirstOrDefaultAsync を使用してください。
• 最後の要素を取得するには LastAsync、唯一の要素を取得して複数あれば例外をスローするには SingleAsync を使用してください。
• FirstAsync は対象の要素を受信した時点で短絡評価を行うため、条件を満たす要素が流れてくる無限シーケンスに対しても使用できます。