JS_Enumerate

Get an array of the enumerable properties of a given object.

Syntax

JSIdArray *
JS_Enumerate(JSContext *cx, JS::HandleObject obj);
Name Type Description
cx JSContext * The context in which to enumerate object properties. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
obj JS::HandleObject The object whose properties are to be enumerated.

Description

JS_Enumerate gets the ids of all own properties of the specified object, obj, that have the JSPROP_ENUMERATE attribute. (The term own property refers to a property that is not inherited from the object's prototype.) This is not quite the same behavior as a JavaScript for...in loop, which converts all property ids to strings and also enumerates inherited properties.

This calls obj's JSClass.enumerate hook.

On success, JS_Enumerate returns a pointer to the first element of an array of property IDs. The application must free this array using JS_DestroyIdArray. On error or exception, JS_Enumerate returns NULL.

The property ids in the returned JSIdArray are subject to garbage collection. As long as obj is reachable, its current property ids are reachable. But, for example, if an application calls back into JavaScript while it is looping over the property ids in the JSIdArray, the script could delete properties from obj. The property ids would then become unreachable and could be collected. Therefore a program that loops over the property ids must either root them all, ensure that the properties are not deleted (in a multithreaded program this requires even greater care), or ensure that garbage collection does not occur.

See Also