A generic value passed to data-binding formatters and handlers.
A Value represents incoming data in formatters and in action and change handlers that take a generic parameter instead of a concrete C++ type.
DefineFormat() passes the bound field to your formatter as a Value:
ctx.DefineFormat("comma", [](dd::Value v) {
std::string digits = std::to_string(v.Or(int64_t(0)));
for (int i = int(digits.size()) - 3; i > 0; i -= 3)
digits.insert(i, ",");
return digits;
});
What a Value Holds
An instance represents one of several data shapes:
- An empty state holds no data. Actions dispatched without a payload arrive empty, including every action fired from markup.
- A leaf holds a single value. Formatters, change handlers, and scalar action payloads provide one boolean, numeric, or string value.
- An object holds named members. Actions dispatched with a payload struct provide fields that you look up by name.
Brackets look up an object's members by name:
binding.OnAction<"moveItem">([&](dd::Value request) {
int from = request["from"].Or(0);
int to = request["to"].Or(0);
bag.MoveItem(from, to);
});
Converting Values
Choose the extraction method that matches your error-handling style:
- To() returns a Result. Failure yields a TypeError explaining the mismatch.
- Maybe() returns an optional. Failure yields std::nullopt without an error.
- Or() returns a fallback. Failure returns the default value you supplied.
Conversions target bool, integer types, floating-point types, String, std::string, and reflected enums. Integer values convert to floating-point types, but floating-point values don't convert to integers. Reflected enums convert from string values using their enumerator names.
Indexing a missing member or an empty Value returns an empty Value. Because conversions fail safely on empty instances, you don't need to check Contains() or IsEmpty() before reading a member with Or() or Maybe().
- Note
- dom::data::Value and js::Value are unrelated. A dom::data::Value holds an owned copy of native data rather than a handle into a page's JavaScript context.
- See also
- dom::data::Binding::OnAction(), dom::data::Binding::OnChange(), dom::data::Context::DefineFormat(), dom::data::ActionInfo
|
| | Value ()=default |
| | Create an empty Value.
|
| bool | IsEmpty () const |
| | Whether or not this Value holds nothing.
|
| | operator bool () const |
| | Whether or not this Value holds something (the opposite of IsEmpty()).
|
| bool | IsBoolean () const |
| | Whether or not this Value is a boolean leaf.
|
| bool | IsInt64 () const |
| | Whether or not this Value is an integer leaf.
|
| bool | IsDouble () const |
| | Whether or not this Value is a floating-point leaf.
|
| bool | IsString () const |
| | Whether or not this Value is a string leaf.
|
| bool | IsObject () const |
| | Whether or not this Value is an object (the members of an action's payload struct).
|
| Value | operator[] (const char *name) const |
| | Get a member of an object.
|
| bool | Contains (const char *name) const |
| | Whether or not this Value is an object with a member of the given name.
|
| size_t | member_count () const |
| | Get the number of members (0 unless this Value is an object).
|
| template<typename T> |
| Result< T > | To () const |
| | Convert to a C++ type (see "Converting Values" in the class description).
|
| 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.
|