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.
Serialize object to JArray object, using specific settings.
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. Note that values in dictionary need to be basic c# objects like string, booleans, numbers, or another lists or dictionaries. To turn other classes to JSON object, or for more flexible options, consider using static JArray.Serialize() method.
Parameters
sourceValues
Source values. Each element have to be either JValue, or any basic c# object that can be changed to JValue.
Exceptions
JArgumentException
If any exceptions occurs when trying to turn parameter list to new JArray object.
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.
Value
Array length.
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.
Returns
Array of bools.
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.
Returns
Array of doubles.
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.
Returns
Array of floats.
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 List
Gets the whole JArray object as system list. This is recursive, so if this list contains other lists or JSON objects, those will be also changed to system objects.
Returns
List that doesn't contain any TotalJSON objects on any level.
public long[] AsLongArray ()
Get this array as long array. All the values in this array must be numbers inside long range.
Returns
Array of longs.
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 ']'
Note that for large JArray objects output may be also very long. For debugging purposes, consider also .
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.
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.
Returns
C# 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.
Returns
C# 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.
Returns
C# 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.
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.
public override string ToString ()
Returns compact information of this JArray object as string, for debug purposes.
When you want to get all content of this JArray object in JSON formatted string, use .
Returns
Single string with information of this JArray object.
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.