name: duk_get_prop

proto: |
  duk_bool_t duk_get_prop(duk_context *ctx, duk_idx_t obj_idx);

stack: |
  [ ... obj! ... key! ] -> [ ... obj! ... val! ]  (if key exists)
  [ ... obj! ... key! ] -> [ ... obj! ... undefined! ]  (if key doesn't exist)

summary: |
  <p>Get the property <code>key</code> of a value at <code>obj_idx</code>.
  Return code and error throwing behavior:</p>
  <ul>
  <li>If the property exists, <code>1</code> is returned and <code>key</code>
      is replaced by the property value on the value stack.  However,
      if the property is an accessor, the "getter" function may throw
      an error.</li>
  <li>If the property does not exist, 0 is returned and <code>key</code>
      is replaced by <code>undefined</code> on the value stack.</li>
  <li>If the value at <code>obj_idx</code> is not
      <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-9.10">object coercible</a>,
      throws an error.</li>
  <li>If <code>obj_idx</code> is invalid, throws an error.</li>
  </ul>

  <p>The property read is equivalent to the Ecmascript expression
  <code>res = obj[key]</code> with the exception that the presence or absence of the
  property is indicated by the call return value.  For precise semantics, see
  <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.2.1">Property Accessors</a>,
  <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.7.1">GetValue (V)</a>,
  and <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.12.3">[[Get]] (P)</a>.
  Both the target value and the <code>key</code> are coerced:</p>
  <ul>
  <li>The target value is automatically coerced to an object.  For instance,
      a string is converted to a <code>String</code> and you can access its
      <code>"length"</code> property.</li>
  <li>The <code>key</code> argument is internally coerced to a string.  There is
      an internal fast path for arrays and numeric indices which avoids an
      explicit string coercion, so use a numeric <code>key</code> when applicable.</li>
  </ul>

  <p>If the target is a Proxy object which implements the <code>get</code> trap,
  the trap is invoked and the API call always returns 1 (i.e. property present): the
  absence/presence of properties is not indicated by the <code>get</code> Proxy
  trap.  Thus, the API call return value may be of limited use if the target
  object is potentially a Proxy.</p>

  <p>If the key is a fixed string you can avoid one API call and use the
  <code><a href="#duk_get_prop_string">duk_get_prop_string()</a></code> variant.
  Similarly, if the key is an array index, you can use the
  <code><a href="#duk_get_prop_index">duk_get_prop_index()</a></code> variant.</p>

  <div include="object-can-be-any-value.html" />

example: |
  /* reading [global object].Math.PI */
  duk_push_global_object(ctx);    /* -> [ global ] */
  duk_push_string(ctx, "Math");   /* -> [ global "Math" ] */
  duk_get_prop(ctx, -2);          /* -> [ global Math ] */
  duk_push_string(ctx, "PI");     /* -> [ global Math "PI" ] */
  duk_get_prop(ctx, -2);          /* -> [ global Math PI ] */
  printf("Math.PI is %lf\n", (double) duk_get_number(ctx, -1));
  duk_pop_n(ctx, 3);

  /* reading a configuration value, cfg_idx is normalized
   * index of a configuration object.
   */
  duk_push_string(ctx, "mySetting");
  if (duk_get_prop(ctx, cfg_idx)) {
      const char *str_value = duk_to_string(ctx, -1);
      printf("configuration setting present, value: %s\n", str_value);
  } else {
      printf("configuration setting missing\n");
  }
  duk_pop(ctx);  /* remember to pop, regardless of whether or not present */

tags:
  - property

seealso:
  - duk_get_prop_string
  - duk_get_prop_index

introduced: 1.0.0