# 機能設計書 31-system

## 概要

本ドキュメントは、Nimプログラミング言語の中核モジュールである`system`モジュールの機能設計を記載する。systemモジュールはすべてのNimモジュールに暗黙的にインポートされる基盤モジュールであり、基本型、演算子、メモリ管理機能を提供する。

### 本機能の処理概要

systemモジュールはNimコンパイラと密接に連携し、言語の基本機能を実現するための型、プロシージャ、演算子を提供する。

**業務上の目的・背景**：systemモジュールはNimプログラムの実行に必要不可欠な基盤機能を提供する。整数・浮動小数点・文字列などの基本型定義、メモリ管理（ガベージコレクション連携）、例外処理の基盤、配列・シーケンスなどのコレクション型の基本操作を担う。このモジュールがなければNimプログラムは動作しない。

**機能の利用シーン**：すべてのNimプログラムで自動的に利用される。明示的なインポートは不要であり、ユーザーはsystemモジュールの機能を意識せずに利用できる。変数宣言、算術演算、文字列操作、配列・シーケンス操作、例外処理など、あらゆる場面で利用される。

**主要な処理内容**：
1. 基本型（int, float, bool, char, string, seq, array, set）の定義
2. 算術演算子（+, -, *, /, mod, div）の実装
3. 比較演算子（==, !=, <, >, <=, >=）の実装
4. メモリ管理機能（new, alloc, dealloc, =destroy, =sink, =copy）
5. シーケンス操作（add, del, insert, len, high, low）
6. 文字列操作の基本機能（len, &, add）
7. 例外処理基盤（Exception, raise, try-except）
8. 型情報・型変換機能（typeof, is, ord, chr）
9. スライス操作（.., contains, in, notin）
10. イテレータ基盤（items, pairs）

**関連システム・外部連携**：Nimコンパイラと直接連携し、マジックプロシージャ（{.magic.}）を通じてコンパイラ組み込み機能を呼び出す。C/C++バックエンド、JavaScriptバックエンドと連携してネイティブコードを生成する。

**権限による制御**：権限による制御は存在しない。すべてのNimプログラムで利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面には関連しない（言語基盤モジュール） |

## 機能種別

ライブラリ基盤機能 / 型定義 / 演算子実装 / メモリ管理 / 例外処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| T | typedesc | Yes | ジェネリック型パラメータ | コンパイル時型チェック |
| x | any | No | 各種プロシージャへの入力値 | プロシージャ依存 |

### 入力データソース

ソースコード上のリテラル値、変数、式の評価結果がsystemモジュールの各プロシージャに渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 基本型値 | int/float/bool/char/string | 演算結果・変換結果 |
| コレクション | seq[T]/array[I,T]/set[T] | コレクション操作結果 |
| 参照 | ref T/ptr T | メモリ割り当て結果 |

### 出力先

メモリ上の変数、ヒープ領域、スタック領域

## 処理フロー

### 処理シーケンス

```
1. 型定義・初期化
   └─ 基本型とジェネリック型の定義をコンパイラに登録
2. 演算子解決
   └─ 式中の演算子をsystemモジュールのプロシージャにマッピング
3. メモリ管理
   └─ オブジェクト生成時にnew/allocを呼び出し、破棄時に=destroyを呼び出し
4. 例外処理
   └─ raise文でException派生型を投げ、try-exceptでキャッチ
```

### フローチャート

