# 機能設計書 25-文字列統計

## 概要

本ドキュメントは、Nushellにおける文字列統計機能の設計仕様を記述する。

### 本機能の処理概要

文字列統計機能は、文字列の長さや各種統計情報（行数、単語数、バイト数、文字数など）を取得する機能を提供する。テキスト分析、データ検証、文字列プロパティの取得において有用な基本機能である。

**業務上の目的・背景**：テキストデータの分析において、文字列のサイズや構成を把握することは重要である。ドキュメントの単語数カウント、データサイズの確認、Unicode文字の正確なカウントなど、様々な分析ニーズに対応する。特にマルチバイト文字を含むテキストでは、バイト数と文字数の違いを正確に把握することが必要となる。

**機能の利用シーン**：
- ドキュメントの単語数や行数をカウントする場合
- テキストデータのサイズを確認する場合
- 入力文字列の長さバリデーションを行う場合
- マルチバイト文字を含むテキストの正確な文字数を取得する場合

**主要な処理内容**：
1. `str length` - 文字列の長さを取得（バイト、文字、グラフィムクラスタ）
2. `str stats` - 文字列の統計情報を取得（行数、単語数、バイト数、文字数など）

**関連システム・外部連携**：特になし。Nushell内部の文字列処理として動作する。

**権限による制御**：特になし。すべてのユーザーが使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 結果表示画面 | コマンド実行結果の表示 |

## 機能種別

計算処理 / 統計分析

## 入力仕様

### 入力パラメータ

#### str length

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --grapheme-clusters / -g | Switch | No | グラフィムクラスタでカウント | - |
| --utf-8-bytes / -b | Switch | No | UTF-8バイトでカウント（デフォルト） | - |
| --chars / -c | Switch | No | Unicode文字数でカウント | - |
| rest | CellPath | No | データ構造内の対象セルパス | - |

#### str stats

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 入力文字列から統計を計算 | - |

### 入力データソース

パイプライン入力（文字列、リスト、テーブル、レコード）

## 出力仕様

### 出力データ

#### str length

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | Int | 文字列の長さ |

#### str stats

| 項目名 | 型 | 説明 |
|--------|-----|------|
| lines | Int | 行数 |
| words | Int | 単語数 |
| bytes | Int | バイト数 |
| chars | Int | Unicode文字数 |
| graphemes | Int | グラフィムクラスタ数 |
| unicode-width | Int | Unicode幅 |

### 出力先

パイプライン出力

## 処理フロー

### 処理シーケンス

```
1. パイプラインから入力値を受け取る
   └─ 文字列またはデータ構造を受け付ける
2. コマンド引数を解析する
   └─ カウントモード（バイト/文字/グラフィム）を決定
3. 文字列処理を実行
   └─ str length: 指定モードでの長さを計算
   └─ str stats: すべての統計情報を計算
4. 結果を出力する
```

### フローチャート

