JS_DeleteProperty2

Obsolete since JSAPI 39
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

 

Removes a specified property from an object.

Renamed to JS_DeleteProperty from JSAPI 39.

Syntax

bool
JS_DeleteProperty2(JSContext *cx, JS::HandleObject obj, const char *name,
                   bool *succeeded);
bool
JS_DeleteUCProperty2(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen,
                     bool *succeeded);
bool
JS_DeletePropertyById2(JSContext *cx, JS::HandleObject obj, JS::HandleId id,
                       bool *succeeded); // 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::HandleObject Object from which to delete a property.
name or id const char * or const char16_t or JS::HandleId Name of the property to delete.
namelen size_t (only in JS_DeleteUCProperty2) The length of name in characters; or -1 to indicate that name is null-terminated.
succeeded bool * Out parameter. On success, *succeeded receives false if the property was not deleted because it is permanent and true otherwise.

Description

JS_DeleteProperty2 removes a specified property, name, from an object, obj, and stores true or false in *succeeded. It behaves like the JavaScript expression delete obj[name]. JS_DeleteUCProperty2 is the Unicode version of the function. JS_DeletePropertyById2 is the same but takes a JS::HandleId for the property name.

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 *succeeded is set to true and obj's JSClass.delProperty hook is called (which may change *succeeded). No property is deleted, but this is not an error.
  • If obj has the specified property but it is permanent, then *succeeded receives false. 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, *succeeded is set to true and obj's JSClass.delProperty hook is called (which may change *succeeded). If the hook returns false, the error is propagated. Otherwise, if obj is not configurable, an error is raised. Otherwise, *succeeded receives true and the property is removed.

These functions return true on success, regardless of whether a property was actually deleted. On error or exception, the return value is false, and the value left in *succeeded is unspecified.

JSObjectOps.deleteProperty implements this behavior.

(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.)

To remove all properties from an object, call JS_ClearScope.

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, fscholz, Jorend, Dria, MMondor
 Last updated by: arai,