pvxs/documentation/value.rst

Value Container

nt typedef

#include <pvxs/data.h>
namespace pvxs { ... }

pvxs::Value is the primary data container type used with PVXS. A pvxs::Value may be obtained via the remote peer (client or server), or created locally. See ntapi or typedefapi.

pvxs::Value is a safe pointer-like object which, maybe, references a node in a tree of sub-structures and leaf fields. This tree will be referred to as a Structure as it behaves in many ways like a C 'struct'.

For example, the following code:

Value top = TypeDef(TypeCode::Struct, {
    members::Int32("fldname"),
}).create();

top["fldname"] = 1;

fld = top["fldname"];
fld = 2;

Is analogous to the following pseudo code.

// pseudo-code
struct anon {
    int32_t fldname=0u;
};
void* top = new anon;

static_cast<anon*>(top)->fldname = 1;

void* fld = &static_cast<anon*>(top)->fldname;
static_cast<int32_t*>(fld) = 2;

With the chief functional difference being that the analogs of the casts are made safe. Also, the storage of the underlying Structure will be free'd when no more Values reference it.

A Value which does not reference any underlying Structure is not valid, or "empty".

Value dummy;
assert(!dummy.valid());
assert(!dummy); // operator bool() is an alias for valid()

An invalid Value may be returned on error by some methods. All operations on an invalid Value should be safe and well defined.

Value top(nt::NTScalar{TypeCode::Int32}.create());
int32_t val = top["nonexistant"].as<int32_t>();

In this example, the operator[] lookup of a non-existant field returns an invalid Value. Attempting to extract an integer from this will then throw a pvxs::NoField exception.

Value

Field Lookup

Access to members of structured types is accomplished through pvxs::Value::operator[] or pvxs::Value::lookup. These two methods differ in how errors are communicated. operator[] will return an "invalid" or "empty" Value if the expression does not address a member. lookup() will throw an exception describing where and how expression evaluation failed.

Iteration

pvxs::Value instances pointing to a non-array structured data field (Struct or Union) may be iterated. Iteration comes in three variations: pvxs::Value::iall, pvxs::Value::ichildren, and pvxs::Value::imarked.

For a Struct, iall() is a depth first traversal of all fields. ichildren() traverses all child fields (excluding eg. grandchildren and further). imarked() considers all fields, but only visits those which have beem marked (pvxs::Value::isMarked).

For a Union. iall() and ichildren() are identical, and will visit all possible Union members, excluding the implicit NULL member. Traversal does not effect member selection. imarked() for a Union will visit at most one member (if one is selected)>

Iteration of Union may return Value instances allocated with temporary storage. Changes to these instances will not effect the underlying structure.

Iteration of other field types, including StructA and UnionA is not implemented at this time, and will always appear as empty.

pvxs::Value

pvxs::NoField

pvxs::NoConvert

pvxs::LookupError

Array fields

Array fields are represented with the pvxs::shared_array container using void vs. non-void, and const vs. non-const element types.

Arrays are initially created as non-const and non-void. After being populated, an array may be transformed using pvxs::shared_array::freeze to become const and/or pvxs::shared_array::castTo to become void.

Only const Array values may be stored in pvxs::Value.

shared_array<double> arr({1.0, 2.0});
Value top = nt::NTScalar{TypeCode::Float64A}.create();

top["value"] = arr.freeze();
# freeze() acts like std::move().  arr is now empty

The pvxs::shared_array::freeze method is special in that it acts like std::move() in that it moves the array reference into the returned object. freeze() requires exclusive ownership of the reference being frozen. An exception will be thrown unless pvxs::shared_array::unique would return true.

Array values may be extracted from pvxs::Value as either const void or const non-void. The const non-void option is a convienence which may allocate and do an element by element conversion.

# extract reference, or converted copy
arr = top["value"].as<shared_array<const double>>();

Extract as const void to ensure the Array values are not implicitly copied. This does require calling pvxs::shared_array::original_type to find the pvxs::ArrayType of the underlying array prior to using pvxs::shared_array::castTo.

# extract untyped reference.  Never copies
shared_array<const void> varr = top["value"].as<shared_array<const void>>();
if(varr.original_type()==ArrayType::Float64) {
    # castTo() would throw std::logic_error if the underlying type were not correct.
    shared_array<const double> temp = varr.castTo<const double>();
}

pvxs::shared_array

pvxs::elementSize