# 機能設計書 34-unicode

## 概要

本ドキュメントは、NimプログラミングのUnicode UTF-8エンコーディングサポートモジュールである`unicode`モジュールの機能設計を記載する。unicodeモジュールはUTF-8エンコードされた文字列の操作とRune（Unicodeコードポイント）の処理機能を提供する。

### 本機能の処理概要

unicodeモジュールはUTF-8エンコーディングでの文字列処理を可能にし、マルチバイト文字を正しく扱うための機能を提供する。Rune型を通じてUnicodeコードポイント単位での操作が可能。

**業務上の目的・背景**：グローバル化したソフトウェア開発では、日本語、中国語、アラビア語など様々な言語の文字を正しく処理する必要がある。unicodeモジュールは、UTF-8エンコードされた文字列を文字単位（Rune単位）で正しく操作するための機能を提供し、国際化対応アプリケーションの開発を支援する。

**機能の利用シーン**：
- 多言語対応アプリケーションの開発
- 日本語テキストの処理
- 文字数カウント（バイト数ではなく文字数）
- 大文字・小文字変換（Unicode対応）
- テキストエディタの文字操作

**主要な処理内容**：
1. Rune型の定義（Unicodeコードポイントを表す型）
2. UTF-8エンコード/デコード（toUTF8, runeAt, fastRuneAt）
3. 文字数カウント（runeLen, runeLenAt）
4. 文字列の部分取得（runeSubStr, runeOffset）
5. 大文字・小文字変換（toLower, toUpper, toTitle）
6. 文字種判定（isLower, isUpper, isAlpha, isTitle, isWhiteSpace）
7. UTF-8バリデーション（validateUtf8）
8. Rune比較演算子（==, <%, <=%）

**関連システム・外部連携**：unicode_rangesインクルードファイルでUnicode文字範囲テーブルを使用。

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

## 関連画面

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

## 機能種別

文字エンコーディング / 文字列処理 / 国際化対応

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| s | string/openArray[char] | Yes | UTF-8エンコードされた文字列 | validateUtf8で検証可能 |
| c | Rune | No | Unicodeコードポイント | int32範囲内 |
| i | int/Natural | No | バイト位置またはRune位置 | 範囲内チェック |

### 入力データソース

UTF-8エンコードされた文字列データ。ファイル、ネットワーク、ユーザー入力など。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Rune | Rune | Unicodeコードポイント |
| UTF-8文字列 | string | エンコードされた文字列 |
| 文字数 | int | Rune単位の文字数 |
| バイト位置 | int | UTF-8バイト位置 |
| 判定結果 | bool | 文字種判定の結果 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. UTF-8バイト列の受け取り
   └─ 文字列として入力を受け取る
2. バイト列の解析
   └─ UTF-8のバイトパターンを判定
3. Runeへの変換
   └─ バイト列をコードポイントに変換
4. 処理の実行
   └─ 変換/判定/検索などの処理
5. 結果の返却
   └─ Rune、文字列、または判定結果を返す
```

### フローチャート

```mermaid
flowchart TD
    A[UTF-8文字列入力] --> B{先頭バイトの判定}
    B -->|0xxxxxxx| C[1バイト文字 ASCII]
    B -->|110xxxxx| D[2バイト文字]
    B -->|1110xxxx| E[3バイト文字]
    B -->|11110xxx| F[4バイト文字]
    C --> G[Rune生成]
    D --> G
    E --> G
    F --> G
    G --> H[処理実行]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | UTF-8エンコーディング | 文字列はUTF-8でエンコードされている前提 | すべての関数 |
| BR-02 | 不正バイトの置換 | 不正なUTF-8バイト列はU+FFFD（置換文字）に変換 | fastRuneAt |
| BR-03 | Unicode 12.0.0互換 | Unicode標準バージョン12.0.0に準拠 | 文字種判定 |

### 計算ロジック

UTF-8エンコーディングのバイトパターン:
- 1バイト: `0xxxxxxx` (U+0000-U+007F, ASCII)
- 2バイト: `110xxxxx 10xxxxxx` (U+0080-U+07FF)
- 3バイト: `1110xxxx 10xxxxxx 10xxxxxx` (U+0800-U+FFFF)
- 4バイト: `11110xxx 10xxxxxx 10xxxxxx 10xxxxxx` (U+10000-U+10FFFF)

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

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 置換文字返却 | 不正なUTF-8バイト列 | U+FFFD (replRune)を返す |
| - | -1返却 | runeOffsetで範囲外 | 戻り値のチェック |

