JSValue

Superclass:
NSObject
Declared In:

Introduction

A JSValue is a reference to a value within the JavaScript object space of a JSVirtualMachine. All instances of JSValue originate from a JSContext and hold a strong reference to this JSContext. As long as any value associated with a particular JSContext is retained, that JSContext will remain alive. Where an instance method is invoked upon a JSValue, and this returns another JSValue, the returned JSValue will originate from the same JSContext as the JSValue on which the method was invoked.

All JavaScript values are associated with a particular JSVirtualMachine (the associated JSVirtualMachine is available indirectly via the context property). An instance of JSValue may only be passed as an argument to methods on instances of JSValue and JSContext that belong to the same JSVirtualMachine - passing a JSValue to a method on an object originating from a different JSVirtualMachine will result in an Objective-C exception being raised.


Groups

Creating JavaScript Values

Group members:

+valueWithBool:inContext:

Create a JavaScript value from a BOOL primitive.

+valueWithDouble:inContext:

Create a JavaScript value from a double primitive.

+valueWithInt32:inContext:

Create a JavaScript value from an int32_t primitive.

+valueWithNewArrayInContext:

Create a new, empty JavaScript array.

+valueWithNewErrorFromMessage:inContext:

Create a new JavaScript error object.

+valueWithNewObjectInContext:

Create a new, empty JavaScript object.

+valueWithNewRegularExpressionFromPattern:flags:inContext:

Create a new JavaScript regular expression object.

+valueWithNullInContext:

Create the JavaScript value null.

+valueWithObject:inContext:

Create a JSValue by converting an Objective-C object.

+valueWithUInt32:inContext:

Create a JavaScript value from a uint32_t primitive.

+valueWithUndefinedInContext:

Create the JavaScript value undefined.

 

Calling Functions and Constructors

Group members:

-callWithArguments:

Invoke a JSValue as a function.

-constructWithArguments:

Invoke a JSValue as a constructor.

-invokeMethod:withArguments:

Invoke a method on a JSValue.

 

Checking JavaScript Types

Group members:

-isBoolean

Check if a JSValue is a boolean.

-isEqualToObject:

Compare two JSValues using JavaScript's === operator.

-isEqualWithTypeCoercionToObject:

Compare two JSValues using JavaScript's == operator.

-isInstanceOf:

Check if a JSValue is an instance of another object.

-isNull

Check if a JSValue corresponds to the JavaScript value null.

-isNumber

Check if a JSValue is a number.

-isObject

Check if a JSValue is an object.

-isString

Check if a JSValue is a string.

-isUndefined

Check if a JSValue corresponds to the JavaScript value undefined.

 

Accessing Properties

Group members:

-defineProperty:descriptor:

Define properties with custom descriptors on JSValues.

-deleteProperty:

Delete a property from a JSValue.

-hasProperty:

Check if a JSValue has a property.

-setValue:atIndex:

Set an indexed (numerical) property on a JSValue.

-setValue:forProperty:

Set a property on a JSValue.

-valueAtIndex:

Access an indexed (numerical) property on a JSValue.

-valueForProperty:

Access a property of a JSValue.

 

Converting to Objective-C Types

When converting between JavaScript values and Objective-C objects a copy is performed. Values of types listed below are copied to the corresponding types on conversion in each direction. For NSDictionaries, entries in the dictionary that are keyed by strings are copied onto a JavaScript object. For dictionaries and arrays, conversion is recursive, with the same object conversion being applied to all entries in the collection. 


   Objective-C type  |   JavaScript type
 --------------------+---------------------
         nil         |     undefined
        NSNull       |        null
       NSString      |       string
       NSNumber      |   number, boolean
     NSDictionary    |   Object object
       NSArray       |    Array object
        NSDate       |     Date object
       NSBlock (1)   |   Function object (1)
          id (2)     |   Wrapper object (2)
        Class (3)    | Constructor object (3)

(1) Instances of NSBlock with supported arguments types will be presented to JavaScript as a callable Function object. For more information on supported argument types see JSExport.h. If a JavaScript Function originating from an Objective-C block is converted back to an Objective-C object the block will be returned. All other JavaScript functions will be converted in the same manner as a JavaScript object of type Object.

(2) For Objective-C instances that do not derive from the set of types listed above, a wrapper object to provide a retaining handle to the Objective-C instance from JavaScript. For more information on these wrapper objects, see JSExport.h. When a JavaScript wrapper object is converted back to Objective-C the Objective-C instance being retained by the wrapper is returned.

(3) For Objective-C Class objects a constructor object containing exported class methods will be returned. See JSExport.h for more information on constructor objects.

