# 機能設計書 26-length

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `Str\length` 関数の機能設計書です。文字列の長さをバイト数で取得する機能を提供します。

### 本機能の処理概要

`Str\length` 関数は、与えられた文字列の長さをバイト数として返す関数です。文字列内にヌル文字が含まれていても正確にバイト数を返します。

**業務上の目的・背景**：文字列処理において、文字列の長さを取得する操作は最も基本的かつ頻繁に使用される処理の一つです。バッファサイズの計算、文字列の切り詰め判定、入力長の検証など、様々な場面で必要となります。この関数はO(1)の計算量で文字列長を返すため、パフォーマンス上の懸念なく使用できます。

**機能の利用シーン**：
- 入力文字列の長さ制限チェック（例：ユーザー名は最大20バイト）
- バッファサイズの計算
- 文字列操作前の長さ確認
- ループ処理での終了条件判定
- データベースカラムサイズとの整合性チェック

**主要な処理内容**：
1. 入力文字列 `$string` を受け取る
2. PHPの `\strlen()` 関数を呼び出してバイト長を取得
3. 結果を整数値として返す

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

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

## 関連画面

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

## 機能種別

計算処理 / 文字列イントロスペクション

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 文字列のバイト数（0以上の整数） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 関数呼び出し
   └─ $string を引数として受け取る
2. strlen呼び出し
   └─ \strlen($string) でバイト数を取得
3. 結果の返却
   └─ int 値を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始: length呼び出し] --> B[strlen関数でバイト数取得]
    B --> C[バイト数を返す]
    C --> D[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | バイト単位計測 | 長さはバイト数で計測される（文字数ではない） | 常時 |
| BR-02 | ヌル文字対応 | ヌル文字を含む文字列も正確に計測 | 常時 |
| BR-03 | 空文字列 | 空文字列は0を返す | $string === '' |
| BR-04 | O(1)保証 | 計算量は常にO(1) | 常時 |

### 計算ロジック

`\strlen($string)` を直接呼び出し。HHVMのJITによる最適化が適用される。

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし。

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

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

## パフォーマンス要件

- 計算量: O(1)（定数時間）
- HHVMのJIT最適化が適用される
- 純粋関数として実装されており、キャッシュや状態を持たない
- コンテキスト係数 `[]:` が指定されており、副作用なしで実行可能
- 非常に高速な処理（メモリ内のサイズ情報を直接返す）

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

- 純粋関数のため、セキュリティ上の懸念は最小限
- マルチバイト文字列の場合、バイト数と文字数が異なることに注意

## 備考

- 文字数（grapheme単位）を取得する場合は `Str\length_l()` を使用すること
- マルチバイト文字（UTF-8等）では、1文字が複数バイトになる場合がある
- 例：`Str\length("foo\0bar")` は 7 を返す（3 ではない）

---

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

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

### 推奨読解順序

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

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

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

**主要処理フロー**:
- **152-161行目**: 関数のドキュメントコメント。O(1)計算量とヌル文字対応について説明
- **156行目**: `Str\length("foo\0bar")` が 7 を返す例示
- **158行目**: 文字数を取得する場合は `Str\length_l()` を参照
- **162-171行目**: 関数シグネチャと実装
- **164-168行目**: コメントで `Str\length_l()` との違いを説明。`\strlen()` を使う理由（JIT最適化）
- **170行目**: `\strlen($string)` を直接呼び出し

**読解のコツ**: コメントに記載されている通り、`Str\length_l()` with bytes locale と機能的には同等ですが、`\strlen()` を直接使うことでHHVMのJIT最適化の恩恵を受けられます。

#### Step 2: ロケール対応版との比較

文字数ベースの長さ取得関数を確認します。

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

**主要処理フロー**:
- **171-186行目**: `length_l` の定義
- **173-176行目**: O(1)またはO(n)の計算量がロケールに依存することを説明
- **185行目**: `_Str\strlen_l($string, $locale)` への委譲

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

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

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

**主要処理フロー**:
- **241-247行目**: `provideLength` メソッドでテストデータを定義
- **242行目**: 空文字列 `''` は 0
- **243行目**: `'0'` は 1
- **244行目**: `'hello'` は 5
- **249-254行目**: テスト実行メソッド

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

```
Str\length($string)
    │
    └─ \strlen($string)
           │
           └─ [PHP/HHVM内部実装]
                  └─ メモリ内サイズ情報を返す (O(1))
```

### データフロー図

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

$string (string) ───▶ length() ───▶ int (バイト数)
                          │
                          ▼
                    \strlen()
                          │
                          ▼
                    [HHVM JIT最適化]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| introspect.php | `src/str/introspect.php` | ソース | 公開API定義（バイト長） |
| introspect_l.php | `src/str/introspect_l.php` | ソース | ロケール対応実装（文字長） |
| StrIntrospectTest.php | `tests/str/StrIntrospectTest.php` | テスト | ユニットテスト |
