name: duk_enum

proto: |
  void duk_enum(duk_context *ctx, duk_idx_t obj_idx, duk_uint_t enum_flags);

stack: |
  [ ... obj! ... ] -> [ ... obj! ... enum! ]

summary: |
  <p>Create an enumerator for object at <code>obj_idx</code>.  Enumeration
  details can be controlled with <code>enum_flags</code>.  If the target value
  is not an object, throws an error.</p>

  <p>Enumeration flags:</p>
  <table>
  <tr>
  <td>DUK_ENUM_INCLUDE_NONENUMERABLE</td>
  <td>Enumerate also non-enumerable properties, by default only enumerable
      properties are enumerated.</td>
  </tr>
  <tr>
  <td>DUK_ENUM_INCLUDE_HIDDEN</td>
  <td>Enumerate also hidden Symbols, by default hidden Symbols are not
      enumerated.  Use together with <code>DUK_ENUM_INCLUDE_SYMBOLS</code>.
      In Duktape 1.x this flag was called <code>DUK_ENUM_INCLUDE_INTERNAL</code>.</td>
  </tr>
  <tr>
  <td>DUK_ENUM_INCLUDE_SYMBOLS</td>
  <td>Include Symbols in the enumeration result.  Hidden Symbols are not
      included unless <code>DUK_ENUM_INCLUDE_HIDDEN</code> is specified.</td>
  </tr>
  <tr>
  <td>DUK_ENUM_EXCLUDE_STRINGS</td>
  <td>Exclude strings from the enumeration result.  By default strings are
      included.</td>
  </tr>
  <tr>
  <td>DUK_ENUM_OWN_PROPERTIES_ONLY</td>
  <td>Enumerate only an object's "own" properties, by default also inherited
      properties are enumerated.</td>
  </tr>
  <tr>
  <td>DUK_ENUM_ARRAY_INDICES_ONLY</td>
  <td>Enumerate only array indices, i.e. property names of the form "0", "1",
      "2", etc.</td>
  </tr>
  <tr>
  <td>DUK_ENUM_SORT_ARRAY_INDICES</td>
  <td>Apply the ES2015 [[OwnPropertyKeys]] enumeration order over the whole
      enumeration result rather than per inheritance level, this has the
      effect of sorting array indices (even when inherited).  Also symbols
      are sorted after ordinary string keys (both in insertion order).</td>
  </tr>
  <tr>
  <td>DUK_ENUM_NO_PROXY_BEHAVIOR</td>
  <td>Enumerate a Proxy object itself without invoking Proxy behaviors.</td>
  </tr>
  </table>

  <p>Without any flags the enumeration behaves like <code>for-in</code>:
  own and inherited enumerable properties are included, and enumeration
  order follows the
  <a href="http://www.ecma-international.org/ecma-262/6.0/#sec-ordinary-object-internal-methods-and-internal-slots-ownpropertykeys">ECMAScript ES2015 [[OwnPropertyKeys]]</a>
  enumeration order, applied for each inheritance level.</p>

  <p>Once the enumerator has been created, use
  <code><a href="#duk_next">duk_next()</a></code> to extract keys (or key/value
  pairs) from the enumerator.</p>

  <div class="note">
  The ES2015 [[OwnPropertyKeys]] enumeration order is:
  (1) array indices in ascending order, (2) non-array-index keys in their
  insertion order, and (3) symbols in their insertion order.  This rule
  is applied separately for each inheritance level, so that if array index
  keys are inherited, they will appear out-of-order in the result.  For
  most practical code this is not an issue because array indices are very
  rarely inherited.  You can force the whole enumeration sequence to be
  sorted using <code>DUK_ENUM_SORT_ARRAY_INDICES</code>.
  </div>

example: |
  duk_enum(ctx, -3, DUK_ENUM_INCLUDE_NONENUMERABLE);

  while (duk_next(ctx, -1 /*enum_idx*/, 0 /*get_value*/)) {
      /* [ ... enum key ] */
      printf("-> key %s\n", duk_get_string(ctx, -1));
      duk_pop(ctx);  /* pop_key */
  }

  duk_pop(ctx);  /* pop enum object */

tags:
  - object
  - property

seealso:
  - duk_next

introduced: 1.0.0