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 JS::HandleId 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 ES2015 (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 ES2015 (rev 29 9.1.9) is performed.

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.

See Also