ADC Home > Reference Library > Reference > Carbon > Internet & Web > JavaScriptCore Framework Reference

JSValueRef.h

Includes:

Overview

Functions

JSValueGetType: Returns a JavaScript value's type.
JSValueIsBoolean: Tests whether a JavaScript value's type is the boolean type.
JSValueIsEqual: Tests whether two JavaScript values are equal, as compared by the JS == operator.
JSValueIsInstanceOfConstructor: Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.
JSValueIsNull: Tests whether a JavaScript value's type is the null type.
JSValueIsNumber: Tests whether a JavaScript value's type is the number type.
JSValueIsObject: Tests whether a JavaScript value's type is the object type.
JSValueIsObjectOfClass: Tests whether a JavaScript value is an object with a given class in its class chain.
JSValueIsStrictEqual: Tests whether two JavaScript values are strict equal, as compared by the JS === operator.
JSValueIsString: Tests whether a JavaScript value's type is the string type.
JSValueIsUndefined: Tests whether a JavaScript value's type is the undefined type.
JSValueMakeBoolean: Creates a JavaScript value of the boolean type.
JSValueMakeNull: Creates a JavaScript value of the null type.
JSValueMakeNumber: Creates a JavaScript value of the number type.
JSValueMakeString: Creates a JavaScript value of the string type.
JSValueMakeUndefined: Creates a JavaScript value of the undefined type.
JSValueProtect: Protects a JavaScript value from garbage collection.
JSValueToBoolean: Converts a JavaScript value to boolean and returns the resulting boolean.
JSValueToNumber: Converts a JavaScript value to number and returns the resulting number.
JSValueToObject: Converts a JavaScript value to object and returns the resulting object.
JSValueToStringCopy: Converts a JavaScript value to string and copies the result into a JavaScript string.
JSValueUnprotect: Unprotects a JavaScript value from garbage collection.

JSValueGetType

Returns a JavaScript value's type.

