cpp_api

📄Description

The C++ value API is used by native modules, extension code, and embedded integrations to create, inspect, and extract Nelson values. The main entry point is the public header ArrayOf.hpp, which exposes the NELSON_ARRAYOF_API_VERSION macros for version checks.

Factory functions on ArrayOf describe the value they create directly. Common examples include doubleScalar, singleScalar, logicalScalar, int32Scalar, doubleRowVector, doubleMatrix2d, cellArray, structArray, stringArray, table, and handle.

Simple property accessors use short noun names such as rows, columns, elementCount, dimensions, dataClass, fieldNames, and referenceCount. These functions must stay cheap and must not hide allocation.

Names beginning with as extract an existing C++ value from a Nelson value, for example asDoubleScalar, asUtf8String, asWideString, asIndexVector, and asFunctionHandle.

Names beginning with to create a new representation. Names beginning with toAllocated, such as toAllocatedUtf8CString, make ownership and allocation explicit.

Mutation and state follow the usual verb prefixes: setX mutates a property, isX tests state, and makeX transforms the value in place.

The API preserves fast paths: scalar inline storage, cached dimensions in Data, copy-on-write ownership, and pointer access without hidden allocation. Pointers returned by value objects remain valid only while the owning value and its storage state remain valid.

💡Examples

Create and inspect a scalar value.

ArrayOf value = ArrayOf::doubleScalar(3.0);
double scalar = value.asDoubleScalar();
indexType rows = value.rows();
indexType cols = value.columns();

Create a cell array and read simple properties.

ArrayOfVector items;
items << ArrayOf::doubleScalar(1.0);
items << ArrayOf::stringArray("name");
ArrayOf cells = ArrayOf::cellArray(items);
indexType count = cells.elementCount();