For all methods taking arguments of type id, arguments will be converted into a JavaScript value according to the above conversion.

Group members:

-toArray

Convert a JSValue to a NSArray.

-toBool

Convert a JSValue to a boolean.

-toDate

Convert a JSValue to a NSDate.

-toDictionary

Convert a JSValue to a NSDictionary.

-toDouble

Convert a JSValue to a double.

-toInt32

Convert a JSValue to an int32_t.

-toNumber

Convert a JSValue to a NSNumber.

-toObject

Convert this JSValue to an Objective-C object.

-toObjectOfClass:

Convert a JSValue to an Objective-C object of a specific class.

-toString

Convert a JSValue to a NSString.

-toUInt32

Convert a JSValue to a uint32_t.

Methods

-callWithArguments:

Invoke a JSValue as a function.

-constructWithArguments:

Invoke a JSValue as a constructor.

-defineProperty:descriptor:

Define properties with custom descriptors on JSValues.

-deleteProperty:

Delete a property from a JSValue.

-hasProperty:

Check if a JSValue has a property.

-invokeMethod:withArguments:

Invoke a method on a JSValue.

-isBoolean

Check if a JSValue is a boolean.

-isEqualToObject:

Compare two JSValues using JavaScript's === operator.

-isEqualWithTypeCoercionToObject:

Compare two JSValues using JavaScript's == operator.

-isInstanceOf:

Check if a JSValue is an instance of another object.

-isNull

Check if a JSValue corresponds to the JavaScript value null.

-isNumber

Check if a JSValue is a number.

-isObject

Check if a JSValue is an object.

-isString

Check if a JSValue is a string.

-isUndefined

Check if a JSValue corresponds to the JavaScript value undefined.

-setValue:atIndex:

Set an indexed (numerical) property on a JSValue.

-setValue:forProperty:

Set a property on a JSValue.

-toArray

Convert a JSValue to a NSArray.

-toBool

Convert a JSValue to a boolean.

-toDate

Convert a JSValue to a NSDate.

-toDictionary

Convert a JSValue to a NSDictionary.

-toDouble

Convert a JSValue to a double.

-toInt32

Convert a JSValue to an int32_t.

-toNumber

Convert a JSValue to a NSNumber.

-toObject

Convert this JSValue to an Objective-C object.

-toObjectOfClass:

Convert a JSValue to an Objective-C object of a specific class.

-toString

Convert a JSValue to a NSString.

-toUInt32

Convert a JSValue to a uint32_t.

-valueAtIndex:

Access an indexed (numerical) property on a JSValue.

-valueForProperty:

Access a property of a JSValue.

+valueWithBool:inContext:

Create a JavaScript value from a BOOL primitive.

+valueWithDouble:inContext:

Create a JavaScript value from a double primitive.

+valueWithInt32:inContext:

Create a JavaScript value from an int32_t primitive.

+valueWithNewArrayInContext:

Create a new, empty JavaScript array.

+valueWithNewErrorFromMessage:inContext:

Create a new JavaScript error object.

+valueWithNewObjectInContext:

Create a new, empty JavaScript object.

+valueWithNewRegularExpressionFromPattern:flags:inContext:

Create a new JavaScript regular expression object.

+valueWithNullInContext:

Create the JavaScript value null.

+valueWithObject:inContext:

Create a JSValue by converting an Objective-C object.

+valueWithUInt32:inContext:

Create a JavaScript value from a uint32_t primitive.

+valueWithUndefinedInContext:

Create the JavaScript value undefined.

callWithArguments:

Invoke a JSValue as a function. 

- (JSValue *)callWithArguments:(NSArray *)arguments;
Parameters
arguments

The arguments to pass to the function.

Return Value

The return value of the function call.

Discussion

In JavaScript, if a function doesn't explicitly return a value then it implicitly returns the JavaScript value undefined.

constructWithArguments:

Invoke a JSValue as a constructor. 

- (JSValue *)constructWithArguments:(NSArray *)arguments;
Parameters
arguments

The arguments to pass to the constructor.

Return Value

The return value of the constructor call.

Discussion

This is equivalent to using the new syntax in JavaScript.

defineProperty:descriptor:

Define properties with custom descriptors on JSValues. 

- (void)defineProperty:(NSString *)property descriptor:(id)descriptor;
Discussion

This method may be used to create a data or accessor property on an object. This method operates in accordance with the Object.defineProperty method in the JavaScript language.

deleteProperty:

Delete a property from a JSValue. 

- (BOOL)deleteProperty:(NSString *)property;
Return Value

YES if deletion is successful, NO otherwise.

hasProperty:

Check if a JSValue has a property. 

