# 機能設計書 69-Vec\chunk

## 概要

本ドキュメントは、Hack Standard Library（HSL）の`Vec\chunk`関数の機能設計を記載する。この関数は、Traversableを指定されたサイズのチャンク（塊）に分割し、vecのvecとして返す。

### 本機能の処理概要

**業務上の目的・背景**：
大量のデータを処理する際、一度にすべてを処理するのではなく、小さな塊に分割して処理することで、メモリ効率やパフォーマンスを改善できる。例えば、バッチ処理、ページネーション、並列処理のタスク分割、API呼び出しの分割などに使用される。この関数は、コレクションを均等なサイズのチャンクに分割する機能を提供する。

**機能の利用シーン**：
- バッチ処理でのデータ分割
- データベースへの一括挿入の分割
- API呼び出しのレート制限対応
- 並列処理用のタスク分割
- グリッドレイアウトの行分割

**主要な処理内容**：
1. チャンクサイズが正の値であることを検証
2. 空の結果vecを初期化
3. Traversableをforeachで反復し、チャンクサイズごとに新しいvecを作成
4. 各要素を適切なチャンクに追加
5. 最後のチャンクは指定サイズより小さい場合がある

**関連システム・外部連携**：
外部システムとの連携はない。純粋な関数型ユーティリティとして動作する。

**権限による制御**：
権限による制御は存在しない。

## 関連画面

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

## 機能種別

計算処理 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $traversable | Traversable<Tv> | Yes | 分割対象のコレクション | なし |
| $size | int | Yes | 各チャンクのサイズ | 正の整数でなければならない |

### 入力データソース

プログラムコードからの直接呼び出し。vec、dict、Set、Vector、イテレータなど、Traversableを実装する任意の型を受け付ける。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | vec<vec<Tv>> | チャンクに分割されたvecのvec。最後のチャンクはサイズより小さい場合がある |

### 出力先

呼び出し元への戻り値として返却。

## 処理フロー

### 処理シーケンス

```
1. チャンクサイズの検証
   └─ invariant($size > 0, ...)

2. 空の結果vecと変数を初期化
   └─ $result = vec[]
   └─ $ii = 0 (現在位置)
   └─ $chunk_number = -1 (チャンクインデックス)

3. Traversableをforeachで反復
   └─ foreach ($traversable as $value)

4. 新しいチャンクの開始判定
   └─ if ($ii % $size === 0)
   └─ 新しい空のvecを結果に追加
   └─ チャンク番号をインクリメント

5. 要素を現在のチャンクに追加
   └─ $result[$chunk_number][] = $value

6. 結果vecを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{size > 0?}
    B -->|No| C[InvariantException]
    B -->|Yes| D[変数初期化]
    D --> E{traversableに次の要素があるか}
    E -->|Yes| F{ii % size === 0?}
    F -->|Yes| G[新しいチャンク作成]
    F -->|No| H[要素をチャンクに追加]
    G --> H
    H --> I[ii++]
    I --> E
    E -->|No| J[結果vecを返却]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 均等分割 | 最後のチャンク以外は指定サイズの要素数を持つ | 常時 |
| BR-02 | 最後のチャンク | 入力が均等に割り切れない場合、最後のチャンクは小さくなる | 入力サイズ % size != 0 |
| BR-03 | 順序保持 | 元のコレクションの走査順序がチャンク内でも保持される | 常時 |
| BR-04 | 空入力 | 空のコレクションを入力した場合、空のvecを返す | 入力が空 |

### 計算ロジック

チャンク数 = ceil(入力サイズ / チャンクサイズ)
最後のチャンクサイズ = 入力サイズ % チャンクサイズ （0の場合はチャンクサイズ）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | sizeが0以下の場合 | 正の値を指定する |

### リトライ仕様

リトライは不要（純粋関数であり、同じ入力に対して常に同じ結果を返す）。

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

トランザクション管理は不要（メモリ内処理のみ）。

## パフォーマンス要件

- 時間計算量: O(n)、nは入力コレクションのサイズ
- 空間計算量: O(n)、すべての要素を新しい構造に格納

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

- 純粋関数であり、外部リソースへのアクセスは行わない
- 非常に大きなコレクションを小さなチャンクに分割する場合、チャンクの数が多くなる点に注意

## 備考

- チャンクサイズが入力サイズより大きい場合、1つのチャンクにすべての要素が含まれる
- `Str\chunk`は文字列を固定長の文字列に分割する類似機能
- 属性`<<__NoAutoLikes>>`が付与されており、自動的なLike型変換が無効化されている

---

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

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

### 推奨読解順序

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

vec<vec<T>>（ネストしたvec）の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transform.php | `src/vec/transform.php` | chunk関数の定義場所と型シグネチャ |

**読解のコツ**: `vec<vec<Tv>>`は「Tv型要素のvecのvec」を表す。外側のvecはチャンクのリスト、内側の各vecは個々のチャンクを表す。

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

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

**主要処理フロー**:
1. **23-27行目**: 関数シグネチャと属性 - __NoAutoLikes付き
2. **28行目**: チャンクサイズの正の値検証
3. **29-31行目**: 変数初期化（結果vec、カウンタ、チャンク番号）
4. **32-40行目**: foreachループでチャンク構築
5. **33-36行目**: 新しいチャンクの開始判定と作成
6. **38行目**: 要素をチャンクに追加
7. **41行目**: 結果vecを返却

#### Step 3: 関連関数との比較

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | - | Str\chunk | 文字列のチャンク分割 |

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

```
Vec\chunk()
    │
    └─ foreach反復
           ├─ チャンク境界判定 (ii % size === 0)
           ├─ 新チャンク作成
           └─ 要素追加
```

### データフロー図

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

Traversable<Tv>     ───▶  foreach反復処理  ───────────▶   vec<vec<Tv>>
$size               ───▶                                 (チャンクリスト)
                              │
                              ▼
                         チャンク境界判定
                         ii % size === 0
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
              新チャンク作成        既存チャンクに追加
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/vec/transform.php` | ソース | chunk関数の実装 |
| VecTransformTest.php | `tests/vec/VecTransformTest.php` | テスト | chunkのユニットテスト（17-53行目） |
