# 機能設計書 78-数列生成

## 概要

本ドキュメントは、Nushellの数列生成機能の設計仕様を定義する。seq、seq date、seq charコマンドは、数値・日付・文字のシーケンスを生成する機能を提供する。

### 本機能の処理概要

数列生成機能は、指定された範囲と増分に基づいて、数値、日付、文字のシーケンスを生成する機能群である。ListStreamとして遅延生成され、大きなシーケンスでもメモリ効率が良い。

**業務上の目的・背景**：連続した数値や日付のリストを生成することは、ループ処理、日付範囲の処理、テストデータ生成など多くの場面で必要となる。本機能により、これらのシーケンスを簡潔に生成できる。

**機能の利用シーン**：
- 1から100までの連続数値を生成したい場合
- 特定の日付範囲を生成したい場合
- アルファベットのシーケンスを生成したい場合
- 浮動小数点数の範囲を指定増分で生成したい場合

**主要な処理内容**：
1. `seq`：数値シーケンスを生成（整数または浮動小数点）
2. `seq date`：日付シーケンスを生成（フォーマット指定可能）
3. `seq char`：ASCII文字シーケンスを生成

**関連システム・外部連携**：
- chronoクレート：日付処理
- nu-protocol::ListStream：遅延リスト生成

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

## 関連画面

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

## 機能種別

シーケンス生成機能

## 入力仕様

### 入力パラメータ

#### seq

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| rest | Number... | Yes | シーケンス値（1〜3個） | 空でないこと |

引数のパターン：
- 1個: `seq end` → 1からendまで
- 2個: `seq start end` → startからendまで
- 3個: `seq start step end` → startからendまでstep刻み

#### seq date

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --output-format (-o) | String | No | 出力日付フォーマット（デフォルト: %Y-%m-%d） | - |
| --input-format (-i) | String | No | 入力日付フォーマット（デフォルト: %Y-%m-%d） | - |
| --begin-date (-b) | String | No | 開始日付 | - |
| --end-date (-e) | String | No | 終了日付 | - |
| --increment (-n) | Duration/Int | No | 増分（デフォルト: 1day） | 0以外 |
| --days (-d) | Int | No | 日数（--periodsで上書き） | - |
| --periods (-p) | Int | No | ピリオド数 | - |
| --reverse (-r) | switch | No | 逆順で生成 | - |

#### seq char

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| start | String | Yes | 開始文字（ASCII 1文字） | ASCII 1文字 |
| end | String | Yes | 終了文字（ASCII 1文字） | ASCII 1文字 |

### 入力データソース

コマンド引数のみ（パイプライン入力なし）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| seq出力 | List<Number> | 数値のリスト（IntまたはFloat） |
| seq date出力 | List<String> | 日付文字列のリスト |
| seq char出力 | List<String> | 文字のリスト |

### 出力先

標準出力（パイプライン出力）

## 処理フロー

### 処理シーケンス

```
1. seq コマンド
   └─ 引数を解析（first, step, last）
   └─ 浮動小数点を含むか判定
   └─ IntSeqまたはFloatSeqイテレータを作成
   └─ ListStreamとして返却

2. seq date コマンド
   └─ 引数とフラグを解析
   └─ 開始日・終了日を計算
   └─ 増分で日付をインクリメント
   └─ フォーマットして文字列リストを返却

3. seq char コマンド
   └─ 開始文字・終了文字を検証（ASCII 1文字）
   └─ 範囲を計算（昇順/降順）
   └─ 文字リストを返却
```

### フローチャート

```mermaid
flowchart TD
    A[seq コマンド群] --> B{サブコマンド?}

    B -->|seq| C[引数解析]
    C --> D{引数数?}
    D -->|1個| E[first=1, step=1, last=arg]
    D -->|2個| F[first=arg1, step=1, last=arg2]
    D -->|3個| G[first=arg1, step=arg2, last=arg3]
    E --> H{浮動小数点含む?}
    F --> H
    G --> H
    H -->|Yes| I[FloatSeq作成]
    H -->|No| J[IntSeq作成]
    I --> K[ListStream返却]
    J --> K

    B -->|seq date| L[日付オプション解析]
    L --> M[開始日決定]
    M --> N[終了日決定]
    N --> O[増分でループ]
    O --> P[フォーマット出力]

    B -->|seq char| Q[文字検証]
    Q --> R{昇順/降順?}
    R -->|昇順| S[start..=endをイテレート]
    R -->|降順| T[end..=startを逆順イテレート]
    S --> U[文字リスト返却]
    T --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-78-1 | 整数/浮動小数点判定 | 入力に浮動小数点が含まれる場合、出力も浮動小数点 | seq実行時 |
| BR-78-2 | 日付増分デフォルト | --incrementが整数の場合は日数として扱う | seq date実行時 |
| BR-78-3 | periods優先 | --periodsと--daysが両方指定された場合、--periodsが優先 | seq date実行時 |
| BR-78-4 | ASCII制限 | seq charはASCII 1文字のみ受け付ける | seq char実行時 |
| BR-78-5 | 遅延評価 | seqはListStreamで遅延評価される | seq実行時 |

### 計算ロジック

#### seq

```
IntSeq:
  count = first
  while (step >= 0 && count <= last) || (step <= 0 && count >= last):
    yield count
    count += step

