name: duk_substring

proto: |
  void duk_substring(duk_context *ctx, duk_idx_t idx, duk_size_t start_char_offset, duk_size_t end_char_offset);

stack: |
  [ ... str! ... ] -> [ ... substr! ... ]

summary: |
  <p>Replace a string at <code>idx</code> with a substring [<code>start_char_offset</code>,
  <code>end_char_offset</code>[ of the string itself.  If the value at <code>idx</code> is
  not a string or the index is invalid, throws an error.</p>

  <p>The substring operation works with characters, not bytes, and the offsets
  are character offsets.  The semantics of this call are similar to
  <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-15.5.4.15">String.prototype.substring (start, end)</a>.
  Offset values are clamped to string length (there is no need to clamp negative
  values because <code>size_t</code> is unsigned) and if start offset is larger than
  end offset, the result is an empty string.</p>

  <div class="note">
  To get a byte-oriented substring, use
  <code><a href="#duk_get_lstring">duk_get_lstring()</a></code> to get a string data
  pointer and length, and
  <code><a href="#duk_push_lstring">duk_push_lstring()</a></code> to push a slice of
  bytes.
  </div>

example: |
  /* String at index -3 is 'foobar'.  Substring [2,5[ is "oba". */

  duk_substring(ctx, -3, 2, 5);
  printf("substring: %s\n", duk_get_string(ctx, -3));

tags:
  - string

introduced: 1.0.0