# 機能設計書 82-型変換

## 概要

本ドキュメントは、Nushellの型変換（into）コマンド群の機能設計について記述する。これらのコマンドは、様々なデータ型間の明示的な変換を提供し、データ処理パイプラインにおける型の柔軟な操作を可能にする。

### 本機能の処理概要

intoコマンド群は、Nushellの各種データ型（int, float, string, bool, binary, datetime, duration, filesize, record, cell-path, glob）間の相互変換を行う機能を提供する。各サブコマンドは特定の出力型への変換を担当し、入力データの型に応じた適切な変換ロジックを実行する。

**業務上の目的・背景**：シェル環境でのデータ処理では、異なるコマンドの出力を連携させる際に型の不一致が発生することがある。明示的な型変換機能を提供することで、データパイプラインの柔軟性を向上させ、ユーザーが意図した形式でデータを操作できるようにする。また、外部データソース（JSONやCSV）からの入力データを適切な内部型に変換する際にも重要な役割を果たす。

**機能の利用シーン**：文字列から数値への変換（計算処理前）、数値から文字列への変換（表示整形時）、日時データのUnixタイムスタンプ変換、バイナリデータと整数の相互変換、ファイルサイズから数値への変換など、データ型の変更が必要なあらゆる場面で利用される。

**主要な処理内容**：
1. 入力値の型判定
2. 変換対象セルパスの処理（テーブル・レコード内の特定フィールド変換）
3. 型固有の変換ロジック実行（パース、キャスト、フォーマット）
4. エラーハンドリング（変換不可能な値の処理）
5. 変換結果の出力

**関連システム・外部連携**：なし（スタンドアロン機能）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIコマンドとして実行 |

## 機能種別

データ変換 / 型キャスト

## 入力仕様

### 入力パラメータ

#### into int

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --radix (-r) | Number | No | 進数（2-36） | 2-36の範囲 |
| --endian (-e) | String | No | バイトオーダー（native/little/big） | 指定値のみ |
| --signed (-s) | Switch | No | 符号付きとして扱う | - |
| rest | CellPath | No | 変換対象のセルパス | - |

#### into string

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --decimals (-d) | Int | No | 小数点以下桁数 | - |
| rest | CellPath | No | 変換対象のセルパス | - |

#### into float

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| rest | CellPath | No | 変換対象のセルパス | - |

#### into bool

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| rest | CellPath | No | 変換対象のセルパス | - |

### 入力データソース

- パイプライン入力（各種型）
- 変換元として対応する型はサブコマンドによって異なる

## 出力仕様

### 出力データ

| サブコマンド | 出力型 | 説明 |
|--------|-----|------|
| into int | Int | 整数値 |
| into float | Float | 浮動小数点数 |
| into string | String | 文字列 |
| into bool | Bool | 真偽値 |
| into binary | Binary | バイナリデータ |
| into datetime | Date | 日時 |
| into duration | Duration | 期間 |
| into filesize | Filesize | ファイルサイズ |
| into record | Record | レコード |
| into cell-path | CellPath | セルパス |
| into glob | Glob | Globパターン |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの解析
   └─ radix, endian, signed等のオプション取得
2. セルパスの処理
   └─ 指定があれば対象フィールドのみ変換
3. 入力値の型判定
   └─ match式で入力型を特定
4. 型固有の変換ロジック実行
   └─ パース、キャスト、フォーマット処理
5. エラー処理
   └─ 変換不可の場合はShellError返却
6. 結果出力
   └─ 変換後の値をパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{セルパス指定?}
    B -->|Yes| C[operate関数でセルパス処理]
    B -->|No| D[入力値を直接処理]
    C --> E{入力型判定}
    D --> E
    E -->|String| F[文字列パース]
    E -->|Int| G[整数キャスト]
    E -->|Float| H[浮動小数点キャスト]
    E -->|Date| I[日時変換]
    E -->|Binary| J[バイナリ変換]
    E -->|Other| K[型固有処理]
    F --> L{変換成功?}
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    L -->|Yes| M[変換後の値を出力]
    L -->|No| N[エラー返却]
    M --> O[終了]
    N --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-82-01 | 進数指定範囲 | radixは2から36の範囲 | into int使用時 |
| BR-82-02 | バイナリサイズ制限 | バイナリからintへの変換は8バイトまで | into int使用時 |
| BR-82-03 | 日時範囲制限 | 1677-09-21から2262-04-11の範囲 | into int（日時入力時） |
| BR-82-04 | 文字列パース | 0x, 0b, 0oプレフィックスで16/2/8進数 | into int（文字列入力時） |

### 計算ロジック

**into int（日時）**: `datetime.timestamp_nanos()` - Unixエポックからのナノ秒
**into int（バイナリ）**: バイトオーダーに従ってi64に変換
**into float**: 内部的にf64への直接キャスト
**into duration**: ナノ秒単位の整数値として保持

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

