mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
79 lines
3.2 KiB
79 lines
3.2 KiB
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
|
|
|