duktape/website/api/duk_push_literal.yaml

name: duk_push_literal

proto: |
  const char *duk_push_literal(duk_context *ctx, const char *str_literal);

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

summary: |
  <p>Push a C literal into the stack and return a pointer to the interned
  string data area (which may or may not be the same as the argument literal).
  The argument <code>str_literal</code>:</p>
  <ul>
  <li>must be a non-NULL C literal like <code>"foo"</code> which can be operated
      on using e.g. <code>sizeof(str)</code>, where sizeof() yields string
      length, including the automatic NUL terminator (for example, sizeof("foo")
      is 4);</li>
  <li>must have immutable data contents, i.e. read-only memory, or writable
      memory but guaranteed not to be changed; and</li>
  <li>must not contain internal NUL characters, and must have a terminating
      NUL as usual for C strings.</li>
  </ul>

  <p>The <code>str_literal</code> argument may be evaluated multiple times by
  the API macro.  No runtime NULL pointer check is made for the
  <code>str_literal</code> argument so passing in a NULL causes memory unsafe
  behavior.</p>

  <p>This call is conceptually equivalent to duk_push_string().  Calling code
  only needs to use it if the minor differences in footprint or speed
  matter.  The properties of immutable C literals allows minor optimizations
  in Duktape internals:</p>
  <ul>
  <li>The length of the string can be computed at compile time using
      <code>sizeof(str_literal) - 1</code> at the call site.</li>
  <li>By default heap strings accessed via C literals (duk_push_literal()
      or any of the literal convenience calls like duk_get_prop_literal())
      are automatically pinned until the next mark-and-sweep round, and
      there's a lookup cache for mapping a C literal address to the pinned
      internal heap string.  This optimization doesn't assume string
      deduplication (which is common but not guaranteed), i.e. there may be
      multiple addresses with the same literal data.</li>
  <li>Because the string data is assumed to be immutable, the internal
      string representation could just point to the data instead of
      making a copy.  (This optimization is not done as of Duktape 2.3.)</li>
  </ul>

  <p>If input string might contain internal NUL characters, use
  <code><a href="#duk_push_lstring">duk_push_lstring()</a></code> instead.
  For <code>duk_push_literal()</code> handling of embedded NULs depends
  on config options and calling code should never rely on the behavior.</p>

example: |
  /* Basic case. */
  duk_push_literal(ctx, "foo");

  /* Argument may involve compile time concatenation and parentheses. */
  duk_push_literal(ctx, ("foo" "bar"));

  /* Argument may also be e.g. DUK_HIDDEN_SYMBOL() which produces a literal. */
  duk_push_literal(ctx, DUK_HIDDEN_SYMBOL("mySymbol"));

tags:
  - stack
  - literal
  - experimental

introduced: 2.3.0