# 機能設計書 34-uppercase

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\uppercase` 関数の機能設計について記載する。この関数は文字列内のすべてのアルファベット文字を大文字に変換する機能を提供する。

### 本機能の処理概要

`Str\uppercase` 関数は、入力文字列内のすべてのアルファベット文字（a-z）を対応する大文字（A-Z）に変換するための関数である。非アルファベット文字（数字、記号など）はそのまま保持される。

**業務上の目的・背景**：文字列の正規化やフォーマット処理において、大文字に統一することは一般的な要件である。例えば、コードやIDの表示、タイトルの強調、定数名の表示などにおいて、すべて大文字にする処理が必要となる。この関数により、開発者は簡潔なコードで文字列の大文字変換を実現できる。

**機能の利用シーン**：
- 定数名やコードの正規化（例: "status_active" -> "STATUS_ACTIVE"）
- タイトルや見出しの強調表示
- 識別子の大文字化
- データベースキーの標準化
- フォームフィールドラベルの表示

**主要な処理内容**：
1. 入力文字列を受け取る
2. 内部関数 `_Str\uppercase_l` を呼び出して大文字変換を実行
3. 変換後の文字列を返却

**関連システム・外部連携**：本関数は内部で `_Str\uppercase_l` 組み込み関数を使用する。ロケール依存の変換が必要な場合は `Str\uppercase_l` 関数を使用する。

**権限による制御**：本機能は純粋関数であり、権限による制御は不要である。

## 関連画面

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

## 機能種別

計算処理 / 文字列変換

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | すべてのアルファベットが大文字に変換された文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力文字列を受け取る
2. _Str\uppercase_l関数を呼び出し
   └─ デフォルトロケールで大文字変換を実行
3. 変換後の文字列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[_Str\uppercase_l関数呼び出し]
    B --> C[変換後の文字列を返却]
    C --> D[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | アルファベット変換 | a-zをA-Zに変換 | アルファベット文字のみ |
| BR-02 | 非アルファベット保持 | 数字、記号、空白はそのまま | 非アルファベット文字 |
| BR-03 | 空文字列処理 | 空文字列は空文字列を返す | $string === '' |
| BR-04 | バイト単位処理 | マルチバイト文字はバイト単位で処理 | デフォルトロケール使用時 |

### 計算ロジック

ASCII範囲のアルファベット文字（0x61-0x7A）を対応する大文字（0x41-0x5A）に変換する。

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライ処理は不要（純粋関数のため）。

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

トランザクション管理は不要（データベース操作なし）。

## パフォーマンス要件

- 計算量: O(n) - nは入力文字列の長さ
- 純粋関数属性 `[]:` により副作用なしが保証され、最適化の対象となる

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

- 入力文字列はそのまま処理されるため、エスケープ処理は呼び出し元の責任
- 純粋関数のため、副作用やセキュリティリスクはない

## 備考

- ロケール対応版として `Str\uppercase_l` 関数も提供されている
- トルコ語など特定のロケールでは `i` -> `İ`（ドット付きI）のような特殊な変換が必要な場合があり、その際は `Str\uppercase_l` を使用する
- 小文字変換は `Str\lowercase` を使用
- 最初の文字のみを大文字にする場合は `Str\capitalize` を使用

---

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

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

### 推奨読解順序

#### Step 1: メイン実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transform.php | `src/str/transform.php` | uppercase関数のメイン実装 |

**主要処理フロー**:
- **361-365行目**: 関数のドキュメントコメント
- **366-368行目**: 関数シグネチャと実装（単一行で内部関数を呼び出し）

**読解のコツ**: この関数は `lowercase` と対称的な構造を持ち、内部の `_Str\uppercase_l` 関数を呼び出すだけのラッパーである。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | transform_l.php | `src/str/transform_l.php` | uppercase_l関数のロケール対応版実装 |

**主要処理フロー**:
- **326-339行目**: Localeオブジェクトを受け取り、ロケール依存の大文字変換を実行

#### Step 3: テストコードで動作を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StrTransformTest.php | `tests/str/StrTransformTest.php` | uppercaseのテストケース |
| 3-2 | StrLocaleTest.php | `tests/str/StrLocaleTest.php` | ロケール対応版のテストケース |

**主要処理フロー**:
- **806-821行目**: provideUppercaseテストデータと testUppercaseテストメソッド
- StrLocaleTest.php **420-423行目**: testUppercaseL - ロケール依存の変換テスト

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

```
Str\uppercase($string)
    │
    └─ _Str\uppercase_l($string)
           └─ HHVM組み込み関数
```

### データフロー図

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

$string ─────────────▶ _Str\uppercase_l() ─────▶ 大文字変換済み文字列

例: "hello world" ──▶ "HELLO WORLD"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/str/transform.php` | ソース | uppercase関数のメイン実装 |
| transform_l.php | `src/str/transform_l.php` | ソース | ロケール対応版uppercase_l関数の実装 |
| StrTransformTest.php | `tests/str/StrTransformTest.php` | テスト | uppercaseのユニットテスト |
| StrLocaleTest.php | `tests/str/StrLocaleTest.php` | テスト | ロケール対応版のユニットテスト |
