Discuss this help topic in SecureBlackbox Forum

Handle complex types

JSON format supports two complex types: object and array.

An object is a named collection of properties. Properties can be of different types including arrays and other objects. The simplest and preferable way to get and set properties values is to use their names. Also, it's possible to get/set them by index.

An array is an indexed collection of elements. Elements can be of different types including objects and other arrays. Elements in arrays are accessible by their indices.

Composing objects

To set a new value to properties of the simple types, call one of SetBooleanValue(), SetDoubleValue(), SetNullValue(), SetIntegerValue() and SetStringValue() methods. Each of these methods has two parameters: a property name and a value. SetNullValue() method accepts a property name only. If a property with the specified name doesn't exist yet, it is created with the specified value. If a property with the specified name already exists and it is of complex type, an exception is raised.

var obj = new TElJsonObject();
obj.SetBooleanValue("boolean_value", true);
obj.SetDoubleValue("number_value", 2943.20);
obj.SetIntegerValue("integer_value", 100);
obj.SetNullValue("null_value");
obj.SetStringValue("string_value", "test");
This produces the following output:
{
    "boolean_value": true,
    "integer_value": 100,
    "null_value": null,
    "number_value": 2943.2,
    "string_value": "test"
}

Properties of the complex types are set another way: if a property with the specified name already exists, the old instance of TElJsonObject/TElJsonArray class is replaced by the new one.

var child = new TElJsonObject();
obj["child_object"] = child;
child.SetNullValue("test");

var arr = new TElJsonArray();
obj["child_array"] = arr;
arr.Append("first");
arr.Append(2);
This produces the following output:
{
    "boolean_value": true,
    "child_array":
	  [
		"first",
		2
	  ],
    "child_object":
	  {
		"test": null
	  },
    "integer_value": 100,
    "null_value": null,
    "number_value": 2943.2,
    "string_value": "test"
}

Analyzing objects

To get values of simple properties, call the object's one of "get-value" methods: GetBooleanValue(), GetDoubleValue, GetIntegerValue, GetStringValue. Each of these methods has two declarations.

The first declaration has only name parameter; such methods return value of the property with the specified name. If no such property exists in the object or its type cannot be converted to the method result's type, an exception is raised.

The second declaration has two parameters, one for property name and another for a default value to be returned if no such property exists in the object or the property type cannot be converted to the method result's type.

Also, there is IsNullValue() method available. It returns True if the object contains a property with the specified name and this property has a null value.

The examples below use the object composed in the previous topic section.

// returns True; if there is no property with name "boolean_value" exist or
// its value cannot be converted to boolean type, an exception is thrown
bool booleanValue = obj.GetBooleanValue("boolean_value");

// returns 2943.2; if there is no property with name "number_value" exist or
// its value cannot be converted to double type, an exception is thrown
double doubleValue = obj.GetDoubleValue("number_value");

// returns 100; if there is no  property with name "integer_value" exist or
// its value cannot be converted to integer type, an exception is thrown
long integerValue = obj.GetIntegerValue("integer_value");

// returns "test" (w/o quotes); if there is no  property with name "string_value"
// exist or the property is an array or an object, an exception is thrown
string stringValue = obj.GetStringValue("string_value");

// returns True; if the object doesn't contain a property with name "null_value" or
// its value is not null, the method returns False; no exception is thrown
if (obj.IsNullValue("null_value")) ;

// as there is no such property, the default value "True" is returned
bool booleanFake = obj.GetBooleanValue("boolean_fake", true);

// returns 35.82
double doubleFake = obj.GetDoubleValue("double_fake", 35.82);

// returns 0
long integerFake = obj.GetIntegerValue("integer_fake", 0);

// returns an empty string
string stringFake = obj.GetStringValue("string_fake", String.Empty);

// the first call returns False as there is no property with name "null_fake";
// the second call returns False as the "string_value" property is not of null type
if (obj.IsNullValue("null_fake") or (obj.IsNullValue("string_value")) {}

To get an object type property, there are two methods available: GetObject() and GetObjectIfExists(). The GetObject() method returns an instance of TElJsonObject if the property with the specified name exists and it contains an object. If no such property available or it doesn't contain an object, an exception is raised. The GetObjectIfExists method doesn't raise an exception if there is no such property in the object or the property doesn't contain an object. Instead, the method returns null/nil/Nothing.

The similar methods are available to get properties of the array type. The methods are GetArray and GetArrayIfExists. They behave absolutely the same way as described above for GetObject and GetObjectIfExists methods.

// returns an instance of TElJsonObject; if there is no property with name "child_object"
// available or it is not of object type, an exception is thrown
var childObj = obj.GetObject("child_object");

// returns null as there is no such property
var fakeObj = obj.GetObjectIfExists("fake_object");

// returns an instance of TElJsonArray; if there is no property with name "child_array"
// available or it is not of array type, an exception is thrown
var childArr = obj.GetArray("child_array");

// returns null as there is no such property
var fakeArr = obj.GetObjectIfExists("fake_array");
Also, there is a way to enumerate all the properties available in an object.
for (int i = 0; i < obj.Count; i++)
    Console.WriteLine("{0}: {1}", obj.NameAtIndex(i), obj.ValueAtIndex(i));
This code produces the following output:
boolean_value: true
child_array: SBJSON.TElJsonArray
child_object: SBJSON.TElJsonObject
integer_value: 100
null_value: null
number_value: 2943.2
string_value: test

Composing arrays

An array is an ordered list of elements of different types. To add a new element to the end of an array, use an appropriate Append method. These methods accept parameters of different types and return the index of the new element. Indices are zero-based.

The sample below shows how to add elements of the simple types.

var arr = new TElJsonArray();

// adds a boolean entity with the value set to True
arr.Append(true);

// adds a number entity with the value set to 2943.20
arr.Append(2943.20);

// adds a number entity with the value set to 100
arr.Append(100);

// adds a null entity
arr.Append();

// addes a string entity
arr.Append("test");
This code produces the following output:
[
    true,
    2943.2,
    100,
    null,
    "test"
]

If you need to change the value of an already existing element, you can use SetBooleanValue, SetDoubleValue, SetIntegerValue, SetNullValue and SetStringValue methods. These methods take an element index and a new value as parameters. The SetNullValue method requires only an element index. If no element with the specified index exists in the array or the element is an object or another array, an exception is thrown.

var arr = new TElJsonArray();

arr.SetStringValue(0, "changed");
arr.SetNullValue(1);
arr.SetBooleanValue(2, false);
arr.SetIntegerValue(3, 500);
arr.SetDoubleValue(4, 12344.89);

This code produces the following output:

[
    "changed",
    null,
    false,
    500,
    12344.89
]

In order to add an element of a complex type to an array, it's needed to create an instance for this element first and then to call the Append() method and pass the created instance to it. If you need to insert the created instance at a certain position, call the Insert() method instead of Append().

var arr = new TElJsonArray();

// adding an element of object type
var childObj = new TElJsonObject();
arr.Append(childObj);
childObj.SetNullValue("test");

// adding an element of array type
var childArr = new TElJsonArray();
arr.Insert(3, childArr);
childArr.Append("first");
childArr.Append(2);
This code produces the following output:
[
    true,
    2943.2,
    100,
    [
	  "first",
	  2
    ],
    null,
    "test",
    {
	  "test": null
    }
]

How To articles about basic JSON questions

Discuss this help topic in SecureBlackbox Forum