# 機能設計書 54-join

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\join` 関数の機能設計書である。この関数はTraversable（反復可能なコレクション）の要素を指定した区切り文字列で結合し、単一の文字列を生成する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：
複数のデータ要素を単一の文字列に結合する処理は、データ表示、ファイル出力、API通信など多くの場面で必要とされる。例えば、CSVデータの生成、URLパラメータの構築、ログメッセージの組み立てなど。`Str\join` 関数は、PHPの `implode` 関数に相当する機能を型安全に提供し、様々なコレクション型から一貫した方法で文字列を生成可能にする。

**機能の利用シーン**：
- CSV行データの生成（カンマ区切り）
- URLパスやパラメータの構築（スラッシュや&記号区切り）
- ログメッセージの組み立て
- HTMLクラス属性の生成（スペース区切り）
- SQLのIN句用文字列の生成
- 配列要素のデバッグ出力

**主要な処理内容**：
1. 入力としてTraversable（配列、Vector、Set、Map、イテレータなど）を受け取る
2. 区切り文字列（glue）を受け取る
3. コレクションの要素を順番に走査
4. 各要素を文字列に変換し、区切り文字列で連結
5. 結合された文字列を返却

**関連システム・外部連携**：
本関数は純粋な文字列操作であり、外部システムとの直接的な連携はない。ただし、生成された文字列はファイル出力やAPI通信など様々な用途に使用される。

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

## 関連画面

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

## 機能種別

文字列結合処理 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $pieces | Traversable<arraykey> | Yes | 結合する要素のコレクション | arraykey型（intまたはstring）の要素を持つTraversable |
| $glue | string | Yes | 要素間の区切り文字列 | 任意の文字列（空文字も可） |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 要素を区切り文字列で結合した文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 関数呼び出し
   └─ Str\join($pieces, $glue) が呼び出される
2. 変数初期化
   └─ 出力文字列を空文字で初期化、最初の要素フラグをtrueに設定
3. コレクション走査
   └─ foreach でコレクションの各要素を順番に処理
4. 要素結合
   └─ 最初の要素: そのまま出力文字列に設定
   └─ 2番目以降: glue + 要素を出力文字列に追加
5. 結果返却
   └─ 結合された文字列を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力: $pieces, $glue]
    B --> C[出力文字列を空文字で初期化]
    C --> D[first = true]
    D --> E{次の要素あり?}
    E -->|No| I[結果を返却]
    E -->|Yes| F{first == true?}
    F -->|Yes| G[out = 要素を文字列化]
    F -->|No| H[out += glue + 要素を文字列化]
    G --> J[first = false]
    H --> E
    J --> E
    I --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-54-01 | 要素の文字列化 | 各要素は(string)キャストで文字列に変換される | 常時 |
| BR-54-02 | 空コレクション | 空のコレクションの場合、空文字を返す | コレクションが空の場合 |
| BR-54-03 | 単一要素 | 要素が1つの場合、glueは使用されない | 要素数が1の場合 |
| BR-54-04 | 区切り位置 | glueは要素間にのみ挿入され、先頭・末尾には付かない | 常時 |

### 計算ロジック

特定の計算ロジックは存在しない。文字列連結操作のみ。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 本関数は例外をスローしない | - |

### リトライ仕様

リトライは不要（同期的な純粋関数のため）

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

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

## パフォーマンス要件

- 計算量: O(n) - n はコレクションの要素数
- 純粋関数 `[]` として定義されており、副作用なし
- 文字列連結は `.=` 演算子を使用

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

- SQL文字列を生成する場合は、適切なエスケープ処理が必要
- HTML出力用の文字列を生成する場合は、XSS対策が必要
- 本関数自体はエスケープ処理を行わない

## 備考

- PHPの `implode()` 関数と同等の機能を型安全に提供
- `readonly` 修飾子により、入力コレクションの変更は行わない
- 要素型は `arraykey`（int または string）に制限されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | combine.php | `src/str/combine.php` | 関数シグネチャと型パラメータを確認 |

**読解のコツ**:
- `Traversable<arraykey>` は int または string 型の要素を持つ反復可能なコレクション
- `readonly` 修飾子は引数が読み取り専用であることを示す

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | combine.php | `src/str/combine.php` | join 関数の実装（23-38行目） |

**主要処理フロー**:
1. **23-26行目**: 関数定義と引数（`$pieces`, `$glue`）
2. **27行目**: 出力文字列を空文字で初期化 `$out = ""`
3. **28行目**: 最初の要素フラグを初期化 `$first = true`
4. **29-36行目**: foreachループで要素を走査
5. **30-32行目**: 最初の要素の処理 - そのまま代入
6. **33-35行目**: 2番目以降の要素 - glueを付けて連結
7. **37行目**: 結合された文字列を返却

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StrCombineTest.php | `tests/str/StrCombineTest.php` | テストデータとアサーション（17-37行目） |

**主要ポイント**:
- **18行目**: テストデータ（vec, Vector, Set, Map, keyset, dict, イテレータ）
- **35-36行目**: 結果の検証（'-'で結合）

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

```
Str\join($pieces, $glue)
    │
    └─ foreach ($pieces as $item)
           │
           ├─ $first == true: $out = (string)$item
           │
           └─ $first == false: $out .= $glue.(string)$item
```

### データフロー図

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

$pieces ─────────────────▶
 (Traversable<arraykey>)   Str\join ─────────────▶ joined string
                               │
$glue ───────────────────▶     │
 (string)                      │
                               ▼
                          foreach loop
                               │
                               ▼
                        string concatenation
```

### 関連ファイル一覧

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