JSType JSValueGetType(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue whose type you want to obtain.

Return Value

A value of type JSType that identifies value's type.

JSValueIsBoolean

Tests whether a JavaScript value's type is the boolean type.

bool JSValueIsBoolean(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to test.

Return Value

true if value's type is the boolean type, otherwise false.

JSValueIsEqual

Tests whether two JavaScript values are equal, as compared by the JS == operator.

bool JSValueIsEqual(
    JSContextRef ctx,
    JSValueRef a,
    JSValueRef b,
    JSValueRef *exception);

Parameters

ctx: The execution context to use.
a: The first value to test.
b: The second value to test.
exception: A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

Return Value

true if the two values are equal, false if they are not equal or an exception is thrown.

JSValueIsInstanceOfConstructor

Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.

bool JSValueIsInstanceOfConstructor(
    JSContextRef ctx,
    JSValueRef value,
    JSObjectRef constructor,
    JSValueRef *exception);

Parameters

ctx: The execution context to use.
value: The JSValue to test.
constructor: The constructor to test against.
exception: A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

Return Value

true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false.

JSValueIsNull

Tests whether a JavaScript value's type is the null type.

bool JSValueIsNull(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to test.

Return Value

true if value's type is the null type, otherwise false.

JSValueIsNumber

Tests whether a JavaScript value's type is the number type.

bool JSValueIsNumber(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to test.

Return Value

true if value's type is the number type, otherwise false.

JSValueIsObject

Tests whether a JavaScript value's type is the object type.

bool JSValueIsObject(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to test.

Return Value

true if value's type is the object type, otherwise false.

JSValueIsObjectOfClass

Tests whether a JavaScript value is an object with a given class in its class chain.

bool JSValueIsObjectOfClass(
    JSContextRef ctx,
    JSValueRef value,
    JSClassRef jsClass);

Parameters

ctx: The execution context to use.
value: The JSValue to test.
jsClass: The JSClass to test against.

Return Value

true if value is an object and has jsClass in its class chain, otherwise false.

JSValueIsStrictEqual

Tests whether two JavaScript values are strict equal, as compared by the JS === operator.

bool JSValueIsStrictEqual(
    JSContextRef ctx,
    JSValueRef a,
    JSValueRef b);

Parameters

ctx: The execution context to use.
a: The first value to test.
b: The second value to test.

Return Value

true if the two values are strict equal, otherwise false.

JSValueIsString

Tests whether a JavaScript value's type is the string type.

bool JSValueIsString(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to test.

Return Value

true if value's type is the string type, otherwise false.

JSValueIsUndefined

Tests whether a JavaScript value's type is the undefined type.

bool JSValueIsUndefined(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to test.

Return Value

true if value's type is the undefined type, otherwise false.

JSValueMakeBoolean

Creates a JavaScript value of the boolean type.

JSValueRef JSValueMakeBoolean(
    JSContextRef ctx,
    bool boolean);

Parameters

ctx: The execution context to use.
boolean: The bool to assign to the newly created JSValue.

Return Value

A JSValue of the boolean type, representing the value of boolean.

JSValueMakeNull

Creates a JavaScript value of the null type.

JSValueRef JSValueMakeNull(
    JSContextRef ctx);

Parameters

ctx: The execution context to use.

Return Value

The unique null value.

JSValueMakeNumber

Creates a JavaScript value of the number type.

JSValueRef JSValueMakeNumber(
    JSContextRef ctx,
    double number);

Parameters

ctx: The execution context to use.
number: The double to assign to the newly created JSValue.

Return Value

A JSValue of the number type, representing the value of number.

JSValueMakeString

Creates a JavaScript value of the string type.

JSValueRef JSValueMakeString(
    JSContextRef ctx,
    JSStringRef string);

Parameters

ctx: The execution context to use.
string: The JSString to assign to the newly created JSValue. The newly created JSValue retains string, and releases it upon garbage collection.

Return Value

A JSValue of the string type, representing the value of string.

JSValueMakeUndefined

Creates a JavaScript value of the undefined type.

JSValueRef JSValueMakeUndefined(
    JSContextRef ctx);

Parameters

ctx: The execution context to use.

Return Value

The unique undefined value.

JSValueProtect

Protects a JavaScript value from garbage collection.

void JSValueProtect(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to protect.

Discussion

Use this method when you want to store a JSValue in a global or on the heap, where the garbage collector will not be able to discover your reference to it.

A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.

JSValueToBoolean

Converts a JavaScript value to boolean and returns the resulting boolean.

bool JSValueToBoolean(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to convert.

Return Value

The boolean result of conversion.

JSValueToNumber

Converts a JavaScript value to number and returns the resulting number.

double JSValueToNumber(
    JSContextRef ctx,
    JSValueRef value,
    JSValueRef *exception);

Parameters

ctx: The execution context to use.
value: The JSValue to convert.
exception: A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

Return Value

The numeric result of conversion, or NaN if an exception is thrown.

JSValueToObject

Converts a JavaScript value to object and returns the resulting object.

JSObjectRef JSValueToObject(
    JSContextRef ctx,
    JSValueRef value,
    JSValueRef *exception);

Parameters

ctx: The execution context to use.
value: The JSValue to convert.
exception: A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

Return Value

The JSObject result of conversion, or NULL if an exception is thrown.

JSValueToStringCopy

Converts a JavaScript value to string and copies the result into a JavaScript string.

JSStringRef JSValueToStringCopy(
    JSContextRef ctx,
    JSValueRef value,
    JSValueRef *exception);

Parameters

ctx: The execution context to use.
value: The JSValue to convert.
exception: A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.

Return Value

A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule.

JSValueUnprotect

Unprotects a JavaScript value from garbage collection.

void JSValueUnprotect(
    JSContextRef ctx,
    JSValueRef value);

Parameters

ctx: The execution context to use.
value: The JSValue to unprotect.

Discussion

A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.

Typedefs

JSType

A constant identifying the type of a JSValue.

typedef enum { 
    kJSTypeUndefined, 
    kJSTypeNull, 
    kJSTypeBoolean, 
    kJSTypeNumber, 
    kJSTypeString, 
    kJSTypeObject 
} JSType;

Constants

kJSTypeUndefined
The unique undefined value.

kJSTypeNull
The unique null value.

kJSTypeBoolean
A primitive boolean value, one of true or false.

kJSTypeNumber
A primitive number value.

kJSTypeString
A primitive string value.

kJSTypeObject
An object value (meaning that this JSValueRef is a JSObjectRef).

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11