# 機能設計書 34-String拡張

## 概要

本ドキュメントは、mrubyのStringクラスにswapcase, concat, start_with?, end_with?, tr, center, ljust, rjust, chars, lines, upto, each_char, codepoints等の拡張メソッドを追加するgem（mruby-string-ext）の機能設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：CRuby互換のString操作メソッドを提供し、文字列処理の表現力を向上させる。大文字小文字変換、接頭辞/接尾辞判定、文字変換（tr）、パディング、文字単位操作等を利用可能にする。

**機能の利用シーン**：テキスト整形（center, ljust, rjust）、文字列検証（start_with?, end_with?）、文字単位イテレーション（each_char, chars, codepoints）、文字変換（swapcase, tr）、文字列連結（concat/<<）、範囲イテレーション（upto）等。

**主要な処理内容**：
1. 大文字小文字変換: swapcase, swapcase!（ASCII領域のみ）
2. 文字列連結: concat/<<（複数引数対応、Integer引数時はchr変換）
3. 接頭辞/接尾辞判定: start_with?, end_with?（複数パターン対応）
4. 文字変換: tr, tr!, tr_s, tr_s!（パターン構文対応）
5. 文字単位操作: each_char, chars, codepoints/each_codepoint, lines
6. パディング: center, ljust, rjust
7. バイナリ連結: append_as_bytes
8. 範囲イテレーション: upto

**関連システム・外部連携**：MRB_UTF8_STRING有効時はUTF-8エンコーディング対応。

**権限による制御**：なし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面なし |

## 機能種別

文字列操作 / データ変換処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| prefixes/suffixes | String | Yes(start/end) | チェック対象文字列（複数指定可） | Stringであること |
| pattern | String | Yes(tr) | 変換パターン | trパターン構文に従うこと |
| width | Integer | Yes(center等) | パディング幅 | 正の整数 |
| padstr | String | No(center等) | パディング文字列 | デフォルトはスペース |
| max | String | Yes(upto) | イテレーション終端 | Stringであること |

### 入力データソース

メソッド呼び出し時の引数。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| String | String | 変換結果の文字列 |
| Boolean | true/false | start_with?, end_with?の結果 |
| Array | Array | chars, codepointsの結果 |
| self | String | each_char, linesのブロック付き呼び出し結果 |

### 出力先

メソッドの戻り値。

## 処理フロー

### 処理シーケンス

```
1. swapcase: 各文字を走査し大文字⇔小文字変換（ASCII範囲のみ）
2. concat: 引数を順に連結。Integer引数はchr変換後に連結
3. start_with?: memcmpで各prefixと先頭部分を比較
4. end_with?: memcmpで各suffixと末尾部分を比較
5. tr: パターンをパースし、各文字の変換マッピングを適用
```

### フローチャート

```mermaid
flowchart TD
    A[start_with?呼び出し] --> B[各prefixを順にチェック]
    B --> C{prefix長 <= self長?}
    C -->|No| D[次のprefix]
    C -->|Yes| E{memcmp一致?}
    E -->|Yes| F[return true]
    E -->|No| D
    D --> G{全prefix処理済み?}
    G -->|No| B
    G -->|Yes| H[return false]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ASCII範囲制限 | swapcase等の大文字小文字変換はASCII範囲のみ | swapcase, swapcase! |
| BR-02 | Integer引数のchr変換 | concatのInteger引数はchr変換される | concat/<<でInteger引数時 |
| BR-03 | UTF-8対応 | MRB_UTF8_STRING有効時はUTF-8コードポイントでchr変換 | Integer引数のchr変換時 |
| BR-04 | 破壊的メソッドのnil返却 | bang!メソッドは変更がなかった場合nilを返す | swapcase! |

### 計算ロジック

- **tr**: パターン構文（`a-z`形式の範囲指定、`^`による反転）をパースし、文字マッピングテーブルを構築して一括変換

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | RangeError | chr変換でコードポイント範囲外 | "X out of char range" |
| - | TypeError | uptoの引数がStringでない | "no implicit conversion of X into String" |

### リトライ仕様

なし。

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

なし。

## パフォーマンス要件

start_with?/end_with?はO(prefix数 * prefix長)。trはO(n)（nは文字列長）。

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

なし。

## 備考

- CとRubyのハイブリッド実装（メイン処理はC、イテレーション系はRuby）
- MRB_UTF8_STRINGコンパイルフラグでUTF-8サポートが有効化される

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | string.c | `mrbgems/mruby-string-ext/src/string.c` | tr_pattern構造体（256-266行目）- trのパターン表現 |

**読解のコツ**: `RSTRING_PTR`/`RSTRING_LEN`マクロでRuby文字列のCポインタと長さを取得する。`RSTR_BINARY_P`でバイナリ文字列かどうかを判定する。

#### Step 2: C実装メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | string.c | `mrbgems/mruby-string-ext/src/string.c` | 各メソッドのC実装 |

**主要処理フロー**:
- **14-26行目**: int_chr_binary - バイナリchr変換
- **57-80行目**: str_swapcase_bang - 大文字小文字スワップ
- **121-137行目**: str_concat0 - 複数引数concat処理
- **188-209行目**: str_start_with - 接頭辞判定
- **217-240行目**: str_end_with - 接尾辞判定
- **282-351行目**: tr_parse_pattern - trパターンパース

#### Step 3: Ruby実装メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | string.rb | `mrbgems/mruby-string-ext/mrblib/string.rb` | Ruby実装のメソッド群 |

**主要処理フロー**:
- **6-13行目**: each_char - 文字単位イテレーション
- **27-34行目**: chars - 文字配列取得
- **60-70行目**: lines - 行分割
- **102-144行目**: upto - 文字列範囲イテレーション

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

```
String#メソッド
    |
    +-- [C実装]
    |   +-- str_swapcase_bang -> RSTRING_PTR走査
    |   +-- str_start_with -> memcmp
    |   +-- str_concat_m -> str_concat -> int_chr_binary/int_chr_utf8
    |   +-- tr系 -> tr_parse_pattern -> tr_find_character -> tr_get_character
    |
    +-- [Ruby実装]
        +-- each_char -> self[pos]
        +-- chars -> __chars
        +-- upto -> self.ord, max.ord, self.succ
```

### データフロー図

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

String (self) ──────▶ C/Ruby処理関数 ──────▶ 変換後String / Array / Boolean
引数 (pattern等)       文字走査・変換
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| string.c | `mrbgems/mruby-string-ext/src/string.c` | ソース(C) | C実装メソッド群 |
| string.rb | `mrbgems/mruby-string-ext/mrblib/string.rb` | ソース(Ruby) | Ruby実装メソッド群 |
| mrbgem.rake | `mrbgems/mruby-string-ext/mrbgem.rake` | 設定 | gem定義 |
| string.rb | `mrbgems/mruby-string-ext/test/string.rb` | テスト | テストケース |
