This article needs a technical review. How you can help.
Assign a value to a property of an object.
Syntax
bool JS_SetProperty(JSContext *cx, JS::HandleObject obj, const char *name, JS::HandleValue v); bool JS_SetUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, JS::HandleValue v); bool JS_SetPropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, JS::HandleValue v); // Added in SpiderMonkey 1.8.1
Name | Type | Description |
---|---|---|
cx |
JSContext * |
Pointer to a JS context from which to derive runtime information. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext . |
obj |
JS::HandleValue |
Object to which the property to set belongs. |
name or id |
const char * or const char16_t *or |
Name of the property to set. |
namelen |
size_t |
(only in JS_SetUCProperty ) The length of name in characters; or -1 to indicate that name is null-terminated. |
v |
JS::HandleValue |
In/out parameter. *vp is the value to assign to the property. Ordinarily this function leaves v unchanged, but it is possible for a JSClass.addProperty hook or a non-default setter to assign to v . |
Description
JS_SetProperty
assigns the value v
to the property name
of the object obj
. It behaves like the JavaScript expression obj[name] = v
. JS_SetUCProperty
is the Unicode version of the function. JS_SetPropertyById
is the same but takes a JS::HandleId
for the property name.
If obj
is a Proxy
, the JS_SetProperty
[[Set]] internal method defined in ES6 (rev 29 9.5.9) is performed.
If obj
is a native object with custom setGeneric
op, the op is called with (cx, obj, id, &v, false))
.
Otherwise, [[Set]] internal method defined in ES6 (rev 29 9.1.9) is performed.
- If the lookup found no property with the given name, or if it found that obj inherits such a property from a non-native object, then a new own property is added to obj, as described below. The new property is
JSPROP_ENUMERATE
. - Otherwise, if the lookup found a read-only property or
obj
non-extensible, nothing happens, but this is not an error. In strict mode, a warning is issued. - Otherwise, if
obj
has an own property with the given name, then the existing property's value is set as described below.
Creation of new properties
One of the cases above involves creating a new own property on obj. The name of the new property is given by name
or id
. The initial stored value of the new property is undefined
. Its getter and setter are the JSClass.getProperty
and setProperty
hooks of obj
's class, and its property attributes are exactly JSPROP_ENUMERATE
. After the new property is added, the JSClass.addProperty
hook is called with the arguments (cx, obj, id, &v)
. This hook may assign to v
. If the hook succeeds and the property has a stored value, then the value left in v
by the addProperty
hook becomes the stored value of the property.
Setting the value.
Two of the cases above can involve setting the value of a new or existing property of obj
. This is done as follows. If the property has a JavaScript setter, it is called; otherwise, if it has a JavaScript getter, then an error is reported; otherwise the property's setter is called, passing the arguments (cx, obj, id, &v)
. If the setter succeeds and the property has a stored value, then the value left in v
becomes the stored value of the property.
On success, JS_SetProperty
returns true
, and the value in v
is left unchanged unless a hook or setter modified it. On error or exception, it returns false
, and the value left in v
is unspecified.
Internally, property assignment, including all the behavior described above, is implemented by obj
's JSObjectOps.setProperty
callback.