Under the hood, scalar values are a special case of arrays containing a single element. Scalars have dimension zero i.e., a shape defined by an empty integer array, e.g. int shape[0] in a corresponding XField element.
In this way scalars are distinguished from true arrays containing just a single elements, which have dimensionality <=1 and shapes e.g., int shape[1] = {1} or int shape[2] = {1, 1}. The difference, while subtle, becomes more obvious when serializing the array, e.g. to JSON. A scalar floating point value of 1.04, for example, will appear as 1.04 in JSON, whereas the 1D and 2D single-element arrays will be serialized as { 1.04 } or {{ 1.04 }}, respectively.
Note, that there is no requirement that the native array has the same dimensionality as it's nominal format in the field. We could have declared data as a 1D array double data[2 * 3 * 4] = ..., or really any array (pointer) containing doubles with storage for at least 24 elements. It is the sizes array, along with the dimensionality, which together define the number of elements used from it, and the shape of the array for xchange.
Arrays of irregular shape or mixed element types can be represented by fields containing an array of XField entries:
and then eventually destroyed after use as:
Once a structure is populated – either by having constructed it programatically, or e.g. by parsing a JSON definition of it from a string or file – you can access its content and/or modify it.
E.g., to retrieve the "property" field from the above example structure:
or to retrieve the "subsystem" structure from within:
Conversely you can set / update fields in a structure using xSetField() / xSetSubstruct(), e.g.:
You can also remove existing fields from structures using xRemoveField(), e.g.
The normal xGetField() and xGetSubstruct() functions have computational costs that scale linearly with the number of direct fields in the structure. It is not much of an issue for structures that contain dozens of, or even a couple hundred, fields (per layer). For much larger structures, which have a fixed layout, there is an option for a potentially much more efficient hash-based lookup also. E.g. instead of xGetField() you may use xLookupField():
| double xGetAsDouble | +( | +const XStructure * | +s, | +
| + | + | const char * | +id | +
| + | ) | ++ |
Return a double-precision floating point value associated to the field by the specified name, or else NAN if the field cannot be represented as a decimal value. This call will use widening conversions as necessary to convert between numerical types (e.g. short to double), while for string values will attempt to parse a decomal value.
If the field is an array, the first element is converted and returned.
+| s | Structure from which to retrieve a given field. |
| id | Name or aggregate ID of the field to retrieve. |
References XField::isSerialized, NAN, XField::type, XField::value, X_BOOLEAN, X_BYTE, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_LONG, X_RAW, X_SHORT, X_STRING, x_trace_null(), xElementSizeOf(), xGetField(), and xIsCharSequence().
+ +| long xGetAsLong | +( | +const XStructure * | +s, | +
| + | + | const char * | +id, | +
| + | + | long | +defaultValue | +
| + | ) | ++ |
Return an integer value associated to the field by the specified name, or else the specified default value if the field cannot be represented as an integer. This call will use both widening and narrowing conversions, and rounding, as necessary to convert between numerical types (e.g. float to long), while for string values will attempt to parse an integer value.
If the field is an array, the first element is converted and returned.
+| s | Structure from which to retrieve a given field. |
| id | Name or aggregate ID of the field to retrieve. |
| defaultValue | The value to return if the structure contains no field with the specified ID, or if it cannot be represented as an integer though narrowing or widening conversions, rounding, or through parsing. |
References XField::isSerialized, NAN, XField::type, XField::value, X_BOOLEAN, X_BYTE, X_DOUBLE, x_error(), X_FLOAT, X_INT, X_LONG, X_RAW, X_SHORT, X_STRING, x_trace(), xElementSizeOf(), xGetField(), and xIsCharSequence().
+Return the field by the specified name, or NULL if no such field exists.
+Return the reference to the field by the specified name, or NULL if no such field exists.