Public classes


Scripts/

   JArray
   JBoolean
   JNull
   JNumber
   JSON
   JString
   JValue

Scripts/Exceptions/

      DeserializeException
      JArgumentException
      JArgumentNullException
      JArrayIndexOutOfRangeException
      JNumberFormatException
      JNumberOverflowException
      JSONKeyAlreadyExistsException
      JSONKeyNotFoundException
      JValueNullException
      JValueTypeException
      ParseException
      ProtectedException
      SerializeException
      UnknownObjectTypeException

Scripts/Settings/

      CreateStringSettings
      ParseStringSettings


Introduction page

JSON
Derived from JValue


Basic JSON object. Instance of this class contains key-value pairs, where key is always string and values can be any JValue objects. New values can be added, removed and replaced freely.


Constructors

public JSON ()Creates new empty JSON object.
public JSON (IDictionary sourceKeysAndValues)Creates new JSON object from c# dictionary.

Indexer

public JValue this [string key]Gets or sets (adds or replaces) the value specified by key.

Properties

public int CountGets the count of key/value pairs in this JSON.
public string[] KeysGets all the keys in this JSON object.

Methods

public void Add (string key, object value)Add new key/value pair to this JSON.
public void AddOrReplace (string key, object value)Add or replace key/value pair in this JSON.
public void Clear ()Remove all the key/value pairs from this JSON, leaving it empty.
public bool ContainsKey (string keyToSearch)Check whatever this JSON object contains key/value pair with specified key.
public string CreatePrettyString ()Turns this JSON object to JSON formatted, but easily human readable string.
public string CreateString ()Turns this JSON object to single JSON formatted string that can be easily stored or sent to another system.
public string CreateString (CreateStringSettings settings)Turns this JSON object to single JSON formatted string using specified settings.
public override bool Equals (object anotherObject)Test if another object equals to this object.
public JValue Get (string key)Gets value specified by key.
public bool GetBool (string key)Gets c# bool value specified by key.
public float GetFloat (string key)Gets floating point number specified by key.
public int GetInt (string key)Gets integer number specified by key.
public JArray GetJArray (string key)Gets JArray specified by key.
public JNumber GetJNumber (string key)Gets JNumber value specified by key.
public JSON GetJSON (string key)Gets JSON value specified by key.
public string GetString (string key)Gets string value specified by key.
public bool IsJNull (string key)Check if value specified by key is JNull.
public bool IsProtected ()Check whatever this JSON is protected.
public void Remove (string key)Remove value specified by key.
public void Replace (string key, object value)Replace existing key/value pair in this JSON.
public void SetProtected ()Sets this JSON and all its childen protected (read only).

Static Methods

public static JSON ParseString (string jsonObjectAsSingleString)Turns JSON formatted string to new JSON object.
public static JSON ParseString (string jsonObjectAsSingleString, ParseStringSettings parseStringSettings)Turns JSON formatted string to new JSON object, using specified settings.
public static JSON[] ParseStringToMultiple (string multipleJsonObjectsAsSingleString)Turns single string to multiple new JSON objects.
public static JSON[] ParseStringToMultiple (string multipleJsonObjectsAsSingleString, ParseStringSettings parseStringSettings)Turns single string to multiple new JSON objects, using specified settings.

Constructors

public JSON ()

Creates new empty JSON object.


public JSON (IDictionary sourceKeysAndValues)

Creates new JSON object from c# dictionary.

ParameterssourceKeysAndValuesAll the keys and values to be added to this JSON. Keys have to be strings and values have to be either JValue, or any basic c# object that can be changed to JValue.

ExceptionsJArgumentExceptionIf any key in dictionary is not string.
 JArgumentNullExceptionIf parameter is null.
 UnknownObjectTypeExceptionIf any value in dictionary is unsupported type.


Indexer

public JValue this [string key]

Gets or sets (adds or replaces) the value specified by key.

ParameterskeyKey of the value to get or set, can not be null.

