ElementAtAsync

1. 概要

ElementAtAsync は、Observable シーケンスから指定したインデックス位置の要素を取り出し、その結果を Task として返すオペレーターです。int によるゼロベースのインデックス指定に加え、System.Index（^n 構文）による末尾からの指定もサポートします。インデックスが範囲外の場合に例外をスローするバージョンと、既定値を返す ElementAtOrDefaultAsync バージョンがあります。

2. シグネチャ

int インデックス指定

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

ゼロベースの index で指定した位置の要素を返します。インデックスが範囲外の場合は ArgumentOutOfRangeException をスローします。

System.Index 指定

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

System.Index による指定で、^1 で最後の要素、^2 で最後から 2 番目の要素を取得できます。末尾からの指定の場合、シーケンスの完了まで待機する必要があります。

int インデックス指定（OrDefault）

public static Task<T> ElementAtOrDefaultAsync<T>(
    this Observable<T> source,
    int index,
    T defaultValue,
    CancellationToken cancellationToken = default)

インデックスが範囲外の場合に例外をスローせず、defaultValue を返します。

System.Index 指定（OrDefault）

public static Task<T> ElementAtOrDefaultAsync<T>(
    this Observable<T> source,
    Index index,
    T defaultValue,
    CancellationToken cancellationToken = default)

System.Index 版の OrDefault オーバーロードです。

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

オーバーロード	用途
ElementAtAsync(int)	先頭からの位置が分かっている場合
ElementAtAsync(Index)	末尾からの位置を指定したい場合（^n 構文）
ElementAtOrDefaultAsync(int)	範囲外でも例外を避けたい場合
ElementAtOrDefaultAsync(Index)	末尾指定 + 範囲外の安全なハンドリング

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

ソースシーケンスの要素を受信しながらインデックスをカウントし、指定位置の要素に達した時点でその値が Task の結果として返されます。末尾からの指定（^n）の場合は、シーケンス完了後に結果が確定します。

4. サンプルコード

// ゼロベースインデックスで 3 番目の要素を取得
var source = new[] { 10, 20, 30, 40, 50 }.ToObservable();

int value = await source.ElementAtAsync(2);
Console.WriteLine(value); // 30

// 末尾からのインデックス指定
var source = new[] { 10, 20, 30, 40, 50 }.ToObservable();

int last = await source.ElementAtAsync(^1);
Console.WriteLine(last); // 50

int secondLast = await source.ElementAtAsync(^2);
Console.WriteLine(secondLast); // 40

// 範囲外の場合に既定値を返す
var source = new[] { 1, 2, 3 }.ToObservable();

int value = await source.ElementAtOrDefaultAsync(10, defaultValue: -1);
Console.WriteLine(value); // -1

5. 補足

• インデックス 0 を指定する場合は FirstAsync の使用を推奨します。最後の要素を取得する場合は LastAsync のほうが意図が明確です。
• int 版の ElementAtAsync は、指定インデックスに達した時点で短絡評価を行い、後続の要素を待機しません。System.Index の末尾指定（^n）では、シーケンス全体の長さが必要なため、OnCompleted まで待機します。