JArray
Derived from
JValue
JSON array that may contain any number of JValue objects, including zero (empty array). Objects in array stay in order they are added in to the array. New values can be added, removed and replaced freely.
Constructors
Indexer
public JValue this [int index] | Gets or sets (replaces) the value specified by index. |
Properties
public int Length | Gets the length of this array. | public JValue[] Values | Gets all the values in this JArray object as system array. |
Methods
Static Methods
Constructors
public JArray () Creates a new empty instance of JArray.
public JArray (IList sourceValues) Creates new JArray object from system list or array of objects. Parameters | sourceValues | Source values. Each element have to be either JValue, or any basic c# object that can be changed to JValue. |
Exceptions | JArgumentNullException | If parameter is null. | | UnknownObjectTypeException | If any value in parameter array/list is unsupported type. |
Indexer
public JValue this [int index] Gets or sets (replaces) the value specified by index. Parameters | index | Index of the value to get or set. |
Value | Any JValue object, can not be null but can be JNull. |
Properties
public int Length Gets the length of this array.
public JValue[] Values Gets all the values in this JArray object as system array. You can use this to loop through all the values in this JArray, for example: foreach (JValue value in jarray.Values) {...}
Array of returned values is shallow copy of internal array of this JArray object. This means you can add or remove values from this JArray while looping through the values. For example, removing all the number elements from the JArray: foreach (JValue value in jarray.Values) { if (value is JNumber) { jarray.RemoveValue(value); } }
Value | All the values in this JArray object. |
Methods
public void Add (object value) Add new value to end of this array. Parameters | value | Value to add. Either any JValue, or any basic c# object that can be changed to JValue (string, bool, numbers and null). |
Exceptions | JArgumentException | If adding parameter value to this JArray would cause circular JSON, meaning this JArray or recursively any of its children would contain this JArray itself. | | ProtectedException | If this JArray object is set protected (read only). | | UnknownObjectTypeException | If parameter value is unsupported type. |
public bool[] AsBoolArray () Get this array as boolean array. All the values in this array must be booleans. Exceptions | JValueTypeException | If any value in array is other than boolean. |
public decimal[] AsDecimalArray () Get this array as decimal array. All the values in this array must be numbers inside decimal range. Returns | Array of decimals. |
Exceptions | JValueTypeException | If any value in array is other than number. |
public double[] AsDoubleArray () Get this array as double-precision float array. All the values in this array must be numbers inside double range. Exceptions | JValueTypeException | If any value in array is other than number. |
public float[] AsFloatArray () Get this array as float array. All the values in this array must be numbers inside float range. Exceptions | JValueTypeException | If any value in array is other than number. |
public int[] AsIntArray () Get this array as integer array. All the values in this array must be numbers inside integer range. Returns | Array of integers. |
Exceptions | JValueTypeException | If any value in array is other than number. |
public JArray[] AsJArrayArray () Get this array as arrays. All the values in this array must be other arrays or nulls. Returns | Array of JArray elements. May contains null elements, but returning array itself can not be null. |
Exceptions | JValueTypeException | If any value in array is other than array or null. |
public JSON[] AsJSONArray () Get this array as JSON array. All the values in this array must be JSON or JNull objects. Returns | Array of JSON elements. May contains null elements, but returning array itself can not be null. |
Exceptions | JValueTypeException | If any value in array is other than JSON object or null. |
public long[] AsLongArray () Get this array as long array. All the values in this array must be numbers inside long range. Exceptions | JValueTypeException | If any value in array is other than number. |
public string[] AsStringArray () Get this array as string array. All the values in this array must be strings or nulls. Returns | Array of strings. May contains null elements, but returning array itself can not be null. |
Exceptions | JValueTypeException | If any value in array is other than string or null. |
public void Clear () Remove all the values from this JArray, leaving it empty. Exceptions | ProtectedException | If this JArray object is set protected (read only). |
public bool ContainsValue (object valueToSearch) Check whatever this JArray object contains specified value. Parameters | valueToSearch | Value to look for. |
Returns | true if this JArray contains 'valueToSearch', false otherwise. |
Exceptions | UnknownObjectTypeException | If parameter value is unsupported type and therefore can not exist in this JArray. |
public string CreatePrettyString () Turns this JSON array to string 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 JArray. This method is just a shortcut for doing: CreateStringSettings createStringSettings = new CreateStringSettings(); createStringSettings.HumanReadable = true; string output = CreateString(createStringSettings);
Returns | This array as JSON formatted string, containing only basic ascii characters between [32..126], line feeds and tabs. |
public override string CreateString () Turns this JSON array to single JSON formatted string. String always starts with character '[' and ends to character ']' Returns | This array as JSON formatted string, containing only basic ascii characters between [32..126] without line feeds. |
public override string CreateString (CreateStringSettings settings) Turns this JSON array to single JSON formatted string using specified settings. String always starts with character '[' and ends to character ']' Returns | This array as JSON formatted string. |
public void DebugInEditor (string debugName) Adds this JArray 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. Parameters | debugName | Name of this object in debug window. |
public T Deserialize<T> () Deserialize this JArray to object, using default settings. Type parameters | T | Type of object that can hold all the content of this JArray. |
Returns | Object of wanted type. |
Exceptions | DeserializeException | If any exceptions occurs when trying to deserialize this JArray to object. |
public T Deserialize<T> (DeserializeSettings deserializeSettings) Deserialize this JArray to object, using specified settings. Type parameters | T | Type of object that can hold all the content of this JArray. |
Parameters | deserializeSettings | Settings used for deserialization. |
Returns | Object of wanted type. |
Exceptions | DeserializeException | If any exceptions occurs when trying to deserialize this JArray 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 JArray. Two JArray objects are equal if both contains same amount of elements and every element in same indexes equals to each other. Parameters | anotherObject | Another object that is compared to this one. |
Returns | True if objects are equal, false otherwise. |
public JValue Get (int index) Get value from specific index in this array. Parameters | index | Index of element to get. |
Returns | JValue object from index. Returned value is never null, but it can be JNull. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. |
public bool GetBool (int index) Gets C# bool value from specific index in this array. This method will cause exception if value is anything else than JBoolean. Parameters | index | Array index where to get bool value. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | JValueTypeException | If value in index is not JBoolean. |
public float GetFloat (int index) Gets floating point number from specific index in this array. 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 jArray.GetJNumber(index).AsFloat(); If there is need to get number value from JArray in some very specific format, use GetJNumber(index) and then use methods provided by JNumber class, for example jArray.GetJNumber(index).AsDecimal(); Parameters | index | Array index where to get float value. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | JNumberOverflowException | If number stored to this JNumber doesn't fit in float. | | JValueNullException | If value mapped to this key is null. | | JValueTypeException | If value in index is not JNumber. |
public int GetInt (int index) Gets integer number from specific index in this array. 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 jArray.GetJNumber(index).AsInt(); If there is need to get number value from JArray in some very specific format, use GetJNumber(index) and then methods provided by JNumber class, for example jArray.GetJNumber(index).AsULong(); Parameters | index | Array index where to get int value. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | JNumberFormatException | If number stored to this JNumber is floating point number. | | JNumberOverflowException | If number stored to this JNumber doesn't fit in int. | | JValueNullException | If value mapped to this key is null. | | JValueTypeException | If value in index is not JNumber. |
public JArray GetJArray (int index) Gets JArray value from specific index in this array. This method will cause exception if value is anything else than JArray or JNull. Parameters | index | Array index where to get JArray value. |
Returns | JArray or null if value at index is JNull. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | JValueTypeException | If value in index is not JArray or JNull. |
public JNumber GetJNumber (int index) Gets JNumber value from specific index in this array. This method will cause exception if value is anything else than JNumber or JNull. Parameters | index | Array index where to get JNumber value. |
Returns | JNumber or null if value at index is JNull. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | JValueTypeException | If value in index is not JNumber or JNull. |
public JSON GetJSON (int index) Gets JSON value from specific index in this array. This method will cause exception if value is anything else than JSON or JNull. Parameters | index | Array index where to get JSON value. |
Returns | JSON or null if value at index is JNull. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | JValueTypeException | If value in index is not JSON or JNull. |
public string GetString (int index) Gets C# string value from specific index in this array. This method will cause exception if value is anything else than JString or JNull. Parameters | index | Array index where to get string value. |
Returns | C# string or null if value at index is JNull. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | JValueTypeException | If value in index is not JString or JNull. |
public void InsertAt (int index, object value) Insert new value to specific index. Just like when using Add method, nothing is replaced and array length will be one more after this. Index may be equal to current array length, in that case this method works exactly as Add(JValue) Parameters | index | Index in array where to insert new value. | | value | Value to insert. Value can't be null but it can be JNull. |
Exceptions | JArgumentException | If adding parameter value to this JArray would cause circular JSON, meaning this JArray or recursively any of its children would contain this JArray itself. | | JArrayIndexOutOfRangeException | If parameter index is negative, or more than this JArray length. | | ProtectedException | If this JArray object is set protected (read only). | | UnknownObjectTypeException | If parameter value is unsupported type. |
public bool IsEmpty () Check whatever this JArray object is empty (length is 0). Returns | true if this array is empty, false otherwise. |
public bool IsJNull (int index) Check if value in specified index is JNull. Parameters | index | Array index to check. |
Returns | true value in index is JNull, false otherwise. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than equal to this JArray length. |
public bool IsProtected () Check whatever this JArray 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. Returns | true if this object is protected, false otherwise |
public void RemoveAt (int index) Remove value from specific index. After this array length will be one less than before. Parameters | index | Index in array where to remove the value. |
Exceptions | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | ProtectedException | If this JArray object is set protected (read only). |
public void RemoveValue (object valueToRemove) Removes first instance of value that equals to parameter value. Parameters | valueToRemove | Value to be removed. |
Exceptions | JArgumentException | If can not found any value matching the parameter. | | ProtectedException | If this JArray object is set protected (read only). | | UnknownObjectTypeException | If parameter value is unsupported type and therefore can not exist in this JArray. |
public void ReplaceAt (int index, object value) Replace value to specific index in this array. Array length won't change. This can only replace existing values and can not be used to add new values to array. Trying to set value outside array size will cause exception. Parameters | index | Index in array where value should be replaced. | | value | Value to set. Either any JValue, or any basic c# object that can be changed to JValue (string, bool, numbers and null). |
Exceptions | JArgumentException | If adding parameter value to this JArray would cause circular JSON, meaning this JArray or recursively any of its children would contain this JArray itself. | | JArrayIndexOutOfRangeException | If parameter index is negative, or more than or equal to this JArray length. | | ProtectedException | If this JArray object is set protected (read only). | | UnknownObjectTypeException | If parameter value is unsupported type. |
public void SetProtected () Sets this JArray 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.
internal bool deepContainsObject (JValue obj) Check whatever this JArray object or recursively any of child objects contains specified object. Parameters | obj | Object to look for. |
Returns | true if this exact 'obj' object exists somewhere in JSON tree hierarchy starting from this object, false otherwise. |
Static Methods
public static JArray ParseString (string jsonArrayInSingleString) Turns JSON array formatted string to new JSON array object. Parameters | jsonArrayInSingleString | Source string where to read array. |
Returns | New JSON array object. |
Exceptions | JArgumentNullException | If parameter string is null. | | ParseException | If input string can not be parsed to JArray. |
public static JArray ParseString (string jsonArrayInSingleString, string debugIDForExceptions) Turns JSON array formatted string to new JSON array object. Debug ID is added to this parse operation, which will be added to any possible exceptions that may occur during parse. This method is for convenience. This method will create new ParseStringSettings object and set value for DebugIDForExceptions, then call ParseString(string jsonArrayInSingleString, ParseStringSettings parseStringSettings) method. Parameters | jsonArrayInSingleString | Source string where to read array. | | debugIDForExceptions | ID that will be added to any possible exception message. This value have no effect to resulting JArray object. |
Returns | New JSON array object. |
Exceptions | JArgumentNullException | If parameter string is null. | | ParseException | If input string can not be parsed to JArray. |
public static JArray ParseString (string jsonArrayInSingleString, ParseStringSettings parseStringSettings) Turns JSON array formatted string to new JSON array object, using specified settings. Parameters | jsonArrayInSingleString | Source string where to read array. | | parseStringSettings | Settings to be used when parsing the string. |
Returns | New JSON array object. |
Exceptions | JArgumentNullException | If parameter string or settings object is null. | | ParseException | If input string can not be parsed to JArray. |
public static JArray Serialize (object objectToSerialize) Serialize object to new JArray object, using default settings. Parameters | objectToSerialize | Object that can be serialized to JArray such as list or system array. |
Returns | JArray object containing items from parameter object. |
Exceptions | SerializeException | If any exceptions occurs when trying to serialize object to new JArray. |
public static JArray Serialize (object objectToSerialize, SerializeSettings serializeSettings) Serialize object to JArray object, using specific settings. Parameters | objectToSerialize | Object that can be serialized to JArray such as list or system array. | | serializeSettings | Settings used for serialization. |
Returns | JArray object containing items from parameter object. |
Exceptions | SerializeException | If any exceptions occurs when trying to serialize object to new JArray. |
|