# 機能設計書 18-compare_ci

## 概要

本ドキュメントは、Hack Standard Library（HSL）のStr名前空間における`compare_ci`関数の機能設計を記述する。この関数は、2つの文字列の大小比較を大文字小文字を無視して行い、比較結果を整数で返す。

### 本機能の処理概要

`compare_ci`関数は、2つの文字列を辞書順で比較し、その結果を整数で返す。大文字と小文字を区別しない（case-insensitive）比較を行い、ロケールに基づいた照合（collation）を使用する。

**業務上の目的・背景**：ユーザー入力の検証、ファイル名の比較、識別子のマッチングなど、大文字小文字を区別せずに文字列を比較したい場面は多い。この関数により、明示的な大文字/小文字変換なしに効率的な比較が可能になる。

**機能の利用シーン**：ユーザー名やメールアドレスの照合、ファイル拡張子の判定、設定キーの比較、HTTPヘッダー名の比較、プログラミング言語のキーワード判定など、大文字小文字を区別しない文字列比較が必要な場面で使用される。

**主要な処理内容**：
1. 2つの文字列を受け取る
2. ロケールに基づいた大文字小文字無視の照合関数（strcasecmp_l）を呼び出す
3. 比較結果を整数で返す（負/0/正）

**関連システム・外部連携**：内部で`_Str\strcasecmp_l`を使用し、ロケールに基づいた大文字小文字無視の文字列比較を行う。

**権限による制御**：特段の権限制御はない。純粋関数として動作する。

## 関連画面

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

## 機能種別

文字列比較 / 純粋関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| string1 | string | Yes | 比較する最初の文字列 | - |
| string2 | string | Yes | 比較する2番目の文字列 | - |

### 入力データソース

関数の引数として渡される文字列

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 比較結果: string1 < string2 の場合は負の値、string1 > string2 の場合は正の値、等しい場合は0（大文字小文字無視） |

### 出力先

呼び出し元に整数を返す

## 処理フロー

### 処理シーケンス

```
1. 引数の2つの文字列を受け取る
2. _Str\strcasecmp_l関数を呼び出す
   └─ ロケールに基づいた大文字小文字無視の照合比較を実行
3. 比較結果の整数を返す
```

### フローチャート

```mermaid
flowchart TD
    A[compare_ci呼び出し] --> B[strcasecmp_l実行]
    B --> C{比較結果}
    C -->|string1 < string2| D[負の値を返却]
    C -->|string1 = string2| E[0を返却]
    C -->|string1 > string2| F[正の値を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 大文字小文字無視 | 大文字と小文字を同一視して比較する | 常時適用 |
| BR-02 | ロケール照合 | ロケールに基づいた照合順序を使用 | 常時適用 |
| BR-03 | 純粋関数 | 副作用なし、同じ入力には同じ出力 | 常時適用 |

### 計算ロジック

```
戻り値 = strcasecmp_l(string1, string2)
```

- 戻り値 < 0: string1がstring2より小さい（大文字小文字無視）
- 戻り値 = 0: string1とstring2が等しい（大文字小文字無視）
- 戻り値 > 0: string1がstring2より大きい（大文字小文字無視）

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

該当なし（本機能は純粋な文字列操作でデータベースを使用しない）

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 計算量: O(min(len(string1), len(string2)))
- メモリ: 追加のメモリ割り当てなし

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

- タイミング攻撃に対して脆弱な可能性がある（パスワード比較には使用しないこと）
- パスワードやトークンの比較には定数時間比較関数を使用すること

## 備考

- 大文字小文字を区別した比較には`Str\compare()`を使用
- 関連ガイド: /hack/built-in-types/string

---

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

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

### 推奨読解順序

#### Step 1: 関数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | introspect.php | `src/str/introspect.php` | compare_ci関数の定義と実装 |

**読解のコツ**: `_ci`サフィックスは「case-insensitive」（大文字小文字無視）を意味する。HSLの命名規則として一貫している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | introspect.php | `src/str/introspect.php` | compare_ci関数の実装詳細 |

**主要処理フロー**:
1. **30-37行目**: docコメント。戻り値の意味と関連関数への参照
2. **38-42行目**: compare_ci関数本体
3. **38-41行目**: 関数シグネチャ。2つのstring引数を受け取り、intを返す
4. **42行目**: _Str\strcasecmp_l関数の呼び出し

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | introspect.php | `src/str/introspect.php` | compare関数との比較 |

**主要処理フロー**:
- **compare**: strcoll_lを使用（大文字小文字区別）
- **compare_ci**: strcasecmp_lを使用（大文字小文字無視）

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

```
Str\compare_ci(string1, string2)
    │
    └─ _Str\strcasecmp_l(string1, string2)
           │
           └─ ロケールベースの大文字小文字無視照合比較
                  │
                  └─ 整数結果を返却
```

### データフロー図

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

string1 ─────────────┐
                     ├──▶ Str\compare_ci() ───────────▶ int
string2 ─────────────┘         │
                               ▼
                         strcasecmp_l()
                               │
                         ┌─────┼─────┐
                         ▼     ▼     ▼
                        < 0    0    > 0
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| introspect.php | `src/str/introspect.php` | ソース | compare_ci関数およびその他の文字列検査関数 |
| introspect_l.php | `src/str/introspect_l.php` | ソース | ロケール対応版の文字列検査関数 |
