value¶

Context のメソッドではなく、モジュール直下の関数として提供される Value 操作 API のリファレンスです。型定義は type を参照してください。

値の生成¶

makeInt¶

pub fn makeInt(ctx: *Context, v: i64) Value

整数値から Value を作ります。i32 の範囲に収まる場合は整数表現、収まらない場合は倍精度浮動小数点表現にフォールバックします(JavaScript の Number は常に IEEE754 double のため)。

makeFloat¶

pub fn makeFloat(v: f64) Value

f64 から Value を作ります。Context を必要としません。

makeBool¶

pub fn makeBool(v: bool) Value

真偽値から Value を作ります。

makeNull¶

pub fn makeNull() Value

JavaScript の null を表す Value を返します。

makeUndefined¶

pub fn makeUndefined() Value

JavaScript の undefined を表す Value を返します。

makeString¶

pub fn makeString(ctx: *Context, s: []const u8) !Value

UTF-8 文字列から文字列 Value を作ります。エンジン内部は UTF-16 意味論を CESU-8(サロゲートペアを2つの3バイト列として符号化した表現)で表現しているため、s に astral 文字(U+10000 以上、UTF-8 で4バイト)が含まれる場合は内部で正規化されます。戻り値は他の make* 系と同様に GC 未ルートであり、GC を誘発しうる別の割り当てを行う前に setProperty/setGlobal/defineProperty へ即座に attach するか、HandleScope/protect でルートしてください。

makeSymbol¶

pub fn makeSymbol(ctx: *Context, description: []const u8) !Value

description を持つ一意な Symbol 値を作ります。呼び出すたびに新しい Symbol ID が割り当てられます。戻り値は GC 未ルートです。makeString と同様、即座にオブジェクトへ attach するか HandleScope/protect でルートしてください。

makeBigInt¶

pub fn makeBigInt(ctx: *Context, v: i64) !Value

i64 から BigInt 値を作ります。エンジン内部の BigInt は任意精度ですが、このホスト API で受け渡しできるのは i64 の範囲に限られます(i64 を超える値は JavaScript 側で生成するか、文字列経由で受け渡してください)。戻り値は GC 未ルートです。

値の変換¶

toBool¶

pub fn toBool(v: Value) bool

JavaScript の truthy/falsy 変換規則(ToBoolean)を適用します。

toInt¶

pub fn toInt(v: Value) i64

数値 Value を i64 へ変換します。整数表現ならそのまま、浮動小数点表現なら切り捨て(@intFromFloat)します。数値以外の Value を渡した場合の動作は未規定です。

toFloat¶

pub fn toFloat(v: Value) f64

数値 Value を f64 へ変換します。

toString¶

pub fn toString(ctx: *Context, v: Value) ![]const u8

任意の Value を文字列化します。プレーンオブジェクトが文字列型の stack own プロパティを持つ場合はその値をそのまま返し、なければ仕様準拠の ToString(ToPrimitive の string hint で対象自身の toString() を呼ぶ)にフォールバックします。エンジン生成エラーの stack は "{name}: {message}" に続けて呼び出しフレームごとの \n at ... 行が付く複数行の形式です。それ以外の値は JavaScript の ToString 相当の変換結果を返します。戻り値の所有権は呼び出し側に移るため、ctx.allocator.free() で解放してください。

toBigInt¶

pub fn toBigInt(v: Value) ?i64

BigInt 値を i64 として取り出します。v が BigInt でない、または値が i64 の範囲に収まらない場合は null。

型判定¶

いずれも Context を必要としない純粋な述語関数です。

pub fn isNull(v: Value) bool
pub fn isUndefined(v: Value) bool
pub fn isBool(v: Value) bool
pub fn isNumber(v: Value) bool
pub fn isString(v: Value) bool
pub fn isArray(v: Value) bool
pub fn isObject(v: Value) bool
pub fn isFunction(v: Value) bool
pub fn isPromise(v: Value) bool
pub fn isMap(v: Value) bool
pub fn isSet(v: Value) bool
pub fn isDate(v: Value) bool
pub fn isRegex(v: Value) bool
pub fn isTypedArray(v: Value) bool
pub fn isDataView(v: Value) bool
pub fn isArrayBuffer(v: Value) bool
pub fn isGenerator(v: Value) bool
pub fn isProxy(v: Value) bool
pub fn isWeakRef(v: Value) bool
pub fn isSymbol(v: Value) bool
pub fn isBigInt(v: Value) bool

isObject は「ヒープに確保された何らかのオブジェクトか」という判定ではなく、defineProperty/setProperty/makeObject が扱うプレーンオブジェクトかどうかを判定する点に注意してください。配列やネイティブ関数などは isObject では false になり、それぞれ専用の is* 関数で判定します。

プロパティ・要素アクセス¶

getProperty¶

pub fn getProperty(val: Value, name: []const u8) Value

プレーンオブジェクトの name プロパティを読みます。Proxy の場合はターゲットがプレーンオブジェクトであればそちらから読みます。該当しない場合・見つからない場合は undefined。ゲッター/セッターは経由しません(プロトタイプチェーン上の値をたどりますが、アクセサは呼び出しません — 単純なデータプロパティ取得です)。

getIndex¶

pub fn getIndex(val: Value, index: usize) Value

配列の index 番目の要素を返します。val が配列でない、または範囲外の場合は undefined。

getLength¶

pub fn getLength(val: Value) usize

配列の要素数を返します。配列でない場合は 0。

getHostData / setHostData¶

pub fn getHostData(val: Value) ?*anyopaque
pub fn setHostData(val: Value, data: ?*anyopaque, finalizer: ?*const fn (?*anyopaque) void) void

プレーンオブジェクトに紐付けたホスト側データポインタを読み書きします。Context.makeHostObject で作成済みのオブジェクトに対しても、通常の makeObject で作ったオブジェクトに対しても使えます。finalizer はオブジェクトが GC で回収される際に一度だけ呼ばれます(null なら何もしません)。val がプレーンオブジェクトでない場合、getHostData は null を返し、setHostData は何もしません。

getFunctionData¶

pub fn getFunctionData(val: Value) ?*anyopaque

Context.makeFunctionWithData で紐付けたユーザーデータを取り出します。val がそれ以外の値(通常の関数・makeFunction で作った関数など)の場合は null。HostMethod コールバック内で Context.getCurrentCallee() と組み合わせて自身に紐付いたデータへアクセスするのが典型的な使い方です。

Promise¶

promiseState¶

pub fn promiseState(val: Value) ?PromiseState

Promise の現在の状態(pending/fulfilled/rejected)を返します。val が Promise でなければ null。

promiseResult¶

pub fn promiseResult(val: Value) Value

Promise の結果値(fulfill 値または reject 理由)を返します。pending 状態、または val が Promise でない場合は undefined。

JSON¶

いずれもグローバルの JSON オブジェクトの parse/stringify を内部で呼び出すヘルパーです。JSON グローバルが存在しない、または関数でない場合は error.RuntimeError を返します。

parseJSON¶

pub fn parseJSON(ctx: *Context, json_str: []const u8) !Value

JSON 文字列をパースして Value を返します。パースエラー(不正な JSON)は JSON.parse が投げる例外がそのまま EvalError(error.UncaughtException など)として伝播します。

stringifyJSON¶

pub fn stringifyJSON(ctx: *Context, val: Value) ![]const u8

Value を JSON 文字列化します。戻り値は呼び出し側が ctx.allocator.free() で解放してください。