This article needs a technical review. How you can help.
Create a new JSString
whose characters are stored in external memory.
Syntax
JSString * JS_NewExternalString(JSContext *cx, const char16_t *chars, size_t length, const JSStringFinalizer *fin); JSString * JS_NewExternalStringWithClosure(JSContext *cx, jschar *chars, size_t length, int type, void *closure); // Obsolete since JSAPI 13
Name | Type | Description |
---|---|---|
cx |
JSContext * |
The context in which to create the new string. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext . |
chars |
const char16_t * or const jschar * |
Pointer to the first element of an array of char16_t s. This array is used as the character buffer of the JSString to be created. The array must be populated with the desired character data before JS_NewExternalString is called, and the array must remain in memory, with its contents unchanged, for as long as the JavaScript engine needs to hold on to it. (Ultimately, the string will be garbage collected, and the JavaScript engine will call the string finalizer callback, allowing the application to free the array.) The array does not need to be zero-terminated. |
length |
size_t |
The number of characters in the array chars . |
fin |
JSStringFinalizer |
A string finalizer the JavaScript engine should use (later) to free the string buffer chars . Added in SpiderMonkey 17 |
type |
int |
(JS_NewExternalStringWithClosure only) Indicates which string finalizer callback the JavaScript engine should use (later) to free the string buffer chars . This must be an id number previously returned by a successful call to JS_AddExternalStringFinalizer . Obsolete since JSAPI 13 |
closure |
void * |
(JS_NewExternalStringWithClosure only) Arbitrary, application-defined data to include in the string object after it's created. If you use this as a pointer, you should clean it up in the external string finalizer that was previously set up using JS_AddExternalStringFinalizer . Obsolete since JSAPI 13 |
Description
JS_NewExternalString
and JS_NewExternalStringWithClosure
create a new JSString
whose characters are stored in external memory, i.e., memory allocated by the application, not the JavaScript engine. Since the program allocated the memory, it will need to free it; this happens in an external string finalizer indicated by the type
parameter.
JS_NewExternalStringWithClosure
works similarly, except it accepts an additional parameter, closure
, which is saved in the string's internal data structure. It can be retrieved later by calling JS_GetExternalStringClosure
. This is application-defined data you can associate with the string.
To determine if a string was created as an external string, you can call JS_IsExternalString
.
See Also
- MXR ID Search for
JS_NewExternalString
JS_GetExternalStringClosure
JS_IsExternalString
- bug 724810 - replaced
type
withfin
parameter, and removeJS_NewExternalStringWithClosure