SingleAsync

1. 概要

SingleAsync は、Observable シーケンスの唯一の要素、または条件を満たす唯一の要素を取り出し、その結果を Task<T> として返すオペレーターです。対象となる要素がちょうど 1 つだけの場合にその要素を返します。対象要素が 0 個の場合、または 2 個以上ある場合は InvalidOperationException をスローします。

2. シグネチャ

唯一の要素の取得

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

シーケンスに含まれる要素がちょうど 1 つであることを保証し、その要素を返します。要素が 0 個または 2 個以上の場合は例外をスローします。

条件を満たす唯一の要素を取得

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

predicate が true を返す要素がちょうど 1 つだけであることを保証し、その要素を返します。条件を満たす要素が 0 個または 2 個以上の場合は例外をスローします。

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

オーバーロード	用途
条件なし	シーケンス全体に要素が 1 つだけであることを確認して取得する
条件あり	条件を満たす要素が 1 つだけであることを確認して取得する

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

シーケンスが唯一の要素で完了した場合にその値を出力します。要素が 0 個または 2 個以上の場合はエラーとなります。

4. サンプルコード

// 要素が 1 つだけのシーケンス → 成功
var source = Observable.Return(42);

int value = await source.SingleAsync();
Console.WriteLine(value); // 42

// 条件を満たす要素が 1 つだけ → 成功
var source = new[] { 10, 15, 20, 25 }.ToObservable();

int value = await source.SingleAsync(x => x == 20);
Console.WriteLine(value); // 20

// 空のシーケンス → 例外
try
{
    var empty = Observable.Empty<int>();
    int value = await empty.SingleAsync();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex.Message); // シーケンスに要素が含まれていません
}

// 条件を満たす要素が複数ある → 例外
try
{
    var multiple = new[] { 10, 15, 20, 25 }.ToObservable();
    int value = await multiple.SingleAsync(x => x >= 20);
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex.Message); // 条件を満たす要素が複数あります
}

// 複数要素のシーケンス → 例外
try
{
    var multiple = new[] { 1, 2, 3 }.ToObservable();
    int value = await multiple.SingleAsync();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex.Message); // シーケンスに複数の要素が含まれています
}