mirror of https://github.com/svaarala/duktape.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
68 lines
2.8 KiB
68 lines
2.8 KiB
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
|
|
|