- (BOOL)hasProperty:(NSString *)property;
Return Value

Returns YES if property is present on the value.

Discussion

This method has the same function as the JavaScript operator in.

invokeMethod:withArguments:

Invoke a method on a JSValue. 

- (JSValue *)invokeMethod:(NSString *)method withArguments:(NSArray *)arguments;
Parameters
method

The name of the method to be invoked.

arguments

The arguments to pass to the method.

Return Value

The return value of the method call.

Discussion

Accesses the property named method from this value and calls the resulting value as a function, passing this JSValue as the this value along with the specified arguments.

isBoolean

Check if a JSValue is a boolean. 

- (BOOL)isBoolean;

isEqualToObject:

Compare two JSValues using JavaScript's === operator. 

- (BOOL)isEqualToObject:(id)value;

isEqualWithTypeCoercionToObject:

Compare two JSValues using JavaScript's == operator. 

- (BOOL)isEqualWithTypeCoercionToObject:(id)value;

isInstanceOf:

Check if a JSValue is an instance of another object. 

- (BOOL)isInstanceOf:(id)value;
Discussion

This method has the same function as the JavaScript operator instanceof. If an object other than a JSValue is passed, it will first be converted according to the aforementioned rules.

isNull

Check if a JSValue corresponds to the JavaScript value null. 

- (BOOL)isNull;

isNumber

Check if a JSValue is a number. 

- (BOOL)isNumber;
Discussion

In JavaScript, there is no differentiation between types of numbers. Semantically all numbers behave like doubles except in special cases like bit operations.

isObject

Check if a JSValue is an object. 

- (BOOL)isObject;

isString

Check if a JSValue is a string. 

- (BOOL)isString;

isUndefined

Check if a JSValue corresponds to the JavaScript value undefined. 

- (BOOL)isUndefined;

setValue:atIndex:

Set an indexed (numerical) property on a JSValue. 

- (void)setValue:(id)value atIndex:(NSUInteger)index;
Discussion

For JSValues that are JavaScript arrays, indices greater than UINT_MAX - 1 will not affect the length of the array.

setValue:forProperty:

Set a property on a JSValue. 

- (void)setValue:(id)value forProperty:(NSString *)property;

toArray

Convert a JSValue to a NSArray. 

- (NSArray *)toArray;
Return Value

The NSArray containing the recursively converted contents of the converted JavaScript array.

Discussion

If the value is null or undefined then nil is returned. If the value is not an object then a JavaScript TypeError will be thrown. The property length is read from the object, converted to an unsigned integer, and an NSArray of this size is allocated. Properties corresponding to indicies within the array bounds will be copied to the array, with JSValues converted to equivalent Objective-C objects as specified.

toBool

Convert a JSValue to a boolean. 

- (BOOL)toBool;
Return Value

The boolean result of the conversion.

Discussion

The JSValue is converted to a boolean according to the rules specified by the JavaScript language.

toDate

Convert a JSValue to a NSDate. 

- (NSDate *)toDate;
Return Value

The NSDate created using the converted time interval.

Discussion

The value is converted to a number representing a time interval since 1970 which is then used to create a new NSDate instance.

toDictionary

Convert a JSValue to a NSDictionary. 

- (NSDictionary *)toDictionary;
Return Value

The NSDictionary containing the recursively converted contents of the converted JavaScript object.

Discussion

If the value is null or undefined then nil is returned. If the value is not an object then a JavaScript TypeError will be thrown. All enumerable properties of the object are copied to the dictionary, with JSValues converted to equivalent Objective-C objects as specified.

toDouble

Convert a JSValue to a double. 

- (double)toDouble;
Return Value

The double result of the conversion.

Discussion

The JSValue is converted to a number according to the rules specified by the JavaScript language.

toInt32

Convert a JSValue to an int32_t. 

- (int32_t)toInt32;
Return Value

The int32_t result of the conversion.

Discussion

The JSValue is converted to an integer according to the rules specified by the JavaScript language.

toNumber

Convert a JSValue to a NSNumber. 

- (NSNumber *)toNumber;
Return Value

The NSNumber result of the conversion.

Discussion

If the JSValue represents a boolean, a NSNumber value of YES or NO will be returned. For all other types the value will be converted to a number according to the rules specified by the JavaScript language.

toObject

Convert this JSValue to an Objective-C object. 

- (id)toObject;
Return Value

The Objective-C representation of this JSValue.

Discussion

The JSValue is converted to an Objective-C object according to the conversion rules specified above.

toObjectOfClass:

Convert a JSValue to an Objective-C object of a specific class. 

- (id)toObjectOfClass:(Class)expectedClass;
Return Value