```mermaid
flowchart TD
    A[Nimソースコード] --> B{式の解析}
    B -->|型定義| C[type宣言処理]
    B -->|演算| D[演算子プロシージャ呼び出し]
    B -->|メモリ操作| E[new/alloc/dealloc]
    B -->|例外| F[raise/try-except]
    C --> G[コンパイル結果]
    D --> G
    E --> G
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 暗黙的インポート | systemモジュールは明示的importなしで利用可能 | すべてのNimモジュール |
| BR-02 | マジックプロシージャ | {.magic.}プラグマ付きプロシージャはコンパイラ組み込み | コンパイル時 |
| BR-03 | ライフサイクル管理 | =destroy, =sink, =copyで値のライフサイクルを制御 | ARC/ORC GC使用時 |

### 計算ロジック

- `high(T)`: 型Tの最大値を返す（整数型の場合、ビット幅に基づく）
- `low(T)`: 型Tの最小値を返す
- `len(s)`: シーケンス/配列/文字列の要素数を返す
- `ord(x)`: 文字または列挙型の内部整数値を返す
- `chr(i)`: 整数値0-255を文字に変換

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

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IndexDefect | Defect | 配列/シーケンスの範囲外アクセス | インデックスの範囲チェック |
| RangeDefect | Defect | 範囲型への範囲外値代入 | 値の範囲チェック |
| OverflowDefect | Defect | 整数オーバーフロー | 計算前の範囲確認 |
| DivByZeroDefect | Defect | ゼロ除算 | 除数のゼロチェック |
| NilAccessDefect | Defect | nil参照へのアクセス | nil判定の実施 |
| OutOfMemDefect | Defect | メモリ不足 | メモリ使用量の最適化 |

### リトライ仕様

Defectは回復不能なエラーであり、リトライは想定されない。

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

トランザクション管理は行わない（メモリ操作レベルの処理）。

## パフォーマンス要件

- 基本演算子は定数時間O(1)で実行
- シーケンスのadd操作は償却定数時間
- メモリアロケーションはGCの実装に依存

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

- `addr`/`unsafeAddr`は安全でないメモリアクセスを許可するため、使用には注意が必要
- `UncheckedArray`は境界チェックを行わないため、バッファオーバーフローのリスクがある
- `cast`による強制型変換は型安全性を破壊する可能性がある

## 備考

systemモジュールはNim言語の心臓部であり、コンパイラのバージョンアップに伴い変更される可能性がある。

---

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

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

### 推奨読解順序

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

基本型定義とジェネリック型の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | system.nim | `lib/system.nim` | 基本型（static, type, Ordinal）の定義（39-96行目） |
| 1-2 | basic_types.nim | `lib/system/basic_types.nim` | int, float, bool, charなどの基本型定義 |

**読解のコツ**: `{.magic.}`プラグマはコンパイラ組み込み機能を示す。これらのプロシージャは実装が空でもコンパイラが特別に処理する。

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

systemモジュールは暗黙的にインポートされるため、エントリーポイントはモジュール全体。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | system.nim | `lib/system.nim` | モジュール冒頭のドキュメントコメント（10-22行目） |

**主要処理フロー**:
1. **25行目**: `include "system/basic_types"` - 基本型定義を読み込み
2. **34行目**: `include "system/compilation"` - コンパイル情報を読み込み
3. **452行目**: `include "system/arithmetics"` - 算術演算子を読み込み
4. **453行目**: `include "system/comparisons"` - 比較演算子を読み込み
5. **738行目**: `include "system/setops"` - 集合演算子を読み込み

#### Step 3: メモリ管理機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | system.nim | `lib/system.nim` | new, =destroy, =sink, =copy, move（131-414行目） |

**主要処理フロー**:
- **161-172行目**: `=wasMoved`と`move`プロシージャ - 値の移動セマンティクス
- **385-406行目**: `=destroy`と`=dup` - デストラクタとコピー
- **408-413行目**: `=sink` - ムーブ代入

#### Step 4: 配列・シーケンス操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | system.nim | `lib/system.nim` | high, low, len, newSeq（205-712行目） |

**主要処理フロー**:
- **205-265行目**: `high`プロシージャ群 - 最大インデックス取得
- **283-357行目**: `low`プロシージャ群 - 最小インデックス取得
- **611-660行目**: `newSeq`, `newSeqOfCap` - シーケンス生成
- **662-712行目**: `len`プロシージャ群 - 長さ取得

#### Step 5: スライスと包含チェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | system.nim | `lib/system.nim` | HSlice, Slice, contains, in, notin（420-790行目） |

**主要処理フロー**:
- **420-445行目**: `HSlice`, `Slice`型と`..`演算子
- **741-765行目**: `contains`, `in`, `notin` - 包含チェック
- **767-790行目**: `is`, `isnot` - 型チェック

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

```
system.nim (メインモジュール)
    │
    ├─ include "system/basic_types"
    │      └─ 基本型定義（int, float, bool, char等）
    │
    ├─ include "system/compilation"
    │      └─ コンパイル時定数・情報
    │
    ├─ include "system/arithmetics"
    │      └─ +, -, *, /, mod, div演算子
    │
    ├─ include "system/comparisons"
    │      └─ ==, !=, <, >, <=, >=演算子
    │
    ├─ include "system/setops"
    │      └─ 集合演算（+, *, -, card等）
    │
    └─ include "system/inclrtl"
           └─ ランタイムライブラリ連携
```

### データフロー図

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

リテラル値      ───▶  型定義・初期化       ───▶  型付き値
  42, "hello"            (basic_types)               int, string

演算式          ───▶  演算子プロシージャ   ───▶  計算結果
  a + b                  (arithmetics)               int/float

メモリ要求      ───▶  new/alloc           ───▶  参照/ポインタ
  new(obj)               (memory mgmt)               ref T

例外発生        ───▶  raise               ───▶  Exception伝播
  raise E               (exception)                  スタック巻き戻し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| system.nim | `lib/system.nim` | ソース | メインモジュール、基本型・演算子・メモリ管理 |
| basic_types.nim | `lib/system/basic_types.nim` | ソース | int, float, bool, char等の基本型定義 |
| compilation.nim | `lib/system/compilation.nim` | ソース | コンパイル時情報・定数 |
| arithmetics.nim | `lib/system/arithmetics.nim` | ソース | 算術演算子実装 |
| comparisons.nim | `lib/system/comparisons.nim` | ソース | 比較演算子実装 |
| setops.nim | `lib/system/setops.nim` | ソース | 集合演算実装 |
| inclrtl.nim | `lib/system/inclrtl.nim` | ソース | ランタイムライブラリ連携 |
| hti.nim | `lib/system/hti.nim` | ソース | 型情報ヘッダ |
| exceptions.nim | `lib/system/exceptions.nim` | ソース | 例外定義 |
