summaryrefslogtreecommitdiff
path: root/node_modules/node-addon-api/doc/object.md
diff options
context:
space:
mode:
Diffstat (limited to 'node_modules/node-addon-api/doc/object.md')
-rw-r--r--node_modules/node-addon-api/doc/object.md236
1 files changed, 236 insertions, 0 deletions
diff --git a/node_modules/node-addon-api/doc/object.md b/node_modules/node-addon-api/doc/object.md
new file mode 100644
index 0000000..3241054
--- /dev/null
+++ b/node_modules/node-addon-api/doc/object.md
@@ -0,0 +1,236 @@
+# Object
+
+The `Napi::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:
+
+- [`Napi::Value`](value.md) and extends [`Napi::Array`](array.md)
+- [`Napi::ArrayBuffer`](array_buffer.md)
+- [`Napi::Buffer<T>`](buffer.md)
+- [`Napi::Function`](function.md)
+- [`Napi::TypedArray`](typed_array.md).
+
+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
+#include <napi.h>
+
+using namespace Napi;
+
+Void Init(Env env) {
+
+ // Create a new instance
+ Object obj = Object::New(env);
+
+ // Assign values to properties
+ obj.Set("hello", "world");
+ obj.Set(uint32_t(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(uint32_t(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
+
+### 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 `Napi::Object` instance.
+
+### New()
+
+```cpp
+Napi::Object Napi::Object::New(napi_env env);
+```
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object.
+
+Creates a new `Napi::Object` value.
+
+### Set()
+
+```cpp
+void Napi::Object::Set (____ key, ____ value);
+```
+- `[in] key`: The name for the property being assigned.
+- `[in] value`: The value being assigned to the property.
+
+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`
+- [`Napi::Value`](value.md)
+- `const char*`
+- `const std::string&`
+- `uint32_t`
+
+While the value must be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char*`
+- `std::string&`
+- `bool`
+- `double`
+
+### Get()
+
+```cpp
+Napi::Value Napi::Object::Get(____ key);
+```
+- `[in] key`: The name of the property to return the value for.
+
+Returns the [`Napi::Value`](value.md) associated with the key property. Returns the value *undefined* if the key does not exist.
+
+The `key` can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char *`
+- `const std::string &`
+- `uint32_t`
+
+### Has()
+
+```cpp
+bool Napi::Object::Has (____ key) const;
+```
+- `[in] key`: The name of the property to check.
+
+Returns a `bool` that is *true* if the object has a property named `key` and *false* otherwise.
+
+### InstanceOf()
+
+```cpp
+bool Napi::Object::InstanceOf (const Function& constructor) const
+```
+- `[in] constructor`: The constructor [`Napi::Function`](function.md) of the value that is being compared with the object.
+
+Returns a `bool` that is true if the `Napi::Object` is an instance created by the `constructor` and false otherwise.
+
+Note: This is equivalent to the JavaScript instanceof operator.
+
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T>
+inline void AddFinalizer(Finalizer finalizeCallback, T* data);
+```
+
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+- `[in] data`: The data to associate with the object.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. `finalizeCallback`
+has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data);
+```
+where `data` is the pointer that was passed into the call to `AddFinalizer()`.
+
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T, typename Hint>
+inline void AddFinalizer(Finalizer finalizeCallback,
+ T* data,
+ Hint* finalizeHint);
+```
+
+- `[in] data`: The data to associate with the object.
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. An additional hint
+may be given. It will also be passed to `finalizeCallback`, which has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data, Hint* hint);
+```
+where `data` and `hint` are the pointers that were passed into the call to `AddFinalizer()`.
+
+### DefineProperty()
+
+```cpp
+void Napi::Object::DefineProperty (const Napi::PropertyDescriptor& property);
+```
+- `[in] property`: A [`Napi::PropertyDescriptor`](property_descriptor.md).
+
+Define a property on the object.
+
+### DefineProperties()
+
+```cpp
+void Napi::Object::DefineProperties (____ properties)
+```
+- `[in] properties`: A list of [`Napi::PropertyDescriptor`](property_descriptor.md). Can be one of the following types:
+ - const std::initializer_list<Napi::PropertyDescriptor>&
+ - const std::vector<Napi::PropertyDescriptor>&
+
+Defines properties on the object.
+
+### Operator[]()
+
+```cpp
+Napi::PropertyLValue<std::string> Napi::Object::operator[] (const char* utf8name);
+```
+- `[in] utf8name`: UTF-8 encoded null-terminated property name.
+
+Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property.
+
+```cpp
+Napi::PropertyLValue<std::string> Napi::Object::operator[] (const std::string& utf8name);
+```
+- `[in] utf8name`: UTF-8 encoded property name.
+
+Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property.
+
+```cpp
+Napi::PropertyLValue<uint32_t> Napi::Object::operator[] (uint32_t index);
+```
+- `[in] index`: Element index.
+
+Returns a [`Napi::PropertyLValue`](propertylvalue.md) or sets an indexed property or array element.
+
+```cpp
+Napi::Value Napi::Object::operator[] (const char* utf8name) const;
+```
+- `[in] utf8name`: UTF-8 encoded null-terminated property name.
+
+Returns the named property as a [`Napi::Value`](value.md).
+
+```cpp
+Napi::Value Napi::Object::operator[] (const std::string& utf8name) const;
+```
+- `[in] utf8name`: UTF-8 encoded property name.
+
+Returns the named property as a [`Napi::Value`](value.md).
+
+```cpp
+Napi::Value Napi::Object::operator[] (uint32_t index) const;
+```
+- `[in] index`: Element index.
+
+Returns an indexed property or array element as a [`Napi::Value`](value.md).