name: duk_throw

proto: |
  duk_ret_t duk_throw(duk_context *ctx);

stack: |
  [ ... val! ]

summary: |
  <p>Throw the value on top of the stack.  This call never returns.</p>

  <p>Even though the function never returns, the prototype describes a return
  value which allows code such as:</p>
  <pre class="c-code">
  if (argvalue &lt; 0) {
      duk_push_error_object(ctx, DUK_ERR_TYPE_ERROR, "invalid argument: %d", (int) argvalue);
      return duk_throw(ctx);
  }
  </pre>

  <p>If the return value is ignored, cast to void to avoid compilation
  warnings:</p>
  <pre class="c-code">
  if (argvalue &lt; 0) {
      duk_push_error_object(ctx, DUK_ERR_TYPE_ERROR, "invalid argument: %d", (int) argvalue);
      (void) duk_throw(ctx);
  }
  </pre>

example: |
  /* Throw a string value; equivalent to the ECMAScript code:
   *
   *   throw "this string is thrown";
   */

  duk_push_string(ctx, "this string is thrown");
  (void) duk_throw(ctx);

tags:
  - error

seealso:
  - duk_error
  - duk_push_error_object

introduced: 1.0.0