# 機能設計書 32-strutils

## 概要

本ドキュメントは、Nimプログラミング言語の文字列操作ユーティリティモジュールである`strutils`モジュールの機能設計を記載する。strutilsモジュールは文字列の分割、結合、検索、変換などの高レベルな文字列操作機能を提供する。

### 本機能の処理概要

strutilsモジュールはsystemモジュールの基本的な文字列機能を拡張し、より高度な文字列操作のためのプロシージャ、イテレータ、テンプレートを提供する。

**業務上の目的・背景**：文字列操作はほぼすべてのプログラムで必要とされる基本機能である。strutilsモジュールは、文字列の分割・結合、大文字・小文字変換、検索・置換、パディング、インデントなど、日常的なプログラミングで頻繁に使用される文字列操作を効率的に行うための関数群を提供する。

**機能の利用シーン**：
- テキストファイルの解析と処理
- ユーザー入力の検証とフォーマット
- ログメッセージの生成
- CSV等の区切り文字で分割されたデータの処理
- 文字列の正規化と比較

**主要な処理内容**：
1. 文字集合定義（Whitespace, Letters, Digits, HexDigits等）
2. 文字判定関数（isAlphaAscii, isDigit, isSpaceAscii, isLowerAscii, isUpperAscii）
3. 大文字・小文字変換（toLowerAscii, toUpperAscii, capitalizeAscii）
4. 文字列比較（cmpIgnoreCase, cmpIgnoreStyle）
5. 文字列分割（split, rsplit, splitLines, splitWhitespace）
6. 文字列結合（join）
7. 文字列検索（find, rfind, contains）
8. 文字列置換（replace, replaceWord）
9. 文字列トリミング（strip, stripLineEnd）
10. 文字列フォーマット（indent, unindent, align, repeat）

**関連システム・外部連携**：unicodeモジュールからtoLower, toUpperをインポートしてエクスポート。parseutilsモジュールを内部で使用。

**権限による制御**：権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面には関連しない（ライブラリモジュール） |

## 機能種別

文字列操作ユーティリティ / データ変換 / 文字列検証

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| s | string | Yes | 操作対象の文字列 | なし |
| c | char | No | 操作対象の文字 | なし |
| sep | char/string/set[char] | No | 分割セパレータ | なし |
| maxsplit | int | No | 最大分割数（-1で無制限） | -1以上 |

### 入力データソース

プログラム内の文字列リテラル、ファイルから読み込んだ文字列、ユーザー入力など。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変換結果 | string | 変換・操作後の文字列 |
| 判定結果 | bool | 文字・文字列判定の結果 |
| 分割結果 | seq[string] | 分割された文字列のシーケンス |
| 比較結果 | int | 比較結果（0:等しい, <0:小さい, >0:大きい） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力文字列の受け取り
   └─ 引数として文字列を受け取る
2. 処理タイプに応じた操作
   └─ 分割/結合/変換/検索/置換など
3. 結果の生成
   └─ 新しい文字列またはシーケンスを生成
4. 結果の返却
   └─ 呼び出し元に結果を返す
```

### フローチャート

```mermaid
flowchart TD
    A[入力文字列] --> B{処理タイプ}
    B -->|分割| C[split/rsplit処理]
    B -->|変換| D[toLower/toUpper処理]
    B -->|検索| E[find/contains処理]
    B -->|置換| F[replace処理]
    C --> G[結果返却]
    D --> G
    E --> G
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ASCII限定処理 | toLowerAscii, toUpperAscii等はASCII文字のみ対応 | ASCII文字 |
| BR-02 | 空セパレータ処理 | 空のセパレータは元の文字列を返す | split系関数 |
| BR-03 | 大文字小文字無視比較 | cmpIgnoreCaseはA-Zとa-zを同一視 | 比較関数 |

### 計算ロジック

- `cmpIgnoreCase(a, b)`: 両文字列を小文字に変換して比較
- `cmpIgnoreStyle(a, b)`: 両文字列を正規化（小文字化+アンダースコア除去）して比較
- `toLowerAscii(c)`: `c xor 0b00100000`（大文字のビットを反転）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

### テーブル別操作詳細

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ValueError | Exception | parseIntで数値変換失敗 | 入力値の検証 |
| IndexDefect | Defect | 空文字列へのインデックスアクセス | 長さチェック |

### リトライ仕様

リトライは不要。入力値の検証で対処。

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

トランザクション管理は不要。

