duktape/website/api/duk_put_prop.yaml

=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