name: duk_replace

proto: |
  void duk_replace(duk_context *ctx, duk_idx_t to_idx);

stack: |
  [ ... old(to_idx)! ... val! ] -> [ ... val(to_idx)! ... ]

summary: |
  <p>Replace value at <code>to_idx</code> with a value popped from the
  stack top.  If <code>to_idx</code> is an invalid index, throws an error.</p>

  <div class="note">
  Negative indices are evaluated prior to popping the value at the stack
  top.  This is also illustrated by the example.
  </div>

example: |
  duk_push_int(ctx, 123);
  duk_push_int(ctx, 234);
  duk_push_int(ctx, 345);       /* -> [ 123 234 345 ] */
  duk_push_string(ctx, "foo");  /* -> [ 123 234 345 "foo" ] */
  duk_replace(ctx, -3);         /* -> [ 123 "foo" 345 ] */

tags:
  - stack

seealso:
  - duk_insert

introduced: 1.0.0