ValueAny JValue object, can not be null but can be JNull.


Properties

public int Count

Gets the count of key/value pairs in this JSON.

ValueCount of key/value pairs.


public string[] Keys

Gets all the keys in this JSON object. You can use this to loop through all the keys in this json, for example: foreach (string key in json.Keys) {...}

Array of returned string keys is copy of internal dictionary keys of this JSON object. This means you can add or remove values from this JSON while looping through the keys. For example:
foreach (string key in json.Keys) {
if (shouldRemove(key)) {
json.Remove(key);
}
}


Methods

public void Add (string key, object value)

Add new key/value pair to this JSON. This method will prevent accidental overwriting old values with same key. If there already is key/value pair with same key, this method will throw an exception.

ParameterskeyKey of the value, can not be null.
 valueValue to add. Either any JValue, or any basic c# object that can be changed to JValue (string, bool, numbers and null).

ExceptionsJArgumentExceptionIf adding parameter value to this JSON would cause circular JSON, meaning this JSON or recursively any of its children would contain this JSON itself.
 JArgumentNullExceptionIf parameter key is null.
 JSONKeyAlreadyExistsExceptionIf parameter key already exists in this JSON.
 ProtectedExceptionIf this JSON object is set protected (read only).
 UnknownObjectTypeExceptionIf parameter value is unsupported type.


public void AddOrReplace (string key, object value)

Add or replace key/value pair in this JSON. Possible previous value with same key is replaced.

ParameterskeyKey of the value, can not be null.
 valueValue to set. Either any JValue, or any basic c# object that can be changed to JValue (string, bool, numbers and null).

ExceptionsJArgumentExceptionIf adding parameter value to this JSON would cause circular JSON, meaning this JSON or recursively any of its children would contain this JSON itself.
 JArgumentNullExceptionIf parameter key or value is null.
 ProtectedExceptionIf this JSON object is set protected (read only).
 UnknownObjectTypeExceptionIf parameter value is unsupported type.


public void Clear ()

Remove all the key/value pairs from this JSON, leaving it empty.

ExceptionsProtectedExceptionIf this JSON object is set protected (read only).


public bool ContainsKey (string keyToSearch)

Check whatever this JSON object contains key/value pair with specified key.

ParameterskeyToSearchKey to look for.

Returnstrue if key exists, false otherwise.

ExceptionsJArgumentNullExceptionIf parameter value is null.


public string CreatePrettyString ()

Turns this JSON object to JSON formatted, but easily human readable string. This output is not as tightly packed as string returned by CreateString() but contains all the same data and is still completely valid JSON.

This method is just a shortcut for doing:
CreateStringSettings createStringSettings = new CreateStringSettings();
createStringSettings.HumanReadable = true;
string output = CreateString(createStringSettings);

ReturnsThis JSON object as JSON formatted string, containing only basic ascii characters between [32..126] and line feeds.


public string CreateString ()

Turns this JSON object to single JSON formatted string that can be easily stored or sent to another system. String always starts with character '{' and ends to character '}' and contains no linefeeds.

ReturnsThis JSON object as JSON formatted string, containing only basic ascii characters between [32..126] without line feeds.


public string CreateString (CreateStringSettings settings)

Turns this JSON object to single JSON formatted string using specified settings.

ReturnsThis JSON object as JSON formatted string.


public override bool Equals (object anotherObject)

Test if another object equals to this object. Another object can't be null and it have to be instance of JSON. Two JSON objects are equal if both contains same keys and every element mapped to each key equals to each other.

Note that string representation generated using CreateString() may not have identical output from two JSON objects that still equals. This is because key-value pairs may be in different order when they are written to string.

ParametersanotherObjectAnother object that is compared to this one.

ReturnsTrue if objects are equal, false otherwise.


public JValue Get (string key)

Gets value specified by key. This method will cause exception if key/value pair doesn't exist. Returned value may be JSON, JString, JNumber, JBoolean, JArray or JNull.

ParameterskeyKey of the value to get.

