diff --git a/site/source/docs/api_reference/val.h.rst b/site/source/docs/api_reference/val.h.rst index 3cf898cbb7a3a..d056d94167e8e 100644 --- a/site/source/docs/api_reference/val.h.rst +++ b/site/source/docs/api_reference/val.h.rst @@ -1,10 +1,8 @@ .. _val-h: -================================ -val.h (under-construction) -================================ - -.. COMMENT (Not rendered) : This created from val.h header file on 10 Aug 2014-03 +===== +val.h +===== The *Embind* C++ class :cpp:class:`emscripten::val` (defined in `val.h `_) is used to *transliterate* JavaScript code to C++. @@ -31,7 +29,7 @@ Guide material for this class can be found in :ref:`embind-val-guide`. .. code:: cpp val xhr = val::global("XMLHttpRequest").new_(); - xhr.call("open", std::string("GET"), std::string("http://url")); + xhr.call("open", std::string("GET"), std::string("http://url")); You can test whether the ``open`` method call was successful using :cpp:func:`~emscripten::val::operator[]` to read an object property, then :cpp:func:`~emscripten::val::as` to coerce the type: @@ -48,7 +46,16 @@ Guide material for this class can be found in :ref:`embind-val-guide`. } See :ref:`embind-val-guide` for other examples. + + + .. warning:: JavaScript values can't be shared across threads, so neither can ``val`` instances that bind them. + + For example, if you want to cache some JavaScript global as a ``val``, you need to retrieve and bind separate instances of that global by its name in each thread. + The easiest way to do this is with a ``thread_local`` declaration: + + .. code:: cpp + thread_local const val Uint8Array = val::global("Uint8Array"); .. todo:: @@ -74,193 +81,129 @@ Guide material for this class can be found in :ref:`embind-val-guide`. Creates and returns a new ``Array``. - :returns: The new ``Array``. - .. cpp:function:: static val object() Creates and returns a new ``Object``. - :returns: The new ``Object``. - .. cpp:function:: static val undefined() Creates a ``val`` that represents ``undefined``. - :returns: The ``val`` that represents ``undefined``. - .. cpp:function:: static val null() - Creates a ``val`` that represents ``null``. ``val::undefined()`` is the same, but for undefined. - - :returns: A ``val`` that represents ``null``. - - - .. cpp:function:: static val take_ownership(internal::EM_VAL e) - - **HamishW**-Replace with description. - - :returns: **HamishW**-Replace with description. + Creates a ``val`` that represents ``null``. .. cpp:function:: static val global(const char* name) - Looks up a global symbol. - - :param const char* name: **HamishW**-Replace with description. - :returns: **HamishW**-Replace with description. + Looks up a global value by the specified ``name``. .. cpp:function:: static val module_property(const char* name) - Looks up a symbol on the emscripten Module object. - - :param const char* name: **HamishW**-Replace with description. - :returns: **HamishW**-Replace with description. + Looks up a value by the provided ``name`` on the Emscripten Module object. .. cpp:function:: explicit val(T&& value) Constructor. - A ``val`` can be constructed by explicit construction from any C++ type. For example, ``val(true)`` or ``val(std::string("foo"))``. - - :param T&& value: Any C++ type. - - - **HamishW** Don't know how following "floating statement works". Leaving here for discussion - ``val() = delete;`` + Creates a ``val`` by conversion from any Embind-compatible C++ type. + For example, ``val(true)`` or ``val(std::string("foo"))``. .. cpp:function:: explicit val(const char* v) - **HamishW**-Replace with description. - - :param const char* v: **HamishW**-Replace with description. + Constructs a ``val`` instance from a string literal. .. cpp:function:: val(val&& v) - - **HamishW**-Replace with description. - - :param val&& v: **HamishW**-Replace with description. + + Moves ownership of a value to a new ``val`` instance. .. cpp:function:: val(const val& v) - - **HamishW**-Replace with description. - - :param const val& v: **HamishW**-Replace with description. + + Creates another reference to the same value behind the provided ``val`` instance. .. cpp:function:: ~val() - Destructor. **HamishW**-Replace with further description or delete comment. + Removes the currently bound value by decreasing its refcount. .. cpp:function:: val& operator=(val&& v) - - **HamishW**-Replace with description. - - :param val&& v: **HamishW**-Replace with description. - :returns: **HamishW**-Replace with description. + + Removes a reference to the currently bound value and takes over the provided one. .. cpp:function:: val& operator=(const val& v) - **HamishW**-Replace with description. - - :param val&& v: **HamishW**-Replace with description. - :returns: **HamishW**-Replace with description. + Removes a reference to the currently bound value and creates another reference to + the value behind the provided ``val`` instance. .. cpp:function:: bool hasOwnProperty(const char* key) const - Test whether ... **HamishW**-Replace with description. - - :param const char* key: **HamishW**-Replace with description. - :returns: **HamishW**-Replace with description. - - - .. cpp:function:: val new_() - - prototype: + Checks if the JavaScript object has own (non-inherited) property with the specified name. - :: - template - val new_(Args&&... args) const + .. cpp:function:: val new_(Args&&... args) const - **HamishW**-Replace with description. - - :param Args&&... args: **HamishW**-Replace with description. Note that this is a templated value. - :returns: **HamishW**-Replace with description. + Assumes that current value is a constructor, and creates an instance of it. + Equivalent to a JavaScript expression `new currentValue(...)`. .. cpp:function:: val operator[](const T& key) const - **HamishW**-Replace with description. - - :param const T& key: **HamishW**-Replace with description. Note that this is a templated value. - :returns: **HamishW**-Replace with description. + Get the specified (``key``) property of a JavaScript object. .. cpp:function:: void set(const K& key, const val& v) - Set the specified (``key``) property of a JavaScript object (accessed through a ``val``) with the value ``v``. **HamishW**-Replace with description. - - :param const K& key: **HamishW**-Replace with description. Note that this is a templated value. - :param const val& v: **HamishW**-Replace with description. Note that this is a templated value. - - - .. cpp:function:: val operator()(Args&&... args) + Set the specified (``key``) property of a JavaScript object (accessed through a ``val``) with the value ``v``. - **HamishW**-Replace with description. - :param Args&&... args: **HamishW**-Replace with description. Note that this is a templated value. + .. cpp:function:: val operator()(Args&&... args) const + + Assumes that current value is a function, and invokes it with provided arguments. .. cpp:function:: ReturnValue call(const char* name, Args&&... args) const - **HamishW**-Replace with description. - - :param const char* name: **HamishW**-Replace with description. - :param Args&&... args: **HamishW**-Replace with description. Note that this is a templated value. + Invokes the specified method (``name``) on the current object with provided arguments. .. cpp:function:: T as() const - **HamishW**-Replace with description. - - :returns: **HamishW**-Replace with description. Note that this is a templated value. + Converts current value to the specified C++ type. .. cpp:function:: val typeof() const - **HamishW**-Replace with description. - - :returns: **HamishW**-Replace with description. + Returns the result of a JavaScript ``typeof`` operator invoked on the current value. .. cpp:function:: std::vector vecFromJSArray(const val& v) - Copies a javascript array into a std::vector, checking the type of each element. - For a more efficient but unsafe version working with numbers, see convertJSArrayToNumberVector. + Copies a JavaScript array into a ``std::vector``, converting each element via ``.as()``. + For a more efficient but unsafe version working with numbers, see ``convertJSArrayToNumberVector``. - :param val v: The javascript array to be copied - :returns: A std::vector made from the javascript array + :param val v: The JavaScript array to be copied + :returns: A ``std::vector`` made from the javascript array .. cpp:function:: std::vector convertJSArrayToNumberVector(const val& v) - Converts a javascript object into a std::vector efficiently, as if using the javascript `Number()` function on each element. - This is way more efficient than vecFromJSArray on any array with more than 2 values, but is less safe. - No type checking is done, so any invalid array entry will silently be replaced by a NaN value (or 0 for interger types). + Converts a JavaScript array into a ``std::vector`` efficiently, as if using the javascript `Number()` function on each element. + This is way more efficient than ``vecFromJSArray`` on any array with more than 2 values, but is not suitable for arrays of non-numeric values. + No type checking is done, so any invalid array entry will silently be replaced by a NaN value (or 0 for integer types). - :param val v: The javascript (typed) array to be copied + :param val v: The JavaScript (typed) array to be copied :returns: A std::vector made from the javascript array @@ -270,7 +213,7 @@ Guide material for this class can be found in :ref:`embind-val-guide`. :returns: The fulfilled value. - This method requires :ref:`Asyncify` to be enabled. + .. note:: This method requires :ref:`Asyncify` to be enabled. .. cpp:type: EMSCRIPTEN_SYMBOL(name)