CSPro ⇄ JSON Conversions: Array Object

A CSPro Array is generally represented as a JSON array. The underlying values of the Array are serialized according to the JSON serialization rules for numeric values or string values.

Based on JSON serialization options—defined as an application property or dynamically—an Array can be serialized as a sparse array represented as a JSON object. In this mode, the JSON object's property names represent array indices and the object's property values represent non-default values. Default values are considered 0, or default for saved arrays. Array indices are serialized starting at 0, even though in CSPro access starts at 1.

For example, with this Array:

Array values(2, 3) = 111, 0, 222, 0, 0, 999;

The two types of serialization result in the following JSON:

Full Array (default)	Sparse Array
[ [ 111.0, 0.0, 222.0 ], [ 0.0, 0.0, 999.0 ] ]	{ "0": { "0": 111.0, "2": 222.0 }, "1": { "2": 999.0 } }

When converting a JSON value to an Array, an exception occurs if the value is not an array or an object. A JSON array is parsed as a full array; a JSON object is parsed as a sparse array. If parsing a JSON array, an exception occurs if there are more dimensions to the array than those defined by the CSPro Array. If the JSON array has more values for a given dimension compared with the CSPro Array, those excess values are ignored. If parsing a JSON object, an exception occurs if the array indices—which begin at 0—are invalid, though indices greater than a given dimension's length are ignored. An exception occurs if any of values cannot be converted to a CSPro number or string.

Example 1

Array string spicyPeppers(2, 3) = "Carolina Reaper", "Ghost", "Habanero",
"Jalapeño", "Serrano", "Trinidad Moruga Scorpion";

spicyPeppers.getJson() // returns:

{
"name": "spicyPeppers",
"type": "Array",
"contentType": "string",
"saveArray": false,
"dimensions": [
2,
3
],
"value": [
[
"Carolina Reaper",
"Ghost",
"Habanero"
],
[
"Jalapeño",
"Serrano",
"Trinidad Moruga Scorpion"
]
]
}

Example 2 (Full Array)

Array values(2, 2) = 1.23, refused, 0, 9;

values.getValueJson(serializationOptions := "{ \"ArrayFormat\": \"full\" }") // returns:

[
[
1.23,
"REFUSED"
],
[
0.0,
9.0
]
]

Example 3 (Sparse Array)

values.getValueJson(serializationOptions := "{ \"ArrayFormat\": \"sparse\" }")) // returns:

{
"0": {
"0": 1.23,
"1": "REFUSED"
},
"1": {
"1": 9.0
}
}