docs
Loading...
Searching...
No Matches
Value

#include <Ultralight/js/Value.h>

Overview

A handle to a live JavaScript value.

A Value represents a live JavaScript value on a page. You use it to hold page objects and functions across calls, interacting with them directly without converting them to C++ types.

This example interacts with an object on the page:

js::Value player = ctx["game"]["player"];
double health = player["health"].Or(0.0); // read (0.0 if anything fails)
player["score"] = 1200; // write
player["respawn"](10, 20); // call a method (`this` is player)
A handle to a live JavaScript value.
Definition Value.h:276
T Or(T fallback) const
Convert to a C++ type like To() but with a fallback.

Handle States

A handle is always in one of these states:

State When operator bool Calls
Valid On a live page true Work normally
Empty Default-constructed, moved from, or failed read false Do nothing
Gone Page navigated, frame removed, or View destroyed false Do nothing

An empty Value differs from JavaScript null and undefined. A missing property reads as a valid Value holding undefined, while an empty handle represents an uninitialized handle or a failed operation.

Every operation is safe in all three states, allowing property reads and method calls to chain without checking each step.

This call chains safely even if the HUD object doesn't exist:

ctx["hud"]["showToast"]("Saved"); // does nothing if there's no hud

When an operation returns a failed js::Result, inspect js::Error::is_empty() to check for an empty handle or js::Error::is_page_gone() to check whether the page navigated away.

A handle whose page is gone never recovers, even when that page is restored from the back-forward cache.

To interact with the new page, get a new Value from that page's js::Context. Every page-lifetime handle across the JavaScript API follows these rules.

Copies and Lifetimes

Copying a Value creates another reference to the same JavaScript value.

Holding a Value keeps the underlying JavaScript value from being garbage-collected, but it doesn't keep the page or its View alive.

For ownership cycles between bound instances and JavaScript objects, see js::ClassBuilder.

A const Value still lets you change the underlying JavaScript value, matching the behavior of a const RefPtr.

Type Conversions

