# 機能設計書 82-drop

## 概要

本ドキュメントは、Hack Standard Library (HSL) の Dict モジュールにおける `drop` 関数の機能設計を記述する。この関数は、KeyedTraversable の最初の n 個のエントリを除いた新しい dict を返す機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：データ処理において、先頭の一定数の要素をスキップして残りの要素を処理するパターンは一般的である。例えば、ページネーション処理でオフセットを適用する場合や、ヘッダー行を除いた CSV データの処理、バッチ処理で既に処理済みのエントリをスキップする場合などに使用される。本関数は、このようなスキップ処理を効率的かつ型安全に行うためのユーティリティを提供する。

**機能の利用シーン**：
- ページネーション処理でオフセット位置からのデータを取得する場合
- データストリームの先頭にあるメタデータやヘッダーをスキップする場合
- イテレーション処理で特定位置から処理を開始する場合
- `take` 関数と組み合わせて部分範囲を取得する場合

**主要な処理内容**：
1. 引数 n が非負であることを検証（負の場合は invariant 違反でエラー）
2. 入力の KeyedTraversable を順次イテレート
3. 最初の n 個のエントリはスキップ
4. n+1 番目以降のエントリを新しい dict に追加
5. 結果の dict を返却

**関連システム・外部連携**：本関数は純粋な計算処理であり、外部システムとの連携はない。

**権限による制御**：本関数は汎用ユーティリティであり、権限による制御は行わない。

## 関連画面

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

## 機能種別

計算処理（コレクション操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $traversable | KeyedTraversable<Tk, Tv> | Yes | 処理対象の KeyedTraversable | なし |
| $n | int | Yes | スキップするエントリ数 | 非負整数（0以上） |

### 入力データソース

関数引数として直接渡される KeyedTraversable オブジェクトと整数値。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | dict<Tk, Tv> | 最初の n エントリを除いた残りのエントリを含む dict |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ $n < 0 の場合、invariant 違反でエラー
2. 結果用の空 dict を初期化
3. カウンタ $ii を -1 で初期化
4. $traversable を foreach でイテレート
   ├─ $ii をインクリメント
   ├─ $ii < $n の場合は continue でスキップ
   └─ それ以外は結果 dict にエントリを追加
5. 結果の dict を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{n >= 0 か?}
    B -->|No| C[invariant 違反エラー]
    B -->|Yes| D[result = dict[], ii = -1]
    D --> E{次のエントリがあるか?}
    E -->|No| F[result を返却]
    E -->|Yes| G[ii++]
    G --> H{ii < n か?}
    H -->|Yes| E
    H -->|No| I[result にエントリを追加]
    I --> E
    F --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-82-01 | 非負整数制約 | n は 0 以上の整数でなければならない | 常時 |
| BR-82-02 | 元の順序保持 | 結果の dict は元の順序を保持する | 常時 |
| BR-82-03 | キーの保持 | スキップされなかったエントリは元のキーを保持する | 常時 |
| BR-82-04 | 過剰スキップ | n が要素数以上の場合、空の dict を返す | 常時 |

### 計算ロジック

エントリのスキップ:
- インデックス i（0始まり）のエントリは、i < n の場合スキップされる
- i >= n のエントリが結果に含まれる

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

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

本関数はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | invariant 違反 | n < 0 の場合 | 呼び出し前に n >= 0 を保証する |
| - | 型エラー | 不正な型の引数が渡された場合 | Hack型システムによりコンパイル時に検出 |

### リトライ仕様

本関数は純粋関数であり、リトライの概念は適用されない。

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

本関数はステートレスな純粋関数であり、トランザクション管理は不要。

## パフォーマンス要件

- 時間計算量: O(n)、n は $traversable のサイズ
- 空間計算量: O(n)、n は $traversable のサイズ

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

- 純粋関数であり、副作用がないためセキュリティリスクは低い
- 入力データの検証は呼び出し元の責任

## 備考

- `take` 関数と対になる関数で、`take` は最初の n 個を取得、`drop` は最初の n 個をスキップ
- イテレータを使用する場合、一度スキップしたエントリは再度取得できないため注意

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

Hack の組み込み型である dict, KeyedTraversable について理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.php | `src/dict/select.php` | dict 型の基本操作と関数シグネチャの理解 |

**読解のコツ**: `Tk as arraykey` は Tk が arraykey（int または string）のサブタイプであることを示す制約。

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

drop 関数の定義を確認する。

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

**主要処理フロー**:
1. **51-54行目**: 関数シグネチャの定義
2. **55行目**: invariant で n >= 0 を検証
3. **56-57行目**: 結果 dict と カウンタの初期化
4. **58-65行目**: foreach ループでスキップと追加処理

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.php | `src/dict/select.php` | take 関数の実装（189-207行目）- 対になる関数 |

**主要処理フロー**:
- **189-207行目**: take は drop と逆で最初の n 個を取得

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

```
Dict\drop($traversable, $n)
    |
    +-- invariant($n >= 0, ...)  [入力検証]
    |
    +-- foreach ($traversable as $key => $value)
            |
            +-- $result[$key] = $value  [条件付きで追加]
```

### データフロー図

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

$traversable ──────> foreach ループ ──────────────────> dict<Tk, Tv>
(KeyedTraversable)      |
                        +-- インデックス < n: スキップ
                        |
                        +-- インデックス >= n: 結果に追加

$n ─────────────────> スキップ数の制御
(int)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.php | `src/dict/select.php` | ソース | drop 関数の実装 |
| DictSelectTest.php | `tests/dict/DictSelectTest.php` | テスト | drop のユニットテスト（59-109行目） |
