@@ -406,11 +406,12 @@ added: v8.0.0
406
406
-->
407
407
``` C
408
408
NODE_EXTERN napi_status napi_create_error (napi_env env,
409
- const char * msg,
409
+ napi_value msg,
410
410
napi_value* result);
411
411
```
412
412
- `[in] env`: The environment that the API is invoked under.
413
- - `[in] msg`: C string representing the text to be associated with.
413
+ - `[in] msg`: napi_value that references a JavaScript String to be
414
+ used as the message for the Error.
414
415
- `[out] result`: `napi_value` representing the error created.
415
416
416
417
Returns `napi_ok` if the API succeeded.
@@ -423,11 +424,12 @@ added: v8.0.0
423
424
-->
424
425
```C
425
426
NODE_EXTERN napi_status napi_create_type_error(napi_env env,
426
- const char* msg,
427
+ napi_value msg,
427
428
napi_value* result);
428
429
```
429
430
- ` [in] env ` : The environment that the API is invoked under.
430
- - ` [in] msg ` : C string representing the text to be associated with.
431
+ - ` [in] msg ` : napi_value that references a JavaScript String to be
432
+ used as the message for the Error.
431
433
- ` [out] result ` : ` napi_value ` representing the error created.
432
434
433
435
Returns ` napi_ok ` if the API succeeded.
@@ -445,7 +447,8 @@ NODE_EXTERN napi_status napi_create_range_error(napi_env env,
445
447
napi_value* result);
446
448
```
447
449
- `[in] env`: The environment that the API is invoked under.
448
- - `[in] msg`: C string representing the text to be associated with.
450
+ - `[in] msg`: napi_value that references a JavaScript String to be
451
+ used as the message for the Error.
449
452
- `[out] result`: `napi_value` representing the error created.
450
453
451
454
Returns `napi_ok` if the API succeeded.
@@ -562,16 +565,17 @@ for (int i = 0; i < 1000000; i++) {
562
565
```
563
566
564
567
When nesting scopes, there are cases where a handle from an
565
- inner scope needs to live beyond the lifespan of that scope. N-API supports an
568
+ inner scope needs to live beyond the lifespan of that scope. N-API supports an
566
569
'escapable scope' in order to support this case. An escapable scope
567
- allows one or more handles to be 'promoted' so that they 'escape ' the
568
- current scope and the lifespan of the handle(s) changes from the current
570
+ allows one handle to be 'promoted' so that it 'escapes ' the
571
+ current scope and the lifespan of the handle changes from the current
569
572
scope to that of the outer scope.
570
573
571
574
The methods available to open/close escapable scopes are
572
575
[ ` napi_open_escapable_handle_scope ` ] [ ] and [ ` napi_close_escapable_handle_scope ` ] [ ] .
573
576
574
- The request to promote a handle is made through the [ ` napi_escape_handle ` ] [ ] .
577
+ The request to promote a handle is made through [ ` napi_escape_handle ` ] [ ] which
578
+ can only be called once.
575
579
576
580
#### napi_open_handle_scope
577
581
<!-- YAML
@@ -618,7 +622,7 @@ NODE_EXTERN napi_status
618
622
619
623
Returns `napi_ok` if the API succeeded.
620
624
621
- This API open a new scope from which objects can be promoted
625
+ This API open a new scope from which one object can be promoted
622
626
to the outer scope.
623
627
624
628
#### napi_close_escapable_handle_scope
@@ -657,9 +661,9 @@ Object in the outer scope.
657
661
658
662
Returns `napi_ok` if the API succeeded.
659
663
660
- This API promotes the handle to the JavaScript object so that it valid
661
- for the lifetime of the outer scope.
662
-
664
+ This API promotes the handle to the JavaScript object so that it is valid
665
+ for the lifetime of the outer scope. It can only be called once per scope.
666
+ If it is called more than once an error will be returned.
663
667
664
668
### References to objects with a lifespan longer than that of the native method
665
669
In some cases an addon will need to be able to create and reference objects
@@ -1212,13 +1216,13 @@ added: v8.0.0
1212
1216
-->
1213
1217
``` C
1214
1218
napi_status napi_create_symbol (napi_env env,
1215
- const char * description,
1219
+ napi_value description,
1216
1220
napi_value* result)
1217
1221
```
1218
1222
1219
1223
- `[in] env`: The environment that the API is invoked under.
1220
- - `[in] description`: Null-terminated character buffer representing a
1221
- UTF8-encoded string to describe the symbol.
1224
+ - `[in] description`: Optional napi_value which refers to a JavaScript
1225
+ String to be set as the description for the symbol.
1222
1226
- `[out] result`: A `napi_value` representing a JavaScript Symbol.
1223
1227
1224
1228
Returns `napi_ok` if the API succeeded.
@@ -1299,8 +1303,8 @@ napi_status napi_create_string_utf16(napi_env env,
1299
1303
1300
1304
- ` [in] env ` : The environment that the API is invoked under.
1301
1305
- ` [in] str ` : Character buffer representing a UTF16-LE-encoded string.
1302
- - ` [in] length ` : The length of the string in characters , or -1 if it is
1303
- null-terminated.
1306
+ - ` [in] length ` : The length of the string in two-byte code units , or -1 if
1307
+ it is null-terminated.
1304
1308
- ` [out] result ` : A ` napi_value ` representing a JavaScript String.
1305
1309
1306
1310
Returns ` napi_ok ` if the API succeeded.
@@ -1311,6 +1315,31 @@ The JavaScript String type is described in
1311
1315
[ Section 6.1.4] ( https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type )
1312
1316
of the ECMAScript Language Specification.
1313
1317
1318
+ #### * napi_create_string_latin1*
1319
+ <!-- YAML
1320
+ added: v8.0.0
1321
+ -->
1322
+ ``` C
1323
+ NAPI_EXTERN napi_status napi_create_string_latin1 (napi_env env,
1324
+ const char* str,
1325
+ size_t length,
1326
+ napi_value* result);
1327
+ ```
1328
+
1329
+ - `[in] env`: The environment that the API is invoked under.
1330
+ - `[in] str`: Character buffer representing a latin1-encoded string.
1331
+ - `[in] length`: The length of the string in bytes, or -1 if it is
1332
+ null-terminated.
1333
+ - `[out] result`: A `napi_value` representing a JavaScript String.
1334
+
1335
+ Returns `napi_ok` if the API succeeded.
1336
+
1337
+ This API creates a JavaScript String object from a latin1-encoded C string.
1338
+
1339
+ The JavaScript String type is described in
1340
+ [Section 6.1.4](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type)
1341
+ of the ECMAScript Language Specification.
1342
+
1314
1343
#### *napi_create_string_utf8*
1315
1344
<!-- YAML
1316
1345
added: v8.0.0
@@ -1323,8 +1352,8 @@ napi_status napi_create_string_utf8(napi_env env,
1323
1352
```
1324
1353
1325
1354
- ` [in] env ` : The environment that the API is invoked under.
1326
- - `[in] s `: Character buffer representing a UTF8-encoded string.
1327
- - `[in] length`: The length of the string in characters , or -1 if it is
1355
+ - ` [in] str ` : Character buffer representing a UTF8-encoded string.
1356
+ - ` [in] length ` : The length of the string in bytes , or -1 if it is
1328
1357
null-terminated.
1329
1358
- ` [out] result ` : A ` napi_value ` representing a JavaScript String.
1330
1359
0 commit comments