# 機能設計書 72-map

## 概要

本ドキュメントは、Hack Standard Library（HSL）のVec名前空間が提供する`map`関数の機能設計を記述する。この関数は、Traversableの各要素に関数を適用し、変換結果を新しいvecとして返却する機能を提供する。

### 本機能の処理概要

`Vec\map`関数は、関数型プログラミングにおける基本的な操作であるマップ処理をHack言語で型安全に実装している。入力のTraversableの各要素に変換関数を適用し、変換後の値を含む新しいvecを返却する。

**業務上の目的・背景**：データ変換はアプリケーション開発において最も頻繁に行われる操作の1つである。例えば、データベースから取得したエンティティをDTOに変換する、APIレスポンスを整形する、数値リストに計算を適用するなど、様々な場面でマップ処理が必要となる。`map`関数は、このような変換処理を簡潔かつ型安全に記述することを可能にし、コードの可読性と保守性を向上させる。

**機能の利用シーン**：
- データベースから取得したエンティティ配列をDTO配列に変換する
- 数値配列に算術演算を適用して新しい配列を生成する
- 文字列配列を加工（大文字化、トリム、フォーマット等）する
- オブジェクト配列から特定のプロパティのみを抽出する

**主要な処理内容**：
1. 入力としてTraversableと変換関数を受け取る
2. Traversableの各要素を順次イテレートする
3. 各要素に変換関数を適用する
4. 変換結果を結果vecに追加する
5. すべての変換結果を含む新しいvecを返却する

**関連システム・外部連携**：本機能は純粋な関数であり、外部システムとの連携はない。非同期版として`Vec\map_async`が別途提供されている。

**権限による制御**：本機能は純粋関数であり、権限による制御は適用されない。関数シグネチャの`[ctx $value_func]`は、変換関数のコンテキストを伝播することを示す。

## 関連画面

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

## 機能種別

計算処理 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $traversable | Traversable<Tv1> | Yes | 変換対象のコレクション | なし（空コレクションも許容） |
| $value_func | (function(Tv1)[_]: Tv2) | Yes | 各要素に適用する変換関数 | なし |

### 入力データソース

関数引数として直接渡される。Traversableとして許容される型には、vec、dict、keyset、Vector、Map、Set、およびカスタムIteratorが含まれる。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | vec<Tv2> | 変換関数を適用した結果を含む新しいvec |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 空のvecを結果として初期化
   └─ $result = vec[]
2. Traversableをイテレート
   └─ foreach ($traversable as $value)
3. 変換関数を適用
   └─ $value_func($value)
4. 変換結果を結果vecに追加
   └─ $result[] = $value_func($value)
5. 完成した結果vecを返却
   └─ return $result
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[result = vec空配列を初期化]
    B --> C{traversableに次の要素があるか}
    C -->|Yes| D[次のvalueを取得]
    D --> E[value_func実行でvalueを変換]
    E --> F[変換結果をresultに追加]
    F --> C
    C -->|No| G[resultを返却]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-01 | 順序保持 | 入力順序が出力で保持される | 常時 |
| BR-72-02 | 要素数保持 | 入力と出力の要素数は同一 | 常時 |
| BR-72-03 | 空入力処理 | 空のTraversableは空のvecを返す | 入力が空の場合 |
| BR-72-04 | キー破棄 | KeyedTraversableのキーは破棄される | KeyedTraversable入力時 |
| BR-72-05 | コンテキスト伝播 | 変換関数のコンテキストが伝播される | 常時 |

### 計算ロジック

変換関数$value_funcに依存する。関数自体は単純なループと関数適用のみ。

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 変換関数内例外 | $value_funcが例外をスローした場合 | 呼び出し元で適切にハンドリング |

### リトライ仕様

本機能にリトライ仕様はない。

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

本機能はデータベーストランザクションを使用しない。

## パフォーマンス要件

- 時間計算量: O(n) - nは入力要素数
- 空間計算量: O(n) - 結果格納用のvec
- 注意: 変換関数の計算量がO(f)の場合、全体の時間計算量はO(n * f)となる

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

本機能は純粋関数であり、特別なセキュリティ考慮事項はない。変換関数内でのセキュリティ処理は呼び出し元の責務となる。

## 備考

- 非同期処理が必要な場合は`Vec\map_async`を使用する
- キーを利用した変換が必要な場合は`Vec\map_with_key`を使用する
- コンテキスト記法`[ctx $value_func]`により、変換関数の副作用特性が伝播される

---

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

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

### 推奨読解順序

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

`map`関数で扱うデータ型は、ジェネリクスを用いた型変換パターンである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Hack言語組み込み型 | - | Traversable<Tv1>からvec<Tv2>への型変換を理解する |

**読解のコツ**: HackのジェネリクスにおいてTv1とTv2は異なる型を表す。関数シグネチャを見ると、入力の要素型Tv1が変換関数によってTv2に変換されることがわかる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | transform.php | `src/vec/transform.php` | map関数の定義と実装を確認 |

**主要処理フロー**:
1. **98-101行目**: 関数シグネチャ - ジェネリック型Tv1, Tv2とコンテキスト伝播
2. **102行目**: 空のvecで結果を初期化
3. **103-105行目**: foreachで各要素に変換関数を適用
4. **106行目**: 結果を返却

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | VecTransformTest.php | `tests/vec/VecTransformTest.php` | map関数のテストケースを確認 |

**主要処理フロー**:
- **123-191行目**: provideTestMapメソッドでテストデータを提供
- **124行目**: doublerラムダ関数の定義
- **125-130行目**: 空配列のテストケース
- **131-134行目**: 単一要素のテストケース
- **136-139行目**: Vec\rangeとの組み合わせ
- **151-164行目**: dict、Map、Vectorなど様々な型のテスト
- **181-188行目**: Iterator型のテスト

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

```
呼び出し元コード
    │
    └─ Vec\map($traversable, $value_func)
           │
           └─ foreach ループ
                  │
                  └─ $value_func($value) を各要素に適用
                         │
                         └─ 結果をvecに追加
```

### データフロー図

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

Traversable<Tv1>  ────┐
                      │
                      ├──▶  foreachループで      ───▶  vec<Tv2>
                      │     各要素に$value_funcを
$value_func     ──────┘     適用

例:
vec[1, 2, 3]         ───▶  $x ==> $x * 2       ───▶  vec[2, 4, 6]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/vec/transform.php` | ソース | map関数の実装 |
| VecTransformTest.php | `tests/vec/VecTransformTest.php` | テスト | map関数のユニットテスト |
| async.php | `src/vec/async.php` | ソース | 非同期版map_asyncの実装 |
