val.h

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++.

classemscripten::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:

varxhr=newXMLHttpRequest;
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.

valxhr=val::global("XMLHttpRequest").new_();
xhr.call<void>("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:

constchar*state;
switch(xhr["readyState"].as<int>()){
case0:
state="UNSENT";break;
case1:
state="OPENED";break;
default:
state="etc";
}

See Using val to transliterate JavaScript to C++ 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:

thread_localconstvalUint8Array=val::global("Uint8Array");

staticval array()

Creates and returns a new Array.

staticval object()

Creates and returns a new Object.

staticval u8string(constchar*s)

Creates a val from a string literal in UTF-8 encoding.

staticval u16string(constchar16_t*s)

Creates a val from a string literal in UTF-16 encoding.

staticval undefined()

Creates a val that represents undefined.

staticval null()

Creates a val that represents null.

EM_VALas_handle()const

Returns a raw handle representing this val. This can be used for passing raw value handles to JavaScript and retrieving the values on the other side via Emval.toValue function. Example:

EM_JS(void,log_value,(EM_VALval_handle),{
varvalue=Emval.toValue(val_handle);
console.log(value);// 42
});
valfoo(42);
log_value(foo.as_handle());

staticval take_ownership(EM_VALe)

Creates a val from a raw handle. This can be used for retrieving values from JavaScript, where the JavaScript side should wrap a value with Emval.toHandle, pass it to C++, and then C++ can use take_ownership to convert it to a val instance. Example:

EM_ASYNC_JS(EM_VAL,fetch_json_from_url,(constchar*url),{
varurl=UTF8ToString(url);
varresponse=awaitfetch(url);
varjson=awaitresponse.json();
returnEmval.toHandle(json);
});
valobj=val::take_ownership(fetch_json_from_url("https://httpbin.org/json"));
std::stringauthor=obj["slideshow"]["author"].as<std::string>();

staticval global(constchar*name)

Looks up a global value by the specified name.

staticval module_property(constchar*name)

Looks up a value by the provided name on the Emscripten Module object.

explicitval(T&&value)

Constructor.

Creates a val by conversion from any Embind-compatible C++ type. For example, val(true) or val(std::string("foo")).

explicitval(constchar*v)

Constructs a val instance from a string literal.

val(val &&v)

Moves ownership of a value to a new val instance.

val(constval &v)

Creates another reference to the same value behind the provided val instance.

~val()

Removes the currently bound value by decreasing its refcount.

val &operator=(val &&v)

Removes a reference to the currently bound value and takes over the provided one.

val &operator=(constval &v)

Removes a reference to the currently bound value and creates another reference to the value behind the provided val instance.

boolhasOwnProperty(constchar*key)const

Checks if the JavaScript object has own (non-inherited) property with the specified name.

val new_(Args&&...args)const

Assumes that current value is a constructor, and creates an instance of it. Equivalent to a JavaScript expression new currentValue(...).

val operator[](constT&key)const

Get the specified (key) property of a JavaScript object.

voidset(constK&key, constval &v)

Set the specified (key) property of a JavaScript object (accessed through a val) with the value v.

val operator()(Args&&...args)const

Assumes that current value is a function, and invokes it with provided arguments.

ReturnValuecall(constchar*name, Args&&...args)const

Invokes the specified method (name) on the current object with provided arguments.

Tas()const

Converts current value to the specified C++ type.

val typeof()const

Returns the result of a JavaScript typeof operator invoked on the current value.

std::vector<T>vecFromJSArray(constval &v)

Copies a JavaScript array into a std::vector<T>, converting each element via .as<T>(). 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(constval &v)

Converts a JavaScript array 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 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).

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.

Note

This method requires ASYNCIFY to be enabled.

val operatorco_await()const

The co_await operator allows awaiting JavaScript promises represented by val.

It’s compatible with any C++20 coroutines, but should be normally used inside a val-returning coroutine which will also become a Promise.

For example, it allows you to implement the equivalent of this JavaScript async/await function:

asyncfunctionfoo(){
constresponse=awaitfetch("http://url");
constjson=awaitresponse.json();
returnjson;
}
export{foo};

as a C++ coroutine:

valfoo(){
valresponse=co_awaitval::global("fetch")(std::string("http://url"));
valjson=co_awaitresponse.call<val>("json");
returnjson;
}
EMSCRIPTEN_BINDINGS(module){
function("foo",&foo);
}

Unlike the await() method, it doesn’t need Asyncify as it uses native C++ coroutine transform.

Returns:

A val representing the fulfilled value of this promise.