```mermaid
flowchart TD
    A[入力受信] --> B{コマンド種別}
    B -->|str length| C{カウントモード}
    B -->|str stats| D[全統計計算]
    C -->|grapheme-clusters| E[グラフィム単位カウント]
    C -->|chars| F[文字単位カウント]
    C -->|utf-8-bytes| G[バイト単位カウント]
    E --> H[Int出力]
    F --> H
    G --> H
    D --> I[Record出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-25-1 | デフォルトカウント | バイト単位がデフォルト（UTF-8バイト数） | str length使用時 |
| BR-25-2 | 行カウント | 末尾に改行がない場合も1行としてカウント | str stats使用時 |
| BR-25-3 | 行終端認識 | LF, CR, CRLF, NEL, FF, LS, PSを改行として認識 | str stats使用時 |
| BR-25-4 | 単語カウント | Unicode word boundary によるカウント | str stats使用時 |

### 計算ロジック

str statsで認識される行終端文字：
- LF (0x0A): ラインフィード
- CR (0x0D): キャリッジリターン
- CRLF (0x0D0A): Windows形式改行
- NEL (0x0085): Next Line
- FF (0x0C): フォームフィード
- LS (0x2028): Line Separator
- PS (0x2029): Paragraph Separator

単語カウントはunicode_segmentationクレートの`unicode_words()`を使用。

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

該当なし（メモリ内での文字列処理のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| OnlySupportsThisInputType | 型エラー | 文字列以外の型が入力された場合 | 文字列型を入力する |
| PipelineEmpty | 空入力 | 入力がない場合 | データを入力する |

### リトライ仕様

該当なし

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

該当なし（ステートレス処理）

## パフォーマンス要件

- unicode_segmentationクレートによる正確なグラフィムクラスタ処理
- unicode_widthクレートによるUnicode幅計算
- fancy_regexによる行終端検出

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

特になし

## 備考

- `str length`、`str stats`はともに定数式として評価可能（is_const = true）
- Unicode対応（グラフィムクラスタ、文字数、バイト数の区別が可能）
- 日本語、中国語などの全角文字は`unicode-width`で2としてカウント

---

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

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

### 推奨読解順序

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

統計コマンドの出力形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | stats.rs | `crates/nu-command/src/strings/str_/stats.rs` | Counter enum（223-242行目）- 統計タイプの定義 |
| 1-2 | stats.rs | `crates/nu-command/src/strings/str_/stats.rs` | ALL_COUNTERS定数（245-252行目）- 全カウンタタイプ |

**読解のコツ**: Counter enumは、計測する統計の種類（Lines, Words, Bytes, GraphemeClusters, CodePoints, UnicodeWidth）を定義。

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

コマンド実行の起点を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | length.rs | `crates/nu-command/src/strings/str_/length.rs` | `impl Command for StrLength`（22-135行目） |
| 2-2 | stats.rs | `crates/nu-command/src/strings/str_/stats.rs` | `impl Command for StrStats`（14-96行目） |

**主要処理フロー**:
1. **length.rs 71-88行目**: `run`メソッドでフラグ解析とrun関数呼び出し
2. **stats.rs 37-45行目**: `run`メソッドでstats関数呼び出し

#### Step 3: 統計計算ロジックを理解する

実際のカウント処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | length.rs | `crates/nu-command/src/strings/str_/length.rs` | action関数（153-176行目）- 長さ計算 |
| 3-2 | stats.rs | `crates/nu-command/src/strings/str_/stats.rs` | Count trait実装（179-220行目）- 各カウンタの実装 |
| 3-3 | stats.rs | `crates/nu-command/src/strings/str_/stats.rs` | counter関数（134-151行目）- レコード生成 |

**主要処理フロー**:
- **length.rs 155-163行目**: graphemes/chars/バイト数の分岐
- **stats.rs 182-183行目**: グラフィムクラスタカウント
- **stats.rs 184-213行目**: 行数カウント（改行パターン認識）
- **stats.rs 215行目**: 単語カウント（unicode_words）

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

```
StrLength::run / StrStats::run
    │
    ├─ call.has_flag()
    │      └─ graphemes / chars / utf-8-bytes フラグ解析
    │
    └─ operate() / stats()
           │
           └─ action() / counter()
                  │
                  ├─ val.graphemes(true).count() - グラフィムクラスタ
                  ├─ val.chars().count() - Unicode文字数
                  ├─ val.len() - バイト数
                  │
                  └─ uwc_count() - 全統計計算
                         ├─ Counter::Lines - 行数
                         ├─ Counter::Words - 単語数
                         ├─ Counter::Bytes - バイト数
                         ├─ Counter::CodePoints - コードポイント数
                         ├─ Counter::GraphemeClusters - グラフィム数
                         └─ Counter::UnicodeWidth - Unicode幅
```

### データフロー図

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

String ───▶ str length ───▶ Int
   │             │
   │             └─ バイト/文字/グラフィム選択
   │
   └───────▶ str stats ───▶ Record
                  │           │
                  │           ├─ lines: Int
                  │           ├─ words: Int
                  │           ├─ bytes: Int
                  └─ uwc_count ├─ chars: Int
                              ├─ graphemes: Int
                              └─ unicode-width: Int
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| length.rs | `crates/nu-command/src/strings/str_/length.rs` | ソース | str length コマンド実装 |
| stats.rs | `crates/nu-command/src/strings/str_/stats.rs` | ソース | str stats コマンド実装 |
| mod.rs | `crates/nu-command/src/strings/str_/mod.rs` | ソース | str_モジュール定義 |