### リトライ仕様

リトライは不要。不正入力は置換文字で対処。

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

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

## パフォーマンス要件

- runeLen: O(n) - 文字列を走査
- runeLenAt: O(1) - 1バイト目から判定
- runeAt: O(1) - 直接アクセス
- runeAtPos: O(n) - バイト位置を計算（非推奨）

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

- 不正なUTF-8バイト列による攻撃に対してvalidateUtf8で検証可能
- オーバーロングエンコーディングを検出（0xC0, 0xC1で始まる2バイト列）

## 備考

runeAtPosやruneSubStrは位置計算のためO(n)の処理が必要。パフォーマンスが重要な場合はイテレータの使用を推奨。

---

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

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

### 推奨読解順序

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

Rune型の定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | unicode.nim | `lib/pure/unicode.nim` | Rune型定義（35-41行目） |

**読解のコツ**: RuneはRuneImpl（int32）のdistinct型。これによりUnicodeコードポイント（0〜0x10FFFF）を表現できる。

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

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

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

**主要処理フロー**:
1. **10行目**: UTF-8エンコーディングサポートの宣言
2. **16行目**: Unicode v12.0.0との互換性表明

#### Step 3: UTF-8デコードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | unicode.nim | `lib/pure/unicode.nim` | fastRuneAtテンプレート（84-160行目） |
| 3-2 | unicode.nim | `lib/pure/unicode.nim` | runeAt関数（162-174行目） |

**主要処理フロー**:
- **90-92行目**: 1バイト文字（ASCII）の処理
- **93-101行目**: 2バイト文字の処理
- **102-112行目**: 3バイト文字の処理
- **113-125行目**: 4バイト文字の処理

#### Step 4: 文字数カウントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | unicode.nim | `lib/pure/unicode.nim` | runeLen（45-62行目） |
| 4-2 | unicode.nim | `lib/pure/unicode.nim` | runeLenAt（64-80行目） |

**主要処理フロー**:
- **52-62行目**: 各バイトパターンに応じてインクリメント量を決定
- **74-80行目**: 先頭バイトから文字のバイト長を判定

#### Step 5: UTF-8バリデーションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | unicode.nim | `lib/pure/unicode.nim` | validateUtf8（176-205行目） |

**主要処理フロー**:
- **187-192行目**: 1-2バイト文字の検証
- **193-202行目**: 3-4バイト文字の検証
- **190行目**: オーバーロングエンコーディングの検出

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | unicode.nim | `lib/pure/unicode.nim` | toLower（482-498行目） |
| 6-2 | unicode.nim | `lib/pure/unicode.nim` | toUpper（500行目以降） |

**主要処理フロー**:
- **467-480行目**: binarySearch関数 - 変換テーブルの二分探索
- **491-498行目**: toLower - toLowerRanges/toLowerSingletsテーブルを使用

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

```
unicode.nim (メインモジュール)
    │
    ├─ Rune型定義
    │      └─ distinct int32
    │
    ├─ UTF-8デコード
    │      ├─ fastRuneAt (テンプレート)
    │      └─ runeAt
    │
    ├─ 文字数カウント
    │      ├─ runeLen
    │      └─ runeLenAt
    │
    ├─ 部分文字列
    │      ├─ runeOffset
    │      └─ runeSubStr
    │
    ├─ 大文字・小文字変換
    │      ├─ toLower (binarySearch使用)
    │      └─ toUpper (binarySearch使用)
    │
    └─ include "includes/unicode_ranges"
           └─ toLowerRanges, toUpperRanges等
```

### データフロー図

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

UTF-8バイト列   ───▶  fastRuneAt          ───▶  Rune (int32)
"あ" (E3 81 82)        (バイトパターン解析)        (0x3042)

Rune            ───▶  toUTF8              ───▶  UTF-8バイト列
(0x3042)               (エンコード)               "あ" (E3 81 82)

UTF-8文字列     ───▶  runeLen             ───▶  文字数
"あいう"               (バイト走査)               3
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| unicode.nim | `lib/pure/unicode.nim` | ソース | メインモジュール、Rune型、UTF-8処理 |
| unicode_ranges.nim | `lib/pure/includes/unicode_ranges.nim` | インクルード | Unicode文字範囲テーブル（大文字小文字変換等） |
| strbasics.nim | `lib/std/strbasics.nim` | ソース | 文字列基本操作 |
| inclrtl.nim | `lib/system/inclrtl.nim` | ソース | ランタイムライブラリ連携 |