該当なし（メモリ内変換のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TypeMismatch | 型不一致 | radixが範囲外 | 2-36の値を指定 |
| CantConvert | 変換不可 | パース失敗 | 正しい形式の入力を使用 |
| IncorrectValue | 不正値 | 日時が範囲外 | 有効な日時範囲を使用 |
| IncorrectValue | 不正値 | バイナリが8バイト超 | 8バイト以下のデータを使用 |
| OnlySupportsThisInputType | 非対応入力 | 変換不可能な型 | 対応する型を使用 |

### リトライ仕様

該当なし

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

該当なし（純粋関数的処理）

## パフォーマンス要件

- 単一値の変換はO(1)
- リスト変換はO(n)
- セルパス指定時はアクセスコストを含む

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

特になし

## 備考

- nu_cmd_base::input_handler::operateを使用してセルパス処理を統一
- ロケール設定に応じた数値パース（桁区切り文字の処理）

---

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

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

### 推奨読解順序

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

型変換機能は各サブコマンドで共通のパターンを使用する。まず親コマンドと共通構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.rs | `crates/nu-command/src/conversions/into/command.rs` | Intoコマンド（親コマンド）の定義 |
| 1-2 | mod.rs | `crates/nu-command/src/conversions/into/mod.rs` | サブコマンドのエクスポート一覧 |

**読解のコツ**: 親コマンド`into`はヘルプ表示のみを行い、実際の変換は各サブコマンドが担当する。

#### Step 2: 代表的なサブコマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | int.rs | `crates/nu-command/src/conversions/into/int.rs` | into intの実装（最も複雑） |

**主要処理フロー**:
1. **23-91行目**: シグネチャ定義（radix, endian, signed等のオプション）
2. **101-163行目**: runメソッドでのパラメータ解析
3. **244-379行目**: action関数での型別変換ロジック
4. **381-440行目**: convert_int関数での進数変換
5. **442-511行目**: int_from_string関数での文字列パース

#### Step 3: 他のサブコマンドパターンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | string.rs | `crates/nu-command/src/conversions/into/string.rs` | 文字列変換 |
| 3-2 | float.rs | `crates/nu-command/src/conversions/into/float.rs` | 浮動小数点変換 |
| 3-3 | bool.rs | `crates/nu-command/src/conversions/into/bool.rs` | 真偽値変換 |
| 3-4 | datetime.rs | `crates/nu-command/src/conversions/into/datetime.rs` | 日時変換 |

**共通パターン**:
- CmdArgumentトレイトの実装でセルパス処理を統一
- operate関数で変換ロジックを適用
- match式で入力型ごとの処理を分岐

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

```
IntoInt::run()
    │
    ├─ call.rest() / call.get_flag()
    │      └─ パラメータ解析
    │
    └─ operate(action, args, input, ...)
           │
           ├─ CmdArgument::take_cell_paths()
           │      └─ セルパス取得
           │
           └─ action(&Value, &Arguments, Span)
                  │
                  ├─ match input型
                  │      ├─ Value::String => int_from_string()
                  │      ├─ Value::Float => val as i64
                  │      ├─ Value::Bool => 0 or 1
                  │      ├─ Value::Date => timestamp_nanos()
                  │      ├─ Value::Binary => ByteOrder::read_*()
                  │      └─ ...
                  │
                  └─ Value::int(result, span)
```

### データフロー図

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

各種Value ───▶ 型判定 ───▶ 変換ロジック ───▶ 目的型Value
  "123"          ↓              ↓                   123 (Int)
  true       String→        パース
  45.6       Float→         キャスト
  0x[ff]     Binary→        バイトオーダー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.rs | `crates/nu-command/src/conversions/into/command.rs` | ソース | 親コマンド定義 |
| mod.rs | `crates/nu-command/src/conversions/into/mod.rs` | ソース | モジュールエクスポート |
| int.rs | `crates/nu-command/src/conversions/into/int.rs` | ソース | into int実装 |
| float.rs | `crates/nu-command/src/conversions/into/float.rs` | ソース | into float実装 |
| string.rs | `crates/nu-command/src/conversions/into/string.rs` | ソース | into string実装 |
| bool.rs | `crates/nu-command/src/conversions/into/bool.rs` | ソース | into bool実装 |
| binary.rs | `crates/nu-command/src/conversions/into/binary.rs` | ソース | into binary実装 |
| datetime.rs | `crates/nu-command/src/conversions/into/datetime.rs` | ソース | into datetime実装 |
| duration.rs | `crates/nu-command/src/conversions/into/duration.rs` | ソース | into duration実装 |
| filesize.rs | `crates/nu-command/src/conversions/into/filesize.rs` | ソース | into filesize実装 |
| record.rs | `crates/nu-command/src/conversions/into/record.rs` | ソース | into record実装 |
| cell_path.rs | `crates/nu-command/src/conversions/into/cell_path.rs` | ソース | into cell-path実装 |
| glob.rs | `crates/nu-command/src/conversions/into/glob.rs` | ソース | into glob実装 |
| value.rs | `crates/nu-command/src/conversions/into/value.rs` | ソース | into value実装 |
