val.h (under-construction)

The Embind C++ class emscripten::val (defined in val.h) is used to transliterate JavaScript code to C++.

Guide material for this class can be found in Using val to transliterate JavaScript to C++.

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:

var xhr = new XMLHttpRequest;
xhr.open("GET", "http://url");

This same code can be written in C++, using global() to get the symbol for the global XMLHttpRequest object and then using it to open a URL.

val xhr = val::global("XMLHttpRequest").new_();
xhr.call("open", std::string("GET"), std::string("http://url"));

See Using val to transliterate JavaScript to C++ for other examples.

static val array()

Creates and returns a new Array.

Returns:The new Array.
static val object()

Creates and returns a new Object.

Returns:The new Object.
static val undefined()

Creates a val that represents undefined.

Returns:The val that represents undefined.
static val null()

Creates a val that represents null. val::undefined() is the same, but for undefined.

Returns:A val that represents null.
static val take_ownership(internal::EM_VAL e)

HamishW-Replace with description.

Returns:HamishW-Replace with description.
static val global(const char *name)

Looks up a global symbol.

Parameters:const char* nameHamishW-Replace with description.
Returns:HamishW-Replace with description.
static val module_property(const char *name)

Looks up a symbol on the emscripten Module object.

Parameters:const char* nameHamishW-Replace with description.
Returns:HamishW-Replace with description.
static val module_property(const char *name)

HamishW-Replace with description.

Parameters:const char* nameHamishW-Replace with description.
Returns:HamishW-Replace with description.
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")).

Parameters:T&& value – Any C++ type.

HamishW Don’t know how following “floating statement works”. Leaving here for discussion val() = delete;

explicit val(const char *v)

HamishW-Replace with description.

Parameters:const char* vHamishW-Replace with description.
val(val &&v)

HamishW-Replace with description.

Parameters:val&& vHamishW-Replace with description.
val(const val &v)

HamishW-Replace with description.

Parameters:const val& vHamishW-Replace with description.
~val()

Destructor. HamishW-Replace with further description or delete comment.

val(const val &v)

HamishW-Replace with description.

Parameters:const val& vHamishW-Replace with description.
val &operator=(val &&v)

HamishW-Replace with description.

Parameters:val&& vHamishW-Replace with description.
Returns:HamishW-Replace with description.
val &operator=(const val &v)

HamishW-Replace with description.

Parameters:val&& vHamishW-Replace with description.
Returns:HamishW-Replace with description.
bool hasOwnProperty(const char *key) const

Test whether ... HamishW-Replace with description.

Parameters:const char* keyHamishW-Replace with description.
Returns:HamishW-Replace with description.
val new_()

prototype:

template<typename... Args>
val new_(Args&&... args) const

HamishW-Replace with description.

Parameters:Args&&... argsHamishW-Replace with description. Note that this is a templated value.
Returns:HamishW-Replace with description.
val operator[](const T &key) const

HamishW-Replace with description.

Parameters:const T& keyHamishW-Replace with description. Note that this is a templated value.
Returns:HamishW-Replace with description.
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.

Parameters:
  • const K& keyHamishW-Replace with description. Note that this is a templated value.
  • const val& vHamishW-Replace with description. Note that this is a templated value.
val operator()(Args&&... args)

HamishW-Replace with description.

Parameters:Args&&... argsHamishW-Replace with description. Note that this is a templated value.
ReturnValue call(const char *name, Args&&... args) const

HamishW-Replace with description.

Parameters:
  • const char* nameHamishW-Replace with description.
  • Args&&... argsHamishW-Replace with description. Note that this is a templated value.
T as() const

HamishW-Replace with description.

Returns:HamishW-Replace with description. Note that this is a templated value.
val typeof() const

HamishW-Replace with description.

Returns:HamishW-Replace with description.
std::vector<T> vecFromJSArray(val v)

HamishW-Replace with description.

HamishW. I believe NOT internal. Please confirm.

Parameters:val vHamishW-Replace with description.
Returns:HamishW-Replace with description.