FloatSeq:
  index = 0
  while True:
    count = first + index * step
    if (step >= 0 && count > last) || (step <= 0 && count < last): break
    yield count
    index += 1
```

#### seq date

```
step_size = increment (ナノ秒)
next = start_date
while !is_out_of_range(next):
  yield format(next, out_format)
  next += step_size
```

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | GenericError | seq に引数がない | 引数を指定する |
| - | GenericError | seq date の increment が 0 | 0以外を指定 |
| - | GenericError | seq date の increment が大きすぎる | 範囲内の値を指定 |
| - | GenericError | seq char の引数が ASCII 1文字でない | ASCII 1文字を指定 |
| - | GenericError | seq date の日付パース失敗 | 正しいフォーマットを指定 |
| - | GenericError | seq date の日付範囲外 | 有効な日付範囲を指定 |
| - | GenericError | seq date の日付オーバーフロー | より小さな範囲を指定 |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- seqはListStreamによる遅延評価でメモリ効率を確保
- 大きな範囲でも開始時のメモリ消費は最小限

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

特になし

## 備考

- seqの浮動小数点計算は精度を最大限確保するため、毎回基準値から計算
- seq dateのデフォルト日付フォーマットは%Y-%m-%d
- seq charは昇順・降順両方に対応

---

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

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

### 推奨読解順序

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

イテレータ構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | seq.rs | `crates/nu-command/src/generators/seq.rs` | IntSeq、FloatSeq構造体（151-191行目） |

**読解のコツ**: IntSeqとFloatSeqはIteratorトレイトを実装し、ListStreamに渡される。FloatSeqはインデックスベースで精度を保つ。

#### Step 2: 各コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | seq.rs | `crates/nu-command/src/generators/seq.rs` | seqコマンド - 引数解析と分岐 |
| 2-2 | seq_date.rs | `crates/nu-command/src/generators/seq_date.rs` | seq dateコマンド - 日付処理 |
| 2-3 | seq_char.rs | `crates/nu-command/src/generators/seq_char.rs` | seq charコマンド - 文字処理 |

**主要処理フロー** (seq.rs):
- **89-110行目**: 引数の解析（rest_nums）
- **95-96行目**: 浮動小数点判定
- **113-149行目**: run_seq関数 - IntSeq/FloatSeqの選択と生成

**主要処理フロー** (seq_date.rs):
- **187-274行目**: run関数 - 各フラグの処理
- **288-312行目**: 開始日・終了日の計算
- **388-393行目**: --periodsと--daysの優先度処理
- **447-477行目**: 日付のループと出力

**主要処理フロー** (seq_char.rs):
- **72-116行目**: seq_char関数 - 文字検証と実行
- **118-139行目**: run_seq_char関数 - 範囲生成

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

```
Seq::run (seq.rs)
    └─ seq()
           ├─ 引数解析
           └─ run_seq()
                  ├─ contains_decimals判定
                  └─ ListStream::new()
                         ├─ IntSeq (整数)
                         └─ FloatSeq (浮動小数点)

SeqDate::run (seq_date.rs)
    └─ run_seq_dates()
           ├─ parse_date_string()
           ├─ 開始日/終了日計算
           └─ ループ + format

SeqChar::run (seq_char.rs)
    └─ seq_char()
           ├─ is_single_character()
           └─ run_seq_char()
                  └─ 範囲イテレーション
```

### データフロー図

```
[seq]
引数 (Number...) ───▶ first/step/last ───▶ IntSeq/FloatSeq ───▶ ListStream

[seq date]
フラグ ───▶ 開始日/終了日/増分 ───▶ ループ ───▶ List<String>

[seq char]
start, end ───▶ 範囲計算 ───▶ List<String>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| seq.rs | `crates/nu-command/src/generators/seq.rs` | ソース | seqコマンド |
| seq_date.rs | `crates/nu-command/src/generators/seq_date.rs` | ソース | seq dateコマンド |
| seq_char.rs | `crates/nu-command/src/generators/seq_char.rs` | ソース | seq charコマンド |
| mod.rs | `crates/nu-command/src/generators/mod.rs` | ソース | generatorsモジュール定義 |
