# 機能設計書 43-reverse

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\reverse` 関数の機能設計を記載する。この関数は文字列をバイト単位で逆順に並べ替える機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：文字列の逆順処理は、回文判定、データ形式の変換、特定のアルゴリズム実装など、多くのプログラミングシナリオで必要とされる基本操作である。本機能はバイト単位での逆順処理を提供し、ASCII文字列や固定長バイト列の操作に最適化されている。

**機能の利用シーン**：
- 回文（palindrome）の判定処理
- バイナリデータの逆順処理
- 文字列アルゴリズムの実装（例：接尾辞配列の構築）
- デバッグや可視化目的での文字列操作
- エンコーディングが単一バイト文字の場合の文字列反転

**主要な処理内容**：
1. 入力文字列を受け取る
2. 文字列の先頭と末尾からスワップを行いながら中央に向かって処理
3. 全てのバイトが逆順に並べ替えられた文字列を返す

**関連システム・外部連携**：特になし。純粋なインプレース変換処理。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 画面なし | - | 本プロジェクト（Hack Standard Library）はUIを持たないライブラリプロジェクトのため、画面機能マッピングは該当しません。 |

## 機能種別

文字列変換処理（Transform）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $string | string | Yes | 逆順にする対象の文字列 | なし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | string | バイト単位で逆順にされた文字列 |

### 出力先

関数の戻り値として返却される。

## 処理フロー

### 処理シーケンス

```
1. 引数の受け取り
   └─ $string（対象文字列）を受け取る
2. ポインタの初期化
   └─ $lo = 0（先頭）、$hi = length - 1（末尾）
3. スワップループ
   └─ $lo < $hi の間、$string[$lo]と$string[$hi]を交換
4. ポインタの更新
   └─ $lo++、$hi--
5. 結果の返却
   └─ 逆順にされた文字列を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[文字列を受け取る]
    B --> C[lo = 0, hi = length - 1]
    C --> D{lo < hi ?}
    D -->|Yes| E[string[lo]とstring[hi]を交換]
    E --> F[lo++, hi--]
    F --> D
    D -->|No| G[結果を返却]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-43-01 | バイト単位処理 | 文字ではなくバイト単位で逆順処理する | 常時 |
| BR-43-02 | 空文字列対応 | 空文字列の場合は空文字列を返す | 入力が空の場合 |
| BR-43-03 | 回文不変 | 回文文字列は逆順処理後も同じ文字列となる | 入力が回文の場合 |

### 計算ロジック

- アルゴリズム: 両端ポインタを使用したインプレース・スワップ
- 時間計算量: O(n/2) = O(n)
- 空間計算量: O(1)（追加メモリなし）

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし（同期的な純粋関数）

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

該当なし（データベース操作なし）

## パフォーマンス要件

- 時間計算量: O(n)、n = 文字列長
- 空間計算量: O(1)（インプレース処理）

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

- 本関数は副作用を持たない純粋関数
- マルチバイト文字列（UTF-8等）をバイト単位で逆順にすると不正なエンコーディングになる可能性があるため注意が必要

## 備考

- マルチバイト文字（UTF-8等）を文字単位で逆順にする場合は `Str\reverse_l` を使用すること
- バイト単位の逆順はマルチバイト文字列では意図しない結果になる場合がある

---

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

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

### 推奨読解順序

#### Step 1: 公開API関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transform.php | `src/str/transform.php` | 公開関数reverseの定義とドキュメンテーション |

**主要処理フロー**:
1. **306-313行目**: reverse関数の完全な実装
2. **307行目**: 両端ポインタの初期化（$lo = 0, $hi = length - 1）
3. **308-311行目**: スワップループによるバイト交換

**読解のコツ**: Hackの文字列は配列のようにインデックスアクセスが可能（`$string[$lo]`）。この関数は内部実装を直接持っており、外部関数に委譲していない。

#### Step 2: ロケール対応版との違いを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | transform_l.php | `src/str/transform_l.php` | ロケール対応版reverse_lの定義 |

**主要処理フロー**:
- **291-293行目**: reverse_l関数はロケールを受け取り、文字単位で逆順処理する

#### Step 3: テストケースで挙動を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StrTransformTest.php | `tests/str/StrTransformTest.php` | reverseのテストケースを確認 |

**主要処理フロー**:
- **700-712行目**: providerReverseとtestReverseで様々な入力パターンと期待結果を確認
- **701-706行目**: 空文字列、回文、一般的な文字列のテストケース

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

```
Str\reverse($string)
    │
    └─ [直接実装: 両端ポインタによるスワップループ]
```

### データフロー図

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

$string (string) ──▶ 両端ポインタによるスワップ ──▶ 逆順文字列
                     (lo=0, hi=len-1から中央へ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/str/transform.php` | ソース | 公開API関数の定義（直接実装） |
| transform_l.php | `src/str/transform_l.php` | ソース | ロケール対応版の定義 |
| StrTransformTest.php | `tests/str/StrTransformTest.php` | テスト | 単体テスト |
