.. _val-h: ================================ val.h (under-construction) ================================ .. COMMENT (Not rendered) : This created from val.h header file on 10 Aug 2014-03 The *Embind* C++ class :cpp:class:`emscripten::val` (defined in `val.h `_) is used to *transliterate* JavaScript code to C++. Guide material for this class can be found in :ref:`embind-val-guide`. .. cpp:namespace:: emscripten .. cpp:class:: emscripten::val This class is a C++ data type that can be used to represent (and provide convenient access to) any JavaScript object. You can use it to call a JavaScript object, read and write its properties, or coerce it to a C++ value like a ``bool``, ``int``, or ``std::string``. For example, the code below shows some simple JavaScript for making an XHR request on a URL: .. code:: javascript var xhr = new XMLHttpRequest; xhr.open("GET", "http://url"); This same code can be written in C++, using :cpp:func:`~emscripten::val::global` to get the symbol for the global ``XMLHttpRequest`` object and then using it to open a URL. .. code:: cpp val xhr = val::global("XMLHttpRequest").new_(); 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: .. code:: cpp const char* state; switch (xhr["readyState"].as()) { case 0: state = "UNSENT"; break; case 1: state = "OPENED"; break; default: state = "etc"; } See :ref:`embind-val-guide` for other examples. .. todo:: **HamishW** Notes from source FYI: Can/should these be included? :: // missing operators: // * delete // * in // * instanceof // * ! ~ - + ++ -- // * * / % // * + - // * << >> >>> // * < <= > >= // * == != === !== // * & ^ | && || ?: // // exposing void, comma, and conditional is unnecessary // same with: = += -= *= /= %= <<= >>= >>>= &= ^= |= .. cpp:function:: static val array() 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. .. 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. .. 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. .. 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;`` .. cpp:function:: explicit val(const char* v) **HamishW**-Replace with description. :param const char* v: **HamishW**-Replace with description. .. cpp:function:: val(val&& v) **HamishW**-Replace with description. :param val&& v: **HamishW**-Replace with description. .. cpp:function:: val(const val& v) **HamishW**-Replace with description. :param const val& v: **HamishW**-Replace with description. .. cpp:function:: ~val() Destructor. **HamishW**-Replace with further description or delete comment. .. cpp:function:: val& operator=(val&& v) **HamishW**-Replace with description. :param val&& v: **HamishW**-Replace with description. :returns: **HamishW**-Replace with description. .. cpp:function:: val& operator=(const val& v) **HamishW**-Replace with description. :param val&& v: **HamishW**-Replace with description. :returns: **HamishW**-Replace with description. .. 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: :: template 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. .. 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. .. 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) **HamishW**-Replace with description. :param Args&&... args: **HamishW**-Replace with description. Note that this is a templated value. .. 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. .. cpp:function:: T as() const **HamishW**-Replace with description. :returns: **HamishW**-Replace with description. Note that this is a templated value. .. cpp:function:: val typeof() const **HamishW**-Replace with description. :returns: **HamishW**-Replace with description. .. cpp:function:: std::vector vecFromJSArray(val v) **HamishW**-Replace with description. **HamishW**. I believe NOT internal. Please confirm. :param val v: **HamishW**-Replace with description. :returns: **HamishW**-Replace with description. .. cpp:function:: val await() const Pauses the C++ to ``await`` the ``Promise`` / thenable. :returns: The fulfilled value. This method requires :ref:`Asyncify` to be enabled. .. cpp:type: EMSCRIPTEN_SYMBOL(name) **HamishW**-Replace with description.