## パフォーマンス要件

- 単一文字判定: O(1)
- 文字列変換: O(n) （nは文字列長）
- 文字列分割: O(n)
- 文字列検索: O(n*m) （最悪ケース、mはパターン長）

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

- ユーザー入力の処理時はバッファオーバーフローに注意
- 正規化関数使用時は意図しない文字列一致に注意

## 備考

strutilsはASCII文字を対象とした関数が多い。Unicode文字列を扱う場合はunicodeモジュールを併用すること。

---

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

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

### 推奨読解順序

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

文字集合の定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | strutils.nim | `lib/pure/strutils.nim` | 文字集合定数（91-137行目） |

**読解のコツ**: `set[char]`型は256ビットのビットセットとして実装される。文字がセットに含まれるかの判定は定数時間で行える。

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

モジュール冒頭のドキュメントとインポート文を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | strutils.nim | `lib/pure/strutils.nim` | モジュールドキュメント（10-70行目） |
| 2-2 | strutils.nim | `lib/pure/strutils.nim` | インポート文（73-88行目） |

**主要処理フロー**:
1. **73行目**: `import std/parseutils` - 低レベル解析ユーティリティのインポート
2. **79-80行目**: `from std/unicode import toLower, toUpper` - Unicode関数のインポートとエクスポート

#### Step 3: 文字判定関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | strutils.nim | `lib/pure/strutils.nim` | isAlphaAscii, isDigit等（139-203行目） |

**主要処理フロー**:
- **139-148行目**: `isAlphaAscii` - Letters集合との包含判定
- **160-167行目**: `isDigit` - Digits集合との包含判定
- **169-175行目**: `isSpaceAscii` - Whitespace集合との包含判定

#### Step 4: 大文字・小文字変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | strutils.nim | `lib/pure/strutils.nim` | toLowerAscii, toUpperAscii（205-271行目） |

**主要処理フロー**:
- **205-221行目**: `toLowerAscii(char)` - ビット演算による大文字→小文字変換
- **228-239行目**: `toLowerAscii(string)` - 文字列全体の変換
- **241-258行目**: `toUpperAscii(char)` - ビット演算による小文字→大文字変換

#### Step 5: 文字列比較を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | strutils.nim | `lib/pure/strutils.nim` | cmpIgnoreCase, cmpIgnoreStyle（335-365行目） |

**主要処理フロー**:
- **335-345行目**: `cmpIgnoreCase` - 大文字小文字無視比較
- **350-364行目**: `cmpIgnoreStyle` - スタイル無視比較（正規化比較）

#### Step 6: 文字列分割を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | strutils.nim | `lib/pure/strutils.nim` | splitCommon, split（388-538行目） |

**主要処理フロー**:
- **388-401行目**: `splitCommon` - 分割処理の共通テンプレート
- **422-450行目**: `split(char)` - 単一文字での分割
- **452-507行目**: `split(set[char])` - 文字集合での分割
- **509-538行目**: `split(string)` - 文字列での分割

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

```
strutils.nim (メインモジュール)
    │
    ├─ import std/parseutils
    │      └─ 低レベル解析ユーティリティ
    │
    ├─ from std/unicode import toLower, toUpper
    │      └─ Unicode変換関数
    │
    ├─ import std/private/strimpl
    │      └─ cmpIgnoreStyleImpl, cmpIgnoreCaseImpl
    │      └─ startsWithImpl, endsWithImpl
    │
    └─ 文字集合定義
           └─ Whitespace, Letters, Digits, HexDigits等
```

### データフロー図

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

文字列 "FooBar" ───▶  toLowerAscii()    ───▶  "foobar"

文字列 "a,b,c"  ───▶  split(',')        ───▶  @["a","b","c"]

文字 'A'        ───▶  isAlphaAscii()    ───▶  true

2文字列         ───▶  cmpIgnoreCase()   ───▶  int (0/<0/>0)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| strutils.nim | `lib/pure/strutils.nim` | ソース | メインモジュール、文字列操作関数群 |
| parseutils.nim | `lib/pure/parseutils.nim` | ソース | 低レベル解析ユーティリティ |
| unicode.nim | `lib/pure/unicode.nim` | ソース | Unicode文字列処理 |
| strimpl.nim | `lib/std/private/strimpl.nim` | ソース | 文字列比較の内部実装 |
| inclrtl.nim | `lib/system/inclrtl.nim` | ソース | ランタイムライブラリ連携 |
