# このリファレンスについて

『STD リファレンス』は Kagari の標準ライブラリ `std` のリファレンスです。ライブラリのすべての公開アイテムを、正確なシグネチャと意味とともに、モジュールごとに 1 ページずつ、Node.js の API ドキュメントの形式で記載します。

言語そのもの（構文、関数種別、シーン、フォーム、数値）は [言語リファレンス](../reference/index.md) で説明しています。本リファレンスはその内容を前提とします。

## ページの構成 {#page-structure}

モジュールのページはすべて同じ形をしています。

1. タイトルはモジュールのパスです。例：`` `std::time` ``。
2. **安定性** 行（`> **安定性:** 安定 — …`）がモジュールを要約し、その安定性を示します（後述）。
3. 導入の段落で、モジュールの目的とアイテムの関数種別を説明します。
4. 省略可能な **Overview** 表が、ページ内のアイテムを一覧にします。
5. アイテムごとに H2 節を 1 つ置き、モジュールのソースファイルでの宣言順に並べます。見出しにはアイテムの種類を書きます：`Struct:`、`Enum:`、`Trait:`、`Type:`、`Constant:`、`Function:`。
6. メソッド、関連関数、バリアントのまとまりごとに、型の下に H3 節を 1 つ置きます。

各アイテムの節は、`std` が宣言しているとおりの宣言から始まり、続いて次を記載します。

- 引数ごとに 1 項目：名前、型、意味
- `Returns:` 戻り値の型と意味
- バッジ行：`Kind: … · Builtin: … · Profile: …`（後述）
- 意味、エッジケース、関連する診断、短い例

ガイド（*Staging Recipes*、*System Recipes*）では、アイテムの組み合わせ方を示します。付録には、std アイテムに適用されるコンパイラの規則と、各ランタイムプロファイルが対応する範囲を記載します。

## 安定性 {#stability-index}

|安定性|意味|
|---|---|
|**安定**（Stable）|コンパイラとランタイムが実装済みです。シグネチャと意味は、その旨を明記した新しいツールチェーンのバージョンでのみ変わります。|
|**暫定**（Tentative）|実装済みですが、設計は確定していません。名前、シグネチャ、意味が変わる可能性があります。|
|**予定**（Planned）|設計済み、または要望段階で、実装されていません。ページは意図を説明するもので、まだ何も使えません。|

ページの最初の行がモジュールの安定性を示します。モジュールと異なる安定性のアイテムには、個別に `安定性:` の注記を付けます。

## 種別バッジ {#kind-badges}

アイテムのバッジ行は関数種別を示します。

|バッジ|意味|
|---|---|
|`Kind: const fn`|純粋な関数です。どの種別のコードからも呼べます。物語の中では、定数引数の呼び出しは畳み込まれ、有限型の実行時引数の呼び出しは表化されます。|
|`Kind: fn`|通常のコードです：ゲームシステム、UI、設定。`const fn` や物語からは呼べません。|
|`Kind: pushdown fn`|物語のコードです。物語からのみ呼べ、一部はシーンからのみ呼べます。|

種別間の呼び出し規則は言語の規則そのものです。[関数種別](../reference/concepts/kinds.md) を参照してください。std のメソッドとビルトインにも、自作の関数とまったく同じように適用されます。

## `#[builtin]` アイテム {#builtin-items}

`#[builtin]` が付いたアイテムは `std` 内に本体を持たず、コンパイラまたはエンジンが提供します。

- `#[builtin]` の**型**は不透明です。見えるフィールドはなく、依存できるレイアウトもありません。メソッドと、その型を受け取る関数を通してのみ使います。`Text`、`Screen`、`Narrative`、アセット型がその例です。
- `#[builtin]` の**関数**は、他の関数と同じく宣言どおりのシグネチャと種別を持ちます。
- `#[builtin]` は `std` 専用です。ゲームはビルトインを宣言できません。

`#[builtin]` が付いていないものはすべて通常の Kagari コードで、スタジオが自分で書くこともできたものです。`std::time` やテキスト効果のコンストラクタがその例です。

バッジには `Builtin: yes` または `Builtin: no` と書きます。

## シグネチャの表記 {#signature-conventions}

- シグネチャは `std` のソースから写しています。ドキュメントコメントは短縮または省略しています。
- メソッドの見出しは `` `Type::method(args)` `` とし、`self`、`&self`、`&mut self` は宣言どおりに示します。
- ジェネリクスの引数は Rust と同じく `<T>`、`<T: Eq>`、`<const N: usize>` と書きます。
- `Int<lo, hi>` は言語の範囲付き整数型です。Rust の整数（`u8` … `i128`、`usize`、`isize`）と `bool` は言語の型で、std のアイテムではありません。
- 位置と長さはピクセル、時間は `Duration`、割合は `Decimal` です。
- 「評価エラー」とは、呼び出しが定数評価されるときはコンパイルエラー、それ以外では実行時エラーのことです。

## プロファイルの注記 {#profile-notes}

ランタイムプロファイルとは、ランタイムが提供する機能とアセット形式の集合です。あるプロファイルが対応していないアイテムには、バッジ行に `Profile: not in native_v0` のように記載します。全体の対応表は [ランタイムプロファイル](./appendix/profiles.md) にあります。