# 機能設計書 58-drop

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Vec\drop` 関数の機能設計書である。この関数はTraversableの最初のn要素を除いた新しいvecを返す。

### 本機能の処理概要

**業務上の目的・背景**：
ページネーションやバッチ処理など、コレクションの先頭から一定数の要素をスキップする処理は頻繁に必要とされる。例えば、検索結果の2ページ目以降を表示する場合や、ヘッダー行を除いてデータを処理する場合などが該当する。`Vec\drop` 関数は、指定した数の要素を先頭からスキップし、残りの要素を新しいvecとして返す効率的な方法を提供する。

**機能の利用シーン**：
- ページネーション処理（オフセット指定）
- CSVヘッダー行のスキップ
- バッチ処理での開始位置指定
- キューやリストの先頭要素の除外
- ストリームデータの先頭部分のスキップ

**主要な処理内容**：
1. Traversable（反復可能なコレクション）を受け取る
2. スキップする要素数nを受け取る
3. 最初のn要素をスキップしながら走査
4. n+1番目以降の要素を結果vecに追加
5. 結果をvecとして返却

**関連システム・外部連携**：
本関数は純粋な集合操作であり、外部システムとの直接的な連携はない。最初のn要素のみを取得したい場合は `Vec\take` を使用する。

**権限による制御**：
本機能は純粋関数であり、権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | 画面なし | - | 本プロジェクトはUIを持たないライブラリのため該当なし |

## 機能種別

集合操作処理 / データスライシング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $traversable | Traversable<Tv> | Yes | 処理対象のコレクション | 任意の型の要素を持つTraversable |
| $n | int | Yes | スキップする要素数 | 0以上の整数（負の値は invariant で拒否） |

### 入力データソース

関数呼び出し時の引数として直接渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | vec<Tv> | 最初のn要素を除いた新しいvec |

### 出力先

関数の戻り値として呼び出し元に返却される。

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ $n が負の値の場合、invariant でエラー
2. 変数初期化
   └─ 結果vecを空で初期化、インデックスカウンタを-1で初期化
3. コレクション走査
   └─ foreach で各要素を順番に処理
4. スキップ判定
   └─ インデックスが n 未満の場合は continue でスキップ
5. 要素追加
   └─ n 以上のインデックスの要素を結果vecに追加
6. 結果返却
   └─ 結果vecを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力: $traversable, $n]
    B --> C{$n >= 0 ?}
    C -->|No| D[invariant エラー]
    C -->|Yes| E[result = vec 初期化, ii = -1]
    E --> F{次の要素あり?}
    F -->|No| I[結果を返却]
    F -->|Yes| G[ii++]
    G --> H{ii < $n ?}
    H -->|Yes| F
    H -->|No| J[result に要素を追加]
    J --> F
    I --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-58-01 | 非負整数制約 | $n は0以上の整数でなければならない | 常時 |
| BR-58-02 | 順序保持 | 結果の要素の順序は元のコレクションと同じ | 常時 |
| BR-58-03 | コレクションサイズ超過 | nがコレクションサイズ以上の場合、空のvecを返す | $n >= count($traversable) |
| BR-58-04 | ゼロ指定 | n=0 の場合、全ての要素を含むvecを返す | $n == 0 |

### 計算ロジック

- 計算量: O(n) - nは元のTraversableのサイズ
- 空間計算量: O(n) - nは元のTraversableのサイズ

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を行わない純粋関数である。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $n が負の値 | 0以上の整数を指定する |

### リトライ仕様

リトライは不要（入力検証エラーは修正が必要）

## トランザクション仕様

該当なし（データベース操作を行わないため）

## パフォーマンス要件

- 計算量: O(n) - 全要素を走査
- 純粋関数 `[]` として定義されており、副作用なし
- メモリ効率: 結果のサイズ分のみ確保

## セキュリティ考慮事項

- 入力データの検証は呼び出し側の責任
- 大きな$nを指定しても空のvecが返るだけでエラーにはならない

## 備考

- 最初のn要素のみを取得したい場合は `Vec\take()` を使用
- 部分シーケンスを取得したい場合は `Vec\slice()` を使用
- Traversableを直接処理するため、イテレータにも対応

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: 関数シグネチャを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.php | `src/vec/select.php` | 関数シグネチャと型パラメータ（83行目） |

**読解のコツ**:
- `Traversable<Tv>` は任意の型の要素を持つ反復可能なコレクション
- 戻り値 `vec<Tv>` は入力と同じ要素型のvec

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.php | `src/vec/select.php` | drop 関数の実装（83-95行目） |

**主要処理フロー**:
1. **84行目**: invariant で $n >= 0 を検証
2. **85行目**: 結果vec を空で初期化
3. **86行目**: インデックスカウンタを -1 で初期化
4. **87-93行目**: foreach ループで各要素を処理
5. **88行目**: インデックスをインクリメント
6. **89-91行目**: $n 未満の要素は continue でスキップ
7. **92行目**: $n 以上の要素を結果に追加
8. **94行目**: 結果vecを返却

#### Step 3: テストケースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | VecSelectTest.php | `tests/vec/VecSelectTest.php` | drop テスト（87-124行目） |

**主要ポイント**:
- **88-93行目**: 空のvecに対する動作
- **94-98行目**: n=0 の場合（全要素保持）
- **99-103行目**: nがサイズ超過の場合（空vec）
- **104-108行目**: 部分的なdrop

### プログラム呼び出し階層図

```
Vec\drop($traversable, $n)
    │
    ├─ invariant($n >= 0, ...)  // 入力検証
    │
    └─ foreach ($traversable as $value)  // 要素走査
           │
           ├─ $ii < $n: continue  // スキップ
           │
           └─ $ii >= $n: $result[] = $value  // 追加
```

### データフロー図

```
[入力]                      [処理]                     [出力]

$traversable ───────────▶
 (Traversable<Tv>)         Vec\drop ─────────────▶ vec<Tv>
                               │                   (n+1以降の要素)
$n ────────────────────▶       │
 (int)                         │
                               ▼
                          foreach loop
                               │
                               ├─ 最初のn要素: skip
                               │
                               └─ 残りの要素: collect
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.php | `src/vec/select.php` | ソース | drop関数のパブリックインターフェース |
| VecSelectTest.php | `tests/vec/VecSelectTest.php` | テスト | drop関数のユニットテスト |
