mirror of https://github.com/svaarala/duktape.git
Sami Vaarala
10 years ago
490 changed files with 8119 additions and 7763 deletions
@ -1,35 +0,0 @@ |
|||
=proto |
|||
void *duk_alloc(duk_context *ctx, duk_size_t size); |
|||
|
|||
=summary |
|||
<p>Like <code><a href="#duk_alloc_raw">duk_alloc_raw()</a></code> but may trigger |
|||
a garbage collection to satisfy the request. However, the allocated memory |
|||
itself is not automatically garbage collected. The allocation request may |
|||
fail even after garbage collection, in which case a <code>NULL</code> is returned. |
|||
The allocated memory is not automatically zeroed, and may contain arbitrary garbage.</p> |
|||
|
|||
<p>Memory allocated with <code>duk_alloc()</code> can be freed with either |
|||
<code><a href="#duk_free">duk_free()</a></code> or |
|||
<code><a href="#duk_free_raw">duk_free_raw()</a></code>.</p> |
|||
|
|||
=example |
|||
/* Although duk_alloc() triggers a GC if necessary, it can still fail to |
|||
* allocate the desired amount of memory. Caller must check for NULL |
|||
* (however, if allocation size is 0, a NULL may be returned even in |
|||
* a success case). |
|||
*/ |
|||
void *buf = duk_alloc(ctx, 1024); |
|||
if (buf) { |
|||
printf("allocation successful: %p\n", buf); |
|||
} else { |
|||
printf("allocation failed\n"); |
|||
} |
|||
|
|||
=tags |
|||
memory |
|||
|
|||
=seealso |
|||
duk_alloc_raw |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,36 @@ |
|||
name: duk_alloc |
|||
|
|||
proto: | |
|||
void *duk_alloc(duk_context *ctx, duk_size_t size); |
|||
|
|||
summary: | |
|||
<p>Like <code><a href="#duk_alloc_raw">duk_alloc_raw()</a></code> but may trigger |
|||
a garbage collection to satisfy the request. However, the allocated memory |
|||
itself is not automatically garbage collected. The allocation request may |
|||
fail even after garbage collection, in which case a <code>NULL</code> is returned. |
|||
The allocated memory is not automatically zeroed, and may contain arbitrary garbage.</p> |
|||
|
|||
<p>Memory allocated with <code>duk_alloc()</code> can be freed with either |
|||
<code><a href="#duk_free">duk_free()</a></code> or |
|||
<code><a href="#duk_free_raw">duk_free_raw()</a></code>.</p> |
|||
|
|||
example: | |
|||
/* Although duk_alloc() triggers a GC if necessary, it can still fail to |
|||
* allocate the desired amount of memory. Caller must check for NULL |
|||
* (however, if allocation size is 0, a NULL may be returned even in |
|||
* a success case). |
|||
*/ |
|||
void *buf = duk_alloc(ctx, 1024); |
|||
if (buf) { |
|||
printf("allocation successful: %p\n", buf); |
|||
} else { |
|||
printf("allocation failed\n"); |
|||
} |
|||
|
|||
tags: |
|||
- memory |
|||
|
|||
seealso: |
|||
- duk_alloc_raw |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,32 +0,0 @@ |
|||
=proto |
|||
void *duk_alloc_raw(duk_context *ctx, duk_size_t size); |
|||
|
|||
=summary |
|||
<p>Allocate <code>size</code> bytes using the raw allocation function registered |
|||
to the context. If allocation fails, returns <code>NULL</code>. If <code>size</code> |
|||
is zero, the call may either return a <code>NULL</code> or some non-<code>NULL</code> |
|||
value which may be safely given to e.g. <code>duk_free_raw()</code>. The allocation |
|||
cannot trigger a garbage collection, and the allocated memory is not automatically |
|||
garbage collected. The allocated memory is not automatically zeroed, and may contain |
|||
arbitrary garbage.</p> |
|||
|
|||
<p>Memory allocated with <code>duk_alloc_raw()</code> can be freed with either |
|||
<code><a href="#duk_free">duk_free()</a></code> or |
|||
<code><a href="#duk_free_raw">duk_free_raw()</a></code>.</p> |
|||
|
|||
=example |
|||
void *buf = duk_alloc_raw(ctx, 1024); |
|||
if (buf) { |
|||
printf("allocation successful: %p\n", buf); |
|||
} else { |
|||
printf("allocation failed\n"); |
|||
} |
|||
|
|||
=tags |
|||
memory |
|||
|
|||
=seealso |
|||
duk_alloc |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,33 @@ |
|||
name: duk_alloc_raw |
|||
|
|||
proto: | |
|||
void *duk_alloc_raw(duk_context *ctx, duk_size_t size); |
|||
|
|||
summary: | |
|||
<p>Allocate <code>size</code> bytes using the raw allocation function registered |
|||
to the context. If allocation fails, returns <code>NULL</code>. If <code>size</code> |
|||
is zero, the call may either return a <code>NULL</code> or some non-<code>NULL</code> |
|||
value which may be safely given to e.g. <code>duk_free_raw()</code>. The allocation |
|||
cannot trigger a garbage collection, and the allocated memory is not automatically |
|||
garbage collected. The allocated memory is not automatically zeroed, and may contain |
|||
arbitrary garbage.</p> |
|||
|
|||
<p>Memory allocated with <code>duk_alloc_raw()</code> can be freed with either |
|||
<code><a href="#duk_free">duk_free()</a></code> or |
|||
<code><a href="#duk_free_raw">duk_free_raw()</a></code>.</p> |
|||
|
|||
example: | |
|||
void *buf = duk_alloc_raw(ctx, 1024); |
|||
if (buf) { |
|||
printf("allocation successful: %p\n", buf); |
|||
} else { |
|||
printf("allocation failed\n"); |
|||
} |
|||
|
|||
tags: |
|||
- memory |
|||
|
|||
seealso: |
|||
- duk_alloc |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,28 +0,0 @@ |
|||
=proto |
|||
void duk_base64_decode(duk_context *ctx, duk_idx_t index); |
|||
|
|||
=stack |
|||
[ ... base64_val! ... ] -> [ ... val! ... ] |
|||
|
|||
=summary |
|||
<p>Decodes a base-64 encoded value into a buffer as an in-place operation. |
|||
If the input is invalid, throws an error.</p> |
|||
|
|||
=example |
|||
duk_push_string(ctx, "Zm9v"); |
|||
duk_base64_decode(ctx, -1); /* buffer */ |
|||
printf("base-64 decoded: %s\n", duk_to_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
/* Output: |
|||
* base-64 decoded: foo |
|||
*/ |
|||
|
|||
=tags |
|||
codec |
|||
|
|||
=seealso |
|||
duk_base64_encode |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,29 @@ |
|||
name: duk_base64_decode |
|||
|
|||
proto: | |
|||
void duk_base64_decode(duk_context *ctx, duk_idx_t index); |
|||
|
|||
stack: | |
|||
[ ... base64_val! ... ] -> [ ... val! ... ] |
|||
|
|||
summary: | |
|||
<p>Decodes a base-64 encoded value into a buffer as an in-place operation. |
|||
If the input is invalid, throws an error.</p> |
|||
|
|||
example: | |
|||
duk_push_string(ctx, "Zm9v"); |
|||
duk_base64_decode(ctx, -1); /* buffer */ |
|||
printf("base-64 decoded: %s\n", duk_to_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
/* Output: |
|||
* base-64 decoded: foo |
|||
*/ |
|||
|
|||
tags: |
|||
- codec |
|||
|
|||
seealso: |
|||
- duk_base64_encode |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,33 +0,0 @@ |
|||
=proto |
|||
const char *duk_base64_encode(duk_context *ctx, duk_idx_t index); |
|||
|
|||
=stack |
|||
[ ... val! ... ] -> [ ... base64_val! ... ] |
|||
|
|||
=summary |
|||
<p>Coerces an arbitrary value into a buffer and then encodes the result |
|||
into base-64 as an in-place operation. Returns a pointer to the resulting |
|||
string for convenience.</p> |
|||
|
|||
<div class="note"> |
|||
Coercing to a buffer first coerces a non-buffer value into a string, and |
|||
then coerces the string into a buffer. The resulting buffer contains the |
|||
string in CESU-8 encoding. |
|||
</div> |
|||
|
|||
=example |
|||
duk_push_string(ctx, "foo"); |
|||
printf("base-64 encoded: %s\n", duk_base64_encode(ctx, -1)); |
|||
|
|||
/* Output: |
|||
* base-64 encoded: Zm9v |
|||
*/ |
|||
|
|||
=tags |
|||
codec |
|||
|
|||
=seealso |
|||
duk_base64_decode |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,34 @@ |
|||
name: duk_base64_encode |
|||
|
|||
proto: | |
|||
const char *duk_base64_encode(duk_context *ctx, duk_idx_t index); |
|||
|
|||
stack: | |
|||
[ ... val! ... ] -> [ ... base64_val! ... ] |
|||
|
|||
summary: | |
|||
<p>Coerces an arbitrary value into a buffer and then encodes the result |
|||
into base-64 as an in-place operation. Returns a pointer to the resulting |
|||
string for convenience.</p> |
|||
|
|||
<div class="note"> |
|||
Coercing to a buffer first coerces a non-buffer value into a string, and |
|||
then coerces the string into a buffer. The resulting buffer contains the |
|||
string in CESU-8 encoding. |
|||
</div> |
|||
|
|||
example: | |
|||
duk_push_string(ctx, "foo"); |
|||
printf("base-64 encoded: %s\n", duk_base64_encode(ctx, -1)); |
|||
|
|||
/* Output: |
|||
* base-64 encoded: Zm9v |
|||
*/ |
|||
|
|||
tags: |
|||
- codec |
|||
|
|||
seealso: |
|||
- duk_base64_decode |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,53 +0,0 @@ |
|||
=proto |
|||
void duk_call(duk_context *ctx, duk_idx_t nargs); |
|||
|
|||
=stack |
|||
[ ... func! arg1! ...! argN! ] -> [ ... retval! ] |
|||
|
|||
=summary |
|||
<p>Call target function <code>func</code> with <code>nargs</code> arguments |
|||
(not counting the function itself). The function and its arguments |
|||
are replaced by a single return value. An error thrown during the |
|||
function call is not automatically caught. |
|||
</p> |
|||
|
|||
<p>The target function <code>this</code> binding is initially set to |
|||
<code>undefined</code>. If the target function is not strict, the binding |
|||
is replaced by the global object before the function is invoked; see |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">Entering Function Code</a>. |
|||
If you want to control the <code>this</code> binding, you can use |
|||
<code><a href="#duk_call_method">duk_call_method()</a></code> or |
|||
<code><a href="#duk_call_prop">duk_call_prop()</a></code> instead.</p> |
|||
|
|||
<p>This API call is equivalent to:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = func(arg1, ..., argN); |
|||
</pre> |
|||
|
|||
<p>or:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = func.call(undefined, arg1, ..., argN); |
|||
</pre> |
|||
|
|||
=example |
|||
/* Assume target function is already on stack at func_idx; the target |
|||
* function adds arguments and returns the result. |
|||
*/ |
|||
duk_idx_t func_idx = /* ... */; |
|||
|
|||
duk_dup(ctx, func_idx); |
|||
duk_push_int(ctx, 2); |
|||
duk_push_int(ctx, 3); |
|||
duk_call(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */ |
|||
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
call |
|||
|
|||
=seealso |
|||
duk_call_method |
|||
duk_call_prop |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,54 @@ |
|||
name: duk_call |
|||
|
|||
proto: | |
|||
void duk_call(duk_context *ctx, duk_idx_t nargs); |
|||
|
|||
stack: | |
|||
[ ... func! arg1! ...! argN! ] -> [ ... retval! ] |
|||
|
|||
summary: | |
|||
<p>Call target function <code>func</code> with <code>nargs</code> arguments |
|||
(not counting the function itself). The function and its arguments |
|||
are replaced by a single return value. An error thrown during the |
|||
function call is not automatically caught. |
|||
</p> |
|||
|
|||
<p>The target function <code>this</code> binding is initially set to |
|||
<code>undefined</code>. If the target function is not strict, the binding |
|||
is replaced by the global object before the function is invoked; see |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">Entering Function Code</a>. |
|||
If you want to control the <code>this</code> binding, you can use |
|||
<code><a href="#duk_call_method">duk_call_method()</a></code> or |
|||
<code><a href="#duk_call_prop">duk_call_prop()</a></code> instead.</p> |
|||
|
|||
<p>This API call is equivalent to:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = func(arg1, ..., argN); |
|||
</pre> |
|||
|
|||
<p>or:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = func.call(undefined, arg1, ..., argN); |
|||
</pre> |
|||
|
|||
example: | |
|||
/* Assume target function is already on stack at func_idx; the target |
|||
* function adds arguments and returns the result. |
|||
*/ |
|||
duk_idx_t func_idx = /* ... */; |
|||
|
|||
duk_dup(ctx, func_idx); |
|||
duk_push_int(ctx, 2); |
|||
duk_push_int(ctx, 3); |
|||
duk_call(ctx, 2); /* [ ... func 2 3 ] -> [ 5 ] */ |
|||
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- call |
|||
|
|||
seealso: |
|||
- duk_call_method |
|||
- duk_call_prop |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,48 +0,0 @@ |
|||
=proto |
|||
void duk_call_method(duk_context *ctx, duk_idx_t nargs); |
|||
|
|||
=stack |
|||
[ ... func! this! arg! ...! argN! ] -> [ ... retval! ] |
|||
|
|||
=summary |
|||
<p>Call target function <code>func</code> with an explicit <code>this</code> |
|||
binding and <code>nargs</code> arguments (not counting the function and |
|||
the <code>this</code> binding value). The function object, the <code>this</code> |
|||
binding value, and the function arguments are replaced by a single |
|||
return value. An error thrown during the function call is not |
|||
automatically caught.</p> |
|||
|
|||
<p>If the target function is not strict, the binding value seen by the |
|||
target function may be modified by processing specified in |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">Entering Function Code</a>. |
|||
</p> |
|||
|
|||
<p>This API call is equivalent to:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = func.call(this_binding, arg1, ..., argN); |
|||
</pre> |
|||
|
|||
=example |
|||
/* The target function here prints: |
|||
* |
|||
* this: 123 |
|||
* 2 3 |
|||
* |
|||
* and returns 5. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "function(x,y) { print('this:', this); " |
|||
"print(x,y); return x+y; }"); |
|||
duk_eval(ctx); /* -> [ ... func ] */ |
|||
duk_push_int(ctx, 123); |
|||
duk_push_int(ctx, 2); |
|||
duk_push_int(ctx, 3); |
|||
duk_call_method(ctx, 2); /* [ ... func 123 2 3 ] -> [ 5 ] */ |
|||
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); /* prints 5 */ |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
call |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,49 @@ |
|||
name: duk_call_method |
|||
|
|||
proto: | |
|||
void duk_call_method(duk_context *ctx, duk_idx_t nargs); |
|||
|
|||
stack: | |
|||
[ ... func! this! arg! ...! argN! ] -> [ ... retval! ] |
|||
|
|||
summary: | |
|||
<p>Call target function <code>func</code> with an explicit <code>this</code> |
|||
binding and <code>nargs</code> arguments (not counting the function and |
|||
the <code>this</code> binding value). The function object, the <code>this</code> |
|||
binding value, and the function arguments are replaced by a single |
|||
return value. An error thrown during the function call is not |
|||
automatically caught.</p> |
|||
|
|||
<p>If the target function is not strict, the binding value seen by the |
|||
target function may be modified by processing specified in |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">Entering Function Code</a>. |
|||
</p> |
|||
|
|||
<p>This API call is equivalent to:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = func.call(this_binding, arg1, ..., argN); |
|||
</pre> |
|||
|
|||
example: | |
|||
/* The target function here prints: |
|||
* |
|||
* this: 123 |
|||
* 2 3 |
|||
* |
|||
* and returns 5. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "function(x,y) { print('this:', this); " |
|||
"print(x,y); return x+y; }"); |
|||
duk_eval(ctx); /* -> [ ... func ] */ |
|||
duk_push_int(ctx, 123); |
|||
duk_push_int(ctx, 2); |
|||
duk_push_int(ctx, 3); |
|||
duk_call_method(ctx, 2); /* [ ... func 123 2 3 ] -> [ 5 ] */ |
|||
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); /* prints 5 */ |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- call |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,47 +0,0 @@ |
|||
=proto |
|||
void duk_call_prop(duk_context *ctx, duk_idx_t obj_index, duk_idx_t nargs); |
|||
|
|||
=stack |
|||
[ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... retval! ] |
|||
|
|||
=summary |
|||
<p>Call <code>obj.key</code> with <code>nargs</code> arguments, with <code>this</code> |
|||
binding set to <code>obj</code>. The property name and the function arguments |
|||
are replaced by a single return value; the target object is not touched. |
|||
An error during the function call is not automatically caught.</p> |
|||
|
|||
<p>If the target function is not strict, the binding value seen by the |
|||
target function may be modified by processing specified in |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">Entering Function Code</a>. |
|||
</p> |
|||
|
|||
<p>This API call is equivalent to:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = obj[key](arg1, ..., argN); |
|||
</pre> |
|||
|
|||
<p>or:</p> |
|||
<pre class="ecmascript-code"> |
|||
var func = obj[key]; |
|||
var retval = func.call(obj, arg1, ..., argN); |
|||
</pre> |
|||
|
|||
<div include="object-can-be-any-value.html" /> |
|||
|
|||
=example |
|||
/* obj.myAdderMethod(2,3) -> 5 */ |
|||
duk_idx_t obj_idx = /* ... */; |
|||
|
|||
duk_push_string(ctx, "myAdderMethod"); |
|||
duk_push_int(ctx, 2); |
|||
duk_push_int(ctx, 3); |
|||
duk_call_prop(ctx, obj_idx, 2); /* [ ... "myAdderMethod" 2 3 ] -> [ ... 5 ] */ |
|||
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
property |
|||
call |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,48 @@ |
|||
name: duk_call_prop |
|||
|
|||
proto: | |
|||
void duk_call_prop(duk_context *ctx, duk_idx_t obj_index, duk_idx_t nargs); |
|||
|
|||
stack: | |
|||
[ ... obj! ... key! arg1! ...! argN! ] -> [ ... obj! ... retval! ] |
|||
|
|||
summary: | |
|||
<p>Call <code>obj.key</code> with <code>nargs</code> arguments, with <code>this</code> |
|||
binding set to <code>obj</code>. The property name and the function arguments |
|||
are replaced by a single return value; the target object is not touched. |
|||
An error during the function call is not automatically caught.</p> |
|||
|
|||
<p>If the target function is not strict, the binding value seen by the |
|||
target function may be modified by processing specified in |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4.3">Entering Function Code</a>. |
|||
</p> |
|||
|
|||
<p>This API call is equivalent to:</p> |
|||
<pre class="ecmascript-code"> |
|||
var retval = obj[key](arg1, ..., argN); |
|||
</pre> |
|||
|
|||
<p>or:</p> |
|||
<pre class="ecmascript-code"> |
|||
var func = obj[key]; |
|||
var retval = func.call(obj, arg1, ..., argN); |
|||
</pre> |
|||
|
|||
<div include="object-can-be-any-value.html" /> |
|||
|
|||
example: | |
|||
/* obj.myAdderMethod(2,3) -> 5 */ |
|||
duk_idx_t obj_idx = /* ... */; |
|||
|
|||
duk_push_string(ctx, "myAdderMethod"); |
|||
duk_push_int(ctx, 2); |
|||
duk_push_int(ctx, 3); |
|||
duk_call_prop(ctx, obj_idx, 2); /* [ ... "myAdderMethod" 2 3 ] -> [ ... 5 ] */ |
|||
printf("2+3=%ld\n", (long) duk_get_int(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- property |
|||
- call |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,20 +0,0 @@ |
|||
=proto |
|||
duk_codepoint_t duk_char_code_at(duk_context *ctx, duk_idx_t index, duk_size_t char_offset); |
|||
|
|||
=stack |
|||
[ ... str! ... ] |
|||
|
|||
=summary |
|||
<p>Get the codepoint of a character at character offset <code>char_offset</code> |
|||
of a string at <code>index</code>. If the value at <code>index</code> is not |
|||
a string, an error is thrown. If <code>char_offset</code> is invalid (outside |
|||
the string) a zero is returned.</p> |
|||
|
|||
=example |
|||
printf("char code at char index 12: %ld\n", (long) duk_char_code_at(ctx, -3, 12)); |
|||
|
|||
=tags |
|||
string |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,21 @@ |
|||
name: duk_char_code_at |
|||
|
|||
proto: | |
|||
duk_codepoint_t duk_char_code_at(duk_context *ctx, duk_idx_t index, duk_size_t char_offset); |
|||
|
|||
stack: | |
|||
[ ... str! ... ] |
|||
|
|||
summary: | |
|||
<p>Get the codepoint of a character at character offset <code>char_offset</code> |
|||
of a string at <code>index</code>. If the value at <code>index</code> is not |
|||
a string, an error is thrown. If <code>char_offset</code> is invalid (outside |
|||
the string) a zero is returned.</p> |
|||
|
|||
example: | |
|||
printf("char code at char index 12: %ld\n", (long) duk_char_code_at(ctx, -3, 12)); |
|||
|
|||
tags: |
|||
- string |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,59 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_check_stack(duk_context *ctx, duk_idx_t extra); |
|||
|
|||
=summary |
|||
<p>Ensure that the value stack has at least <code>extra</code> reserved |
|||
(allocated) elements for caller's use, relative to the current stack top. |
|||
Returns 1 if successful, 0 otherwise. If the call is successful, the caller |
|||
is guaranteed that <code>extra</code> elements can be pushed to the value |
|||
stack without a value stack related error (other errors like out-of-memory |
|||
can still occur). The caller MUST NOT rely on being able to push more than |
|||
<code>extra</code> values; although this is possible, such elements are |
|||
reserved for Duktape's internal use.</p> |
|||
|
|||
<p>Upon entry to a Duktape/C function and when outside any call |
|||
there is an automatic reserve (of <code>DUK_API_ENTRY_STACK</code> elements) |
|||
allocated for the caller in addition to call arguments on the value stack. |
|||
If more value stack space is needed, the caller must reserve more space |
|||
explicitly either in the beginning of the function (e.g. if the number of |
|||
elements required is known or can be computed based on arguments) or |
|||
dynamically (e.g. inside a loop). Note that an attempt to push a value |
|||
beyond the currently allocated value stack causes an error: it does not cause |
|||
the value stack to be automatically extended. This simplifies the internal |
|||
implementation.</p> |
|||
|
|||
<p>In addition to user reserved elements, Duktape keeps an automatic |
|||
internal value stack reserve to ensure all API calls have enough |
|||
value stack space to work without further allocations. The value stack |
|||
is also extended in somewhat large steps to minimize memory reallocation |
|||
activity. As a result the internal number of value stack elements |
|||
available beyond the caller specified <code>extra</code> varies considerably. |
|||
The caller does not need to take this into account and should never |
|||
rely on any additional elements being available.</p> |
|||
|
|||
<p>As a general rule |
|||
<code><a href="#duk_require_stack">duk_require_stack()</a></code> should be |
|||
used instead of this function to reserve more stack space. If value stack |
|||
cannot be extended, there is almost never a useful recovery strategy except |
|||
to throw an error and unwind.</p> |
|||
|
|||
=example |
|||
duk_idx_t nargs = duk_get_top(ctx); /* number or arguments */ |
|||
|
|||
/* reserve space for one temporary for each input argument */ |
|||
if (!duk_check_stack(ctx, nargs * 2)) { |
|||
/* return 'undefined' if cannot allocate space */ |
|||
printf("failed to reserve enough stack space\n"); |
|||
return 0; |
|||
} |
|||
|
|||
/* ... */ |
|||
|
|||
=tags |
|||
stack |
|||
|
|||
=seealso |
|||
duk_require_stack |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,60 @@ |
|||
name: duk_check_stack |
|||
|
|||
proto: | |
|||
duk_bool_t duk_check_stack(duk_context *ctx, duk_idx_t extra); |
|||
|
|||
summary: | |
|||
<p>Ensure that the value stack has at least <code>extra</code> reserved |
|||
(allocated) elements for caller's use, relative to the current stack top. |
|||
Returns 1 if successful, 0 otherwise. If the call is successful, the caller |
|||
is guaranteed that <code>extra</code> elements can be pushed to the value |
|||
stack without a value stack related error (other errors like out-of-memory |
|||
can still occur). The caller MUST NOT rely on being able to push more than |
|||
<code>extra</code> values; although this is possible, such elements are |
|||
reserved for Duktape's internal use.</p> |
|||
|
|||
<p>Upon entry to a Duktape/C function and when outside any call |
|||
there is an automatic reserve (of <code>DUK_API_ENTRY_STACK</code> elements) |
|||
allocated for the caller in addition to call arguments on the value stack. |
|||
If more value stack space is needed, the caller must reserve more space |
|||
explicitly either in the beginning of the function (e.g. if the number of |
|||
elements required is known or can be computed based on arguments) or |
|||
dynamically (e.g. inside a loop). Note that an attempt to push a value |
|||
beyond the currently allocated value stack causes an error: it does not cause |
|||
the value stack to be automatically extended. This simplifies the internal |
|||
implementation.</p> |
|||
|
|||
<p>In addition to user reserved elements, Duktape keeps an automatic |
|||
internal value stack reserve to ensure all API calls have enough |
|||
value stack space to work without further allocations. The value stack |
|||
is also extended in somewhat large steps to minimize memory reallocation |
|||
activity. As a result the internal number of value stack elements |
|||
available beyond the caller specified <code>extra</code> varies considerably. |
|||
The caller does not need to take this into account and should never |
|||
rely on any additional elements being available.</p> |
|||
|
|||
<p>As a general rule |
|||
<code><a href="#duk_require_stack">duk_require_stack()</a></code> should be |
|||
used instead of this function to reserve more stack space. If value stack |
|||
cannot be extended, there is almost never a useful recovery strategy except |
|||
to throw an error and unwind.</p> |
|||
|
|||
example: | |
|||
duk_idx_t nargs = duk_get_top(ctx); /* number or arguments */ |
|||
|
|||
/* reserve space for one temporary for each input argument */ |
|||
if (!duk_check_stack(ctx, nargs * 2)) { |
|||
/* return 'undefined' if cannot allocate space */ |
|||
printf("failed to reserve enough stack space\n"); |
|||
return 0; |
|||
} |
|||
|
|||
/* ... */ |
|||
|
|||
tags: |
|||
- stack |
|||
|
|||
seealso: |
|||
- duk_require_stack |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,37 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_check_stack_top(duk_context *ctx, duk_idx_t top); |
|||
|
|||
=summary |
|||
<p>Like <code><a href="#duk_check_stack">duk_check_stack()</a></code>, |
|||
but ensures there is space up to <code>top</code> for caller's use. |
|||
This is sometimes more convenient than specifying the number of |
|||
additional elements (relative to current stack top) to reserve.</p> |
|||
|
|||
<div class="note"> |
|||
The caller specifies the maximum stack top ensured for caller's |
|||
use, not the highest value stack index reserved for the caller. |
|||
For instance, if <code>top</code> is 500, the highest value stack |
|||
index reserved for the caller is 499. |
|||
</div> |
|||
|
|||
<p>As a general rule |
|||
<code><a href="#duk_require_stack_top">duk_require_stack_top()</a></code> should be |
|||
used instead of this function to reserve more stack space. If value stack |
|||
cannot be extended, there is almost never a useful recovery strategy except |
|||
to throw an error and unwind.</p> |
|||
|
|||
=example |
|||
if (duk_check_stack_top(ctx, 100)) { |
|||
printf("value stack guaranteed up to index 99\n"); |
|||
} else { |
|||
printf("cannot get value stack space\n"); |
|||
} |
|||
|
|||
=tags |
|||
stack |
|||
|
|||
=seealso |
|||
duk_require_stack_top |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,38 @@ |
|||
name: duk_check_stack_top |
|||
|
|||
proto: | |
|||
duk_bool_t duk_check_stack_top(duk_context *ctx, duk_idx_t top); |
|||
|
|||
summary: | |
|||
<p>Like <code><a href="#duk_check_stack">duk_check_stack()</a></code>, |
|||
but ensures there is space up to <code>top</code> for caller's use. |
|||
This is sometimes more convenient than specifying the number of |
|||
additional elements (relative to current stack top) to reserve.</p> |
|||
|
|||
<div class="note"> |
|||
The caller specifies the maximum stack top ensured for caller's |
|||
use, not the highest value stack index reserved for the caller. |
|||
For instance, if <code>top</code> is 500, the highest value stack |
|||
index reserved for the caller is 499. |
|||
</div> |
|||
|
|||
<p>As a general rule |
|||
<code><a href="#duk_require_stack_top">duk_require_stack_top()</a></code> should be |
|||
used instead of this function to reserve more stack space. If value stack |
|||
cannot be extended, there is almost never a useful recovery strategy except |
|||
to throw an error and unwind.</p> |
|||
|
|||
example: | |
|||
if (duk_check_stack_top(ctx, 100)) { |
|||
printf("value stack guaranteed up to index 99\n"); |
|||
} else { |
|||
printf("cannot get value stack space\n"); |
|||
} |
|||
|
|||
tags: |
|||
- stack |
|||
|
|||
seealso: |
|||
- duk_require_stack_top |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,20 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_check_type(duk_context *ctx, duk_idx_t index, duk_int_t type); |
|||
|
|||
=stack |
|||
[ ... val! ... ] |
|||
|
|||
=summary |
|||
<p>Matches the type of the value at <code>index</code> against <code>type</code>. |
|||
Returns 1 if the type matches, zero otherwise.</p> |
|||
|
|||
=example |
|||
if (duk_check_type(ctx, -3, DUK_TYPE_NUMBER)) { |
|||
printf("value is a number\n"); |
|||
} |
|||
|
|||
=tags |
|||
stack |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,21 @@ |
|||
name: duk_check_type |
|||
|
|||
proto: | |
|||
duk_bool_t duk_check_type(duk_context *ctx, duk_idx_t index, duk_int_t type); |
|||
|
|||
stack: | |
|||
[ ... val! ... ] |
|||
|
|||
summary: | |
|||
<p>Matches the type of the value at <code>index</code> against <code>type</code>. |
|||
Returns 1 if the type matches, zero otherwise.</p> |
|||
|
|||
example: | |
|||
if (duk_check_type(ctx, -3, DUK_TYPE_NUMBER)) { |
|||
printf("value is a number\n"); |
|||
} |
|||
|
|||
tags: |
|||
- stack |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,22 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_check_type_mask(duk_context *ctx, duk_idx_t index, duk_uint_t mask); |
|||
|
|||
=stack |
|||
[ ... val! ... ] |
|||
|
|||
=summary |
|||
<p>Matches the type of the value at <code>index</code> against the type |
|||
mask bits given in <code>mask</code>. Returns 1 if the value type matches |
|||
one of the type mask bits and zero otherwise.</p> |
|||
|
|||
=example |
|||
if (duk_check_type_mask(ctx, -3, DUK_TYPE_MASK_STRING | |
|||
DUK_TYPE_MASK_NUMBER)) { |
|||
printf("value is a string or a number\n"); |
|||
} |
|||
|
|||
=tags |
|||
stack |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,23 @@ |
|||
name: duk_check_type_mask |
|||
|
|||
proto: | |
|||
duk_bool_t duk_check_type_mask(duk_context *ctx, duk_idx_t index, duk_uint_t mask); |
|||
|
|||
stack: | |
|||
[ ... val! ... ] |
|||
|
|||
summary: | |
|||
<p>Matches the type of the value at <code>index</code> against the type |
|||
mask bits given in <code>mask</code>. Returns 1 if the value type matches |
|||
one of the type mask bits and zero otherwise.</p> |
|||
|
|||
example: | |
|||
if (duk_check_type_mask(ctx, -3, DUK_TYPE_MASK_STRING | |
|||
DUK_TYPE_MASK_NUMBER)) { |
|||
printf("value is a string or a number\n"); |
|||
} |
|||
|
|||
tags: |
|||
- stack |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,50 +0,0 @@ |
|||
=proto |
|||
void duk_compact(duk_context *ctx, duk_idx_t obj_index); |
|||
|
|||
=summary |
|||
<p> |
|||
Resizes an object's internal memory allocation to minimize memory usage. |
|||
If the value at <code>obj_index</code> is not an object, does nothing. |
|||
Although compaction is normally safe, it can fail due to an internal error |
|||
(such as out-of-memory error). Compaction only affects to an object's |
|||
"own properties", not its inherited properties. |
|||
</p> |
|||
|
|||
<p> |
|||
Compaction is not a final operation and has no impact on object semantics. |
|||
Adding new properties to the object is still possible (assuming the object |
|||
is extensible), but causes an object resize. Existing property values can be |
|||
changed (assuming the properties are writable) without affecting the object's |
|||
internal memory allocation. An object can be compacted multiple times: |
|||
for instance, if a new property is added to a previously compacted object, |
|||
the object can be compacted again to minimize memory footprint after the |
|||
property addition. |
|||
</p> |
|||
|
|||
<p> |
|||
Compacting an object saves a small amount of memory per object. It is |
|||
generally useful when (1) memory footprint is very important, (2) an object |
|||
is unlikely to gain new properties, (3) an object is relatively long-lived, |
|||
and (4) when compaction can be applied to enough many objects to make a |
|||
significant difference. |
|||
</p> |
|||
|
|||
<p> |
|||
If <code>Object.seal()</code>, <code>Object.freeze()</code>, or |
|||
<code>Object.preventExtensions()</code> is called, an object is automatically |
|||
compacted. |
|||
</p> |
|||
|
|||
=example |
|||
duk_push_object(ctx); /* [ ... obj ] */ |
|||
duk_push_int(ctx, 42); /* [ ... obj 42 ] */ |
|||
duk_put_prop_string(ctx, -2, "meaningOfLife"); /* [ ... obj ] */ |
|||
duk_compact(ctx, -1); /* [ ... obj ] */ |
|||
|
|||
=tags |
|||
object |
|||
property |
|||
memory |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,51 @@ |
|||
name: duk_compact |
|||
|
|||
proto: | |
|||
void duk_compact(duk_context *ctx, duk_idx_t obj_index); |
|||
|
|||
summary: | |
|||
<p> |
|||
Resizes an object's internal memory allocation to minimize memory usage. |
|||
If the value at <code>obj_index</code> is not an object, does nothing. |
|||
Although compaction is normally safe, it can fail due to an internal error |
|||
(such as out-of-memory error). Compaction only affects to an object's |
|||
"own properties", not its inherited properties. |
|||
</p> |
|||
|
|||
<p> |
|||
Compaction is not a final operation and has no impact on object semantics. |
|||
Adding new properties to the object is still possible (assuming the object |
|||
is extensible), but causes an object resize. Existing property values can be |
|||
changed (assuming the properties are writable) without affecting the object's |
|||
internal memory allocation. An object can be compacted multiple times: |
|||
for instance, if a new property is added to a previously compacted object, |
|||
the object can be compacted again to minimize memory footprint after the |
|||
property addition. |
|||
</p> |
|||
|
|||
<p> |
|||
Compacting an object saves a small amount of memory per object. It is |
|||
generally useful when (1) memory footprint is very important, (2) an object |
|||
is unlikely to gain new properties, (3) an object is relatively long-lived, |
|||
and (4) when compaction can be applied to enough many objects to make a |
|||
significant difference. |
|||
</p> |
|||
|
|||
<p> |
|||
If <code>Object.seal()</code>, <code>Object.freeze()</code>, or |
|||
<code>Object.preventExtensions()</code> is called, an object is automatically |
|||
compacted. |
|||
</p> |
|||
|
|||
example: | |
|||
duk_push_object(ctx); /* [ ... obj ] */ |
|||
duk_push_int(ctx, 42); /* [ ... obj 42 ] */ |
|||
duk_put_prop_string(ctx, -2, "meaningOfLife"); /* [ ... obj ] */ |
|||
duk_compact(ctx, -1); /* [ ... obj ] */ |
|||
|
|||
tags: |
|||
- object |
|||
- property |
|||
- memory |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,148 +0,0 @@ |
|||
=proto |
|||
void duk_compile(duk_context *ctx, duk_uint_t flags); |
|||
|
|||
=stack |
|||
[ ... source! filename! ] -> [ ... function! ] |
|||
|
|||
=summary |
|||
<p>Compile Ecmascript source code and replace it with a compiled function |
|||
object (the code is not executed). The <code>filename</code> argument is stored |
|||
as the <code>fileName</code> property of the resulting function, and is the name |
|||
used in e.g. tracebacks to identify the function. May throw a <code>SyntaxError</code> |
|||
for any compile-time errors (in addition to the usual internal errors like out-of-memory, |
|||
internal limit errors, etc).</p> |
|||
|
|||
<p>The following flags may be given:</p> |
|||
<ul> |
|||
<li><code>DUK_COMPILE_EVAL</code>: compile the input as eval code instead of |
|||
as an Ecmascript program</li> |
|||
<li><code>DUK_COMPILE_FUNCTION</code>: compile the input as a function instead |
|||
of as an Ecmascript program</li> |
|||
<li><code>DUK_COMPILE_STRICT</code>: force the input to be compiled in strict |
|||
mode</li> |
|||
</ul> |
|||
|
|||
<p>The source code being compiled may be:</p> |
|||
|
|||
<ul> |
|||
<li>Program code: compiles into a function with zero arguments, which |
|||
executes like a top level Ecmascript program (default)</li> |
|||
<li>Eval code: compiles into a function with zero arguments, which |
|||
executes like an Ecmascript <code>eval</code> call |
|||
(flag <code>DUK_COMPILE_EVAL</code>)</li> |
|||
<li>Function code: compiles into a function with zero or more arguments |
|||
(flag <code>DUK_COMPILE_FUNCTION</code>)</li> |
|||
</ul> |
|||
|
|||
<p>All of these have slightly different semantics in Ecmascript. See |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4">Establishing an Execution Context</a> |
|||
for a detailed discussion. |
|||
One major difference is that program and eval contexts have an implicit |
|||
return value: the last <i>non-empty</i> statement value is an automatic |
|||
return value for the program or eval code, whereas functions don't have |
|||
an automatic return value. |
|||
</p> |
|||
|
|||
<p>Program and eval code don't have an explicit <code>function</code> syntax. |
|||
For instance, the following can be compiled both as a program and as an |
|||
eval expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
print("Hello world!"); |
|||
123; // implicit return value |
|||
</pre> |
|||
|
|||
<p>Function code follows the Ecmascript <code>function</code> syntax |
|||
(the function name is optional):</p> |
|||
<pre class="ecmascript-code"> |
|||
function adder(x,y) { |
|||
return x+y; |
|||
} |
|||
</pre> |
|||
|
|||
<p>Compiling a function is equivalent to compiling eval code which contains |
|||
a function expression. Note that the outermost parentheses are required, |
|||
otherwise the eval code will register a global function named "adder" instead |
|||
of returning a plain function value:</p> |
|||
<pre class="ecmascript-code"> |
|||
(function adder(x,y) { |
|||
return x+y; |
|||
}) |
|||
</pre> |
|||
|
|||
<p>The bytecode generated for program and eval code is currently slower |
|||
than that generated for functions: a "slow path" is used for all variable |
|||
accesses in program and eval code, and the implicit return value handling |
|||
of program and eval code generates some unnecessary bytecode. From a |
|||
performance point of view (both memory and execution performance) it is |
|||
thus preferable to have as much code inside functions as possible.</p> |
|||
|
|||
<p>When compiling eval and program expressions, be careful to avoid the |
|||
usual Ecmascript gotchas, such as:</p> |
|||
<pre class="ecmascript-code"> |
|||
/* Function at top level is a function declaration which registers a global |
|||
* function, and is different from a function expression. Use parentheses |
|||
* around the top level expression. |
|||
*/ |
|||
|
|||
eval("function adder(x,y) { return x+y; }"); /* registers 'adder' to global */ |
|||
eval("function (x,y) { return x+y; }"); /* not allowed */ |
|||
eval("(function (x,y) { return x+y; })"); /* function expression (anonymous) */ |
|||
eval("(function adder(x,y) { return x+y; })"); /* function expression (named) */ |
|||
|
|||
/* Opening curly brace at top level is interpreted as start of a block |
|||
* expression, not an object literal. Use parentheses around the top |
|||
* level expression. |
|||
*/ |
|||
|
|||
eval("{ myfunc: 1 }"); /* block with -label- "myfunc" and statement "1" (!) */ |
|||
eval("({ myfunc: 1 })"; /* object literal { myfunc: 1 } */ |
|||
</pre> |
|||
|
|||
=example |
|||
/* Program code. Note that the hello() function is a function |
|||
* declaration which gets registered into the global object when |
|||
* executed. Implicit return value is 123. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "print('program');\n" |
|||
"function hello() { print('Hello world!'); }\n" |
|||
"123;"); |
|||
duk_push_string(ctx, "hello"); |
|||
duk_compile(ctx, 0); /* [ source filename ] -> [ func ] */ |
|||
duk_call(ctx, 0); /* [ func ] -> [ result ] */ |
|||
printf("program result: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
/* Eval code */ |
|||
|
|||
duk_push_string(ctx, "2+3"); |
|||
duk_push_string(ctx, "eval"); |
|||
duk_compile(ctx, DUK_COMPILE_EVAL); |
|||
duk_call(ctx, 0); /* [ func ] -> [ result ] */ |
|||
printf("eval result: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
/* Function code */ |
|||
|
|||
duk_push_string(ctx, "function (x,y) { return x+y; }"); |
|||
duk_push_string(ctx, "function"); |
|||
duk_compile(ctx, DUK_COMPILE_FUNCTION); |
|||
duk_push_int(ctx, 5); |
|||
duk_push_int(ctx, 6); |
|||
duk_call(ctx, 2); /* [ func 5 6 ] -> [ result ] */ |
|||
printf("function result: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=seealso |
|||
duk_pcompile |
|||
duk_compile_string |
|||
duk_compile_string_filename |
|||
duk_compile_lstring |
|||
duk_compile_lstring_filename |
|||
duk_compile_file |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,149 @@ |
|||
name: duk_compile |
|||
|
|||
proto: | |
|||
void duk_compile(duk_context *ctx, duk_uint_t flags); |
|||
|
|||
stack: | |
|||
[ ... source! filename! ] -> [ ... function! ] |
|||
|
|||
summary: | |
|||
<p>Compile Ecmascript source code and replace it with a compiled function |
|||
object (the code is not executed). The <code>filename</code> argument is stored |
|||
as the <code>fileName</code> property of the resulting function, and is the name |
|||
used in e.g. tracebacks to identify the function. May throw a <code>SyntaxError</code> |
|||
for any compile-time errors (in addition to the usual internal errors like out-of-memory, |
|||
internal limit errors, etc).</p> |
|||
|
|||
<p>The following flags may be given:</p> |
|||
<ul> |
|||
<li><code>DUK_COMPILE_EVAL</code>: compile the input as eval code instead of |
|||
as an Ecmascript program</li> |
|||
<li><code>DUK_COMPILE_FUNCTION</code>: compile the input as a function instead |
|||
of as an Ecmascript program</li> |
|||
<li><code>DUK_COMPILE_STRICT</code>: force the input to be compiled in strict |
|||
mode</li> |
|||
</ul> |
|||
|
|||
<p>The source code being compiled may be:</p> |
|||
|
|||
<ul> |
|||
<li>Program code: compiles into a function with zero arguments, which |
|||
executes like a top level Ecmascript program (default)</li> |
|||
<li>Eval code: compiles into a function with zero arguments, which |
|||
executes like an Ecmascript <code>eval</code> call |
|||
(flag <code>DUK_COMPILE_EVAL</code>)</li> |
|||
<li>Function code: compiles into a function with zero or more arguments |
|||
(flag <code>DUK_COMPILE_FUNCTION</code>)</li> |
|||
</ul> |
|||
|
|||
<p>All of these have slightly different semantics in Ecmascript. See |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-10.4">Establishing an Execution Context</a> |
|||
for a detailed discussion. |
|||
One major difference is that program and eval contexts have an implicit |
|||
return value: the last <i>non-empty</i> statement value is an automatic |
|||
return value for the program or eval code, whereas functions don't have |
|||
an automatic return value. |
|||
</p> |
|||
|
|||
<p>Program and eval code don't have an explicit <code>function</code> syntax. |
|||
For instance, the following can be compiled both as a program and as an |
|||
eval expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
print("Hello world!"); |
|||
123; // implicit return value |
|||
</pre> |
|||
|
|||
<p>Function code follows the Ecmascript <code>function</code> syntax |
|||
(the function name is optional):</p> |
|||
<pre class="ecmascript-code"> |
|||
function adder(x,y) { |
|||
return x+y; |
|||
} |
|||
</pre> |
|||
|
|||
<p>Compiling a function is equivalent to compiling eval code which contains |
|||
a function expression. Note that the outermost parentheses are required, |
|||
otherwise the eval code will register a global function named "adder" instead |
|||
of returning a plain function value:</p> |
|||
<pre class="ecmascript-code"> |
|||
(function adder(x,y) { |
|||
return x+y; |
|||
}) |
|||
</pre> |
|||
|
|||
<p>The bytecode generated for program and eval code is currently slower |
|||
than that generated for functions: a "slow path" is used for all variable |
|||
accesses in program and eval code, and the implicit return value handling |
|||
of program and eval code generates some unnecessary bytecode. From a |
|||
performance point of view (both memory and execution performance) it is |
|||
thus preferable to have as much code inside functions as possible.</p> |
|||
|
|||
<p>When compiling eval and program expressions, be careful to avoid the |
|||
usual Ecmascript gotchas, such as:</p> |
|||
<pre class="ecmascript-code"> |
|||
/* Function at top level is a function declaration which registers a global |
|||
* function, and is different from a function expression. Use parentheses |
|||
* around the top level expression. |
|||
*/ |
|||
|
|||
eval("function adder(x,y) { return x+y; }"); /* registers 'adder' to global */ |
|||
eval("function (x,y) { return x+y; }"); /* not allowed */ |
|||
eval("(function (x,y) { return x+y; })"); /* function expression (anonymous) */ |
|||
eval("(function adder(x,y) { return x+y; })"); /* function expression (named) */ |
|||
|
|||
/* Opening curly brace at top level is interpreted as start of a block |
|||
* expression, not an object literal. Use parentheses around the top |
|||
* level expression. |
|||
*/ |
|||
|
|||
eval("{ myfunc: 1 }"); /* block with -label- "myfunc" and statement "1" (!) */ |
|||
eval("({ myfunc: 1 })"; /* object literal { myfunc: 1 } */ |
|||
</pre> |
|||
|
|||
example: | |
|||
/* Program code. Note that the hello() function is a function |
|||
* declaration which gets registered into the global object when |
|||
* executed. Implicit return value is 123. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "print('program');\n" |
|||
"function hello() { print('Hello world!'); }\n" |
|||
"123;"); |
|||
duk_push_string(ctx, "hello"); |
|||
duk_compile(ctx, 0); /* [ source filename ] -> [ func ] */ |
|||
duk_call(ctx, 0); /* [ func ] -> [ result ] */ |
|||
printf("program result: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
/* Eval code */ |
|||
|
|||
duk_push_string(ctx, "2+3"); |
|||
duk_push_string(ctx, "eval"); |
|||
duk_compile(ctx, DUK_COMPILE_EVAL); |
|||
duk_call(ctx, 0); /* [ func ] -> [ result ] */ |
|||
printf("eval result: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
/* Function code */ |
|||
|
|||
duk_push_string(ctx, "function (x,y) { return x+y; }"); |
|||
duk_push_string(ctx, "function"); |
|||
duk_compile(ctx, DUK_COMPILE_FUNCTION); |
|||
duk_push_int(ctx, 5); |
|||
duk_push_int(ctx, 6); |
|||
duk_call(ctx, 2); /* [ func 5 6 ] -> [ result ] */ |
|||
printf("function result: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
seealso: |
|||
- duk_pcompile |
|||
- duk_compile_string |
|||
- duk_compile_string_filename |
|||
- duk_compile_lstring |
|||
- duk_compile_lstring_filename |
|||
- duk_compile_file |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,23 +0,0 @@ |
|||
=proto |
|||
void duk_compile_file(duk_context *ctx, duk_uint_t flags, const char *path); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... function! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a filename. The filename associated with the result function |
|||
is <code>path</code> as is.</p> |
|||
|
|||
<div include="path-encoding.html" /> |
|||
|
|||
=example |
|||
duk_compile_file(ctx, 0, "test.js"); |
|||
|
|||
=tags |
|||
compile |
|||
nonportable |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,24 @@ |
|||
name: duk_compile_file |
|||
|
|||
proto: | |
|||
void duk_compile_file(duk_context *ctx, duk_uint_t flags, const char *path); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... function! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a filename. The filename associated with the result function |
|||
is <code>path</code> as is.</p> |
|||
|
|||
<div include="path-encoding.html" /> |
|||
|
|||
example: | |
|||
duk_compile_file(ctx, 0, "test.js"); |
|||
|
|||
tags: |
|||
- compile |
|||
- nonportable |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,26 +0,0 @@ |
|||
=proto |
|||
void duk_compile_lstring(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... function! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string with explicit length. The filename associated with the |
|||
function is automatically provided from the <code>__FILE__</code> preprocessor |
|||
define of the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_compile_lstring(ctx, 0, src, len); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,27 @@ |
|||
name: duk_compile_lstring |
|||
|
|||
proto: | |
|||
void duk_compile_lstring(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... function! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string with explicit length. The filename associated with the |
|||
function is automatically provided from the <code>__FILE__</code> preprocessor |
|||
define of the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_compile_lstring(ctx, 0, src, len); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,25 +0,0 @@ |
|||
=proto |
|||
void duk_compile_lstring_filename(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); |
|||
|
|||
=stack |
|||
[ ... filename! ] -> [ ... function! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string with explicit length.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_push_string(ctx, "myFile.js"); |
|||
duk_compile_lstring_filename(ctx, 0, src, len); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,26 @@ |
|||
name: duk_compile_lstring_filename |
|||
|
|||
proto: | |
|||
void duk_compile_lstring_filename(duk_context *ctx, duk_uint_t flags, const char *src, duk_size_t len); |
|||
|
|||
stack: | |
|||
[ ... filename! ] -> [ ... function! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string with explicit length.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_push_string(ctx, "myFile.js"); |
|||
duk_compile_lstring_filename(ctx, 0, src, len); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,23 +0,0 @@ |
|||
=proto |
|||
void duk_compile_string(duk_context *ctx, duk_uint_t flags, const char *src); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... function! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string. The filename associated with the function is |
|||
automatically provided from the <code>__FILE__</code> preprocessor define of |
|||
the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
duk_compile_string(ctx, 0, "print('program code');"); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,24 @@ |
|||
name: duk_compile_string |
|||
|
|||
proto: | |
|||
void duk_compile_string(duk_context *ctx, duk_uint_t flags, const char *src); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... function! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string. The filename associated with the function is |
|||
automatically provided from the <code>__FILE__</code> preprocessor define of |
|||
the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
duk_compile_string(ctx, 0, "print('program code');"); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,22 +0,0 @@ |
|||
=proto |
|||
void duk_compile_string_filename(duk_context *ctx, duk_uint_t flags, const char *src); |
|||
|
|||
=stack |
|||
[ ... filename! ] -> [ ... function! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
duk_push_string(ctx, "myFile.js"); |
|||
duk_compile_string_filename(ctx, 0, "print('program code');"); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,23 @@ |
|||
name: duk_compile_string_filename |
|||
|
|||
proto: | |
|||
void duk_compile_string_filename(duk_context *ctx, duk_uint_t flags, const char *src); |
|||
|
|||
stack: | |
|||
[ ... filename! ] -> [ ... function! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_compile">duk_compile()</a></code>, but the compile input |
|||
is given as a C string.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
duk_push_string(ctx, "myFile.js"); |
|||
duk_compile_string_filename(ctx, 0, "print('program code');"); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,31 +0,0 @@ |
|||
=proto |
|||
void duk_concat(duk_context *ctx, duk_idx_t count); |
|||
|
|||
=stack |
|||
[ ... val1! ...! valN! ] -> [ ... result! ] |
|||
|
|||
=summary |
|||
<p>Concatenate zero or more values into a result string. The input values |
|||
are automatically coerced with |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-9.8">ToString()</a>.</p> |
|||
|
|||
<p>This primitive minimizes the number of intermediate string interning |
|||
operations and is better than concatenating strings manually.</p> |
|||
|
|||
=example |
|||
duk_push_string(ctx, "foo"); |
|||
duk_push_int(ctx, 123); |
|||
duk_push_true(ctx); |
|||
duk_concat(ctx, 3); |
|||
|
|||
printf("result: %s\n", duk_get_string(ctx, -1)); /* "foo123true" */ |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
string |
|||
|
|||
=seealso |
|||
duk_join |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,32 @@ |
|||
name: duk_concat |
|||
|
|||
proto: | |
|||
void duk_concat(duk_context *ctx, duk_idx_t count); |
|||
|
|||
stack: | |
|||
[ ... val1! ...! valN! ] -> [ ... result! ] |
|||
|
|||
summary: | |
|||
<p>Concatenate zero or more values into a result string. The input values |
|||
are automatically coerced with |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-9.8">ToString()</a>.</p> |
|||
|
|||
<p>This primitive minimizes the number of intermediate string interning |
|||
operations and is better than concatenating strings manually.</p> |
|||
|
|||
example: | |
|||
duk_push_string(ctx, "foo"); |
|||
duk_push_int(ctx, 123); |
|||
duk_push_true(ctx); |
|||
duk_concat(ctx, 3); |
|||
|
|||
printf("result: %s\n", duk_get_string(ctx, -1)); /* "foo123true" */ |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- string |
|||
|
|||
seealso: |
|||
- duk_join |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,33 +0,0 @@ |
|||
=proto |
|||
void duk_copy(duk_context *ctx, duk_idx_t from_index, duk_idx_t to_index); |
|||
|
|||
=stack |
|||
[ ... old(to_index)! ... val(from_index)! ... ] -> [ ... val(to_index)! ... val(from_index)! ... ] |
|||
|
|||
=summary |
|||
<p>Copy a value from <code>from_index</code> to <code>to_index</code>, |
|||
overwriting the previous value. If either index is invalid, throws an |
|||
error.</p> |
|||
|
|||
<p>This is a shorthand for:</p> |
|||
<pre class="c-code"> |
|||
/* to_index must be normalize in case it is negative and would change its |
|||
* meaning after duk_dup(). |
|||
*/ |
|||
to_index = duk_normalize_index(ctx, to_index); |
|||
duk_dup(ctx, from_index); |
|||
duk_replace(ctx, to_index); |
|||
</pre> |
|||
|
|||
=example |
|||
duk_copy(ctx, -3, 1); |
|||
|
|||
=tags |
|||
stack |
|||
|
|||
=seealso |
|||
duk_insert |
|||
duk_replace |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,34 @@ |
|||
name: duk_copy |
|||
|
|||
proto: | |
|||
void duk_copy(duk_context *ctx, duk_idx_t from_index, duk_idx_t to_index); |
|||
|
|||
stack: | |
|||
[ ... old(to_index)! ... val(from_index)! ... ] -> [ ... val(to_index)! ... val(from_index)! ... ] |
|||
|
|||
summary: | |
|||
<p>Copy a value from <code>from_index</code> to <code>to_index</code>, |
|||
overwriting the previous value. If either index is invalid, throws an |
|||
error.</p> |
|||
|
|||
<p>This is a shorthand for:</p> |
|||
<pre class="c-code"> |
|||
/* to_index must be normalize in case it is negative and would change its |
|||
* meaning after duk_dup(). |
|||
*/ |
|||
to_index = duk_normalize_index(ctx, to_index); |
|||
duk_dup(ctx, from_index); |
|||
duk_replace(ctx, to_index); |
|||
</pre> |
|||
|
|||
example: | |
|||
duk_copy(ctx, -3, 1); |
|||
|
|||
tags: |
|||
- stack |
|||
|
|||
seealso: |
|||
- duk_insert |
|||
- duk_replace |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,73 +0,0 @@ |
|||
=proto |
|||
duk_context *duk_create_heap(duk_alloc_function alloc_func, |
|||
duk_realloc_function realloc_func, |
|||
duk_free_function free_func, |
|||
void *heap_udata, |
|||
duk_fatal_function fatal_handler); |
|||
|
|||
=summary |
|||
<p>Create a new Duktape heap and return an initial context (thread). |
|||
If heap initialization fails, a <code>NULL</code> is returned. There is |
|||
currently no way to obtain more detailed error information.</p> |
|||
|
|||
<p>The caller may provide custom memory management functions in |
|||
<code>alloc_func</code>, <code>realloc_func</code>, and <code>free_func</code>; |
|||
the pointers must either all be <code>NULL</code> or all be |
|||
non-<code>NULL</code>. If the pointers are <code>NULL</code>, default |
|||
memory management functions (ANSI C <code>malloc()</code>, <code>realloc()</code> |
|||
, and <code>free()</code>) are used. The memory management functions |
|||
share the same opaque userdata pointer, <code>heap_udata</code>. This |
|||
userdata pointer is also used for other Duktape features (like low memory |
|||
pointer compression macros).</p> |
|||
|
|||
<p>A fatal error handler is provided in <code>fatal_handler</code>. This |
|||
handler is called in unrecoverable error situations such as uncaught |
|||
errors, out-of-memory errors not resolved by garbage collection, etc. |
|||
A caller SHOULD implement a fatal error handler in most applications. |
|||
If not given, a default fatal error handler is used. The default |
|||
handler ultimately calls ANSI C <code>abort()</code>, which may not always |
|||
be the preferred action.</p> |
|||
|
|||
<p>To create a Duktape heap with default settings, use |
|||
<code><a href="#duk_create_heap_default">duk_create_heap_default()</a></code>.</p> |
|||
|
|||
<p>New contexts linked to the same heap can be created with |
|||
<code><a href="#duk_push_thread">duk_push_thread()</a></code> and |
|||
<code><a href="#duk_push_thread_new_globalenv">duk_push_thread_new_globalenv()</a></code>.</p> |
|||
|
|||
=example |
|||
/* |
|||
* Simple case: use default allocation functions and fatal error handler |
|||
*/ |
|||
|
|||
duk_context *ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); |
|||
if (ctx) { |
|||
/* success */ |
|||
} else { |
|||
/* error */ |
|||
} |
|||
|
|||
/* |
|||
* Customized handlers |
|||
*/ |
|||
|
|||
duk_context *ctx = duk_create_heap(my_alloc, my_realloc, my_free, |
|||
(void *) 0xdeadbeef, my_fatal); |
|||
if (ctx) { |
|||
/* success */ |
|||
|
|||
/* ... after heap is no longer needed: */ |
|||
duk_destroy_heap(ctx); |
|||
} else { |
|||
/* error */ |
|||
} |
|||
|
|||
=tags |
|||
heap |
|||
|
|||
=seealso |
|||
duk_create_heap_default |
|||
duk_destroy_heap |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,74 @@ |
|||
name: duk_create_heap |
|||
|
|||
proto: | |
|||
duk_context *duk_create_heap(duk_alloc_function alloc_func, |
|||
duk_realloc_function realloc_func, |
|||
duk_free_function free_func, |
|||
void *heap_udata, |
|||
duk_fatal_function fatal_handler); |
|||
|
|||
summary: | |
|||
<p>Create a new Duktape heap and return an initial context (thread). |
|||
If heap initialization fails, a <code>NULL</code> is returned. There is |
|||
currently no way to obtain more detailed error information.</p> |
|||
|
|||
<p>The caller may provide custom memory management functions in |
|||
<code>alloc_func</code>, <code>realloc_func</code>, and <code>free_func</code>; |
|||
the pointers must either all be <code>NULL</code> or all be |
|||
non-<code>NULL</code>. If the pointers are <code>NULL</code>, default |
|||
memory management functions (ANSI C <code>malloc()</code>, <code>realloc()</code> |
|||
, and <code>free()</code>) are used. The memory management functions |
|||
share the same opaque userdata pointer, <code>heap_udata</code>. This |
|||
userdata pointer is also used for other Duktape features (like low memory |
|||
pointer compression macros).</p> |
|||
|
|||
<p>A fatal error handler is provided in <code>fatal_handler</code>. This |
|||
handler is called in unrecoverable error situations such as uncaught |
|||
errors, out-of-memory errors not resolved by garbage collection, etc. |
|||
A caller SHOULD implement a fatal error handler in most applications. |
|||
If not given, a default fatal error handler is used. The default |
|||
handler ultimately calls ANSI C <code>abort()</code>, which may not always |
|||
be the preferred action.</p> |
|||
|
|||
<p>To create a Duktape heap with default settings, use |
|||
<code><a href="#duk_create_heap_default">duk_create_heap_default()</a></code>.</p> |
|||
|
|||
<p>New contexts linked to the same heap can be created with |
|||
<code><a href="#duk_push_thread">duk_push_thread()</a></code> and |
|||
<code><a href="#duk_push_thread_new_globalenv">duk_push_thread_new_globalenv()</a></code>.</p> |
|||
|
|||
example: | |
|||
/* |
|||
* Simple case: use default allocation functions and fatal error handler |
|||
*/ |
|||
|
|||
duk_context *ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); |
|||
if (ctx) { |
|||
/* success */ |
|||
} else { |
|||
/* error */ |
|||
} |
|||
|
|||
/* |
|||
* Customized handlers |
|||
*/ |
|||
|
|||
duk_context *ctx = duk_create_heap(my_alloc, my_realloc, my_free, |
|||
(void *) 0xdeadbeef, my_fatal); |
|||
if (ctx) { |
|||
/* success */ |
|||
|
|||
/* ... after heap is no longer needed: */ |
|||
duk_destroy_heap(ctx); |
|||
} else { |
|||
/* error */ |
|||
} |
|||
|
|||
tags: |
|||
- heap |
|||
|
|||
seealso: |
|||
- duk_create_heap_default |
|||
- duk_destroy_heap |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,30 +0,0 @@ |
|||
=proto |
|||
duk_context *duk_create_heap_default(void); |
|||
|
|||
=summary |
|||
<p>Create a new Duktape heap and return an initial context (thread). |
|||
If heap initialization fails, a <code>NULL</code> is returned. There is |
|||
currently no way to obtain more detailed error information.</p> |
|||
|
|||
<p>The created heap will use default memory management and fatal error |
|||
handler functions. This API call is equivalent to:</p> |
|||
<pre class="c-code"> |
|||
ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); |
|||
</pre> |
|||
|
|||
=example |
|||
duk_context *ctx = duk_create_heap_default(); |
|||
if (ctx) { |
|||
/* success */ |
|||
|
|||
/* ... after heap is no longer needed: */ |
|||
duk_destroy_heap(ctx); |
|||
} else { |
|||
/* error */ |
|||
} |
|||
|
|||
=tags |
|||
heap |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,31 @@ |
|||
name: duk_create_heap_default |
|||
|
|||
proto: | |
|||
duk_context *duk_create_heap_default(void); |
|||
|
|||
summary: | |
|||
<p>Create a new Duktape heap and return an initial context (thread). |
|||
If heap initialization fails, a <code>NULL</code> is returned. There is |
|||
currently no way to obtain more detailed error information.</p> |
|||
|
|||
<p>The created heap will use default memory management and fatal error |
|||
handler functions. This API call is equivalent to:</p> |
|||
<pre class="c-code"> |
|||
ctx = duk_create_heap(NULL, NULL, NULL, NULL, NULL); |
|||
</pre> |
|||
|
|||
example: | |
|||
duk_context *ctx = duk_create_heap_default(); |
|||
if (ctx) { |
|||
/* success */ |
|||
|
|||
/* ... after heap is no longer needed: */ |
|||
duk_destroy_heap(ctx); |
|||
} else { |
|||
/* error */ |
|||
} |
|||
|
|||
tags: |
|||
- heap |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,34 +0,0 @@ |
|||
=proto |
|||
void duk_debugger_attach(duk_context *ctx, duk_debug_read_function read_cb, duk_debug_write_function write_cb, duk_debug_peek_function peek_cb, duk_debug_read_flush_function read_flush_cb, duk_debug_write_flush_function write_flush_cb, duk_debug_detached_function detached_cb, void *udata); |
|||
|
|||
=summary |
|||
<p>Attach a debugger to the Duktape heap. If debugger support is not |
|||
compiled into Duktape, throws an error. See |
|||
<a href="https://github.com/svaarala/duktape/blob/master/doc/debugger.rst">debugger.rst</a> |
|||
for more information.</p> |
|||
|
|||
<p>The <code>read_cb</code> and <code>write_cb</code> callbacks are mandatory. |
|||
The <code>peek_cb</code> is strongly recommended but optional. The |
|||
<code>read_flush_cb</code> and <code>write_flush_cb</code> callbacks are |
|||
optional. Unimplemented callbacks are indicated using a <code>NULL</code>.</p> |
|||
|
|||
=example |
|||
duk_debugger_attach(ctx, |
|||
my_read_cb, |
|||
my_write_cb, |
|||
my_peek_cb, |
|||
NULL, |
|||
NULL, |
|||
my_detached_cb, |
|||
my_udata); |
|||
|
|||
=tags |
|||
debug |
|||
experimental |
|||
|
|||
=seealso |
|||
duk_debugger_detach |
|||
duk_debugger_cooperate |
|||
|
|||
=introduced |
|||
1.2.0 |
|||
@ -0,0 +1,42 @@ |
|||
name: duk_debugger_attach |
|||
|
|||
proto: | |
|||
void duk_debugger_attach(duk_context *ctx, |
|||
duk_debug_read_function read_cb, |
|||
duk_debug_write_function write_cb, |
|||
duk_debug_peek_function peek_cb, |
|||
duk_debug_read_flush_function read_flush_cb, |
|||
duk_debug_write_flush_function write_flush_cb, |
|||
duk_debug_detached_function detached_cb, |
|||
void *udata); |
|||
|
|||
summary: | |
|||
<p>Attach a debugger to the Duktape heap. If debugger support is not |
|||
compiled into Duktape, throws an error. See |
|||
<a href="https://github.com/svaarala/duktape/blob/master/doc/debugger.rst">debugger.rst</a> |
|||
for more information.</p> |
|||
|
|||
<p>The <code>read_cb</code> and <code>write_cb</code> callbacks are mandatory. |
|||
The <code>peek_cb</code> is strongly recommended but optional. The |
|||
<code>read_flush_cb</code> and <code>write_flush_cb</code> callbacks are |
|||
optional. Unimplemented callbacks are indicated using a <code>NULL</code>.</p> |
|||
|
|||
example: | |
|||
duk_debugger_attach(ctx, |
|||
my_read_cb, |
|||
my_write_cb, |
|||
my_peek_cb, |
|||
NULL, |
|||
NULL, |
|||
my_detached_cb, |
|||
my_udata); |
|||
|
|||
tags: |
|||
- debug |
|||
- experimental |
|||
|
|||
seealso: |
|||
- duk_debugger_detach |
|||
- duk_debugger_cooperate |
|||
|
|||
introduced: 1.2.0 |
|||
@ -1,24 +0,0 @@ |
|||
=proto |
|||
void duk_debugger_cooperate(duk_context *ctx); |
|||
|
|||
=summary |
|||
<p>Check for and execute inbound debug commands without blocking. Debug |
|||
commands are executed in the context of the <code>ctx</code> argument. |
|||
May only be called when no calls into Duktape are in progress (from any |
|||
context). See |
|||
<a href="https://github.com/svaarala/duktape/blob/master/doc/debugger.rst">debugger.rst</a> |
|||
for more information.</p> |
|||
|
|||
=example |
|||
duk_debugger_cooperate(ctx); |
|||
|
|||
=tags |
|||
debug |
|||
experimental |
|||
|
|||
=seealso |
|||
duk_debugger_attach |
|||
duk_debugger_detach |
|||
|
|||
=introduced |
|||
1.2.0 |
|||
@ -0,0 +1,25 @@ |
|||
name: duk_debugger_cooperate |
|||
|
|||
proto: | |
|||
void duk_debugger_cooperate(duk_context *ctx); |
|||
|
|||
summary: | |
|||
<p>Check for and execute inbound debug commands without blocking. Debug |
|||
commands are executed in the context of the <code>ctx</code> argument. |
|||
May only be called when no calls into Duktape are in progress (from any |
|||
context). See |
|||
<a href="https://github.com/svaarala/duktape/blob/master/doc/debugger.rst">debugger.rst</a> |
|||
for more information.</p> |
|||
|
|||
example: | |
|||
duk_debugger_cooperate(ctx); |
|||
|
|||
tags: |
|||
- debug |
|||
- experimental |
|||
|
|||
seealso: |
|||
- duk_debugger_attach |
|||
- duk_debugger_detach |
|||
|
|||
introduced: 1.2.0 |
|||
@ -1,22 +0,0 @@ |
|||
=proto |
|||
void duk_debugger_detach(duk_context *ctx); |
|||
|
|||
=summary |
|||
<p>Detach a debugger from the Duktape heap. If debugger support is not |
|||
compiled into Duktape, throws an error. See |
|||
<a href="https://github.com/svaarala/duktape/blob/master/doc/debugger.rst">debugger.rst</a> |
|||
for more information.</p> |
|||
|
|||
=example |
|||
duk_debugger_detach(ctx); |
|||
|
|||
=tags |
|||
debug |
|||
experimental |
|||
|
|||
=seealso |
|||
duk_debugger_attach |
|||
duk_debugger_cooperate |
|||
|
|||
=introduced |
|||
1.2.0 |
|||
@ -0,0 +1,23 @@ |
|||
name: duk_debugger_detach |
|||
|
|||
proto: | |
|||
void duk_debugger_detach(duk_context *ctx); |
|||
|
|||
summary: | |
|||
<p>Detach a debugger from the Duktape heap. If debugger support is not |
|||
compiled into Duktape, throws an error. See |
|||
<a href="https://github.com/svaarala/duktape/blob/master/doc/debugger.rst">debugger.rst</a> |
|||
for more information.</p> |
|||
|
|||
example: | |
|||
duk_debugger_detach(ctx); |
|||
|
|||
tags: |
|||
- debug |
|||
- experimental |
|||
|
|||
seealso: |
|||
- duk_debugger_attach |
|||
- duk_debugger_cooperate |
|||
|
|||
introduced: 1.2.0 |
|||
@ -1,28 +0,0 @@ |
|||
=proto |
|||
void duk_decode_string(duk_context *ctx, duk_idx_t index, duk_decode_char_function callback, void *udata); |
|||
|
|||
=stack |
|||
[ ... val! ... ] |
|||
|
|||
=summary |
|||
<p>Process string at <code>index</code>, calling <code>callback</code> for each codepoint |
|||
of the string. The callback is given the <code>udata</code> argument and a codepoint. |
|||
The input string is not modified. If the value is not a string or the index is |
|||
invalid, throws an error.</p> |
|||
|
|||
=example |
|||
static void decode_char(void *udata, duk_codepoint_t codepoint) { |
|||
printf("codepoint: %ld\n", (long) codepoint); |
|||
} |
|||
|
|||
duk_push_string(ctx, "test_string"); |
|||
duk_decode_string(ctx, -1, decode_char, NULL); |
|||
|
|||
=tags |
|||
string |
|||
|
|||
=seealso |
|||
duk_map_string |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,29 @@ |
|||
name: duk_decode_string |
|||
|
|||
proto: | |
|||
void duk_decode_string(duk_context *ctx, duk_idx_t index, duk_decode_char_function callback, void *udata); |
|||
|
|||
stack: | |
|||
[ ... val! ... ] |
|||
|
|||
summary: | |
|||
<p>Process string at <code>index</code>, calling <code>callback</code> for each codepoint |
|||
of the string. The callback is given the <code>udata</code> argument and a codepoint. |
|||
The input string is not modified. If the value is not a string or the index is |
|||
invalid, throws an error.</p> |
|||
|
|||
example: | |
|||
static void decode_char(void *udata, duk_codepoint_t codepoint) { |
|||
printf("codepoint: %ld\n", (long) codepoint); |
|||
} |
|||
|
|||
duk_push_string(ctx, "test_string"); |
|||
duk_decode_string(ctx, -1, decode_char, NULL); |
|||
|
|||
tags: |
|||
- string |
|||
|
|||
seealso: |
|||
- duk_map_string |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,142 +0,0 @@ |
|||
=proto |
|||
void duk_def_prop(duk_context *ctx, duk_idx_t obj_index, duk_uint_t flags); |
|||
|
|||
=stack |
|||
[ ... obj! ... key! ] -> [ ... obj! ... ] (if have no value, setter, getter) |
|||
[ ... obj! ... key! value! ] -> [ ... obj! ... ] (if have value) |
|||
[ ... obj! ... key! getter! ] -> [ ... obj! ... ] (if have getter, but no setter) |
|||
[ ... obj! ... key! setter! ] -> [ ... obj! ... ] (if have setter, but no getter) |
|||
[ ... obj! ... key! getter! setter! ] -> [ ... obj! ... ] (if have both getter and setter) |
|||
|
|||
=summary |
|||
<p>Create or alter the attributes of property <code>key</code> of object at |
|||
<code>obj_index</code>, with semantics like |
|||
<code><a href="http://www.ecma-international.org/ecma-262/5.1/#sec-15.2.3.6">Object.defineProperty()</a></code>. |
|||
When the requested change is not allowed (e.g. property is not configurable), a |
|||
<code>TypeError</code> is thrown. If the target is not an object (or the |
|||
index is invalid) an error is thrown.</p> |
|||
|
|||
<p>The flags field provides "have" flags to indicate what property attributes |
|||
are changed (this models the partial property descriptors allowed by |
|||
<code>Object.defineProperty()</code>). Values for the writable, configurable, |
|||
and enumerable attributes are given in the flags field, while property value, |
|||
getter, and setter are given as value stack arguments. When creating a new |
|||
property, missing attribute values cause |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.6.1">Ecmascript defaults</a> |
|||
to be used (false for all boolean attributes, undefined for value, getter, setter); |
|||
when modifying an existing property missing attribute values mean that existing |
|||
attribute values are not touched.</p> |
|||
|
|||
<p>With the <code>DUK_DEFPROP_FORCE</code> flag property changes can be forced |
|||
even when an operation would normally fail due to a non-extensible target object |
|||
or a non-configurable property. This cannot be done from Ecmascript code with |
|||
<code>Object.defineProperty()</code> and is useful for e.g. sandboxing setup. |
|||
In some cases even a forced change is not possible and will cause an error to be |
|||
thrown. For instance, properties implemented internally as virtual properties |
|||
(such as string "length" and index properties) cannot be modified because they |
|||
don't have concrete internal storage and thus no way of recording changes.</p> |
|||
|
|||
<p>Some examples (see further examples below):</p> |
|||
<ul> |
|||
<li>To set the writable attribute, set flags to |
|||
<code>DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE</code>.</li> |
|||
<li>To clear the writable attribute, set flags to |
|||
<code>DUK_DEFPROP_HAVE_WRITABLE</code>.</li> |
|||
<li>To set value, clear writable, and set enumerable, set flags to |
|||
<code>DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE</code> |
|||
and provide the property value as a stack argument.</li> |
|||
<li>To forcibly set the value of a non-configurable property, set flags to |
|||
<code>DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_FORCE</code> and provide the |
|||
new property value as a stack argument.</li> |
|||
</ul> |
|||
|
|||
<p>This API call is useful for various things:</p> |
|||
<ul> |
|||
<li>To create properties with non-default attributes directly from C code.</li> |
|||
<li>To create accessor (getter/setter) properties directly from C code.</li> |
|||
<li>To modify the property attributes of existing properties directly from C code.</li> |
|||
</ul> |
|||
|
|||
<p>See API testcase |
|||
<a href="https://github.com/svaarala/duktape/blob/master/api-testcases/test-def-prop.c">test-def-prop.c</a> |
|||
for more examples.</p> |
|||
|
|||
=example |
|||
duk_idx_t obj_idx = /* ... */; |
|||
|
|||
/* Create an ordinary property which is writable and configurable, but |
|||
* not enumerable. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_prop_1"); |
|||
duk_push_int(ctx, 123); /* prop value */ |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_VALUE | |
|||
DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE | |
|||
DUK_DEFPROP_HAVE_ENUMERABLE | 0 | |
|||
DUK_DEFPROP_HAVE_CONFIGURABLE | DUK_DEFPROP_CONFIGURABLE); |
|||
|
|||
/* Change the property value and make it non-writable. Don't touch other |
|||
* attributes. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_prop_1"); |
|||
duk_push_int(ctx, 321); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_VALUE | |
|||
DUK_DEFPROP_HAVE_WRITABLE | 0); |
|||
|
|||
/* Make the property non-configurable, don't touch value or other attributes. */ |
|||
|
|||
duk_push_string(ctx, "my_prop_1"); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_CONFIGURABLE | 0); |
|||
|
|||
/* Create an accessor property which is non-configurable and non-enumerable. |
|||
* Attribute flags are not given so they default to Ecmascript defaults |
|||
* (false) automatically. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_accessor_1"); |
|||
duk_push_c_function(ctx, my_getter, 0 /*nargs*/); |
|||
duk_push_c_function(ctx, my_setter, 1 /*nargs*/); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_GETTER | |
|||
DUK_DEFPROP_HAVE_SETTER); |
|||
|
|||
/* Create an accessor property which is non-configurable but enumerable. |
|||
* Attribute flags are given explicitly which is easier to read without |
|||
* knowing about Ecmascript attribute default values. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_accessor_2"); |
|||
duk_push_c_function(ctx, my_getter, 0 /*nargs*/); |
|||
duk_push_c_function(ctx, my_setter, 1 /*nargs*/); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_GETTER | |
|||
DUK_DEFPROP_HAVE_SETTER | |
|||
DUK_DEFPROP_HAVE_CONFIGURABLE | /* clear */ |
|||
DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE); /* set */ |
|||
|
|||
/* Change the value of a non-configurable property by force. */ |
|||
duk_push_string(ctx, "my_nonconfigurable_prop"); |
|||
duk_push_value(ctx, 321); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_VALUE | |
|||
DUK_DEFPROP_FORCE); |
|||
|
|||
=tags |
|||
property |
|||
sandbox |
|||
experimental |
|||
|
|||
=seealso |
|||
|
|||
=introduced |
|||
1.1.0 |
|||
@ -0,0 +1,141 @@ |
|||
name: duk_def_prop |
|||
|
|||
proto: | |
|||
void duk_def_prop(duk_context *ctx, duk_idx_t obj_index, duk_uint_t flags); |
|||
|
|||
stack: | |
|||
[ ... obj! ... key! ] -> [ ... obj! ... ] (if have no value, setter, getter) |
|||
[ ... obj! ... key! value! ] -> [ ... obj! ... ] (if have value) |
|||
[ ... obj! ... key! getter! ] -> [ ... obj! ... ] (if have getter, but no setter) |
|||
[ ... obj! ... key! setter! ] -> [ ... obj! ... ] (if have setter, but no getter) |
|||
[ ... obj! ... key! getter! setter! ] -> [ ... obj! ... ] (if have both getter and setter) |
|||
|
|||
summary: | |
|||
<p>Create or alter the attributes of property <code>key</code> of object at |
|||
<code>obj_index</code>, with semantics like |
|||
<code><a href="http://www.ecma-international.org/ecma-262/5.1/#sec-15.2.3.6">Object.defineProperty()</a></code>. |
|||
When the requested change is not allowed (e.g. property is not configurable), a |
|||
<code>TypeError</code> is thrown. If the target is not an object (or the |
|||
index is invalid) an error is thrown.</p> |
|||
|
|||
<p>The flags field provides "have" flags to indicate what property attributes |
|||
are changed (this models the partial property descriptors allowed by |
|||
<code>Object.defineProperty()</code>). Values for the writable, configurable, |
|||
and enumerable attributes are given in the flags field, while property value, |
|||
getter, and setter are given as value stack arguments. When creating a new |
|||
property, missing attribute values cause |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.6.1">Ecmascript defaults</a> |
|||
to be used (false for all boolean attributes, undefined for value, getter, setter); |
|||
when modifying an existing property missing attribute values mean that existing |
|||
attribute values are not touched.</p> |
|||
|
|||
<p>With the <code>DUK_DEFPROP_FORCE</code> flag property changes can be forced |
|||
even when an operation would normally fail due to a non-extensible target object |
|||
or a non-configurable property. This cannot be done from Ecmascript code with |
|||
<code>Object.defineProperty()</code> and is useful for e.g. sandboxing setup. |
|||
In some cases even a forced change is not possible and will cause an error to be |
|||
thrown. For instance, properties implemented internally as virtual properties |
|||
(such as string "length" and index properties) cannot be modified because they |
|||
don't have concrete internal storage and thus no way of recording changes.</p> |
|||
|
|||
<p>Some examples (see further examples below):</p> |
|||
<ul> |
|||
<li>To set the writable attribute, set flags to |
|||
<code>DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE</code>.</li> |
|||
<li>To clear the writable attribute, set flags to |
|||
<code>DUK_DEFPROP_HAVE_WRITABLE</code>.</li> |
|||
<li>To set value, clear writable, and set enumerable, set flags to |
|||
<code>DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE</code> |
|||
and provide the property value as a stack argument.</li> |
|||
<li>To forcibly set the value of a non-configurable property, set flags to |
|||
<code>DUK_DEFPROP_HAVE_VALUE | DUK_DEFPROP_FORCE</code> and provide the |
|||
new property value as a stack argument.</li> |
|||
</ul> |
|||
|
|||
<p>This API call is useful for various things:</p> |
|||
<ul> |
|||
<li>To create properties with non-default attributes directly from C code.</li> |
|||
<li>To create accessor (getter/setter) properties directly from C code.</li> |
|||
<li>To modify the property attributes of existing properties directly from C code.</li> |
|||
</ul> |
|||
|
|||
<p>See API testcase |
|||
<a href="https://github.com/svaarala/duktape/blob/master/api-testcases/test-def-prop.c">test-def-prop.c</a> |
|||
for more examples.</p> |
|||
|
|||
example: | |
|||
duk_idx_t obj_idx = /* ... */; |
|||
|
|||
/* Create an ordinary property which is writable and configurable, but |
|||
* not enumerable. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_prop_1"); |
|||
duk_push_int(ctx, 123); /* prop value */ |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_VALUE | |
|||
DUK_DEFPROP_HAVE_WRITABLE | DUK_DEFPROP_WRITABLE | |
|||
DUK_DEFPROP_HAVE_ENUMERABLE | 0 | |
|||
DUK_DEFPROP_HAVE_CONFIGURABLE | DUK_DEFPROP_CONFIGURABLE); |
|||
|
|||
/* Change the property value and make it non-writable. Don't touch other |
|||
* attributes. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_prop_1"); |
|||
duk_push_int(ctx, 321); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_VALUE | |
|||
DUK_DEFPROP_HAVE_WRITABLE | 0); |
|||
|
|||
/* Make the property non-configurable, don't touch value or other attributes. */ |
|||
|
|||
duk_push_string(ctx, "my_prop_1"); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_CONFIGURABLE | 0); |
|||
|
|||
/* Create an accessor property which is non-configurable and non-enumerable. |
|||
* Attribute flags are not given so they default to Ecmascript defaults |
|||
* (false) automatically. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_accessor_1"); |
|||
duk_push_c_function(ctx, my_getter, 0 /*nargs*/); |
|||
duk_push_c_function(ctx, my_setter, 1 /*nargs*/); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_GETTER | |
|||
DUK_DEFPROP_HAVE_SETTER); |
|||
|
|||
/* Create an accessor property which is non-configurable but enumerable. |
|||
* Attribute flags are given explicitly which is easier to read without |
|||
* knowing about Ecmascript attribute default values. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "my_accessor_2"); |
|||
duk_push_c_function(ctx, my_getter, 0 /*nargs*/); |
|||
duk_push_c_function(ctx, my_setter, 1 /*nargs*/); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_GETTER | |
|||
DUK_DEFPROP_HAVE_SETTER | |
|||
DUK_DEFPROP_HAVE_CONFIGURABLE | /* clear */ |
|||
DUK_DEFPROP_HAVE_ENUMERABLE | DUK_DEFPROP_ENUMERABLE); /* set */ |
|||
|
|||
/* Change the value of a non-configurable property by force. */ |
|||
duk_push_string(ctx, "my_nonconfigurable_prop"); |
|||
duk_push_value(ctx, 321); |
|||
duk_def_prop(ctx, |
|||
obj_idx, |
|||
DUK_DEFPROP_HAVE_VALUE | |
|||
DUK_DEFPROP_FORCE); |
|||
|
|||
tags: |
|||
- property |
|||
- sandbox |
|||
- experimental |
|||
|
|||
introduced: 1.1.0 |
|||
@ -1,71 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_del_prop(duk_context *ctx, duk_idx_t obj_index); |
|||
|
|||
=stack |
|||
[ ... obj! ... key! ] -> [ ... obj! ... ] |
|||
|
|||
=summary |
|||
<p>Delete the property <code>key</code> of a value at <code>obj_index</code>. |
|||
<code>key</code> is removed from the stack. Return code and error throwing |
|||
behavior:</p> |
|||
<ul> |
|||
<li>If property exists and is configurable (deletable), deletes the |
|||
property and returns <code>1</code>.</li> |
|||
<li>If property exists but is not configurable, throws an error |
|||
(strict mode semantics).</li> |
|||
<li>If property does not exist, returns <code>1</code> (<i>not</i> 0).</li> |
|||
<li>If the value at <code>obj_index</code> is not |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-9.10">object coercible</a>, |
|||
throws an error.</li> |
|||
<li>If <code>obj_index</code> is invalid, throws an error.</li> |
|||
</ul> |
|||
|
|||
<p>The property deletion is equivalent to the Ecmascript expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
delete obj[key] |
|||
</pre> |
|||
|
|||
<p>For semantics, see |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.2.1">Property Accessors</a>, |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.4.1">The delete operator</a> |
|||
and <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.12.7">[[Delete]] (P, Throw)</a>. |
|||
The return value and error throwing behavior mirrors the Ecmascript |
|||
<code>delete</code> operator behavior. |
|||
Both the target value and the <code>key</code> are coerced:</p> |
|||
<ul> |
|||
<li>The target value is automatically coerced to an object. However, this |
|||
object is a temporary one, so deleting its properties is not very useful.</li> |
|||
<li>The <code>key</code> argument is internally coerced to a string. There is |
|||
an internal fast path for arrays and numeric indices which avoids an |
|||
explicit string coercion, so use a numeric <code>key</code> when applicable.</p> |
|||
</ul> |
|||
|
|||
<div class="note"> |
|||
This API call returns <code>1</code> when the target property does not exist. |
|||
This is not very intuitive, but follows Ecmascript semantics: |
|||
<code>delete obj.nonexistent</code> also evaluates to <code>true</code>. |
|||
</div> |
|||
|
|||
<p>If the key is a fixed string you can avoid one API call and use the |
|||
<code><a href="#duk_del_prop_string">duk_del_prop_string()</a></code> variant. |
|||
Similarly, if the key is an array index, you can use the |
|||
<code><a href="#duk_del_prop_index">duk_del_prop_index()</a></code> variant.</p> |
|||
|
|||
<div include="object-can-be-any-value.html" /> |
|||
|
|||
=example |
|||
duk_bool_t rc; |
|||
|
|||
duk_push_string(ctx, "myProperty"); |
|||
rc = duk_del_prop(ctx, -3); |
|||
printf("delete obj.myProperty -> rc=%d\n", (int) rc); |
|||
|
|||
=tags |
|||
property |
|||
|
|||
=seealso |
|||
duk_del_prop_string |
|||
duk_del_prop_index |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,72 @@ |
|||
name: duk_del_prop |
|||
|
|||
proto: | |
|||
duk_bool_t duk_del_prop(duk_context *ctx, duk_idx_t obj_index); |
|||
|
|||
stack: | |
|||
[ ... obj! ... key! ] -> [ ... obj! ... ] |
|||
|
|||
summary: | |
|||
<p>Delete the property <code>key</code> of a value at <code>obj_index</code>. |
|||
<code>key</code> is removed from the stack. Return code and error throwing |
|||
behavior:</p> |
|||
<ul> |
|||
<li>If property exists and is configurable (deletable), deletes the |
|||
property and returns <code>1</code>.</li> |
|||
<li>If property exists but is not configurable, throws an error |
|||
(strict mode semantics).</li> |
|||
<li>If property does not exist, returns <code>1</code> (<i>not</i> 0).</li> |
|||
<li>If the value at <code>obj_index</code> is not |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-9.10">object coercible</a>, |
|||
throws an error.</li> |
|||
<li>If <code>obj_index</code> is invalid, throws an error.</li> |
|||
</ul> |
|||
|
|||
<p>The property deletion is equivalent to the Ecmascript expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
delete obj[key] |
|||
</pre> |
|||
|
|||
<p>For semantics, see |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.2.1">Property Accessors</a>, |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.4.1">The delete operator</a> |
|||
and <a href="http://www.ecma-international.org/ecma-262/5.1/#sec-8.12.7">[[Delete]] (P, Throw)</a>. |
|||
The return value and error throwing behavior mirrors the Ecmascript |
|||
<code>delete</code> operator behavior. |
|||
Both the target value and the <code>key</code> are coerced:</p> |
|||
<ul> |
|||
<li>The target value is automatically coerced to an object. However, this |
|||
object is a temporary one, so deleting its properties is not very useful.</li> |
|||
<li>The <code>key</code> argument is internally coerced to a string. There is |
|||
an internal fast path for arrays and numeric indices which avoids an |
|||
explicit string coercion, so use a numeric <code>key</code> when applicable.</p> |
|||
</ul> |
|||
|
|||
<div class="note"> |
|||
This API call returns <code>1</code> when the target property does not exist. |
|||
This is not very intuitive, but follows Ecmascript semantics: |
|||
<code>delete obj.nonexistent</code> also evaluates to <code>true</code>. |
|||
</div> |
|||
|
|||
<p>If the key is a fixed string you can avoid one API call and use the |
|||
<code><a href="#duk_del_prop_string">duk_del_prop_string()</a></code> variant. |
|||
Similarly, if the key is an array index, you can use the |
|||
<code><a href="#duk_del_prop_index">duk_del_prop_index()</a></code> variant.</p> |
|||
|
|||
<div include="object-can-be-any-value.html" /> |
|||
|
|||
example: | |
|||
duk_bool_t rc; |
|||
|
|||
duk_push_string(ctx, "myProperty"); |
|||
rc = duk_del_prop(ctx, -3); |
|||
printf("delete obj.myProperty -> rc=%d\n", (int) rc); |
|||
|
|||
tags: |
|||
- property |
|||
|
|||
seealso: |
|||
- duk_del_prop_string |
|||
- duk_del_prop_index |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,28 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_del_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); |
|||
|
|||
=stack |
|||
[ ... obj! ... ] -> [ ... obj! ... ] |
|||
|
|||
=summary |
|||
<p>Like <code><a href="#duk_del_prop">duk_del_prop()</a></code>, |
|||
but the property name is given as an unsigned integer |
|||
<code>arr_index</code>. This is especially useful for deleting |
|||
array elements (but is not limited to that).</p> |
|||
|
|||
<p>Conceptually the number is coerced to a string for the |
|||
property deletion, e.g. <code>123</code> would be equivalent to a property |
|||
name <code>"123"</code>. Duktape avoids an explicit coercion whenever |
|||
possible.</p> |
|||
|
|||
=example |
|||
duk_bool_t rc; |
|||
|
|||
rc = duk_del_prop_index(ctx, -3, 123); |
|||
printf("delete obj[123] -> rc=%d\n", (int) rc); |
|||
|
|||
=tags |
|||
property |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,29 @@ |
|||
name: duk_del_prop_index |
|||
|
|||
proto: | |
|||
duk_bool_t duk_del_prop_index(duk_context *ctx, duk_idx_t obj_index, duk_uarridx_t arr_index); |
|||
|
|||
stack: | |
|||
[ ... obj! ... ] -> [ ... obj! ... ] |
|||
|
|||
summary: | |
|||
<p>Like <code><a href="#duk_del_prop">duk_del_prop()</a></code>, |
|||
but the property name is given as an unsigned integer |
|||
<code>arr_index</code>. This is especially useful for deleting |
|||
array elements (but is not limited to that).</p> |
|||
|
|||
<p>Conceptually the number is coerced to a string for the |
|||
property deletion, e.g. <code>123</code> would be equivalent to a property |
|||
name <code>"123"</code>. Duktape avoids an explicit coercion whenever |
|||
possible.</p> |
|||
|
|||
example: | |
|||
duk_bool_t rc; |
|||
|
|||
rc = duk_del_prop_index(ctx, -3, 123); |
|||
printf("delete obj[123] -> rc=%d\n", (int) rc); |
|||
|
|||
tags: |
|||
- property |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,22 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_del_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); |
|||
|
|||
=stack |
|||
[ ... obj! ... ] -> [ ... obj! ... ] |
|||
|
|||
=summary |
|||
<p>Like <code><a href="#duk_del_prop">duk_del_prop()</a></code>, |
|||
but the property name is given as a NUL-terminated C string |
|||
<code>key</code>.</p> |
|||
|
|||
=example |
|||
duk_bool_t rc; |
|||
|
|||
rc = duk_del_prop_string(ctx, -3, "propertyName"); |
|||
printf("delete obj.propertyName -> rc=%d\n", (int) rc); |
|||
|
|||
=tags |
|||
property |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,23 @@ |
|||
name: duk_del_prop_string |
|||
|
|||
proto: | |
|||
duk_bool_t duk_del_prop_string(duk_context *ctx, duk_idx_t obj_index, const char *key); |
|||
|
|||
stack: | |
|||
[ ... obj! ... ] -> [ ... obj! ... ] |
|||
|
|||
summary: | |
|||
<p>Like <code><a href="#duk_del_prop">duk_del_prop()</a></code>, |
|||
but the property name is given as a NUL-terminated C string |
|||
<code>key</code>.</p> |
|||
|
|||
example: | |
|||
duk_bool_t rc; |
|||
|
|||
rc = duk_del_prop_string(ctx, -3, "propertyName"); |
|||
printf("delete obj.propertyName -> rc=%d\n", (int) rc); |
|||
|
|||
tags: |
|||
- property |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,29 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_del_var(duk_context *ctx); |
|||
|
|||
=stack |
|||
[ ... varname! ] -> [ ... ] |
|||
|
|||
=summary |
|||
XXX |
|||
|
|||
<p>The identifier deletion is equivalent to the Ecmascript expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
delete varname |
|||
</pre> |
|||
|
|||
<div class="note"> |
|||
Attempt to delete an identifier is compile time SyntaxError in strict mode |
|||
code. Because Duktape/C functions run in strict mode, the semantics for this |
|||
call are currently not very useful when called from inside a Duktape/C function. |
|||
</div> |
|||
|
|||
=example |
|||
XXX |
|||
|
|||
=tags |
|||
variable |
|||
omit |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,30 @@ |
|||
name: duk_del_var |
|||
|
|||
proto: | |
|||
duk_bool_t duk_del_var(duk_context *ctx); |
|||
|
|||
stack: | |
|||
[ ... varname! ] -> [ ... ] |
|||
|
|||
summary: | |
|||
XXX |
|||
|
|||
<p>The identifier deletion is equivalent to the Ecmascript expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
delete varname |
|||
</pre> |
|||
|
|||
<div class="note"> |
|||
Attempt to delete an identifier is compile time SyntaxError in strict mode |
|||
code. Because Duktape/C functions run in strict mode, the semantics for this |
|||
call are currently not very useful when called from inside a Duktape/C function. |
|||
</div> |
|||
|
|||
example: | |
|||
XXX |
|||
|
|||
tags: |
|||
- variable |
|||
- omit |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,19 +0,0 @@ |
|||
=proto |
|||
void duk_destroy_heap(duk_context *ctx); |
|||
|
|||
=summary |
|||
<p>Destroy a Duktape heap. The argument context can be any context linked |
|||
to the heap. All resources related to the heap are freed and must not be |
|||
referenced after the call completes. These resources include all contexts |
|||
linked to the heap, and also all string and buffer pointers within the heap.</p> |
|||
|
|||
<p>If <code>ctx</code> is <code>NULL</code>, the call is a no-op.</p> |
|||
|
|||
=example |
|||
duk_destroy_heap(ctx); |
|||
|
|||
=tags |
|||
heap |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,20 @@ |
|||
name: duk_destroy_heap |
|||
|
|||
proto: | |
|||
void duk_destroy_heap(duk_context *ctx); |
|||
|
|||
summary: | |
|||
<p>Destroy a Duktape heap. The argument context can be any context linked |
|||
to the heap. All resources related to the heap are freed and must not be |
|||
referenced after the call completes. These resources include all contexts |
|||
linked to the heap, and also all string and buffer pointers within the heap.</p> |
|||
|
|||
<p>If <code>ctx</code> is <code>NULL</code>, the call is a no-op.</p> |
|||
|
|||
example: | |
|||
duk_destroy_heap(ctx); |
|||
|
|||
tags: |
|||
- heap |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,27 +0,0 @@ |
|||
=proto |
|||
void duk_dump_context_stderr(duk_context *ctx); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... ] |
|||
|
|||
=summary |
|||
<p>Like <code><a href="#duk_push_context_dump">duk_push_context_dump()</a></code> but |
|||
the context dump is written to <code>stderr</code> and nothing is left on |
|||
the value stack.</p> |
|||
|
|||
<p>If file I/O has been disabled, this call is a NOP.</p> |
|||
|
|||
<div include="no-production-dump-calls.html" /> |
|||
|
|||
=example |
|||
duk_push_int(ctx, 123); |
|||
duk_push_string(ctx, "foo"); |
|||
duk_dump_context_stderr(ctx); |
|||
|
|||
=tags |
|||
stack |
|||
debug |
|||
nonportable |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,28 @@ |
|||
name: duk_dump_context_stderr |
|||
|
|||
proto: | |
|||
void duk_dump_context_stderr(duk_context *ctx); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... ] |
|||
|
|||
summary: | |
|||
<p>Like <code><a href="#duk_push_context_dump">duk_push_context_dump()</a></code> but |
|||
the context dump is written to <code>stderr</code> and nothing is left on |
|||
the value stack.</p> |
|||
|
|||
<p>If file I/O has been disabled, this call is a NOP.</p> |
|||
|
|||
<div include="no-production-dump-calls.html" /> |
|||
|
|||
example: | |
|||
duk_push_int(ctx, 123); |
|||
duk_push_string(ctx, "foo"); |
|||
duk_dump_context_stderr(ctx); |
|||
|
|||
tags: |
|||
- stack |
|||
- debug |
|||
- nonportable |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,27 +0,0 @@ |
|||
=proto |
|||
void duk_dump_context_stdout(duk_context *ctx); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... ] |
|||
|
|||
=summary |
|||
<p>Like <code><a href="#duk_push_context_dump">duk_push_context_dump()</a></code> but |
|||
the context dump is written to <code>stdout</code> and nothing is left on |
|||
the value stack.</p> |
|||
|
|||
<p>If file I/O has been disabled, this call is a NOP.</p> |
|||
|
|||
<div include="no-production-dump-calls.html" /> |
|||
|
|||
=example |
|||
duk_push_int(ctx, 123); |
|||
duk_push_string(ctx, "foo"); |
|||
duk_dump_context_stdout(ctx); |
|||
|
|||
=tags |
|||
stack |
|||
debug |
|||
nonportable |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,28 @@ |
|||
name: duk_dump_context_stdout |
|||
|
|||
proto: | |
|||
void duk_dump_context_stdout(duk_context *ctx); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... ] |
|||
|
|||
summary: | |
|||
<p>Like <code><a href="#duk_push_context_dump">duk_push_context_dump()</a></code> but |
|||
the context dump is written to <code>stdout</code> and nothing is left on |
|||
the value stack.</p> |
|||
|
|||
<p>If file I/O has been disabled, this call is a NOP.</p> |
|||
|
|||
<div include="no-production-dump-calls.html" /> |
|||
|
|||
example: | |
|||
duk_push_int(ctx, 123); |
|||
duk_push_string(ctx, "foo"); |
|||
duk_dump_context_stdout(ctx); |
|||
|
|||
tags: |
|||
- stack |
|||
- debug |
|||
- nonportable |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,23 +0,0 @@ |
|||
=proto |
|||
void duk_dup(duk_context *ctx, duk_idx_t from_index); |
|||
|
|||
=stack |
|||
[ ... val! ... ] -> [ ... val! ... val! ] |
|||
|
|||
=summary |
|||
<p>Push a duplicate of value at <code>from_index</code> to the stack. |
|||
If <code>from_index</code> is invalid, throws an error.</p> |
|||
|
|||
=example |
|||
duk_push_int(ctx, 123); /* -> [ ... 123 ] */ |
|||
duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ |
|||
duk_dup(ctx, -2); /* -> [ ... 123 234 123 ] */ |
|||
|
|||
=tags |
|||
stack |
|||
|
|||
=seealso |
|||
duk_dup_top |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,24 @@ |
|||
name: duk_dup |
|||
|
|||
proto: | |
|||
void duk_dup(duk_context *ctx, duk_idx_t from_index); |
|||
|
|||
stack: | |
|||
[ ... val! ... ] -> [ ... val! ... val! ] |
|||
|
|||
summary: | |
|||
<p>Push a duplicate of value at <code>from_index</code> to the stack. |
|||
If <code>from_index</code> is invalid, throws an error.</p> |
|||
|
|||
example: | |
|||
duk_push_int(ctx, 123); /* -> [ ... 123 ] */ |
|||
duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ |
|||
duk_dup(ctx, -2); /* -> [ ... 123 234 123 ] */ |
|||
|
|||
tags: |
|||
- stack |
|||
|
|||
seealso: |
|||
- duk_dup_top |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,23 +0,0 @@ |
|||
=proto |
|||
void duk_dup_top(duk_context *ctx); |
|||
|
|||
=stack |
|||
[ ... val! ] -> [ ... val! val! ] |
|||
|
|||
=summary |
|||
<p>Push a duplicate of the value at stack top to the stack. |
|||
If the value stack is empty, throws an error.</p> |
|||
|
|||
<p>Equivalent to calling |
|||
<code><a href="#duk_dup">duk_dup(ctx, -1)</a></code>.</p> |
|||
|
|||
=example |
|||
duk_push_int(ctx, 123); /* -> [ ... 123 ] */ |
|||
duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ |
|||
duk_dup_top(ctx); /* -> [ ... 123 234 234 ] */ |
|||
|
|||
=tags |
|||
stack |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,24 @@ |
|||
name: duk_dup_top |
|||
|
|||
proto: | |
|||
void duk_dup_top(duk_context *ctx); |
|||
|
|||
stack: | |
|||
[ ... val! ] -> [ ... val! val! ] |
|||
|
|||
summary: | |
|||
<p>Push a duplicate of the value at stack top to the stack. |
|||
If the value stack is empty, throws an error.</p> |
|||
|
|||
<p>Equivalent to calling |
|||
<code><a href="#duk_dup">duk_dup(ctx, -1)</a></code>.</p> |
|||
|
|||
example: | |
|||
duk_push_int(ctx, 123); /* -> [ ... 123 ] */ |
|||
duk_push_int(ctx, 234); /* -> [ ... 123 234 ] */ |
|||
duk_dup_top(ctx); /* -> [ ... 123 234 234 ] */ |
|||
|
|||
tags: |
|||
- stack |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,70 +0,0 @@ |
|||
=proto |
|||
void duk_enum(duk_context *ctx, duk_idx_t obj_index, duk_uint_t enum_flags); |
|||
|
|||
=stack |
|||
[ ... obj! ... ] -> [ ... obj! ... enum! ] |
|||
|
|||
=summary |
|||
<p>Create an enumerator for object at <code>obj_index</code>. Enumeration |
|||
details can be controlled with <code>enum_flags</code>. If the target value |
|||
is not an object, throws an error.</p> |
|||
|
|||
<p>Enumeration flags:</p> |
|||
<ul> |
|||
<li><code>DUK_ENUM_INCLUDE_NONENUMERABLE</code>: enumerate also non-enumerable |
|||
properties (by default only enumerable properties are enumerated)</li> |
|||
<li><code>DUK_ENUM_INCLUDE_INTERNAL</code>: enumerate also internal properties |
|||
(by default internal properties are not enumerated)</li> |
|||
<li><code>DUK_ENUM_OWN_PROPERTIES_ONLY</code>: enumerate only an object's "own" |
|||
properties (by default also inherited properties are enumerated) </li> |
|||
<li><code>DUK_ENUM_ARRAY_INDICES_ONLY</code>: enumerate only array indices, |
|||
i.e. property names of the form "0", "1", "2", etc.</li> |
|||
<li><code>DUK_ENUM_SORT_ARRAY_INDICES</code>: guarantee that array indices are |
|||
sorted by their numeric value, only use with <code>DUK_ENUM_ARRAY_INDICES_ONLY</code>; |
|||
this is quite slow</li> |
|||
</ul> |
|||
|
|||
<p>Without any flags, enumeration follows the Ecmascript default enumeration |
|||
semantics, as in the expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
for (key in obj) { |
|||
print(key, obj[i]); |
|||
} |
|||
</pre> |
|||
|
|||
<p>Once the enumerator has been created, use |
|||
<code><a href="#duk_next">duk_next()</a></code> to extract keys (or key/value |
|||
pairs) from the enumerator.</p> |
|||
|
|||
<div class="note"> |
|||
Array indices are usually enumerated in a sorted order even without the |
|||
<code>DUK_ENUM_SORT_ARRAY_INDICES</code> flag. This is not the case |
|||
for "sparse arrays" which contain a lot of gaps (unused indices). |
|||
Duktape represents such arrays internally using a key-value representation |
|||
instead of a plain array, which affects key enumeration order. |
|||
The criteria for switching from a dense to a sparse array are internal details |
|||
and potentially version dependent. With the <code>DUK_ENUM_SORT_ARRAY_INDICES</code> |
|||
flag the array indices will be sorted even for sparse arrays, at the |
|||
cost of an explicit key sorting pass. |
|||
</div> |
|||
|
|||
=example |
|||
duk_enum(ctx, -3, DUK_ENUM_INCLUDE_NONENUMERABLE); |
|||
|
|||
while (duk_next(ctx, -1 /*enum_index*/, 0 /*get_value*/)) { |
|||
/* [ ... enum key ] */ |
|||
printf("-> key %s\n", duk_get_string(ctx, -1)); |
|||
duk_pop(ctx); /* pop_key */ |
|||
} |
|||
|
|||
duk_pop(ctx); /* pop enum object */ |
|||
|
|||
=tags |
|||
object |
|||
property |
|||
|
|||
=seealso |
|||
duk_next |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,71 @@ |
|||
name: duk_enum |
|||
|
|||
proto: | |
|||
void duk_enum(duk_context *ctx, duk_idx_t obj_index, duk_uint_t enum_flags); |
|||
|
|||
stack: | |
|||
[ ... obj! ... ] -> [ ... obj! ... enum! ] |
|||
|
|||
summary: | |
|||
<p>Create an enumerator for object at <code>obj_index</code>. Enumeration |
|||
details can be controlled with <code>enum_flags</code>. If the target value |
|||
is not an object, throws an error.</p> |
|||
|
|||
<p>Enumeration flags:</p> |
|||
<ul> |
|||
<li><code>DUK_ENUM_INCLUDE_NONENUMERABLE</code>: enumerate also non-enumerable |
|||
properties (by default only enumerable properties are enumerated)</li> |
|||
<li><code>DUK_ENUM_INCLUDE_INTERNAL</code>: enumerate also internal properties |
|||
(by default internal properties are not enumerated)</li> |
|||
<li><code>DUK_ENUM_OWN_PROPERTIES_ONLY</code>: enumerate only an object's "own" |
|||
properties (by default also inherited properties are enumerated) </li> |
|||
<li><code>DUK_ENUM_ARRAY_INDICES_ONLY</code>: enumerate only array indices, |
|||
i.e. property names of the form "0", "1", "2", etc.</li> |
|||
<li><code>DUK_ENUM_SORT_ARRAY_INDICES</code>: guarantee that array indices are |
|||
sorted by their numeric value, only use with <code>DUK_ENUM_ARRAY_INDICES_ONLY</code>; |
|||
this is quite slow</li> |
|||
</ul> |
|||
|
|||
<p>Without any flags, enumeration follows the Ecmascript default enumeration |
|||
semantics, as in the expression:</p> |
|||
<pre class="ecmascript-code"> |
|||
for (key in obj) { |
|||
print(key, obj[i]); |
|||
} |
|||
</pre> |
|||
|
|||
<p>Once the enumerator has been created, use |
|||
<code><a href="#duk_next">duk_next()</a></code> to extract keys (or key/value |
|||
pairs) from the enumerator.</p> |
|||
|
|||
<div class="note"> |
|||
Array indices are usually enumerated in a sorted order even without the |
|||
<code>DUK_ENUM_SORT_ARRAY_INDICES</code> flag. This is not the case |
|||
for "sparse arrays" which contain a lot of gaps (unused indices). |
|||
Duktape represents such arrays internally using a key-value representation |
|||
instead of a plain array, which affects key enumeration order. |
|||
The criteria for switching from a dense to a sparse array are internal details |
|||
and potentially version dependent. With the <code>DUK_ENUM_SORT_ARRAY_INDICES</code> |
|||
flag the array indices will be sorted even for sparse arrays, at the |
|||
cost of an explicit key sorting pass. |
|||
</div> |
|||
|
|||
example: | |
|||
duk_enum(ctx, -3, DUK_ENUM_INCLUDE_NONENUMERABLE); |
|||
|
|||
while (duk_next(ctx, -1 /*enum_index*/, 0 /*get_value*/)) { |
|||
/* [ ... enum key ] */ |
|||
printf("-> key %s\n", duk_get_string(ctx, -1)); |
|||
duk_pop(ctx); /* pop_key */ |
|||
} |
|||
|
|||
duk_pop(ctx); /* pop enum object */ |
|||
|
|||
tags: |
|||
- object |
|||
- property |
|||
|
|||
seealso: |
|||
- duk_next |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,36 +0,0 @@ |
|||
=proto |
|||
duk_bool_t duk_equals(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); |
|||
|
|||
=stack |
|||
[ ... val1! ... val2! ... ] |
|||
|
|||
=summary |
|||
<p>Compare values at <code>index1</code> and <code>index2</code> for equality. |
|||
Returns 1 if values are considered equal using Ecmascript |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.9.1">Equals</a> |
|||
operator (<code>==</code>) semantics, otherwise returns 0. Also returns 0 if either |
|||
index is invalid.</p> |
|||
|
|||
<p>Because |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.9.3">The Abstract Equality Comparison Algorithm</a> |
|||
used by the Equals operator performs value coercion (<code>ToNumber()</code> and <code>ToPrimitive()</code>), |
|||
the comparison may have side effects and may throw an error. The strict equality comparison, |
|||
available through <code><a href="#duk_strict_equals">duk_strict_equals()</a></code>, has no |
|||
side effects.</p> |
|||
|
|||
<p>Comparison algorithm for Duktape custom types is described in |
|||
<a href="http://duktape.org/guide.html#non-strict-equality-algorithm">Equality (non-strict)</a>.</p> |
|||
|
|||
=example |
|||
if (duk_equals(ctx, -3, -7)) { |
|||
printf("values at indices -3 and -7 are equal\n"); |
|||
} |
|||
|
|||
=tags |
|||
compare |
|||
|
|||
=seealso |
|||
duk_strict_equals |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,37 @@ |
|||
name: duk_equals |
|||
|
|||
proto: | |
|||
duk_bool_t duk_equals(duk_context *ctx, duk_idx_t index1, duk_idx_t index2); |
|||
|
|||
stack: | |
|||
[ ... val1! ... val2! ... ] |
|||
|
|||
summary: | |
|||
<p>Compare values at <code>index1</code> and <code>index2</code> for equality. |
|||
Returns 1 if values are considered equal using Ecmascript |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.9.1">Equals</a> |
|||
operator (<code>==</code>) semantics, otherwise returns 0. Also returns 0 if either |
|||
index is invalid.</p> |
|||
|
|||
<p>Because |
|||
<a href="http://www.ecma-international.org/ecma-262/5.1/#sec-11.9.3">The Abstract Equality Comparison Algorithm</a> |
|||
used by the Equals operator performs value coercion (<code>ToNumber()</code> and <code>ToPrimitive()</code>), |
|||
the comparison may have side effects and may throw an error. The strict equality comparison, |
|||
available through <code><a href="#duk_strict_equals">duk_strict_equals()</a></code>, has no |
|||
side effects.</p> |
|||
|
|||
<p>Comparison algorithm for Duktape custom types is described in |
|||
<a href="http://duktape.org/guide.html#non-strict-equality-algorithm">Equality (non-strict)</a>.</p> |
|||
|
|||
example: | |
|||
if (duk_equals(ctx, -3, -7)) { |
|||
printf("values at indices -3 and -7 are equal\n"); |
|||
} |
|||
|
|||
tags: |
|||
- compare |
|||
|
|||
seealso: |
|||
- duk_strict_equals |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,33 +0,0 @@ |
|||
=proto |
|||
void duk_error(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... err! ] |
|||
|
|||
=summary |
|||
<p>Push a new Error object to the stack and throw it. |
|||
This call never returns.</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> |
|||
|
|||
<p>To push an Error object to the stack without throwing it, use |
|||
<code><a href="#duk_push_error_object">duk_push_error_object()</a></code>. |
|||
</p> |
|||
|
|||
=example |
|||
duk_error(ctx, DUK_ERR_RANGE_ERROR, "argument out of range: %d", (int) argval); |
|||
|
|||
=tags |
|||
error |
|||
|
|||
=seealso |
|||
duk_error_va |
|||
duk_throw |
|||
duk_push_error_object |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,34 @@ |
|||
name: duk_error |
|||
|
|||
proto: | |
|||
void duk_error(duk_context *ctx, duk_errcode_t err_code, const char *fmt, ...); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... err! ] |
|||
|
|||
summary: | |
|||
<p>Push a new Error object to the stack and throw it. |
|||
This call never returns.</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> |
|||
|
|||
<p>To push an Error object to the stack without throwing it, use |
|||
<code><a href="#duk_push_error_object">duk_push_error_object()</a></code>. |
|||
</p> |
|||
|
|||
example: | |
|||
duk_error(ctx, DUK_ERR_RANGE_ERROR, "argument out of range: %d", (int) argval); |
|||
|
|||
tags: |
|||
- error |
|||
|
|||
seealso: |
|||
- duk_error_va |
|||
- duk_throw |
|||
- duk_push_error_object |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,30 +0,0 @@ |
|||
=proto |
|||
void duk_error_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... err! ] |
|||
|
|||
=summary |
|||
<p>Vararg variant of |
|||
<code><a href="#duk_error">duk_error()</a></code>.</p> |
|||
|
|||
=example |
|||
void my_range_error(duk_context *ctx, const char *fmt, ...) { |
|||
va_list ap; |
|||
|
|||
va_start(ap, fmt); |
|||
duk_error_va(ctx, DUK_ERR_RANGE_ERROR, fmt, ap); |
|||
va_end(ap); |
|||
} |
|||
|
|||
=tags |
|||
error |
|||
vararg |
|||
|
|||
=seealso |
|||
duk_error |
|||
duk_throw |
|||
duk_push_error_object |
|||
|
|||
=introduced |
|||
1.1.0 |
|||
@ -0,0 +1,31 @@ |
|||
name: duk_error_va |
|||
|
|||
proto: | |
|||
void duk_error_va(duk_context *ctx, duk_errcode_t err_code, const char *fmt, va_list ap); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... err! ] |
|||
|
|||
summary: | |
|||
<p>Vararg variant of |
|||
<code><a href="#duk_error">duk_error()</a></code>.</p> |
|||
|
|||
example: | |
|||
void my_range_error(duk_context *ctx, const char *fmt, ...) { |
|||
va_list ap; |
|||
|
|||
va_start(ap, fmt); |
|||
duk_error_va(ctx, DUK_ERR_RANGE_ERROR, fmt, ap); |
|||
va_end(ap); |
|||
} |
|||
|
|||
tags: |
|||
- error |
|||
- vararg |
|||
|
|||
seealso: |
|||
- duk_error |
|||
- duk_throw |
|||
- duk_push_error_object |
|||
|
|||
introduced: 1.1.0 |
|||
@ -1,55 +0,0 @@ |
|||
=proto |
|||
void duk_eval(duk_context *ctx); |
|||
|
|||
=stack |
|||
[ ... source! ] -> [ ... result! ] |
|||
|
|||
=summary |
|||
<p>Evaluate the Ecmascript source code at the top of the stack, and leave a single |
|||
return value on top of the stack. May throw an error, errors are not caught |
|||
automatically. The filename associated with the temporary eval function is |
|||
automatically provided from the <code>__FILE__</code> preprocessor define |
|||
of the caller.</p> |
|||
|
|||
<p>This is essentially a shortcut for:</p> |
|||
<pre class="c-code"> |
|||
duk_push_string(ctx, __FILE__); |
|||
duk_compile(ctx, DUK_COMPILE_EVAL); /* [ ... source filename ] -> [ function ] */ |
|||
duk_call(ctx, 0); |
|||
</pre> |
|||
|
|||
<p>The source code is evaluated in non-strict mode unless it contains an |
|||
explicit <code>"use strict"</code> directive. In particular, strictness |
|||
of the current context is not transferred into the eval code. This avoids |
|||
confusing behavior where eval strictness would depend on whether eval is |
|||
used inside a Duktape/C function call (strict mode) or outside of one |
|||
(non-strict mode).</p> |
|||
|
|||
<p>If the eval input is a fixed string, you can also use |
|||
<code><a href="#duk_eval_string">duk_eval_string()</a></code>.</p> |
|||
|
|||
=example |
|||
/* Eval result in Ecmascript is the last non-empty statement; here, the |
|||
* result of the eval is the number 123. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "print('Hello world!'); 123;"); |
|||
duk_eval(ctx); |
|||
printf("return value is: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=seealso |
|||
duk_peval |
|||
duk_eval_noresult |
|||
duk_eval_string |
|||
duk_eval_string_noresult |
|||
duk_eval_lstring |
|||
duk_eval_lstring_noresult |
|||
duk_eval_file |
|||
duk_eval_file_noresult |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,56 @@ |
|||
name: duk_eval |
|||
|
|||
proto: | |
|||
void duk_eval(duk_context *ctx); |
|||
|
|||
stack: | |
|||
[ ... source! ] -> [ ... result! ] |
|||
|
|||
summary: | |
|||
<p>Evaluate the Ecmascript source code at the top of the stack, and leave a single |
|||
return value on top of the stack. May throw an error, errors are not caught |
|||
automatically. The filename associated with the temporary eval function is |
|||
automatically provided from the <code>__FILE__</code> preprocessor define |
|||
of the caller.</p> |
|||
|
|||
<p>This is essentially a shortcut for:</p> |
|||
<pre class="c-code"> |
|||
duk_push_string(ctx, __FILE__); |
|||
duk_compile(ctx, DUK_COMPILE_EVAL); /* [ ... source filename ] -> [ function ] */ |
|||
duk_call(ctx, 0); |
|||
</pre> |
|||
|
|||
<p>The source code is evaluated in non-strict mode unless it contains an |
|||
explicit <code>"use strict"</code> directive. In particular, strictness |
|||
of the current context is not transferred into the eval code. This avoids |
|||
confusing behavior where eval strictness would depend on whether eval is |
|||
used inside a Duktape/C function call (strict mode) or outside of one |
|||
(non-strict mode).</p> |
|||
|
|||
<p>If the eval input is a fixed string, you can also use |
|||
<code><a href="#duk_eval_string">duk_eval_string()</a></code>.</p> |
|||
|
|||
example: | |
|||
/* Eval result in Ecmascript is the last non-empty statement; here, the |
|||
* result of the eval is the number 123. |
|||
*/ |
|||
|
|||
duk_push_string(ctx, "print('Hello world!'); 123;"); |
|||
duk_eval(ctx); |
|||
printf("return value is: %lf\n", (double) duk_get_number(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
seealso: |
|||
- duk_peval |
|||
- duk_eval_noresult |
|||
- duk_eval_string |
|||
- duk_eval_string_noresult |
|||
- duk_eval_lstring |
|||
- duk_eval_lstring_noresult |
|||
- duk_eval_file |
|||
- duk_eval_file_noresult |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,28 +0,0 @@ |
|||
=proto |
|||
void duk_eval_file(duk_context *ctx, const char *path); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... result! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but the eval input |
|||
is given as a filename. The filename associated with the temporary |
|||
function created for the eval code is <code>path</code> as is.</p> |
|||
|
|||
<div include="path-encoding.html" /> |
|||
|
|||
=example |
|||
duk_eval_file(ctx, "test.js"); |
|||
printf("result is: %s\n", duk_safe_to_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
compile |
|||
nonportable |
|||
|
|||
=seealso |
|||
duk_eval_file_noresult |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,29 @@ |
|||
name: duk_eval_file |
|||
|
|||
proto: | |
|||
void duk_eval_file(duk_context *ctx, const char *path); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... result! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but the eval input |
|||
is given as a filename. The filename associated with the temporary |
|||
function created for the eval code is <code>path</code> as is.</p> |
|||
|
|||
<div include="path-encoding.html" /> |
|||
|
|||
example: | |
|||
duk_eval_file(ctx, "test.js"); |
|||
printf("result is: %s\n", duk_safe_to_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- compile |
|||
- nonportable |
|||
|
|||
seealso: |
|||
- duk_eval_file_noresult |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,22 +0,0 @@ |
|||
=proto |
|||
void duk_eval_file_noresult(duk_context *ctx, const char *path); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_eval_file">duk_eval_file()</a></code>, but leaves no |
|||
result on the value stack.</p> |
|||
|
|||
<div include="path-encoding.html" /> |
|||
|
|||
=example |
|||
duk_eval_file_noresult(ctx, "test.js"); |
|||
|
|||
=tags |
|||
compile |
|||
nonportable |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,23 @@ |
|||
name: duk_eval_file_noresult |
|||
|
|||
proto: | |
|||
void duk_eval_file_noresult(duk_context *ctx, const char *path); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_eval_file">duk_eval_file()</a></code>, but leaves no |
|||
result on the value stack.</p> |
|||
|
|||
<div include="path-encoding.html" /> |
|||
|
|||
example: | |
|||
duk_eval_file_noresult(ctx, "test.js"); |
|||
|
|||
tags: |
|||
- compile |
|||
- nonportable |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,31 +0,0 @@ |
|||
=proto |
|||
void duk_eval_lstring(duk_context *ctx, const char *src, duk_size_t len); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... result! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but the eval input |
|||
is given as a C string with explicit length. The filename associated with the |
|||
temporary is automatically provided from the <code>__FILE__</code> preprocessor |
|||
define of the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_eval_lstring(ctx, src, len); |
|||
printf("result is: %s\n", duk_get_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=seealso |
|||
duk_eval_lstring_noresult |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,32 @@ |
|||
name: duk_eval_lstring |
|||
|
|||
proto: | |
|||
void duk_eval_lstring(duk_context *ctx, const char *src, duk_size_t len); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... result! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but the eval input |
|||
is given as a C string with explicit length. The filename associated with the |
|||
temporary is automatically provided from the <code>__FILE__</code> preprocessor |
|||
define of the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_eval_lstring(ctx, src, len); |
|||
printf("result is: %s\n", duk_get_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
seealso: |
|||
- duk_eval_lstring_noresult |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,24 +0,0 @@ |
|||
=proto |
|||
void duk_eval_lstring_noresult(duk_context *ctx, const char *src, duk_size_t len); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_eval_lstring">duk_eval_lstring()</a></code>, but leaves no |
|||
result on the value stack.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_eval_lstring_noresult(ctx, src, len); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,25 @@ |
|||
name: duk_eval_lstring_noresult |
|||
|
|||
proto: | |
|||
void duk_eval_lstring_noresult(duk_context *ctx, const char *src, duk_size_t len); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_eval_lstring">duk_eval_lstring()</a></code>, but leaves no |
|||
result on the value stack.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
const char *src = /* ... */; |
|||
duk_size_t len = /* ... */; |
|||
|
|||
duk_eval_lstring_noresult(ctx, src, len); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,25 +0,0 @@ |
|||
=proto |
|||
void duk_eval_noresult(duk_context *ctx); |
|||
|
|||
=stack |
|||
[ ... source! ] -> [ ... ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but leaves no result on |
|||
the value stack.</p> |
|||
|
|||
=example |
|||
duk_push_string(ctx, "print('Hello world!');"); |
|||
duk_eval_noresult(ctx); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=seealso |
|||
duk_eval_string_noresult |
|||
duk_eval_lstring_noresult |
|||
duk_eval_file_noresult |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,26 @@ |
|||
name: duk_eval_noresult |
|||
|
|||
proto: | |
|||
void duk_eval_noresult(duk_context *ctx); |
|||
|
|||
stack: | |
|||
[ ... source! ] -> [ ... ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but leaves no result on |
|||
the value stack.</p> |
|||
|
|||
example: | |
|||
duk_push_string(ctx, "print('Hello world!');"); |
|||
duk_eval_noresult(ctx); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
seealso: |
|||
- duk_eval_string_noresult |
|||
- duk_eval_lstring_noresult |
|||
- duk_eval_file_noresult |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,28 +0,0 @@ |
|||
=proto |
|||
void duk_eval_string(duk_context *ctx, const char *src); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... result! ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but the eval input |
|||
is given as a C string. The filename associated with the temporary |
|||
is automatically provided from the <code>__FILE__</code> preprocessor define |
|||
of the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
duk_eval_string(ctx, "'testString'.toUpperCase()"); |
|||
printf("result is: %s\n", duk_get_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=seealso |
|||
duk_eval_string_noresult |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,29 @@ |
|||
name: duk_eval_string |
|||
|
|||
proto: | |
|||
void duk_eval_string(duk_context *ctx, const char *src); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... result! ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_eval">duk_eval()</a></code>, but the eval input |
|||
is given as a C string. The filename associated with the temporary |
|||
is automatically provided from the <code>__FILE__</code> preprocessor define |
|||
of the caller.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
duk_eval_string(ctx, "'testString'.toUpperCase()"); |
|||
printf("result is: %s\n", duk_get_string(ctx, -1)); |
|||
duk_pop(ctx); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
seealso: |
|||
- duk_eval_string_noresult |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,21 +0,0 @@ |
|||
=proto |
|||
void duk_eval_string_noresult(duk_context *ctx, const char *src); |
|||
|
|||
=stack |
|||
[ ... ] -> [ ... ] |
|||
|
|||
=summary |
|||
<p>Like |
|||
<code><a href="#duk_eval_string">duk_eval_string()</a></code>, but leaves no |
|||
result on the value stack.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
=example |
|||
duk_eval_string_noresult(ctx, "print('testString'.toUpperCase())"); |
|||
|
|||
=tags |
|||
compile |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,22 @@ |
|||
name: duk_eval_string_noresult |
|||
|
|||
proto: | |
|||
void duk_eval_string_noresult(duk_context *ctx, const char *src); |
|||
|
|||
stack: | |
|||
[ ... ] -> [ ... ] |
|||
|
|||
summary: | |
|||
<p>Like |
|||
<code><a href="#duk_eval_string">duk_eval_string()</a></code>, but leaves no |
|||
result on the value stack.</p> |
|||
|
|||
<div include="no-string-intern.html" /> |
|||
|
|||
example: | |
|||
duk_eval_string_noresult(ctx, "print('testString'.toUpperCase())"); |
|||
|
|||
tags: |
|||
- compile |
|||
|
|||
introduced: 1.0.0 |
|||
@ -1,22 +0,0 @@ |
|||
=proto |
|||
void duk_fatal(duk_context *ctx, duk_errcode_t err_code, const char *err_msg); |
|||
|
|||
=summary |
|||
<p>Call fatal error handler with a specified error code and an optional |
|||
message (<code>err_msg</code> may be <code>NULL</code>). The valid range |
|||
for user error codes is [1,16777215].</p> |
|||
|
|||
<p>A fatal error handler never returns and may e.g. exit the current |
|||
process. Error catching points (like <code>try-catch</code> statements |
|||
and error catching API calls) are bypassed, and finalizers are not executed. |
|||
You should only call this function when a truly fatal, unrecoverable error |
|||
has occurred.</p> |
|||
|
|||
=example |
|||
duk_fatal(ctx, DUK_ERR_INTERNAL_ERROR, "assumption failed"); |
|||
|
|||
=tags |
|||
error |
|||
|
|||
=introduced |
|||
1.0.0 |
|||
@ -0,0 +1,23 @@ |
|||
name: duk_fatal |
|||
|
|||
proto: | |
|||
void duk_fatal(duk_context *ctx, duk_errcode_t err_code, const char *err_msg); |
|||
|
|||
summary: | |
|||
<p>Call fatal error handler with a specified error code and an optional |
|||
message (<code>err_msg</code> may be <code>NULL</code>). The valid range |
|||
for user error codes is [1,16777215].</p> |
|||
|
|||
<p>A fatal error handler never returns and may e.g. exit the current |
|||
process. Error catching points (like <code>try-catch</code> statements |
|||
and error catching API calls) are bypassed, and finalizers are not executed. |
|||
You should only call this function when a truly fatal, unrecoverable error |
|||
has occurred.</p> |
|||
|
|||
example: | |
|||
duk_fatal(ctx, DUK_ERR_INTERNAL_ERROR, "assumption failed"); |
|||
|
|||
tags: |
|||
- error |
|||
|
|||
introduced: 1.0.0 |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue