name: duk_push_error_object

proto: |
  duk_idx_t duk_push_error_object(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...);

stack: |
  [ ... ] -> [ ... err! ]

summary: |
  <p>Create a new error object and push it to the value stack (the error is not thrown).
  Returns non-negative index (relative to stack bottom) of the pushed error object.</p>

  <p>The <code>message</code> property of the error object will be set to a <code>sprintf</code>-formatted
  string using <code>fmt</code> and the remaining arguments.  The internal prototype for the created
  error object is chosen based on <code>err_code</code>.  For instance, <code>DUK_ERR_RANGE_ERROR</code>
  causes the built-in <code>RangeError</code> prototype to be used.  The valid range for user error
  codes is [1,16777215].</p>

example: |
  duk_idx_t err_idx;

  err_idx = duk_push_error_object(ctx, DUK_ERR_TYPE_ERROR, "invalid argument value: %d", arg_value);

tags:
  - stack
  - object
  - error

seealso:
  - duk_push_error_object_va

introduced: 1.0.0