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.