name: duk_put_prop

proto: |
  duk_bool_t duk_put_prop(duk_context *ctx, duk_idx_t obj_index);

stack: |
  [ ... obj! ... key! val! ] -> [ ... obj! ... ]

summary: |
  <p>Write <code>val</code> to the property <code>key</code> of a value at
  <code>obj_index</code>.  <code>key</code> and <code>val</code> are removed
  from the stack.  Return code and error throwing behavior:</p>
  <ul>
  <li>If the property write succeeds, returns <code>1</code>.</li>
  <li>If the property write fails, throws an error (strict mode semantics).
      An error may also be thrown by the "setter" function of an accessor property.</li>
  <li>If the value at <code>obj_index</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_index</code> is invalid, throws an error.</li>
  </ul>

  <p>The property write is equivalent to the Ecmascript expression:</p>
  <pre class="ecmascript-code">
  obj[key] = val
  </pre>

  <p>The exact rules of when a property write succeeds or fails are the same
  as for Ecmascript code making the above assignment.</p>

  <p>For 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.2">PutValue (V, W)</a>,
  and <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.12.5">[[Put]] (P, V, Throw)</a>.
  Both the target value and the <code>key</code> are coerced:</p>
  <ul>
  <li>The target value is automatically coerced to an object.  However, the object
      is transitory so writing its properties is not very useful.  Moreover,
      Ecmascript semantics prevent new properties from being created for such
      transitory objects (see
      <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.7.2">PutValue (V, W)</a>,
      step 7 of the special [[Put]] variant).</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.</p>
  </ul>

  <div class="note">
  In Ecmascript an assignment expression has the value of the right-hand-side
  expression, regardless of whether or not the assignment succeeds.  The return
  value for this API call is not specified by Ecmascript or available to
  Ecmascript code: the API call returns <code>0</code> or <code>1</code>
  depending on whether the assignment succeeded or not (with the <code>0</code>
  return value promoted to an error in strict code).
  </div>

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

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

example: |
  duk_bool_t rc;

  duk_push_string(ctx, "key");
  duk_push_string(ctx, "value");
  rc = duk_put_prop(ctx, -3);
  printf("rc=%d\n", (int) rc);

tags:
  - property

seealso:
  - duk_put_prop_string
  - duk_put_prop_index

introduced: 1.0.0