JS_DeleteProperty

Removes a specified property from an object.

Syntax

bool
JS_DeleteProperty(JSContext *cx, JS::HandleObject obj, const char *name);

bool
JS_DeletePropertyById(JSContext *cx, JS::HandleObject obj, jsid id); // Added in SpiderMonkey 1.8.1

// Added in SpiderMonkey 45

bool
JS_DeleteProperty(JSContext *cx, JS::HandleObject obj, const char *name,
                  JS::ObjectOpResult &result);

bool
JS_DeletePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id,
                      JS::ObjectOpResult &result);

bool
JS_DeleteUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen,
                    JS::ObjectOpResult &result);

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::HandleObject Object from which to delete a property.
name or id const char * or jsid or const char16_t * Name of the property to delete.
namelen size_t (only in JS_DeleteUCProperty) The length of name in characters; or -1 to indicate that name is null-terminated.
result JS::ObjectOpResult & (out parameter) Receives the result of the operation.

Description

JS_DeleteProperty removes a specified property, name, from an object, obj. JS_DeletePropertyById is the same but takes a jsid for the property name. These functions are identical to JS_DeleteProperty2 and JS_DeletePropertyById2 except that they do not have an out parameter.

First, a property lookup is performed. Then one of the following cases applies:

  • If obj has no property with the given name or id, or if obj inherits the specified property from its prototype, then obj's JSClass.delProperty hook is called. No property is deleted, but this is not an error.
  • If obj has the specified property but it is permanent, nothing happens. No property is deleted, but this is not an error.
  • Otherwise obj has a non-permanent own property with the given name or id. In this case, obj's JSClass.delProperty hook is called. If the hook returns false, the error is propagated. Otherwise, if obj is not configurable, an error is raised. Otherwise, the property is removed.

These functions return true on success, regardless of whether a property was actually deleted, and false on error or exception.

(In JavaScript 1.2 and earlier, attempting to delete a permanent property caused an error. There is no longer any way to get this behavior.)

Internally, property deletion is implemented by the JSObjectOps.deleteProperty callback.

To remove all properties from an object, call JS_ClearScope.

See Also