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"));

You can test whether the open method call was successful using operator[]() to read an object property, then as() to coerce the type:

const char* state;
switch (xhr["readyState"].as<int>()) {
case 0:
  state = "UNSENT"; break;
case 1:
  state = "OPENED"; break;
default:
  state = "etc";
}

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 name – HamishW**-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 name – HamishW**-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 v – HamishW**-Replace with description.

val(val &&v)¶

HamishW-Replace with description.

Parameters:	val&& v – HamishW-Replace with description.

val(const val &v)¶

HamishW-Replace with description.

Parameters:	const val& v – HamishW-Replace with description.

~val()¶: Destructor. HamishW-Replace with further description or delete comment.

val &operator=(val &&v)¶

HamishW-Replace with description.

Parameters:	val&& v – HamishW-Replace with description.
Returns:	HamishW-Replace with description.

val &operator=(const val &v)¶

HamishW-Replace with description.

Parameters:	val&& v – HamishW-Replace with description.
Returns:	HamishW-Replace with description.

bool hasOwnProperty(const char *key) const¶

Test whether … HamishW-Replace with description.

Parameters:	*const char key – HamishW**-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&&... args – HamishW-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& key – HamishW-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& key – HamishW-Replace with description. Note that this is a templated value. const val& v – HamishW-Replace with description. Note that this is a templated value.

val operator()(Args&&... args)¶

HamishW-Replace with description.

Parameters:	Args&&... args – HamishW-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 name – HamishW-Replace with description. Args&&... args – HamishW**-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(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.

Parameters:	val v – The javascript array to be copied
Returns:	A std::vector<T> made from the javascript array

std::vector<T> convertJSArrayToNumberVector(const val &v)¶

Converts a javascript object into a std::vector<T> 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).

Parameters:	val v – The javascript (typed) array to be copied
Returns:	A std::vector<T> made from the javascript array

val await() const¶

Pauses the C++ to await the Promise / thenable.

Returns:	The fulfilled value.

This method requires Asyncify to be enabled.