ReturnsValue mapped to key. Can't be null, but can be JNull.

ExceptionsJSONKeyNotFoundExceptionIf key doesn't exist in this JSON.


public bool GetBool (string key)

Gets c# bool value specified by key. This method will cause exception if key/value pair doesn't exist or value is not boolean.

ParameterskeyKey of the bool value to get.

ReturnsC# bool value.

ExceptionsJSONKeyNotFoundExceptionIf key doesn't exist in this JSON.
 JValueTypeExceptionIf value mapped to this key is not JBoolean.


public float GetFloat (string key)

Gets floating point number specified by key. This method will cause exception if key/value pair doesn't exist, value is not number or it is outside float range.

This method is for convenience. It is equal to json.GetJNumber(key).AsFloat(); If there is need to get number value from JSON in some very specific format, use GetJNumber(key) and then methods provided by JNumber class, for example json.GetJNumber(key).AsDecimal();

ParameterskeyKey of the float value to get.

ReturnsC# float value.

ExceptionsJNumberOverflowExceptionIf number stored to this JNumber doesn't fit in float.
 JSONKeyNotFoundExceptionIf key doesn't exist in this JSON.
 JValueNullExceptionIf value mapped to this key is null.
 JValueTypeExceptionIf value mapped to this key is not JNumber.


public int GetInt (string key)

Gets integer number specified by key. This method will cause exception if key/value pair doesn't exist, value is not number or it is outside int range.

This method is for convenience. It is equal to json.GetJNumber(key).AsInt(); If there is need to get number value from JSON in some very specific format, use GetJNumber(key) and then methods provided by JNumber class, for example json.GetJNumber(key).AsULong();

ParameterskeyKey of the int value to get.

ReturnsC# int value.

ExceptionsJNumberFormatExceptionIf number stored to this JNumber is floating point number.
 JNumberOverflowExceptionIf number stored to this JNumber doesn't fit in int range.
 JSONKeyNotFoundExceptionIf key doesn't exist in this JSON.
 JValueNullExceptionIf value mapped to this key is null.
 JValueTypeExceptionIf value mapped to this key is not JNumber.


public JArray GetJArray (string key)

Gets JArray specified by key. This method will cause exception if key/value pair doesn't exist or value is anything else than JArray or JNull.

ParameterskeyKey of the array to get.

ReturnsJArray object or null if key was mapped to JNull.

ExceptionsJSONKeyNotFoundExceptionIf key doesn't exist in this JSON.
 JValueNullExceptionIf value mapped to this key is JNull.
 JValueTypeExceptionIf value mapped to this key is not JArray.


public JNumber GetJNumber (string key)

Gets JNumber value specified by key. This method will cause exception if key/value pair doesn't exist or value is anything else than JNumber or JNull.

ParameterskeyKey of the JNumber value to get.

ReturnsJNumber value or null if key was mapped to JNull.

ExceptionsJSONKeyNotFoundExceptionIf key doesn't exist in this JSON.
 JValueTypeExceptionIf value mapped to this key is not JNumber or null.


public JSON GetJSON (string key)

Gets JSON value specified by key. This method will cause exception if key/value pair doesn't exist or value is anything else than JSON or JNull.

ParameterskeyKey of the JSON value to get.

ReturnsJSON value or null if key was mapped to JNull.

ExceptionsJSONKeyNotFoundExceptionIf key doesn't exist in this JSON.
 JValueTypeExceptionIf value mapped to this key is not JSON or JNull.


public string GetString (string key)

Gets string value specified by key. This method will cause exception if key/value pair doesn't exist or value is anything else than JString or JNull.

ParameterskeyKey of the string value to get.

ReturnsC# string or null if key was mapped to JNull.

ExceptionsJSONKeyNotFoundExceptionIf key doesn't exist in this JSON.
 JValueTypeExceptionIf value mapped to this key is not JString of JNull.


public bool IsJNull (string key)

