From e029a076c6bc5ae2303f4027c3c556ddc976918d Mon Sep 17 00:00:00 2001 From: Hitesh Kanwathirtha Date: Thu, 10 May 2018 02:33:17 -0700 Subject: [PATCH] doc: First pass at basic Node Addon API docs PR-URL: https://github.com/nodejs/node-addon-api/pull/268 Reviewed-By: Michael Dawson --- doc/array.md | 5 - doc/basic_types.md | 410 ++++++++++++++++++++++++++++++++++++++++++++- doc/name.md | 5 - doc/string.md | 79 ++++++--- doc/symbol.md | 45 ++++- 5 files changed, 506 insertions(+), 38 deletions(-) delete mode 100644 doc/array.md delete mode 100644 doc/name.md diff --git a/doc/array.md b/doc/array.md deleted file mode 100644 index 0672fdb04..000000000 --- a/doc/array.md +++ /dev/null @@ -1,5 +0,0 @@ -# Array - -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) diff --git a/doc/basic_types.md b/doc/basic_types.md index 38e9d3e82..9a4fc71eb 100644 --- a/doc/basic_types.md +++ b/doc/basic_types.md @@ -1,5 +1,409 @@ # Basic Types -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) +Node Addon API consists of a few fundamental data types. These allow a user of +the API to create, convert and introspect fundamental JavaScript types, and +interoperate with their C++ counterparts. + +## Value + +Value is the base class of Node Addon API's fundamental object type hierarchy. +It represents a JavaScript value of an unknown type. It is a thin wrapper around +the N-API datatype `napi_value`. Methods on this class can be used to check +the JavaScript type of the underlying N-API `napi_value` and also to convert to +C++ types. + +### Constructor + +```cpp +Value(); +``` + +Used to create a Node Addon API `Value` that represents an **empty** value. + +```cpp +Value(napi_env env, napi_value value); +``` + +- `[in] env` - The `napi_env` environment in which to construct the Value +object. +- `[in] value` - The underlying JavaScript value that the `Value` instance +represents. + +Returns a Node.js Addon API `Value` that represents the `napi_value` passed +in. + +### Operators + +#### operator napi_value + +```cpp +operator napi_value() const; +``` + +Returns the underlying N-API `napi_value`. If the instance is _empty_, this +returns `nullptr`. + +#### operator == + +```cpp +bool operator ==(const Value& other) const; +``` + +Returns `true` if this value strictly equals another value, or `false` otherwise. + +#### operator != + +```cpp +bool operator !=(const Value& other) const; +``` + +Returns `false` if this value strictly equals another value, or `true` otherwise. + +### Methods + +#### From +```cpp +template +static Value From(napi_env env, const T& value); +``` + +- `[in] env` - The `napi_env` environment in which to construct the Value object. +- `[in] value` - The C++ type to represent in JavaScript. + +Returns a `Napi::Value` representing the input C++ type in JavaScript. + +This method is used to convert from a C++ type to a JavaScript value. +Here, `value` may be any of: +- `bool` - returns a `Napi::Boolean`. +- Any integer type - returns a `Napi::Number`. +- Any floating point type - returns a `Napi::Number`. +- `const char*` (encoded using UTF-8, null-terminated) - returns a `Napi::String`. +- `const char16_t*` (encoded using UTF-16-LE, null-terminated) - returns a `Napi::String`. +- `std::string` (encoded using UTF-8) - returns a `Napi::String`. +- `std::u16string` - returns a `Napi::String`. +- `napi::Value` - returns a `Napi::Value`. +- `napi_value` - returns a `Napi::Value`. + +#### As +```cpp +template T As() const; +``` + +Returns the `Napi::Value` cast to a desired C++ type. + +Use this when the actual type is known or assumed. + +Note: +This conversion does NOT coerce the type. Calling any methods inappropriate for +the actual value type will throw `Napi::Error`. + +#### StrictEquals +```cpp +bool StrictEquals(const Value& other) const; +``` + +- `[in] other` - The value to compare against. + +Returns true if the other `Napi::Value` is strictly equal to this one. + +#### Env +```cpp +Napi::Env Env() const; +``` + +Returns the environment that the value is associated with. See +[`Napi::Env`](env.md) for more details about environments. + +#### IsEmpty +```cpp +bool IsEmpty() const; +``` + +Returns `true` if the value is uninitialized. + +An empty value is invalid, and most attempts to perform an operation on an +empty value will result in an exception. An empty value is distinct from +JavaScript `null` or `undefined`, which are valid values. + +When C++ exceptions are disabled at compile time, a method with a `Value` +return type may return an empty value to indicate a pending exception. If C++ +exceptions are not being used, callers should check the result of +`Env::IsExceptionPending` before attempting to use the value. + +#### Type +```cpp +napi_valuetype Type() const; +``` + +Returns the underlying N-API `napi_valuetype` of the value. + +#### IsUndefined +```cpp +bool IsUndefined() const; +``` + +Returns `true` if the underlying value is a JavaScript `undefined` or `false` +otherwise. + +#### IsNull +```cpp +bool IsNull() const; +``` + +Returns `true` if the underlying value is a JavaScript `null` or `false` +otherwise. + +#### IsBoolean +```cpp +bool IsBoolean() const; +``` + +Returns `true` if the underlying value is a JavaScript `true` or JavaScript +`false`, or `false` if the value is not a Boolean value in JavaScript. + +#### IsNumber +```cpp +bool IsNumber() const; +``` + +Returns `true` if the underlying value is a JavaScript `Number` or `false` +otherwise. + +#### IsString +```cpp +bool IsString() const; +``` + +Returns `true` if the underlying value is a JavaScript `String` or `false` +otherwise. + +#### IsSymbol +```cpp +bool IsSymbol() const; +``` + +Returns `true` if the underlying value is a JavaScript `Symbol` or `false` +otherwise. + +#### IsArray +```cpp +bool IsArray() const; +``` + +Returns `true` if the underlying value is a JavaScript `Array` or `false` +otherwise. + +#### IsArrayBuffer +```cpp +bool IsArrayBuffer() const; +``` + +Returns `true` if the underlying value is a JavaScript `ArrayBuffer` or `false` +otherwise. + +#### IsTypedArray +```cpp +bool IsTypedArray() const; +``` + +Returns `true` if the underlying value is a JavaScript `TypedArray` or `false` +otherwise. + +#### IsObject +```cpp +bool IsObject() const; +``` + +Returns `true` if the underlying value is a JavaScript `Object` or `false` +otherwise. + +#### IsFunction +```cpp +bool IsFunction() const; +``` + +Returns `true` if the underlying value is a JavaScript `Function` or `false` +otherwise. + +#### IsPromise +```cpp +bool IsPromise() const; +``` + +Returns `true` if the underlying value is a JavaScript `Promise` or `false` +otherwise. + +#### IsDataView +```cpp +bool IsDataView() const; +``` + +Returns `true` if the underlying value is a JavaScript `DataView` or `false` +otherwise. + +#### IsBuffer +```cpp +bool IsBuffer() const; +``` + +Returns `true` if the underlying value is a Node.js `Buffer` or `false` +otherwise. + +#### IsExternal +```cpp +bool IsExternal() const; +``` + +Returns `true` if the underlying value is a N-API external object or `false` +otherwise. + +#### ToBoolean +```cpp +Boolean ToBoolean() const; +``` + +Returns a `Napi::Boolean` representing the `Napi::Value`. + +This is a wrapper around `napi_coerce_to_boolean`. This will throw a JavaScript +exception if the coercion fails. If C++ exceptions are not being used, callers +should check the result of `Env::IsExceptionPending` before attempting to use +the returned value. + + +#### ToNumber +```cpp +Number ToNumber() const; +``` + +Returns a `Napi::Number` representing the `Napi::Value`. + +Note: +This can cause script code to be executed according to JavaScript semantics. +This is a wrapper around `napi_coerce_to_number`. This will throw a JavaScript +exception if the coercion fails. If C++ exceptions are not being used, callers +should check the result of `Env::IsExceptionPending` before attempting to use +the returned value. + + +#### ToString +```cpp +String ToString() const; +``` + +Returns a `Napi::String` representing the `Napi::Value`. + +Note that this can cause script code to be executed according to JavaScript +semantics. This is a wrapper around `napi_coerce_to_string`. This will throw a +JavaScript exception if the coercion fails. If C++ exceptions are not being +used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + + +#### ToObject +```cpp +Object ToObject() const; +``` + +Returns a `Napi::Object` representing the `Napi::Value`. + +This is a wrapper around `napi_coerce_to_object`. This will throw a JavaScript +exception if the coercion fails. If C++ exceptions are not being used, callers +should check the result of `Env::IsExceptionPending` before attempting to use +the returned value. + + +## Name + +Names are JavaScript values that can be used as a property name. There are two +specialized types of names supported in Node.js Addon API- [`String`](String.md) +and [`Symbol`](Symbol.md). + +### Methods + +#### Constructor +```cpp +Name(); +``` + +Returns an empty `Name`. + +```cpp +Name(napi_env env, napi_value value); +``` +- `[in] env` - The environment in which to create the array. +- `[in] value` - The primitive to wrap. + +Returns a Name created from the JavaScript primitive. + +Note: +The value is not coerced to a string. + +## Array + +Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper +around `napi_value` representing a JavaScript Array. + +### Constructor +```cpp +Array(); +``` + +Returns an empty array. + +If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + + +```cpp +Array(napi_env env, napi_value value); +``` +- `[in] env` - The environment in which to create the array. +- `[in] value` - The primitive to wrap. + +Returns a `Napi::Array` wrapping a `napi_value`. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +### Methods + +#### New +```cpp +static Array New(napi_env env); +``` +- `[in] env` - The environment in which to create the array. + +Returns a new `Napi::Array`. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +#### New + +```cpp +static Array New(napi_env env, size_t length); +``` +- `[in] env` - The environment in which to create the array. +- `[in] length` - The length of the array. + +Returns a new `Napi::Array` with the given length. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +#### New +```cpp +uint32_t Length() const; +``` + +Returns the length of the array. + +Note: +This can execute JavaScript code implicitly according to JavaScript semantics. +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. diff --git a/doc/name.md b/doc/name.md deleted file mode 100644 index 1563f2b8b..000000000 --- a/doc/name.md +++ /dev/null @@ -1,5 +0,0 @@ -# Name - -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) diff --git a/doc/string.md b/doc/string.md index 19324cf4a..fd1ff8b13 100644 --- a/doc/string.md +++ b/doc/string.md @@ -1,51 +1,86 @@ # String -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) -# Methods - -### Constructor - -Creates a new String value from a UTF-8 encoded c++ string. +## Constructor ```cpp -String::New(napi_env env, const std::string& value); +String(); ``` -- `[in] env`: The `napi_env` environment in which to construct the Value object. -- `[in] value`: The C++ primitive from which to instantiate the Value. `value` may be any of: - - std::string& - - std::u16string& - - const char* - - const char16_t* +Returns a new **empty** String instance. -Creates a new empty String +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. -```cpp -String::New(); ``` +String(napi_env env, napi_value value); ///< Wraps a N-API value primitive. +``` +- `[in] env` - The environment in which to create the string. +- `[in] value` - The primitive to wrap. + +Returns a `Napi::String` wrapping a `napi_value`. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +## Operators ### operator std::string ```cpp operator std::string() const; ``` -Converts a String value to a UTF-8 encoded C++ string. + +Returns a UTF-8 encoded C++ string. ### operator std::u16string ```cpp operator std::u16string() const; ``` -Converts a String value to a UTF-16 encoded C++ string. + +Returns a UTF-16 encoded C++ string. + +## Methods + +### New +```cpp +String::New(); +``` + +Returns a new empty String + +### New +```cpp +String::New(napi_env env, const std::string& value); +String::New(napi_env env, const std::u16string& value); +String::New(napi_env env, const char* value); +String::New(napi_env env, const char16_t* value); +``` + +- `[in] env`: The `napi_env` environment in which to construct the Value object. +- `[in] value`: The C++ primitive from which to instantiate the Value. `value` may be any of: + - `std::string&` - represents an ANSI string. + - `std::u16string&` - represents a UTF16-LE string. + - `const char*` - represents a UTF8 string. + - `const char16_t*` - represents a UTF16-LE string. + +Returns a new `Napi::String` that represents the passed in C++ string. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. ### Utf8Value ```cpp std::string Utf8Value() const; ``` -Converts a String value to a UTF-8 encoded C++ string. + +Returns a UTF-8 encoded C++ string. + ### Utf16Value ```cpp std::u16string Utf16Value() const; ``` -Converts a String value to a UTF-16 encoded C++ string. \ No newline at end of file + +Returns a UTF-16 encoded C++ string. \ No newline at end of file diff --git a/doc/symbol.md b/doc/symbol.md index f644d137f..fe7ee9c03 100644 --- a/doc/symbol.md +++ b/doc/symbol.md @@ -1,5 +1,44 @@ # Symbol -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) +## Methods + +### Constructor + +Instantiates a new `Symbol` value + +```cpp +Symbol(); +``` + +Returns a new empty Symbol. + +### New +```cpp +Symbol::New(napi_env env, const std::string& description); +Symbol::New(napi_env env, const char* description); +Symbol::New(napi_env env, String description); +Symbol::New(napi_env env, napi_value description); +``` + +- `[in] env`: The `napi_env` environment in which to construct the Symbol object. +- `[in] value`: The C++ primitive which represents the description hint for the Symbol. + `description` may be any of: + - `std::string&` - ANSI string description. + - `const char*` - represents a UTF8 string description. + - `String` - Node addon API String description. + - `napi_value` - N-API `napi_value` description. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +### Utf8Value +```cpp +static Symbol WellKnown(napi_env env, const std::string& name); +``` + +- `[in] env`: The `napi_env` environment in which to construct the Symbol object. +- `[in] name`: The C++ string representing the `Symbol` to retrieve. + +Returns a `Napi::Symbol` representing a well-known Symbol from the +Symbol registry.