From 85e2734003b49548ee323e5c1801d240bd45b5ee Mon Sep 17 00:00:00 2001 From: Anisha Rohra Date: Tue, 1 May 2018 00:13:38 -0400 Subject: [PATCH 1/5] Updated Object documentation --- doc/object.md | 198 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 195 insertions(+), 3 deletions(-) diff --git a/doc/object.md b/doc/object.md index 1f46ace2f..e9bef1556 100644 --- a/doc/object.md +++ b/doc/object.md @@ -1,5 +1,197 @@ # Object -You are reading a draft of the next documentation and it's in continuos 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/) \ No newline at end of file +Object is a Javascript object value. A common usecase is to assign many values to a single object. + +Object is extended by [Value](value.md) and extends [Array](array.md), [ArrayBuffer](array_buffer.md), [Buffer](buffer.md), [Function](function.md), and [TypedArray](typed_array.md). + +## Methods + +### Empty Constructor + +```cpp +Napi::Object::Object(); +``` +Creates a new empty Object instance. + +### Constructor + +```cpp +Napi::Object::Object(napi_env env, napi_value 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: + - bool + - Any integer type + - Any floating point type + - const char* (encoded using UTF-8, null-terminated) + - const char16_t* (encoded using UTF-16-LE, null-terminated) + - std::string (encoded using UTF-8) + - std::u16string + - napi::Value + - napi_value + +Creates a non-empty Object instance. + +### New() + +```cpp +Object Napi::Object::New(napi_env env); +``` +- `[in] env`: The `napi_env` environment in which to construct the Value object. + +Creates a new Object value. + +### Set() + +```cpp +void Napi::Object::Set (____ key, ____ value); +``` +- `[in] key`: The property that is being assigned a value. +- `[in] value`: The property that is being assigned to a key. + +Assigns the value to the key . + +The key-value pair types can be one of the following: +- `napi_value` key, `napi_value` value +- [Value](value.md) key, [Value](value.md) value + +Alternatively, the key can be any of the following types: +- `const char*` +- `const std::string&` +- `uint32_t` + +While the value must be any of the following types: +- `napi_value` +- [Value](value.md) +- `const char*` +- `std::string&` +- `bool` +- `double` + +### Get() + +```cpp +Value Napi::Object::Get(____ key); +``` +- `[in] key`: The property whose assigned value is being returned. + +Returns the [Value](value.md) associated with the key property. +The `key` can be any of the following types: +- `napi_value` +- [Value](value.md) +- `const char *` +- `const std::string &` +- `uint32_t` + +### Has() + +```cpp +bool Napi::Object::Has (____ key) const; +``` +- `[in] key`: The property that is being checked for having an assigned value. + +Returns a `bool` that is *true* if the `key` has a value property associated with it and *false* otherwise. + +### InstanceOf() + +```cpp +bool Napi::Object::InstanceOf (const Function& constructor) const +``` +- `[in] constructor`: The constructor [Function](function.md) of the value that is being compared with the object. + +Returns a `bool` that is true if the Object is an instance created by the `constructor` and false otherwise. + +Note: This is equivalent to the JavaScript instanceof operator. + +### DefineProperty() + +```cpp +void Napi::Object::DefineProperty (const PropertyDescriptor& property); +``` +- `[in] property`: A [PropertyDescriptor](propertydescriptor.md). + +Define a property on the object. + +### DefineProperties() + +```cpp +void Napi::Object::DefineProperties (____ properties) +``` +- `[in] properties`: A list of [PropertyDescriptor](propertydescriptor.md). Can be one of the following types: + - const std::initializer_list& + - const std::vector& + +Defines properties on the object. + +### Operator[]() + +```cpp +PropertyLValue Napi::Object::operator[] (const char* utf8name); +``` +- `[in] utf8name`: UTF-8 encoded null-terminated property name. + +Returns a [PropertyLValue](propertylvalue.md) as the named property or sets the named property. + +```cpp +PropertyLValue Napi::Object::operator[] (const std::string& utf8name); +``` +- `[in] utf8name`: UTF-8 encoded property name. + +Returns a [PropertyLValue](propertylvalue.md) as the named property or sets the named property. + +```cpp +PropertyLValue Napi::Object::operator[] (uint32_t index); +``` +- `[in] index`: Element index. + +Returns a [PropertyLValue](propertylvalue.md) or sets an indexed property or array element. + +```cpp +Value Napi::Object::operator[] (const char* utf8name) const; +``` +- `[in] utf8name`: UTF-8 encoded null-terminated property name. + +Returns the named property as a [Value](value.md). + +```cpp +Value Napi::Object::operator[] (const std::string& utf8name) const; +``` +- `[in] utf8name`: UTF-8 encoded property name. + +Returns the named property as a [Value](value.md). + +```cpp +Value Napi::Object::operator[] (uint32_t index) const; +``` +- `[in] index`: Element index. + +Returns an indexed property or array element as a [Value](value.md). + +### Example +```cpp +#include + +using namescape Napi; + +Void Init(Env env) { + + // Create a new instance + Object obj = Object::New(env); + + // Assign values to properties + obj.Set("hello", "world"); + obj.Set(42, "The Answer to Life, the Universe, and Everything"); + obj.Set("Douglas Adams", true); + + // Get properties + Value val1 = obj.Get("hello"); + Value val2 = obj.Get(42); + Value val3 = obj.Get("Douglas Adams"); + + // Test if objects have properties. + bool obj1 = obj.Has("hello"); // true + bool obj2 = obj.Has("world"); // false + +} +``` From 4408a767cbb5a7d1449a75ebcae8584b5b89ba03 Mon Sep 17 00:00:00 2001 From: Anisha Rohra Date: Thu, 10 May 2018 12:34:36 -0400 Subject: [PATCH 2/5] Changes made for clarity to object.md --- doc/object.md | 89 +++++++++++++++++++++++++++------------------------ 1 file changed, 47 insertions(+), 42 deletions(-) diff --git a/doc/object.md b/doc/object.md index e9bef1556..9a880142b 100644 --- a/doc/object.md +++ b/doc/object.md @@ -1,8 +1,42 @@ # Object -Object is a Javascript object value. A common usecase is to assign many values to a single object. +The Object class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types: -Object is extended by [Value](value.md) and extends [Array](array.md), [ArrayBuffer](array_buffer.md), [Buffer](buffer.md), [Function](function.md), and [TypedArray](typed_array.md). +- [Value](value.md) and extends [Array](array.md) +- [ArrayBuffer](array_buffer.md) +- [Buffer](buffer.md) +- [Function](function.md) +- [TypedArray](typed_array.md). + +This class provides a number of convenience methods, most of which are used to set or set properties on a JavaScript object. For example, Set() and Get(). + +## Example +```cpp +#include + +using namescape Napi; + +Void Init(Env env) { + + // Create a new instance + Object obj = Object::New(env); + + // Assign values to properties + obj.Set("hello", "world"); + obj.Set(42, "The Answer to Life, the Universe, and Everything"); + obj.Set("Douglas Adams", true); + + // Get properties + Value val1 = obj.Get("hello"); + Value val2 = obj.Get(42); + Value val3 = obj.Get("Douglas Adams"); + + // Test if objects have properties. + bool obj1 = obj.Has("hello"); // true + bool obj2 = obj.Has("world"); // false + +} +``` ## Methods @@ -47,16 +81,14 @@ Creates a new Object value. ```cpp void Napi::Object::Set (____ key, ____ value); ``` -- `[in] key`: The property that is being assigned a value. -- `[in] value`: The property that is being assigned to a key. - -Assigns the value to the key . +- `[in] key`: The name for the property being assigned. +- `[in] value`: The value being assigned to the property. -The key-value pair types can be one of the following: -- `napi_value` key, `napi_value` value -- [Value](value.md) key, [Value](value.md) value +Add a property with the specified key with the specified value to the object. -Alternatively, the key can be any of the following types: +The key can be any of the following types: +- `napi_value` +- [Value][value.md] - `const char*` - `const std::string&` - `uint32_t` @@ -74,9 +106,10 @@ While the value must be any of the following types: ```cpp Value Napi::Object::Get(____ key); ``` -- `[in] key`: The property whose assigned value is being returned. +- `[in] key`: The name of the property to return the value for. + +Returns the [Value](value.md) associated with the key property. Returns NULL if no such key exists. -Returns the [Value](value.md) associated with the key property. The `key` can be any of the following types: - `napi_value` - [Value](value.md) @@ -89,9 +122,9 @@ The `key` can be any of the following types: ```cpp bool Napi::Object::Has (____ key) const; ``` -- `[in] key`: The property that is being checked for having an assigned value. +- `[in] key`: The name of the property to check. -Returns a `bool` that is *true* if the `key` has a value property associated with it and *false* otherwise. +Returns a `bool` that is *true* if the object has a property named `key` and *false* otherwise. ### InstanceOf() @@ -167,31 +200,3 @@ Value Napi::Object::operator[] (uint32_t index) const; - `[in] index`: Element index. Returns an indexed property or array element as a [Value](value.md). - -### Example -```cpp -#include - -using namescape Napi; - -Void Init(Env env) { - - // Create a new instance - Object obj = Object::New(env); - - // Assign values to properties - obj.Set("hello", "world"); - obj.Set(42, "The Answer to Life, the Universe, and Everything"); - obj.Set("Douglas Adams", true); - - // Get properties - Value val1 = obj.Get("hello"); - Value val2 = obj.Get(42); - Value val3 = obj.Get("Douglas Adams"); - - // Test if objects have properties. - bool obj1 = obj.Has("hello"); // true - bool obj2 = obj.Has("world"); // false - -} -``` From b76cc13ceb90d67b4f8fb40fc3c74971d54e4f25 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 29 May 2018 20:19:24 -0400 Subject: [PATCH 3/5] squash fix minor typo --- doc/object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/object.md b/doc/object.md index 9a880142b..af3541242 100644 --- a/doc/object.md +++ b/doc/object.md @@ -8,7 +8,7 @@ The Object class corresponds to a JavaScript object. It is extended by the follo - [Function](function.md) - [TypedArray](typed_array.md). -This class provides a number of convenience methods, most of which are used to set or set properties on a JavaScript object. For example, Set() and Get(). +This class provides a number of convenience methods, most of which are used to set or get properties on a JavaScript object. For example, Set() and Get(). ## Example ```cpp From c325beec156ea355f78b88f5b2912ba087476934 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 29 May 2018 20:20:38 -0400 Subject: [PATCH 4/5] squash: fix minor typo --- doc/object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/object.md b/doc/object.md index af3541242..b51a81b8e 100644 --- a/doc/object.md +++ b/doc/object.md @@ -14,7 +14,7 @@ This class provides a number of convenience methods, most of which are used to s ```cpp #include -using namescape Napi; +using namespace Napi; Void Init(Env env) { From e6788005b1e14a831c2ee3b5f1d601af191dd953 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 29 May 2018 20:22:43 -0400 Subject: [PATCH 5/5] squash: fix link --- doc/object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/object.md b/doc/object.md index b51a81b8e..65b592b33 100644 --- a/doc/object.md +++ b/doc/object.md @@ -88,7 +88,7 @@ Add a property with the specified key with the specified value to the object. The key can be any of the following types: - `napi_value` -- [Value][value.md] +- [Value](value.md) - `const char*` - `const std::string&` - `uint32_t`