Public classes


Scripts/

   JArray
   JBoolean
   JNull
   JNumber
   JSON
   JString
   JValue

Scripts/Attributes/

      ExcludeFromJSONSerializeAttribute
      IncludeToJSONSerializeAttribute

Scripts/Exceptions/

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

Scripts/Settings/

      CreateStringSettings
      DeserializeSettings
      ParseStringSettings
      SerializeSettings


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 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 Dictionary AsDictionary ()Gets the whole JSON object as system dictionary.
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 override string CreateString ()Turns this JSON object to single JSON formatted string that can be easily stored or sent to another system.
public override string CreateString (CreateStringSettings settings)Turns this JSON object to single JSON formatted string using specified settings.
public void DebugInEditor (string debugName)Adds this JSON object to editor debug window so content of JSON object can be followed in Unity editor when application is running.
public T Deserialize<T> ()Deserialize this JSON to object, using default settings.
public T Deserialize<T> (DeserializeSettings deserializeSettings)Deserialize this JSON to object, 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 (read only).
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 SetDebugIDForExceptions (string debugIdForExceptions)Sets debug ID for this JSON object.
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, string debugIDForExceptions)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.
public static JSON Serialize (object objectToSerialize)Serialize object to JSON object, using default settings.
public static JSON Serialize (object objectToSerialize, SerializeSettings serializeSettings)Serialize object to JSON object, using specific settings.

Constructors

public JSON ()

Creates new empty JSON object.


public JSON (IDictionary sourceKeysAndValues)

Creates new JSON object from c# dictionary. Note that values in dictionary need to be basic c# objects like string, booleans, numbers, or another dictionaries or lists. To turn other classes to JSON object, or for more flexible options, consider using static JSON.Serialize() method.

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 exceptions occurs when trying to turn parameter dictionary to new JSON object.
 JArgumentNullExceptionIf parameter is null.
 UnknownObjectTypeExceptionIf any value in dictionary is unsupported type.


Indexer

public JValue this [string key]

Gets or sets the value specified by key. Setting value can do both adding new value or replacing old one with same 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 Dictionary AsDictionary ()

Gets the whole JSON object as system dictionary. This is recursive, so if this JSON contains other JSON objects or lists, those will be also changed to system objects.

ReturnsDictionary that doesn't contain any TotalJSON objects on any level.


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], line feeds and tabs.


public override 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 override string CreateString (CreateStringSettings settings)

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

ReturnsThis JSON object as JSON formatted string.


public void DebugInEditor (string debugName)

Adds this JSON object to editor debug window so content of JSON object can be followed in Unity editor when application is running. Choose "Window" -> "Total JSON" -> "JSON Runtime Debug" from Unity editor menu top open this window.

Calling this method outside Unity editor doesn't do anything.

ParametersdebugNameName of this object in debug window.


public T Deserialize<T> ()

Deserialize this JSON to object, using default settings.

Typically this is used as opposite operation for Serialize. After Serialize is used to turn object to JSON, this method can be used to turn JSON back to object of same type.

Type parametersTType of object that can hold all the content of this JSON.

ReturnsObject of wanted type.

ExceptionsDeserializeExceptionIf any exceptions occurs when trying to deserialize this JSON to object.


public T Deserialize<T> (DeserializeSettings deserializeSettings)

Deserialize this JSON to object, using specified settings.

Typically this is used as opposite operation for Serialize. After Serialize is used to turn object to JSON, this method can be used to turn JSON back to object of same type.

Type parametersTType of object that can hold all the content of this JSON.

ParametersdeserializeSettingsSpecified settings used for deserialization.

ReturnsObject of wanted type.

ExceptionsDeserializeExceptionIf any exceptions occurs when trying to deserialize this JSON to object.


public override bool Equals (object anotherObject)

Test if another object equals to this object. Always returns false if parameter object is null or it is not 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 (read only). 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 SetDebugIDForExceptions (string debugIdForExceptions)

Sets debug ID for this JSON object. This ID is added to any possible exception messages that may occur when handling this JSON.

This is typically useful in production builds where only exception message is logged but full stacktrace may not be available. Settings this debug ID helps to identify which JSON object caused exception.

Note that if this JSON object was parsed from string and ParseStringSettings.DebugIDForExceptions for already set during parse, that same ID is copied to this JSON object.

ParametersdebugIdForExceptionsDebug ID to add to exception messages. Setting this null will disable this feature.


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, string debugIDForExceptions)

Turns JSON formatted string to new JSON object. Debug ID is added to any possible exceptions that may occur during parse or when handling resulting JSON object afterwards.

This method is for convenience. This method will create new ParseStringSettings object and set value for DebugIDForExceptions, then call ParseString(string jsonObjectAsSingleString, ParseStringSettings parseStringSettings) method. See ParseStringSettings class for more information.

ParametersjsonObjectAsSingleStringSource JSON string to turn to JSON object.
 debugIDForExceptionsDebug ID that will be added to any possible exception message. This value have no effect to resulting JSON object.

ReturnsNew JSON object, never null.

ExceptionsJArgumentNullExceptionIf parameter JSON 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 JSON objects 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.


public static JSON Serialize (object objectToSerialize)

Serialize object to JSON object, using default settings.

If parameter object is class or struct, only public fields or fields marked with [SerializeField] are serialized.

ParametersobjectToSerializeObject that can be serialized to JSON without ambiguity. Typically class, struct or dictionary.

ReturnsJSON object containing fields/values from parameter object.

ExceptionsSerializeExceptionIf any exceptions occurs when trying to serialize object to new JSON.


public static JSON Serialize (object objectToSerialize, SerializeSettings serializeSettings)

Serialize object to JSON object, using specific settings.

If parameter object is class or struct, only public fields or fields marked with [SerializeField] are serialized.

ParametersobjectToSerializeObject that can be serialized to JSON without ambiguity. Typically class, struct or dictionary.
 serializeSettingsSpecified settings used for serialization.

ReturnsJSON object containing fields/values from parameter object.

ExceptionsSerializeExceptionIf any exceptions occurs when trying to serialize object to new JSON.