JSNewEnumerateOp

The type of ObjectOps::enumerate. This callback overrides a portion of SpiderMonkey's default [[Enumerate]] internal method.

Syntax

typedef bool
(* JSNewEnumerateOp)(JSContext *cx, JS::HandleObject obj,
                     JS::AutoIdVector &properties); // Added in SpiderMonkeySidebar 38
typedef bool
(* JSNewEnumerateOp)(JSContext *cx, JS::HandleObject obj, JSIterateOp enum_op,
                     JS::MutableHandleValue statep, JS::MutableHandleId idp); // Obsolete since JSAPI 37
Name Type Description
cx JSContext * The context in which the enumeration is taking place.
obj JS::HandleObject The object to be enumerated.
properties JS::AutoIdVector & Out parameter. Id array to populate with all property keys.
enum_op JSIterateOp Obsolete since JSAPI 37 Specifies which step in iteration is happening. See the Description below.
statep JS::MutableHandleId Obsolete since JSAPI 37 In/out parameter. The meaning depends on enum_op. See the Description below.
idp JS::MutableHandleId Obsolete since JSAPI 37 In/out parameter. The meaning depends on enum_op. See the Description below.

Description

From SpiderMonkey 38, JSNewEnumerateOp is the type of ObjectOps::enumerate. This callback overrides a portion of SpiderMonkey's default [[Enumerate]] internal method. When an ordinary object is enumerated, that object and each object on its prototype chain is tested for an enumerate op, and those ops are called in order. The properties each op adds to the properties vector are added to the set of values the for-in loop will iterate over. All of this is nonstandard.

An object is "enumerated" when it's the target of a for-in loop or JS_Enumerate. All other property inspection, including Object.keys(obj), goes through [[OwnKeys]].

The callback's job is to populate properties with all property keys that the for-in loop should visit.

Before JSAPI 37, JSNewEnumerateOp was the type of JSClass.enumerate.

To use a JSNewEnumerateOp in a JSClass, set the JSCLASS_NEW_ENUMERATE bit in the JSClass.flags field and set the JSClass.enumerate field to your JSNewEnumerateOp, casting it to JSEnumerateOp. (SpiderMonkey, noting the JSCLASS_NEW_ENUMERATE flag, will cast that function pointer back to type JSNewEnumerateOp before calling it.)

The behavior depends on the value of enum_op:

JSENUMERATE_INIT

A new, opaque iterator state should be allocated and stored in *statep. (You can use PRIVATE_TO_JSVAL to tag the pointer to be stored).

The number of properties that will be enumerated should be returned as an integer jsval in *idp, if idp is non-null, and provided the number of enumerable properties is known. If idp is non-null and the number of enumerable properties can't be computed in advance, *idp should be set to JSVAL_ZERO.

JSENUMERATE_INIT_ALL
Used identically to JSENUMERATE_INIT, but exposes all properties of the object regardless of enumerability.
JSENUMERATE_NEXT

A previously allocated opaque iterator state is passed in via statep. Return the next jsid in the iteration using *idp. The opaque iterator state pointed at by statep is destroyed and *statep is set to JSVAL_NULL if there are no properties left to enumerate.

JSENUMERATE_DESTROY

Destroy the opaque iterator state previously allocated in *statep by a call to this function when enum_op was JSENUMERATE_INIT or JSENUMERATE_INIT_ALL.

The return value is used to indicate success, with a value of false indicating failure.

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: kscarfone, arai
 Last updated by: kscarfone,