JS_SetProperty

Assign a value to a property of an object.

Syntax

JSBool JS_SetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);

JSBool JS_SetUCProperty(JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, jsval *vp);

JSBool JS_SetPropertyById(JSContext *cx, JSObject *obj, jsid id, jsval *vp); 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 JSObject * Object to which the property to set belongs.
name or id const char * or const jschar * or jsid 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.
vp jsval * In/out parameter. *vp is the value to assign to the property. Ordinarily this function leaves *vp unchanged, but it is possible for a JSClass.addProperty hook or a non-default setter to assign to *vp.

Description

JS_SetProperty assigns the value *vp 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 jsid for the property name.

If obj is sealed, an exception ("name is read-only") is raised. Otherwise, a property lookup is performed (with the flags JSRESOLVE_QUALIFIED | JSRESOLVE_ASSIGNING). If the lookup is successful, exactly one of the following cases applies:

  • 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_ENUMERABLE. If obj's class has the JSCLASS_SHARE_ALL_PROPERTIES flag, it is also JSPROP_SHARED. Then the new property's value is set as described below.
  • Otherwise, if the lookup found a JSPROP_READONLY property, then we are trying to set a read-only property. 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.
  • Otherwise, the lookup found an inherited property with the given name on a native object. If that property is not JSPROP_SHARED, then a new property is added to obj, as described below. If the existing property has a shortid, then the new property will have the same getter, setter, and shortid as the existing property. Then the new property's value is set as described below.
  • Otherwise, obj inherits a JSPROP_SHARED property from a native object. If that object is sealed, then an exception is raised. Otherwise, if the property has a stub setter and does not have a JS getter, then nothing happens (but this is not an error). Otherwise, the property's value is set as described below. No new property is created in this case.

Creation of new properties. Two of the cases above involve 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 JSVAL_VOID. Unless otherwise specified above, its getter and setter are the JSClass.getProperty and setProperty hooks of obj's class, its property attributes are exactly JSPROP_ENUMERATE, and it has no tinyid. After the new property is added, the JSClass.addProperty hook is called with the arguments (cx, obj, id, vp) where id is the new property's name (or tinyid, if any). This hook may assign to *vp. If the hook succeeds and the property has a stored value, then the value left in *vp by the addProperty hook becomes the stored value of the property.

Setting the value. Four 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, vp) where id is the property's name (or tinyid, if any). If the setter succeeds and the property has a stored value, then the value left in *vp becomes the stored value of the property.

On success, JS_SetProperty returns JS_TRUE, and the value in *vp is left unchanged unless a hook or setter modified it. On error or exception, it returns JS_FALSE, and the value left in *vp is unspecified.

Internally, property assignment, including all the behavior described above, is implemented by obj's JSObjectOps.setProperty callback.

MXR ID Search for JS_SetProperty
MXR ID Search for JS_SetUCProperty
MXR ID Search for JS_SetPropertyById

Document Tags and Contributors

Contributors to this page: rillian, Icxhos, Nickolay, MMondor, mauve, spartan018, Dria, Jorend
Last updated by: rillian,