An Objective-C object of the specified Class or nil.

Discussion

The JSValue is converted to an Objective-C object of the specified Class. If the result is not of the specified Class then nil will be returned.

toString

Convert a JSValue to a NSString. 

- (NSString *)toString;
Return Value

The NSString containing the result of the conversion.

Discussion

The JSValue is converted to a string according to the rules specified by the JavaScript language.

toUInt32

Convert a JSValue to a uint32_t. 

- (uint32_t)toUInt32;
Return Value

The uint32_t result of the conversion.

Discussion

The JSValue is converted to an integer according to the rules specified by the JavaScript language.

valueAtIndex:

Access an indexed (numerical) property on a JSValue. 

- (JSValue *)valueAtIndex:(NSUInteger)index;
Return Value

The JSValue for the property at the specified index. Returns the JavaScript value undefined if no property exists at that index.

valueForProperty:

Access a property of a JSValue. 

- (JSValue *)valueForProperty:(NSString *)property;
Return Value

The JSValue for the requested property or the JSValue undefined if the property does not exist.

valueWithBool:inContext:

Create a JavaScript value from a BOOL primitive. 

+ (JSValue *)valueWithBool:(BOOL)value inContext:(JSContext *)context;
Parameters
value
context

The JSContext in which the resulting JSValue will be created.

Return Value

The new JSValue representing the equivalent boolean value.

valueWithDouble:inContext:

Create a JavaScript value from a double primitive. 

+ (JSValue *)valueWithDouble:(double)value inContext:(JSContext *)context;
Parameters
value
context

The JSContext in which the resulting JSValue will be created.

Return Value

The new JSValue representing the equivalent boolean value.

valueWithInt32:inContext:

Create a JavaScript value from an int32_t primitive. 

+ (JSValue *)valueWithInt32:(int32_t)value inContext:(JSContext *)context;
Parameters
value
context

The JSContext in which the resulting JSValue will be created.

Return Value

The new JSValue representing the equivalent boolean value.

valueWithNewArrayInContext:

Create a new, empty JavaScript array. 

+ (JSValue *)valueWithNewArrayInContext:(JSContext *)context;
Parameters
context

The JSContext in which the resulting array will be created.

Return Value

The new JavaScript array.

valueWithNewErrorFromMessage:inContext:

Create a new JavaScript error object. 

+ (JSValue *)valueWithNewErrorFromMessage:(NSString *)message 
        inContext:(JSContext *)context;
Parameters
message

The error message.

context

The JSContext in which the resulting error object will be created.

Return Value

The new JavaScript error object.

valueWithNewObjectInContext:

Create a new, empty JavaScript object. 

+ (JSValue *)valueWithNewObjectInContext:(JSContext *)context;
Parameters
context

The JSContext in which the resulting object will be created.

Return Value

The new JavaScript object.

valueWithNewRegularExpressionFromPattern:flags:inContext:

Create a new JavaScript regular expression object. 

+ (JSValue *)valueWithNewRegularExpressionFromPattern:(NSString *)pattern 
        flags:(NSString *)flags inContext:(JSContext *)context;
Parameters
pattern

The regular expression pattern.

flags

The regular expression flags.

context

The JSContext in which the resulting regular expression object will be created.

Return Value

The new JavaScript regular expression object.

valueWithNullInContext:

Create the JavaScript value null. 

+ (JSValue *)valueWithNullInContext:(JSContext *)context;
Parameters
context

The JSContext to which the resulting JSValue belongs.

Return Value

The JSValue representing the JavaScript value null.

valueWithObject:inContext:

Create a JSValue by converting an Objective-C object. 

+ (JSValue *)valueWithObject:(id)value inContext:(JSContext *)context;
Parameters
value

The Objective-C object to be converted.

Return Value

The new JSValue.

Discussion

The resulting JSValue retains the provided Objective-C object.

valueWithUInt32:inContext:

Create a JavaScript value from a uint32_t primitive. 

+ (JSValue *)valueWithUInt32:(uint32_t)value inContext:(JSContext *)context;
Parameters
value
context

The JSContext in which the resulting JSValue will be created.

Return Value

The new JSValue representing the equivalent boolean value.

valueWithUndefinedInContext:

Create the JavaScript value undefined. 

+ (JSValue *)valueWithUndefinedInContext:(JSContext *)context;
Parameters
context

The JSContext to which the resulting JSValue belongs.

Return Value

The JSValue representing the JavaScript value undefined.

Properties

context

The JSContext that this value originates from.

context

The JSContext that this value originates from. 

@property (readonly,
    strong) JSContext *context;

 

Last Updated: Friday, May 30, 2014