Tutorial from project

// Welcome to this tutorial!

// I will assume that you are familiar with JSON data format. Here is an example:
// { "key1": 1, "key2": "two" }, or more complicated:
// { "key1": "value1", "key2": 123, "key3": [ 1, 2, "3", { "key1": true } ], key4: { "key1": 1 } }
// As you know, there are two JSON data objects, JSON Object and JSON Array.
// JSON Object is set of key/value pairs, where keys are Strings.
// JSON Array is array which holds only values in strict order, accessing them by index.
// Value can be any of String, Number, Boolean, JSON Object or JSON Array.

// In this library you will find both JSONObject and JSONArray data type, so that you
// can easily manipulate JSON, create it, convert it into String and from String back
// into object, and accessing its data, like with any other native type in C#.
// But what is much unique in this library is that even value has its own type, named
// JSONValue, and any type, primitive or complex, can also be represented as this type.
// But let's move to the examples.

// Creating JSONObject:
Debug.WriteLine("\r\nCreating JSONObject");

JSONObject jsonObject = new JSONObject();
// this will create new key if it does not exists, otherwise it will create a new one.
jsonObject["key1"] = "value1";
jsonObject["key2"] = true;
jsonObject["key3"] = 5;
Debug.WriteLine(jsonObject); // it will be automatically converted to String before output.
jsonObject.Remove("key3");
Debug.WriteLine(jsonObject);
String jsonString = jsonObject; // this will also create String from JSONObject.
Debug.WriteLine(jsonObject);

// More about creating JSONObject:
Debug.WriteLine("\r\nMore about creating JSONObject");

jsonObject = new JSONObject(new object[,] {
{ "key1", "1" }, { "key2", 2 }});
Debug.WriteLine(jsonObject);

Dictionary<string, object=""> dictionary = new Dictionary<string, object="">();
dictionary.Add("key1", "value1"); dictionary.Add("key2", DateTime.Now);
jsonObject = new JSONObject(dictionary);
Debug.WriteLine(jsonObject);

// Accessing JSONObject values:
Debug.WriteLine("\r\nAccessing JSONObject values");

jsonObject = new JSONObject(new object[,] {
{ "key1", "1" },
{ "key2", -2.5 },
{ "key3", new JSONObject(new object[,] {
{ "key1", true }, { "key2", 5 }}) } });
Decimal value1 = jsonObject["key2"];
Debug.WriteLine(value1);
UInt32 value2 = jsonObject["key3"]["key2"];
Debug.WriteLine(value2);
jsonObject["key3"]["key1"] = false;
Debug.WriteLine(jsonObject["key3"]["key1"]);

// Parsing JSON Object string:
Debug.WriteLine("\r\nParsing JSON Object string");

jsonObject = JSONObject.Parse("{\"key1\":1,\"key2\":{\"key1\":true,\"key2\":\"2.5\"}}");
Debug.WriteLine(jsonObject);

// Creating JSONArray:
Debug.WriteLine("\r\nCreating JSONArray");

JSONArray jsonArray = new JSONArray();
jsonArray.Add("value1"); jsonArray.Add(2); jsonArray.Add(true);
Debug.WriteLine(jsonArray);
jsonArray.RemoveAt(1);
jsonArray.Insert("value0", 0);
Debug.WriteLine(jsonArray);

// More about creating JSONArray:
Debug.WriteLine("\r\nMore about creating JSONArray");

jsonArray = new JSONArray(new object[] { true, "value2" });
Debug.WriteLine(jsonArray);

List<object> list = new List<object>();
list.Add(1); list.Add("value2");
list.Add(new JSONObject(new Object[,] {
{ "key1", "value1"}, { "key2", true }}));
jsonArray = new JSONArray(list);
Debug.WriteLine(jsonArray);

// Accessing JSONArray values:
Debug.WriteLine("\r\nAccessing JSONArray values");

jsonArray = new JSONArray(new object[] {
true, "value2",
new JSONObject(new object[,] { { "key1", "value1" }, { "key2", 2 } })
});
String value3 = jsonArray[1];
Debug.WriteLine(value3);
String value4 = jsonArray[2]["key2"];
Debug.WriteLine(value4);

// Parsing JSON Array string:
Debug.WriteLine("\r\nParsing JSON Array string");

jsonArray = JSONArray.Parse("[1,{\"key1\":true,\"key2\":\"2.5\"}]");
Debug.WriteLine(jsonArray);

// You have noticed that I'm using nested structures in this example. Parsers
// can also parse nested objects and create complex nested native objects,
// so that JSONObject can parse nested JSON Array and JSONArray can parse
// nested JSON Object.
// But this two types are even more related because there is a type which
// encapsulates them (not really encapsulate in C# term, it's just a wrapper)
// so that it gives them common properties, and that is JSONValue. So every
// value in that nested structure is, in fact, an object of this type.

// JSONValue examples:
Debug.WriteLine("\r\nJSONValue examples");

JSONValue jsonValue = new JSONObject();
jsonValue["key1"] = "value1";
Debug.WriteLine(jsonValue);

jsonValue = JSONValue.Parse("[1,{\"key1\":true,\"key2\":2.5}]");
Debug.WriteLine(jsonValue);

JSONValue jsonValue2 = jsonValue[1]["key1"];
Boolean value5 = jsonValue2;
Debug.WriteLine(value5);

// And of course, Null value example:
Debug.WriteLine("\r\nNull value example");

jsonValue = JSONValue.Parse("[1,{\"key1\":null,\"key2\":\"2.5\"}]");
Debug.WriteLine(jsonValue[1]["key1"].ToString());

// More nested example
Debug.WriteLine("\r\nMore nested example");
String a = "{\"key1\":\"value1\",\"key2\":{\"key21\":{\"key211\":\"value211\"},\"key22\":{\"key221\":\"value221\"}},\"key3\":{\"key31\":\"value31\"}}";
JSONObject b = JSONObject.Parse(a);
Debug.WriteLine(b.ToString());

// Example with whitespaces (now supported)
Debug.WriteLine("\r\nExample with whitespaces");
jsonValue = JSONValue.Parse(" {\"key1\" : {\"key1\" : \"value1\", \"key2\":\"value2\"} , \"key2\":[1 ,\"2.5\" ]}");
Debug.WriteLine(jsonValue.ToString());

// Be careful when parsing invalid strings, or when (implicitly or explicitly)
// typecast values, because exception will be thrown on any invalid operation.

// Also notice the difference between String typecast and ToString() method.
// Typecast will simply convert object to String. ToString() methods makes
// string representation of JSON value, so that String value <value1> becomes
// <"value1">, as it would be in JSON representation. Also, <null> value becomes
// <null> string in JSON. Use ToString() method to display JSON string,
// and typecast to convert values.

// I hope that you like this approach of making JSON for .NET simple and usable.
// And that you enjoyed reading this tutorial, too.