name: duk_inspect_value

proto: |
  void duk_inspect_value(duk_context *ctx, duk_idx_t idx);

stack: |
  [ ... val! ... ] -> [ ... val! ... info! ]

summary: |
  <p>Inspect value at <code>idx</code> and push an object containing Duktape
  specific internal information about the object.  If the value stack index
  is invalid, pushes an object describing a "none" value.</p>

  <div include="inspect-versioning-guarantees.html" />

  <p>The following table summarizes current properties.  Memory byte sizes
  don't include any heap overhead which may vary between 0-16 bytes (or more)
  depending on the allocation functions being used.</p>

  <table>
  <thead>
  <tr><th>Property</th><th>Description</th></tr>
  </thead>
  <tbody>
  <tr>
  <td class="propname">type</td>
  <td>Type number matching <code>DUK_TYPE_xxx</code> from <code>duktape.h</code>.</td>
  </tr>
  <tr>
  <td class="propname">itag</td>
  <td>Internal type tag matching internal <code>DUK_TAG_xxx</code> defines.  Values
      may change between versions, and are dependent on config options and the
      memory layout used for tagged values internally.</td>
  </tr>
  <tr>
  <td class="propname">hptr</td>
  <td>Heap pointer for a heap-allocated value.  Points to the internal Duktape
      header structure related to the value type.  Same value would be returned
      from <code>duk_get_heapptr()</code>.</td>
  </tr>
  <tr>
  <td class="propname">refc</td>
  <td>Reference count.  Reference counts are not adjusted in any way, and
      include references to the value caused by the <code>duk_inspect_value()</code>
      call.</td>
  </tr>
  <tr>
  <td class="propname">class</td>
  <td>For objects, internal class number, matches internal
      <code>DUK_HOBJECT_CLASS_xxx</code> defines.</td>
  </tr>
  <tr>
  <td class="propname">hbytes</td>
  <td>Byte size of main heap object allocation.  For some values this is
      the only allocation, other values have additional allocations.</td>
  </tr>
  <tr>
  <td class="propname">pbytes</td>
  <td>Byte size of an object's property table.  The property table includes
      a possible array part, a possible hash part, and a key/value entry part.</td>
  </tr>
  <tr>
  <td class="propname">bcbytes</td>
  <td>Byte size of Ecmascript function bytecode (instructions, constants).
      Shared between all instances (closures) of a certain function template.</td>
  </tr>
  <tr>
  <td class="propname">dbytes</td>
  <td>Byte size of the current allocation of a dynamic or external buffer.
      Note that external buffer allocations are not part of the Duktape heap.</td>
  </tr>
  <tr>
  <td class="propname">esize</td>
  <td>Object entry part size in elements.</td>
  </tr>
  <tr>
  <td class="propname">enext</td>
  <td>Object entry part first free index (= index of next property slot to be
      used).  In practice matches number of own properties for objects that
      don't have uncompacted deleted keys.</td>
  </tr>
  <tr>
  <td class="propname">asize</td>
  <td>Object array part size in elements, zero if no array part or array part
      has been abandoned (sparse array).  May be larger or smaller than the
      apparent array <code>.length</code>.</td>
  </tr>
  <tr>
  <td class="propname">hsize</td>
  <td>Object hash part size in elements.</td>
  </tr>
  <tr>
  <td class="propname">tstate</td>
  <td>Internal thread state, matches internal <code>DUK_HTHREAD_STATE_xxx</code>
      defines.</td>
  </tr>
  <tr>
  <td class="propname">variant</td>
  <td>Identifies type variants for certain types.  For strings, variant 0 is
      an ordinary heap allocated string while variant 1 is an external string.
      For buffers, variant 0 is a fixed buffer, 1 is a dynamic buffer, and 2
      is an external buffer.</td>
  </tr>
  </tbody>
  </table>

example: |
  duk_inspect_value(ctx, -3);
  duk_get_prop_string(ctx, -1, "refc");
  printf("refcount of value at -3: %ld\n", (long) duk_to_int(ctx, -1));
  duk_pop_2(ctx);

tags:
  - stack
  - inspect

introduced: 2.0.0