This article needs a technical review. How you can help.
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 |
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 givenname
orid
, or ifobj
inherits the specified property from its prototype, then*succeeded
is set totrue
andobj
'sJSClass.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 ispermanent
, then*succeeded
receivesfalse
. No property is deleted, but this is not an error. - Otherwise
obj
has a non-permanent own property with the givenname
orid
. In this case,*succeeded
is set totrue
andobj
'sJSClass.delProperty
hook is called (which may change*succeeded
). If the hook returnsfalse
, the error is propagated. Otherwise, ifobj
is not configurable, an error is raised. Otherwise,*succeeded
receivestrue
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
.