The conversion methods To(), Maybe(), and Or() are strict about the JavaScript type (the string "7" doesn't convert to a number), differing only in how they report a failure.

To convert values using JavaScript's own coercion rules, call ToNumber(), ToString(), ToBoolean(), or ToJSON() directly on the Value. For the full list of supported types, see js::TypeTraits.

This example compares strict conversion against JavaScript coercion:

js::Value level = player["level"]; // the string "7"
double strict = level.Or(0.0); // 0.0 (not a number)
double loose = level.ToNumber().value_or(0.0); // 7.0 (JavaScript's rules)
Result< double > ToNumber() const
Convert to a number using JavaScript's rules.
Definition Value.h:481

Values Across Pages

A Value belongs to the page that created it. You can pass a Value directly only between frames of the same top-level page that share an exact origin, never across separate Views.

Using a Value on a page that can't take it fails with a TypeError whose error code is ULJS_CROSS_CONTEXT. To transfer data between separate pages or Views, copy the data using JSON or native C++ types.

This example transfers player data to a page in another View using JSON:

js::Context bestiary(bestiary_view.get()); // a page in another View
std::string json = player.ToJSON().value_or("null");
bestiary["player"] = js::OrEmpty(bestiary.MakeFromJSON(json));
JavaScript execution environment for a page.
Definition Context.h:263
Result< std::string > ToJSON(unsigned indent=0) const
Convert to JSON text like JSON.stringify() does.
Definition Value.h:540
T OrEmpty(Result< T > result)
Get a Result's value, or a default-constructed T if it holds an error.
Definition Error.h:539
Note
js::Value and dom::data::Value are unrelated types (dom::data::Value is the value type of the data-binding API).
See also
js::Context, js::Error, js::TypeTraits, js::WeakValue
Inheritance diagram for Value:
ArrayBuffer TypedArray< T >

Classes

class  Ref
 A reference to a property of a Value (returned by Value::operator[]). More...

Static Public Member Functions

static Value Adopt (ULJSValue handle)
 Take ownership of a handle from the C API without adding a reference.
static Value FromBorrowed (ULJSValue handle)
 Add a reference to a handle the library owns (eg, a callback argument) so it can outlive the callback.

Public Member Functions

 Value ()
 Create an empty Value.
 Value (const Value &other)
 Copy constructor (adds a reference to the same JavaScript value).
 Value (Value &&other) noexcept
 Move constructor (other becomes empty).
Value & operator= (Value other) noexcept
 Assignment (copies or moves other into this Value).
 ~Value ()
 Destructor (releases this handle).
 operator bool () const
 Whether or not this Value is valid (it isn't empty and its page is still alive).
bool IsEmpty () const
 Whether or not this Value holds nothing (see "Handle States" above).
bool IsAlive () const
 Whether or not this Value's page is still alive (the same test as operator bool).
Type type () const
 Get the type of the value.
bool IsUndefined () const
 Whether or not the value is undefined.
bool IsNull () const
 Whether or not the value is null.
bool IsNullish () const
 Whether or not the value is null or undefined.
bool IsBoolean () const
 Whether or not the value is a boolean.
bool IsNumber () const
 Whether or not the value is a number.
bool IsBigInt () const
 Whether or not the value is a BigInt (eg, 10n).
bool IsString () const
 Whether or not the value is a string.
bool IsObject () const
 Whether or not the value is an object.
bool IsArray () const
 Whether or not the value is an Array.
bool IsCallable () const
 Whether or not the value can be called (see Call() and Invoke()).
bool IsFunction () const
 Whether or not the value is a function.
bool IsPromise () const
 Whether or not the value is a Promise.
bool IsConstructor () const
 Whether or not the value can be called with new (see Construct()).
ObjectKind object_kind () const
 Get the kind of object the value is (eg, a Map, a Date, or an ordinary object).
bool StrictEquals (const Value &other) const
 Whether or not this value and other are strictly equal (like JavaScript's ===).
Result< double > TimeValue () const
 Get the time value of a Date, in milliseconds since the epoch (like date.getTime()).
Result< bool > ToBoolean () const
 Convert to a boolean using JavaScript's rules (this never runs script).
Result< double > ToNumber () const
 Convert to a number using JavaScript's rules.
Result< std::string > ToString () const
 Convert to a UTF-8 string using JavaScript's rules.
Result< std::string > ToJSON (unsigned indent=0) const
 Convert to JSON text like JSON.stringify() does.
Result< Value > GetProperty (const char *name) const
 Get a property of this object (own or inherited).
bool Has (const char *name) const
 Whether or not this object has a property (own or inherited).
Result< bool > HasProperty (const char *name) const
 Whether or not this object has a property (like Has(), but reports failures).
Result< void > SetProperty (const char *name, const Value &value, PropertyAttributes attributes=PropertyAttributes::None) const
 Set a property of this object.
Result< bool > DeleteProperty (const char *name) const
 Delete a property of this object (like JavaScript's delete operator).
template<detail::PropertyIndex I>
Result< bool > DeleteProperty (I index) const
 Delete an element of this object by index (eg, arr.DeleteProperty(2)).
bool Delete (const char *name) const
 Delete a property of this object (like DeleteProperty(), but without the failure reason).
template<detail::PropertyIndex I>
bool Delete (I index) const
 Delete an element of this object by index (like Delete(), but taking an index).
bool HasOwn (const char *name) const
 Whether or not this object has an own property (one that isn't inherited, like Object.hasOwn()).
template<detail::PropertyIndex I>
bool HasOwn (I index) const
 Whether or not this object has an own element at an index (eg, arr.HasOwn(2) is false for a hole).
Result< bool > HasOwnProperty (const char *name) const
 Whether or not this object has an own property (like HasOwn(), but reports failures).
template<detail::PropertyIndex I>
Result< bool > HasOwnProperty (I index) const
 Whether or not this object has an own element at an index (like HasOwn(), but reports failures).
Result< std::vector< std::string > > OwnKeys (OwnKeysFlags flags=OwnKeysFlags::None) const
 Get the names of this object's own properties, without reading their values.
Result< bool > DefineProperty (const char *name, const Value &value, PropertyAttributes attributes=PropertyAttributes::None) const
 Define a data property of this object (like Reflect.defineProperty()).
Result< bool > DefineAccessor (const char *name, const Value &getter, const Value &setter, PropertyAttributes attributes=PropertyAttributes::None) const
 Define an accessor property of this object, with a getter and a setter function (like Reflect.defineProperty() with get and set).
Result< void > Freeze () const
 Freeze this object (like Object.freeze()), so no property can be added, removed, or changed afterward.
Result< Value > Call (const Value &this_value, const Value *args, size_t argc) const
 Call this value as a function.
Result< Value > Call (const Value &this_value, std::span< const Value > args) const
 Call this value as a function with the arguments in a range (eg, a std::vector<js::Value>).
template<typename T>
Result< T > To () const
 Convert to a C++ type.
template<typename T>
std::optional< T > Maybe () const
 Convert to a C++ type like To() but without the failure reason.
template<typename T>
T Or (T fallback) const
 Convert to a C++ type like To() but with a fallback.
std::string Or (const char *fallback) const
 Convert to a std::string like To() but with a string-literal fallback.
template<typename R = Value, typename... A>
Result< R > Invoke (A &&... args) const
 Call this value as a function with typed arguments and result.
template<typename R = Value, typename... A>
Result< R > InvokeOn (const Value &this_value, A &&... args) const
 Call this value as a function with an explicit this (otherwise the same as Invoke()).
template<typename R = Value, typename... A>
Result< R > Construct (A &&... args) const
 Call this value as a constructor with new, with typed arguments and result.
Result< Value > Construct (std::span< const Value > args) const
 Call this value as a constructor with new, with the arguments in a range.
template<typename... A>
Result< Value > operator() (A &&... args) const
 Call this value as a function: on_save(path) is the same as on_save.Invoke(path).
template<typename F>
bool Then (F &&on_settled) const
 Wait for this promise to settle without a coroutine.
template<typename T, typename F>
requires (!std::is_same_v<T, Value>)
bool Then (F &&on_settled) const
 Wait for this promise to settle and convert its value to a C++ type.
Ref operator[] (const char *name) const
 Access a property to read, assign, or call it.
template<detail::PropertyIndex I>
Ref operator[] (I index) const
ULJSValue raw () const
 Get the C API handle without transferring ownership.
ULJSValue LeakRef ()
 Give up ownership of the C API handle and return it (like RefPtr::LeakRef()).

Protected Member Functions

 Value (ULJSValue handle)

Constructor & Destructor Documentation

◆ Value() [1/4]

Value ( )
inline

Create an empty Value.

◆ Value() [2/4]

Value ( const Value & other)
inline

Copy constructor (adds a reference to the same JavaScript value).

◆ Value() [3/4]

Value ( Value && other)
inlinenoexcept

Move constructor (other becomes empty).

◆ ~Value()

~Value ( )
inline

Destructor (releases this handle).

◆ Value() [4/4]

Value ( ULJSValue handle)
inlineexplicitprotected

Member Function Documentation

◆ Adopt()

Value Adopt ( ULJSValue handle)
inlinestatic

Take ownership of a handle from the C API without adding a reference.

Use this for a handle you'd otherwise destroy with ulDestroyJSValue() (eg, the return value of a C function).

Parameters
handleThe handle to take ownership of.
Returns
Returns a Value that owns handle.
Note
For a handle the library owns (eg, a callback argument), use FromBorrowed().

◆ Call() [1/2]

Result< Value > Call ( const Value & this_value,
const Value * args,
size_t argc ) const
inlinenodiscard

Call this value as a function.

Parameters
this_valueThe this value for the call (an empty Value uses the global object).
argsThe arguments (an empty Value passes undefined).
argcThe number of entries in args.
Returns
Returns the function's return value. Fails with a JavaScript exception if the call throws or this value can't be called.

◆ Call() [2/2]

Result< Value > Call ( const Value & this_value,
std::span< const Value > args ) const
inlinenodiscard

Call this value as a function with the arguments in a range (eg, a std::vector<js::Value>).

Parameters
this_valueThe this value for the call (an empty Value uses the global object).
argsThe arguments.
Returns
Returns the function's return value and fails the same way as the overload above.

◆ Construct() [1/2]

template<typename R = Value, typename... A>
Result< R > Construct ( A &&... args) const

Call this value as a constructor with new, with typed arguments and result.

The arguments and the result (when you give R) convert through js::TypeTraits, as for Invoke():

js::Result<js::Value> lookup = ctx["Map"].Construct();
js::Result<js::Value> launch = ctx["Date"].Construct(2026, 0, 15);
Expected< T, Error > Result
The result of a JavaScript operation that can fail: a T or a js::Error.
Definition Error.h:520
Parameters
argsThe arguments to pass to the constructor.
Returns
Returns the new object converted to R. Fails with a TypeError if this value can't be called with new or the result doesn't convert to R, or with a JavaScript exception if the constructor throws.
Note
A std::vector<js::Value> argument passes one Array. To pass a list of arguments you build at run time, wrap it in a std::span<const js::Value> (see the overload below).

◆ Construct() [2/2]

Result< Value > Construct ( std::span< const Value > args) const
inlinenodiscard

Call this value as a constructor with new, with the arguments in a range.

std::vector<js::Value> args = { ctx.Make(3.0), ctx.Make(4.0) };
js::Result<js::Value> point = point_class.Construct(std::span<const js::Value>(args));
Parameters
argsThe arguments (an empty Value passes undefined).
Returns
Returns the new object and fails the same way as the overload above.

◆ DefineAccessor()

Result< bool > DefineAccessor ( const char * name,
const Value & getter,
const Value & setter,
PropertyAttributes attributes = PropertyAttributes::None ) const
inlinenodiscard

Define an accessor property of this object, with a getter and a setter function (like Reflect.defineProperty() with get and set).

The flags work as for DefineProperty(), except PropertyAttributes::ReadOnly, which doesn't apply to an accessor. Pass an empty Value to leave out the getter or the setter:

js::Value getter = ctx.MakeFunction("level", [] { return GetLevel(); });
obj.DefineAccessor("level", getter, js::Value()); // no setter
Result< bool > DefineAccessor(const char *name, const Value &getter, const Value &setter, PropertyAttributes attributes=PropertyAttributes::None) const
Define an accessor property of this object, with a getter and a setter function (like Reflect....
Definition Value.h:896
Parameters
nameThe property name (NULL is treated as "").
getterThe getter function (an empty Value for none).
setterThe setter function (an empty Value for none).
attributesThe flags combined with |.
Returns
Returns true if the property was defined, or false if the object refused (see DefineProperty()). Fails with a TypeError if this value isn't an object, if both functions are empty, or if one isn't callable, or with a JavaScript exception if the definition throws.
Note
Redefining an existing accessor keeps the getter or setter you leave out, so this can't remove one. To remove one, delete the property and define it again.

◆ DefineProperty()

Result< bool > DefineProperty ( const char * name,
const Value & value,
PropertyAttributes attributes = PropertyAttributes::None ) const
inlinenodiscard

Define a data property of this object (like Reflect.defineProperty()).

Unlike SetProperty(), this always applies the flags you give, whether or not the property exists already. No flags means a writable, enumerable, deletable property (the opposite of Object.defineProperty()'s defaults):

obj.DefineProperty("version", ctx.Make(2.0),
@ DontDelete
The property can't be deleted.
Definition Value.h:78
@ ReadOnly
Script can't change its value.
Definition Value.h:76
Parameters
nameThe property name (NULL is treated as "").
valueThe value (an empty Value defines undefined).
attributesThe flags combined with |.
Returns
Returns true if the property was defined, or false if the object refused (eg, an existing property that can't be deleted, an object that's frozen or can't be extended, or a property of a bound native class). Fails with a TypeError if this value isn't an object, or with a JavaScript exception if the definition throws (eg, in a Proxy's defineProperty handler).
Note
Defining a data property over an accessor property replaces the accessor.

◆ Delete() [1/2]

bool Delete ( const char * name) const
inlinenodiscard

Delete a property of this object (like DeleteProperty(), but without the failure reason).

Parameters
nameThe property name (NULL is treated as "").
Returns
Returns the delete operator's result (see DeleteProperty()).
Note
Any failure returns false. Use DeleteProperty() if you need the reason.

◆ Delete() [2/2]

template<detail::PropertyIndex I>
bool Delete ( I index) const
inlinenodiscard

Delete an element of this object by index (like Delete(), but taking an index).

Parameters
indexThe index (any integer type; a negative index deletes the property with that name).
Returns
Returns the delete operator's result (see DeleteProperty()).
Note
Any failure returns false. Use DeleteProperty() if you need the reason.

◆ DeleteProperty() [1/2]

Result< bool > DeleteProperty ( const char * name) const
inlinenodiscard

Delete a property of this object (like JavaScript's delete operator).

js::Result<bool> deleted = settings.DeleteProperty("cache");
Parameters
nameThe property name (NULL is treated as "").
Returns
Returns the delete operator's result: true if the property was deleted or didn't exist, false if the object refused (eg, a property created with PropertyAttributes::DontDelete, or a frozen object). Fails with a JavaScript exception if the delete throws (eg, in a Proxy's deleteProperty handler).
Note
Unlike SetProperty(), a refusal isn't ignored: it returns false.

◆ DeleteProperty() [2/2]

template<detail::PropertyIndex I>
Result< bool > DeleteProperty ( I index) const
inlinenodiscard

Delete an element of this object by index (eg, arr.DeleteProperty(2)).

Deleting an array element leaves a hole, so the array's length doesn't change. A negative index deletes the property with that name, as JavaScript does (-1 deletes "-1").

Parameters
indexThe index (any integer type).
Returns
Returns the delete operator's result and fails the same way as the overload above.

◆ Freeze()

Result< void > Freeze ( ) const
inlinenodiscard

Freeze this object (like Object.freeze()), so no property can be added, removed, or changed afterward.

Returns
Returns success (a value that isn't an object, or an object that's already frozen, succeeds without change). Fails with a TypeError if the object can't be frozen (eg, the global object, a Proxy whose handler refuses, or an instance of a bound native class), or with a JavaScript exception if a Proxy's handler throws.
Note
Unlike DeleteProperty() and DefineProperty(), a refusal here is an error, as it is in JavaScript.

◆ FromBorrowed()

Value FromBorrowed ( ULJSValue handle)
inlinestatic

Add a reference to a handle the library owns (eg, a callback argument) so it can outlive the callback.

Parameters
handleThe borrowed handle.
Returns
Returns a Value with its own reference to handle.
Note
For a handle you own, use Adopt().

◆ GetProperty()

Result< Value > GetProperty ( const char * name) const
inlinenodiscard

Get a property of this object (own or inherited).

Parameters
nameThe property name (NULL is treated as "").
Returns
Returns the property value (undefined if there's no such property). Fails with a JavaScript exception if a getter throws.

◆ Has()

bool Has ( const char * name) const
inline

Whether or not this object has a property (own or inherited).

Unlike reading the property, this returns true for a property set to undefined. It doesn't run JavaScript getters, but on an instance of a bound native class (see js::ClassBuilder) the property's native getter does run.

Parameters
nameThe property name (NULL is treated as "").
Note
Any failure returns false. Use HasProperty() if you need the reason.

◆ HasOwn() [1/2]

bool HasOwn ( const char * name) const
inline

Whether or not this object has an own property (one that isn't inherited, like Object.hasOwn()).

Like Has(), this doesn't run JavaScript getters, but on an instance of a bound native class the property's native getter does run.

Parameters
nameThe property name (NULL is treated as "").
Note
Any failure returns false. Use HasOwnProperty() if you need the reason.

◆ HasOwn() [2/2]

template<detail::PropertyIndex I>
bool HasOwn ( I index) const
inline

Whether or not this object has an own element at an index (eg, arr.HasOwn(2) is false for a hole).

Parameters
indexThe index (any integer type; a negative index checks the property with that name).
Note
Any failure returns false. Use HasOwnProperty() if you need the reason.

◆ HasOwnProperty() [1/2]

Result< bool > HasOwnProperty ( const char * name) const
inlinenodiscard

Whether or not this object has an own property (like HasOwn(), but reports failures).

Parameters
nameThe property name (NULL is treated as "").
Returns
Returns whether the object has the property itself. Fails with a JavaScript exception if the check throws (eg, in a Proxy's getOwnPropertyDescriptor handler, or in a bound native class's property getter).

◆ HasOwnProperty() [2/2]

template<detail::PropertyIndex I>
Result< bool > HasOwnProperty ( I index) const
inlinenodiscard

Whether or not this object has an own element at an index (like HasOwn(), but reports failures).

Parameters
indexThe index (any integer type; a negative index checks the property with that name).
Returns
Returns whether the object has the element itself and fails the same way as the overload above.

◆ HasProperty()

Result< bool > HasProperty ( const char * name) const
inlinenodiscard

Whether or not this object has a property (like Has(), but reports failures).

Parameters
nameThe property name (NULL is treated as "").
Returns
Returns whether the property exists. Fails with a JavaScript exception if the check throws (eg, in a Proxy's has handler).

◆ Invoke()

template<typename R = Value, typename... A>
Result< R > Invoke ( A &&... args) const

Call this value as a function with typed arguments and result.

The arguments and the result (when you give R) convert through js::TypeTraits:

js::Result<double> total = fn.Invoke<double>(3, "x");
fn.Invoke(path); // result left as a js::Value
Parameters
argsThe arguments to pass to the function.
Returns
Returns the call's result converted to R. Fails with a JavaScript exception if the call throws, or with a TypeError if the result doesn't convert to R.
Note
The function's this is the global object. To call a method on an object, call through operator[] (obj["m"](x)) or use InvokeOn().

◆ InvokeOn()

template<typename R = Value, typename... A>
Result< R > InvokeOn ( const Value & this_value,
A &&... args ) const

Call this value as a function with an explicit this (otherwise the same as Invoke()).

js::Result<js::Value> row = fn.InvokeOn(receiver, 42);
ContainerSpec< Children... > row(ContainerOptions options, Children... children)
Describe a row container with child elements.
Definition Builder.h:125
Parameters
this_valueThe this value for the call.
argsThe arguments to pass to the function.
Returns
Returns the call's result and fails the same way as Invoke().

◆ IsAlive()

bool IsAlive ( ) const
inline

Whether or not this Value's page is still alive (the same test as operator bool).

Note
Safe to call from any thread, but off the Renderer's thread the result may already be out of date when you act on it.

◆ IsArray()

bool IsArray ( ) const
inline

Whether or not the value is an Array.

◆ IsBigInt()

bool IsBigInt ( ) const
inline

Whether or not the value is a BigInt (eg, 10n).

◆ IsBoolean()

bool IsBoolean ( ) const
inline

Whether or not the value is a boolean.

◆ IsCallable()

bool IsCallable ( ) const
inline

Whether or not the value can be called (see Call() and Invoke()).

◆ IsConstructor()

bool IsConstructor ( ) const
inline

Whether or not the value can be called with new (see Construct()).

◆ IsEmpty()

bool IsEmpty ( ) const
inline

Whether or not this Value holds nothing (see "Handle States" above).

◆ IsFunction()

bool IsFunction ( ) const
inline

Whether or not the value is a function.

Note
A few callable objects aren't functions (eg, the constructor of a native class). Use IsCallable() to check whether you can call a value.

◆ IsNull()

bool IsNull ( ) const
inline

Whether or not the value is null.

◆ IsNullish()

bool IsNullish ( ) const
inline

Whether or not the value is null or undefined.

◆ IsNumber()

bool IsNumber ( ) const
inline

Whether or not the value is a number.

◆ IsObject()

bool IsObject ( ) const
inline

Whether or not the value is an object.

Arrays and functions are objects too (use IsArray() or IsFunction() to tell them apart).

◆ IsPromise()

bool IsPromise ( ) const
inline

Whether or not the value is a Promise.

This has no side effects: the promise isn't marked as handled.

◆ IsString()

bool IsString ( ) const
inline

Whether or not the value is a string.

◆ IsUndefined()

bool IsUndefined ( ) const
inline

Whether or not the value is undefined.

◆ LeakRef()

ULJSValue LeakRef ( )
inline

Give up ownership of the C API handle and return it (like RefPtr::LeakRef()).

Returns
Returns the handle. You must destroy it with ulDestroyJSValue() when finished.

◆ Maybe()

template<typename T>
std::optional< T > Maybe ( ) const
nodiscard

Convert to a C++ type like To() but without the failure reason.

Returns
Returns the converted value or nullopt on any failure.

◆ object_kind()

ObjectKind object_kind ( ) const
inline

Get the kind of object the value is (eg, a Map, a Date, or an ordinary object).

This never runs script, so it's safe on any value, a Proxy included.

if (value.object_kind() == js::ObjectKind::Date)
ShowDate(value.TimeValue().value_or(0.0));
@ Date
Definition Value.h:132
Returns
Returns the kind (ObjectKind::None for a value that isn't an object, and ObjectKind::Invalid for an empty Value or one whose page is gone).
Note
Later versions may add kinds, so handle a kind you don't know (see ObjectKind).

◆ operator bool()

operator bool ( ) const
inlineexplicit

Whether or not this Value is valid (it isn't empty and its page is still alive).

◆ operator()()

template<typename... A>
Result< Value > operator() ( A &&... args) const
inline

Call this value as a function: on_save(path) is the same as on_save.Invoke(path).

Parameters
argsThe arguments to pass to the function.
Returns
Returns the call's result and fails the same way as Invoke().

◆ operator=()

Value & operator= ( Value other)
inlinenoexcept

Assignment (copies or moves other into this Value).

◆ operator[]() [1/2]

Value::Ref operator[] ( const char * name) const
inline

Access a property to read, assign, or call it.

double volume = settings["volume"].Or(0.0);
settings["volume"] = 5.0;
settings["nested"]["deep"] = js::null;
settings["save"]("slot1"); // method call: `this` = settings
constexpr NullType null
The JavaScript null value.
Definition Value.h:49

A read that fails (the Value is empty or its page is gone, it holds null or undefined, or a getter throws) gives you an empty Value instead of an error, like JavaScript's optional chaining. Use GetProperty() or SetProperty() when you need the reason.

Parameters
nameThe property name.
Returns
Returns a Value::Ref for the property.
Note
A missing property reads as a valid undefined Value (operator bool returns true). Use Has() to check whether a property exists.
Note
You can also index with any integer type (eg, arr[2]). A negative index reads the property with that name as JavaScript does (arr[-1] reads "-1").

◆ operator[]() [2/2]

template<detail::PropertyIndex I>
Value::Ref operator[] ( I index) const

◆ Or() [1/2]

std::string Or ( const char * fallback) const
nodiscard

Convert to a std::string like To() but with a string-literal fallback.

Parameters
fallbackThe text to return if the conversion fails.
Returns
Returns the converted string or fallback on any failure.

◆ Or() [2/2]

template<typename T>
T Or ( T fallback) const
nodiscard

Convert to a C++ type like To() but with a fallback.

Parameters
fallbackThe value to return if the conversion fails.
Returns
Returns the converted value or fallback on any failure.
Note
The fallback's type is the type converted to, so pass 0.0 (not 0) to read a number that can have a fraction: Or(0) converts to int and fails on 3.5.

◆ OwnKeys()

Result< std::vector< std::string > > OwnKeys ( OwnKeysFlags flags = OwnKeysFlags::None) const
inlinenodiscard

Get the names of this object's own properties, without reading their values.

The names come in the same order as Object.getOwnPropertyNames() (integer keys in ascending order, then the rest in the order they were added). Inherited properties and Symbol keys aren't listed.

No getter runs, so this is a safe way to walk an object you don't control:

for (const std::string& key : obj.OwnKeys().value_or({}))
Log(key);
Parameters
flagsOwnKeysFlags::IncludeNonEnumerable to also list non-enumerable properties (eg, an array's length).
Returns
Returns the names. Fails with a JavaScript exception if listing them throws (eg, in a Proxy's ownKeys handler).
Note
An array or typed array lists one name per element, so a large one gives a large list.

◆ raw()

ULJSValue raw ( ) const
inline

Get the C API handle without transferring ownership.

Returns
Returns the handle for use with the <Ultralight/CAPI/CAPI_JSValue.h> functions.

◆ SetProperty()

Result< void > SetProperty ( const char * name,
const Value & value,
PropertyAttributes attributes = PropertyAttributes::None ) const
inlinenodiscard

Set a property of this object.

Parameters
nameThe property name (NULL is treated as "").
valueThe value to assign (an empty Value assigns undefined).
attributesThe flags combined with |. They only apply if this creates the property (see PropertyAttributes).
Returns
Returns success. Fails with a JavaScript exception if a setter throws.
Note
Like an assignment in non-strict JavaScript, a write the object refuses (a frozen object, or a read-only property) is silently ignored and still returns success.

◆ StrictEquals()

bool StrictEquals ( const Value & other) const
inline

Whether or not this value and other are strictly equal (like JavaScript's ===).

Two handles to one object are equal, strings compare by content, NaN never equals anything, and +0 equals -0. This never runs script.

Parameters
otherThe value to compare with.
Returns
Returns whether the values are strictly equal (false if either Value is empty or its page is gone).

◆ Then() [1/2]

template<typename T, typename F>
requires (!std::is_same_v<T, Value>)
bool Then ( F && on_settled) const
inlinenodiscard

Wait for this promise to settle and convert its value to a C++ type.

bool waiting = promise.Then<std::string>([](js::Result<std::string> r) {
if (r)
ApplyName(*r);
});
Parameters
on_settledA callable that takes a js::Result<T>.
Returns
Returns true if this value is a Promise and on_settled will run (see Then()).
Note
If the value doesn't convert to T (see To()), on_settled gets the TypeError.

◆ Then() [2/2]

template<typename F>
bool Then ( F && on_settled) const
inlinenodiscard

Wait for this promise to settle without a coroutine.

on_settled runs once on the Renderer's thread during a later Renderer::Update(). Its Result holds the promise's value or an Error with the rejection reason. If the page goes away first, it gets a page-gone Error instead, so it always runs.

// Page: myApp.nativeReady(fetch('/level.json').then(r => r.json()));
api["nativeReady"] = [](js::Value promise) {
bool waiting = promise.Then([](js::Result<js::Value> r) {
if (r)
LoadLevel(*r); // fulfilled: r holds the value
else if (!r.error().is_page_gone())
Log(r.error().message()); // rejected: r.error() holds the reason
});
if (!waiting)
Log("nativeReady expects a Promise");
};
Parameters
on_settledA callable that takes a js::Result<js::Value>.
Returns
Returns true if this value is a Promise and on_settled will run. Otherwise it returns false and destroys on_settled without running it.
Note
A rejection you wait for this way counts as handled, so the page doesn't report it as unhandled.
Note
In a coroutine, use co_await js::Await<T>(promise) instead (see <Ultralight/js/Task.h>).

◆ TimeValue()

Result< double > TimeValue ( ) const
inlinenodiscard

Get the time value of a Date, in milliseconds since the epoch (like date.getTime()).

This reads the Date directly, so it never runs script (a valueOf() the page replaced isn't called).

Returns
Returns the time value (NaN for an Invalid Date). Fails with a TypeError if the value isn't a Date.
See also
Context::MakeDate()

◆ To()

template<typename T>
Result< T > To ( ) const
nodiscard

Convert to a C++ type.

This works for every type js::TypeTraits supports: numbers, strings, containers, optionals, variants, reflected structs and enums, and your own specializations. The value must already have the matching JavaScript type (see "Type Conversions" above).

js::Result<Settings> s = payload["settings"].To<Settings>();
// To walk an array or an object's entries, convert to a container of js::Value:
auto items = arr.To<std::vector<js::Value>>().value_or({});
auto entries = obj.To<std::map<std::string, js::Value>>().value_or({});
// A std::map takes an ordinary object (eg, `{ a: 1 }`), not a Map, Set, or Date:
auto bad = lookup.To<std::map<std::string, double>>(); // fails on `new Map()`
App-specific settings.
Definition App.h:51

An integer type needs a whole number in its range, so To<int>() on 3.5 fails instead of truncating.

Returns
Returns the converted value. Fails with a TypeError (code ULJS_BAD_ARG) if the value doesn't have the requested type. Its message says where and why, like a bound function's (eg, "volume: expected number, got 'loud'").
Note
Requires <Ultralight/js/TypeTraits.h> (or any header that includes it).

◆ ToBoolean()

Result< bool > ToBoolean ( ) const
inlinenodiscard

Convert to a boolean using JavaScript's rules (this never runs script).

Returns
Returns the boolean.

◆ ToJSON()

Result< std::string > ToJSON ( unsigned indent = 0) const
inlinenodiscard

Convert to JSON text like JSON.stringify() does.

Parameters
indentThe number of spaces to indent each level by (0 for compact output, at most 10).
Returns
Returns the JSON text. Fails with a TypeError if the value has no JSON form (undefined, a function, or a Symbol), or with a JavaScript exception if a toJSON() method or a getter throws.

◆ ToNumber()

Result< double > ToNumber ( ) const
inlinenodiscard

Convert to a number using JavaScript's rules.

Returns
Returns the number. Fails with a JavaScript exception if the conversion throws (eg, a valueOf() method throws or the value is a Symbol).

◆ ToString()

Result< std::string > ToString ( ) const
inlinenodiscard

Convert to a UTF-8 string using JavaScript's rules.

Returns
Returns the string. Fails with a JavaScript exception if the conversion throws (eg, a toString() method throws or the value is a Symbol).

◆ type()

Type type ( ) const
inline

Get the type of the value.

Returns
Returns the value's type (Type::Invalid for an empty Value or one whose page is gone).

The documentation for this class was generated from the following file: