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

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

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.

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_local const val Uint8Array = val::global("Uint8Array");

static val array(): Creates and returns a new Array.

static val object(): Creates and returns a new Object.

static val u8string(const char *s): Creates a val from a string literal in UTF-8 encoding.

static val u16string(const char16_t *s): Creates a val from a string literal in UTF-16 encoding.

static val undefined(): Creates a val that represents undefined.

static val null(): Creates a val that represents null.

EM_VAL as_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_VAL val_handle), {
  var value = Emval.toValue(val_handle);
  console.log(value); // 42
});

val foo(42);
log_value(foo.as_handle());

static val take_ownership(EM_VAL e)

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, (const char *url), {
  var url = UTF8ToString(url);
  var response = await fetch(url);
  var json = await response.json();
  return Emval.toHandle(json);
});

val obj = val::take_ownership(fetch_json_from_url("https://httpbin.org/json"));
std::string author = obj["slideshow"]["author"].as<std::string>();

static val global(const char *name): Looks up a global value by the specified name.

static val module_property(const char *name): Looks up a value by the provided name on the Emscripten Module object.

explicit val(T &&value)

Constructor.

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

explicit val(const char *v): Constructs a val instance from a string literal.

val(val &&v): Moves ownership of a value to a new val instance.

val(const val &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=(const val &v): Removes a reference to the currently bound value and creates another reference to the value behind the provided val instance.

bool hasOwnProperty(const char *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[](const T &key) const: Get the specified (key) property of a JavaScript object.

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.

val operator()(Args&&... args) const: Assumes that current value is a function, and invokes it with provided arguments.

ReturnValue call(const char *name, Args&&... args) const: Invokes the specified method (name) on the current object with provided arguments.

T as() 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(const val &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(const val &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 operator co_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:

async function foo() {
  const response = await fetch("http://url");
  const json = await response.json();
  return json;
}

export { foo };

as a C++ coroutine:

val foo() {
  val response = co_await val::global("fetch")(std::string("http://url"));
  val json = co_await response.call<val>("json");
  return json;
}

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.