Check if value specified by key is JNull. This method throws exception if key doesn't exist.

ParameterskeyKey of the value to test.

Returnstrue if value exists and it is JNull, false otherwise.

ExceptionsJSONKeyNotFoundExceptionIf key doesn't exist in this JSON.


public bool IsProtected ()

Check whatever this JSON is protected. If it is, it also means that all its childen are protected, but nothing can be assumed of parents of this object.

Returnstrue if this object is protected, false otherwise


public void Remove (string key)

Remove value specified by key. This method throws exception if key doesn't exist.

ParameterskeyKey of the value to remove.

ExceptionsJArgumentNullExceptionIf parameter key is null.
 JSONKeyNotFoundExceptionIf parameter key doesn't exist in this JSON.
 ProtectedExceptionIf this JSON object is set protected (read only).


public void Replace (string key, object value)

Replace existing key/value pair in this JSON. If there isn't key/value pair with same key, this method will throw an exception.

ParameterskeyKey of the value, can not be null.
 valueValue to set. Either any JValue, or any basic c# object that can be changed to JValue (string, bool, numbers and null).

ExceptionsJArgumentExceptionIf adding parameter value to this JSON would cause circular JSON, meaning this JSON or recursively any of its children would contain this JSON itself.
 JArgumentNullExceptionIf parameter key or value is null.
 JSONKeyNotFoundExceptionIf parameter key doesn't exist in this JSON.
 ProtectedExceptionIf this JSON object is set protected (read only).
 UnknownObjectTypeExceptionIf parameter value is unsupported type.


public void SetProtected ()

Sets this JSON and all its childen protected (read only). New values can't be added and old values replaced or removed.

Typically this is called only for top level JSON. Protecetion can't be cancelled, once it is set, it will stay.


Static Methods

public static JSON ParseString (string jsonObjectAsSingleString)

Turns JSON formatted string to new JSON object.

ParametersjsonObjectAsSingleStringSource JSON string to turn to JSON object.

ReturnsNew JSON object, never null.

ExceptionsJArgumentNullExceptionIf parameter string is null.
 ParseExceptionIf input string can not be parsed to JSON.


public static JSON ParseString (string jsonObjectAsSingleString, ParseStringSettings parseStringSettings)

Turns JSON formatted string to new JSON object, using specified settings.

ParametersjsonObjectAsSingleStringSource JSON string where to read.
 parseStringSettingsSettings to be used when parsing the string.

ReturnsNew JSON object, never null.

ExceptionsJArgumentNullExceptionIf parameter string or settings object is null.
 ParseExceptionIf input string can not be parsed to JSON.


public static JSON[] ParseStringToMultiple (string multipleJsonObjectsAsSingleString)

Turns single string to multiple new JSON objects. Source string may contain any amount of JSON objects, including zero.

Acceptable input string are for example:
'' (empty string, returns JSON array with length of 0)
'{"hello":"world"}' (returns JSON array with length of 1, normal ParseString method could be used to this one too)
'{}{} {}' (returns JSON array of length 3, all JSONs in array are empty)

ParametersmultipleJsonObjectsAsSingleStringSource string where to read JSON objects.

ReturnsArray of JSON objects. Array may be also empty or contain just one item. Returned value is never null.

ExceptionsJArgumentNullExceptionIf parameter string object is null.
 ParseExceptionIf input string can not be parsed to JSONs.


public static JSON[] ParseStringToMultiple (string multipleJsonObjectsAsSingleString, ParseStringSettings parseStringSettings)

Turns single string to multiple new JSON objects, using specified settings. Source string may contain any amount of JSON objects, including zero.

ParametersmultipleJsonObjectsAsSingleStringSource string where to read JSON objects.
 parseStringSettingsSettings to be used when parsing the string.

ReturnsArray of JSON objects. Array may be also empty or contain just one item. Returned value is never null.

ExceptionsJArgumentNullExceptionIf parameter string or settings object is null.
 ParseExceptionIf input string can not be parsed to JSONs.