# 機能設計書 30-capitalize

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `Str\capitalize` 関数の機能設計書です。文字列の最初の文字を大文字に変換する機能を提供します。

### 本機能の処理概要

`Str\capitalize` 関数は、与えられた文字列の最初の文字を大文字に変換して返す関数です。最初の文字が既に大文字の場合やアルファベットでない場合は、文字列はそのまま返されます。

**業務上の目的・背景**：テキスト処理において、文字列の先頭を大文字にする（キャピタライゼーション）は非常に一般的な操作です。人名、地名、文の先頭など、最初の文字だけを大文字にする必要がある場面で使用されます。この関数は、最初の1文字のみを大文字化し、残りの文字はそのまま保持します。

**機能の利用シーン**：
- 人名の正規化（先頭を大文字に）
- 文の先頭文字の大文字化
- タイトルの一部の処理
- 識別子の正規化
- ユーザー入力の整形

**主要な処理内容**：
1. 入力文字列 `$string` を受け取る
2. 文字列が空の場合は空文字列を返す
3. 最初の1文字を `_Str\uppercase_l` で大文字化
4. 残りの文字列と結合して返す

**関連システム・外部連携**：外部システムとの連携はありません。純粋な文字列操作関数です。

**権限による制御**：特に権限による制御はありません。純粋関数（Pure function）として実装されており、副作用はありません。

## 関連画面

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

## 機能種別

変換処理 / 文字列変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $string | string | Yes | 大文字化する文字列 | なし（空文字列も許可） |

### 入力データソース

関数呼び出し時の引数として直接渡される文字列データ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 最初の文字が大文字化された文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 関数呼び出し
   └─ $string を引数として受け取る
2. 空文字列チェック
   └─ $string === '' の場合は '' を返す
3. 先頭文字の大文字化
   └─ slice($string, 0, 1) を uppercase_l で大文字化
4. 結合
   └─ 大文字化した先頭 + slice($string, 1) を結合
5. 結果の返却
   └─ string 値を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始: capitalize呼び出し] --> B{文字列は空?}
    B -->|Yes| C[空文字列を返す]
    B -->|No| D[最初の1文字を取得]
    D --> E[最初の文字を大文字化]
    E --> F[残りの文字列と結合]
    F --> G[結果を返す]
    C --> H[終了]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 空文字列 | 空文字列は空文字列を返す | $string === '' |
| BR-02 | 先頭のみ変換 | 最初の1文字のみ大文字化、残りは変更なし | 常時 |
| BR-03 | 既存大文字 | 既に大文字の場合はそのまま | 先頭が大文字 |
| BR-04 | 非アルファベット | アルファベットでない場合は変更なし | 先頭が数字等 |

### 計算ロジック

- `uppercase_l(slice($string, 0, 1)) . slice($string, 1)`

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

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

本機能はデータベース操作を行いません。

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし。

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

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

## パフォーマンス要件

- 計算量: O(n) ここで n は文字列の長さ（slice操作のため）
- 純粋関数として実装されており、キャッシュや状態を持たない
- コンテキスト係数 `[]:` が指定されており、副作用なしで実行可能

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

- 純粋関数のため、セキュリティ上の懸念は最小限
- ロケールによる大文字変換の違いに注意（トルコ語の i -> I 問題等）
- 入力文字列のサニタイズは呼び出し元の責任

## 備考

- 全ての文字を大文字にする場合は `Str\uppercase()` を使用すること
- 全ての単語の先頭を大文字にする場合は `Str\capitalize_words()` を使用すること
- ロケールを考慮した大文字化には `Str\capitalize_l()` を使用すること

---

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

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

### 推奨読解順序

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

まず、外部から呼び出される公開関数のインターフェースを理解します。

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

**主要処理フロー**:
- **15-25行目**: 関数のドキュメントコメント
- **15-16行目**: 機能概要。最初の文字を大文字化
- **17-19行目**: 既に大文字またはアルファベットでない場合は変更なし
- **21-22行目**: 関連関数への参照（uppercase, capitalize_words）
- **26-31行目**: 関数シグネチャと実装
- **27-29行目**: 空文字列チェック
- **30行目**: `uppercase_l(slice($string, 0, 1))` で先頭を大文字化し、`slice($string, 1)` と結合

**読解のコツ**: `slice` 関数を使って最初の1文字と残りを分離し、最初の文字だけを `uppercase_l` で大文字化しています。

#### Step 2: ロケール対応版を確認

ロケール対応版の実装を確認します。

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

**主要処理フロー**:
- **15-37行目**: `capitalize_l` の定義
- **20-22行目**: ロケール固有の大文字化ルール（例：`i` -> `I` vs `i` -> `İ`）
- **29-37行目**: 実装。`slice_l` を使ってロケール対応の文字単位で分離

#### Step 3: 関連関数を確認

全単語の大文字化関数を確認します。

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

**主要処理フロー**:
- **33-73行目**: `capitalize_words` の定義
- **44-53行目**: デリミタがnullの場合はロケール定義のデリミタを使用
- **56-72行目**: カスタムデリミタの場合は手動で各単語を処理

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

テストコードから具体的な動作仕様を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | StrTransformTest.php | `tests/str/StrTransformTest.php` | テストケースから具体的な入出力パターンを理解 |

**主要処理フロー**:
- **17-25行目**: `provideCapitalize` メソッドでテストデータを定義
- **18行目**: `'foo'` -> `'Foo'`
- **19行目**: `'Foo'` -> `'Foo'`（既に大文字）
- **20行目**: `'foo foo'` -> `'Foo foo'`（先頭のみ）
- **21行目**: `'123'` -> `'123'`（数字は変更なし）
- **22行目**: `'-foo'` -> `'-foo'`（ハイフンは変更なし）
- **27-33行目**: テスト実行メソッド

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

```
Str\capitalize($string)
    │
    ├─ slice($string, 0, 1)
    │      └─ [最初の1文字を取得]
    │
    ├─ _Str\uppercase_l(...)
    │      └─ [大文字化]
    │
    └─ slice($string, 1)
           └─ [残りの文字列を取得]
```

### データフロー図

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

$string (string) ───▶ capitalize() ───▶ string (大文字化済み)
                          │
                          ├─ 空チェック
                          │
                          ├─ 先頭文字取得 (slice 0,1)
                          │
                          ├─ 大文字化 (uppercase_l)
                          │
                          └─ 残り取得 (slice 1) + 結合
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/str/transform.php` | ソース | 公開API定義（capitalize, capitalize_words） |
| transform_l.php | `src/str/transform_l.php` | ソース | ロケール対応実装 |
| StrTransformTest.php | `tests/str/StrTransformTest.php` | テスト | ユニットテスト |
