public class JSONArray
extends java.lang.Object
get and opt
methods for accessing the values by index, and put methods for
adding or replacing values. The values can be any of these types:
Boolean, JSONArray, JSONObject,
Number, String, or the
JSONObject.NULL object.
The constructor can convert a JSON text into a Java object. The
toString method converts to JSON text.
A get method returns a value if one can be found, and throws an
exception if one cannot be found. An opt method returns a
default value instead of throwing an exception, and so is useful for
obtaining optional values.
The generic get() and opt() methods return an
object which you can cast or query for type. There are also typed
get and opt methods that do type checking and type
coercion for you.
The texts produced by the toString methods strictly conform to
JSON syntax rules. The constructors are more forgiving in the texts they will
accept:
, (comma) may appear just
before the closing bracket.null value will be inserted when there is ,
(comma) elision.' (single
quote).{ } [ ] / \ : , = ; # and if they do not look like numbers and
if they are not the reserved words true, false, or
null.; (semicolon) as
well as by , (comma).| Constructor and Description |
|---|
JSONArray()
Construct an empty JSONArray.
|
JSONArray(java.util.Collection<java.lang.Object> collection)
Construct a JSONArray from a Collection.
|
JSONArray(JSONTokener x)
Construct a JSONArray from a JSONTokener.
|
JSONArray(java.lang.Object array)
Construct a JSONArray from an array
|
JSONArray(java.lang.String source)
Construct a JSONArray from a source JSON text.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addAll(JSONArray other)
Add all the elements from one JSONArray into the array this is called on.
|
java.lang.Object |
get(int index)
Get the object value associated with an index.
|
boolean |
getBoolean(int index)
Get the boolean value associated with an index.
|
double |
getDouble(int index)
Get the double value associated with an index.
|
int |
getInt(int index)
Get the int value associated with an index.
|
JSONArray |
getJSONArray(int index)
Get the JSONArray associated with an index.
|
JSONObject |
getJSONObject(int index)
Get the JSONObject associated with an index.
|
java.util.List<JSONObject> |
getJSONObjectList()
A convenience routine for use with native Java iterations.
|
java.util.List<JSONObject> |
getJSONObjectSet()
Returns the entire JSONArray as a list of JSONObjects.
|
long |
getLong(int index)
Get the long value associated with an index.
|
java.lang.String |
getString(int index)
Get the string associated with an index.
|
java.util.List<java.lang.String> |
getStringList()
A convenience routine for use with native Java iterations.
|
boolean |
isNull(int index)
Determine if the value is null.
|
java.lang.String |
join(java.lang.String separator)
Make a string from the contents of this JSONArray.
|
int |
length()
Get the number of elements in the JSONArray, included nulls.
|
java.lang.Object |
opt(int index)
Get the optional object value associated with an index.
|
boolean |
optBoolean(int index)
Get the optional boolean value associated with an index.
|
boolean |
optBoolean(int index,
boolean defaultValue)
Get the optional boolean value associated with an index.
|
double |
optDouble(int index)
Get the optional double value associated with an index.
|
double |
optDouble(int index,
double defaultValue)
Get the optional double value associated with an index.
|
int |
optInt(int index)
Get the optional int value associated with an index.
|
int |
optInt(int index,
int defaultValue)
Get the optional int value associated with an index.
|
JSONArray |
optJSONArray(int index)
Get the optional JSONArray associated with an index.
|
JSONObject |
optJSONObject(int index)
Get the optional JSONObject associated with an index.
|
long |
optLong(int index)
Get the optional long value associated with an index.
|
long |
optLong(int index,
long defaultValue)
Get the optional long value associated with an index.
|
java.lang.String |
optString(int index)
Get the optional string value associated with an index.
|
java.lang.String |
optString(int index,
java.lang.String defaultValue)
Get the optional string associated with an index.
|
JSONArray |
put(boolean value)
Append a boolean value.
|
JSONArray |
put(java.util.Collection<java.lang.Object> value)
Put a value in the JSONArray, where the value will be a
JSONArray which is produced from a Collection.
|
JSONArray |
put(double value)
Append a double value.
|
JSONArray |
put(int value)
Append an int value.
|
JSONArray |
put(int index,
boolean value)
Put or replace a boolean value in the JSONArray.
|
JSONArray |
put(int index,
java.util.Collection<java.lang.Object> value)
Put a value in the JSONArray, where the value will be a
JSONArray which is produced from a Collection.
|
JSONArray |
put(int index,
double value)
Put or replace a double value.
|
JSONArray |
put(int index,
int value)
Put or replace an int value.
|
JSONArray |
put(int index,
long value)
Put or replace a long value.
|
JSONArray |
put(int index,
java.util.Map<java.lang.String,java.lang.Object> value)
Put a value in the JSONArray, where the value will be a
JSONObject that is produced from a Map.
|
JSONArray |
put(int index,
java.lang.Object value)
Put or replace an object value in the JSONArray.
|
JSONArray |
put(long value)
Append an long value.
|
JSONArray |
put(java.util.Map<java.lang.String,java.lang.Object> value)
Put a value in the JSONArray, where the value will be a
JSONObject which is produced from a Map.
|
JSONArray |
put(java.lang.Object value)
Append an object value.
|
static JSONArray |
readFromFile(java.io.File inFile)
Construct a JSONArray object from a file.
|
java.lang.Object |
remove(int index)
Remove an index and close the hole.
|
JSONObject |
toJSONObject(JSONArray names)
Produce a JSONObject by combining a JSONArray of names with the values
of this JSONArray.
|
java.lang.String |
toString()
Make a JSON text of this JSONArray.
|
java.lang.String |
toString(int indentFactor)
Make a formatted JSON text of this JSONArray.
|
java.io.Writer |
write(java.io.Writer writer)
Write the contents of the JSONArray as JSON text to a writer.
|
java.io.Writer |
write(java.io.Writer writer,
int indentFactor,
int indent)
Write the contents of the JSONArray as JSON text to a writer with
sub elements indented by the amount specified.
|
void |
writeToFile(java.io.File outFile) |
public JSONArray()
public JSONArray(JSONTokener x) throws JSONException
x - A JSONTokenerJSONException - If there is a syntax error.public JSONArray(java.lang.String source)
throws JSONException
source - A string that begins with
[ (left bracket)
and ends with ] (right bracket).JSONException - If there is a syntax error.public JSONArray(java.util.Collection<java.lang.Object> collection)
collection - A Collection.public JSONArray(java.lang.Object array)
throws JSONException
JSONException - If not an array.public static JSONArray readFromFile(java.io.File inFile) throws java.lang.Exception
java.lang.Exceptionpublic void writeToFile(java.io.File outFile)
throws java.lang.Exception
java.lang.Exceptionpublic java.lang.Object get(int index)
throws JSONException
index - The index must be between 0 and length() - 1.JSONException - If there is no value for the index.public boolean getBoolean(int index)
throws JSONException
index - The index must be between 0 and length() - 1.JSONException - If there is no value for the index or if the
value is not convertible to boolean.public double getDouble(int index)
throws JSONException
index - The index must be between 0 and length() - 1.JSONException - If the key is not found or if the value cannot
be converted to a number.public int getInt(int index)
throws JSONException
index - The index must be between 0 and length() - 1.JSONException - If the key is not found or if the value is not a number.public JSONArray getJSONArray(int index) throws JSONException
index - The index must be between 0 and length() - 1.JSONException - If there is no value for the index. or if the
value is not a JSONArraypublic JSONObject getJSONObject(int index) throws JSONException
index - subscriptJSONException - If there is no value for the index or if the
value is not a JSONObjectpublic java.util.List<JSONObject> getJSONObjectSet() throws java.lang.Exception
java.lang.Exceptionpublic long getLong(int index)
throws JSONException
index - The index must be between 0 and length() - 1.JSONException - If the key is not found or if the value cannot
be converted to a number.public java.lang.String getString(int index)
throws JSONException
index - The index must be between 0 and length() - 1.JSONException - If there is no string value for the index.public boolean isNull(int index)
index - The index must be between 0 and length() - 1.public java.lang.String join(java.lang.String separator)
throws JSONException
separator string is inserted between each element.
Warning: This method assumes that the data structure is acyclical.separator - A string that will be inserted between the elements.JSONException - If the array contains an invalid number.public int length()
public java.lang.Object opt(int index)
index - The index must be between 0 and length() - 1.public boolean optBoolean(int index)
index - The index must be between 0 and length() - 1.public boolean optBoolean(int index,
boolean defaultValue)
index - The index must be between 0 and length() - 1.defaultValue - A boolean default.public double optDouble(int index)
index - The index must be between 0 and length() - 1.public double optDouble(int index,
double defaultValue)
index - subscriptdefaultValue - The default value.public int optInt(int index)
index - The index must be between 0 and length() - 1.public int optInt(int index,
int defaultValue)
index - The index must be between 0 and length() - 1.defaultValue - The default value.public JSONArray optJSONArray(int index)
index - subscriptpublic JSONObject optJSONObject(int index)
index - The index must be between 0 and length() - 1.public long optLong(int index)
index - The index must be between 0 and length() - 1.public long optLong(int index,
long defaultValue)
index - The index must be between 0 and length() - 1.defaultValue - The default value.public java.lang.String optString(int index)
index - The index must be between 0 and length() - 1.public java.lang.String optString(int index,
java.lang.String defaultValue)
index - The index must be between 0 and length() - 1.defaultValue - The default value.public JSONArray put(boolean value)
value - A boolean value.public JSONArray put(java.util.Collection<java.lang.Object> value)
value - A Collection value.public JSONArray put(double value) throws JSONException
value - A double value.JSONException - if the value is not finite.public JSONArray put(int value)
value - An int value.public JSONArray put(long value)
value - A long value.public JSONArray put(java.util.Map<java.lang.String,java.lang.Object> value)
value - A Map value.public JSONArray put(java.lang.Object value)
value - An object value. The value should be a
Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the
JSONObject.NULL object.public JSONArray put(int index, boolean value) throws JSONException
index - The subscript.value - A boolean value.JSONException - If the index is negative.public JSONArray put(int index, java.util.Collection<java.lang.Object> value) throws JSONException
index - The subscript.value - A Collection value.JSONException - If the index is negative or if the value is
not finite.public JSONArray put(int index, double value) throws JSONException
index - The subscript.value - A double value.JSONException - If the index is negative or if the value is
not finite.public JSONArray put(int index, int value) throws JSONException
index - The subscript.value - An int value.JSONException - If the index is negative.public JSONArray put(int index, long value) throws JSONException
index - The subscript.value - A long value.JSONException - If the index is negative.public JSONArray put(int index, java.util.Map<java.lang.String,java.lang.Object> value) throws JSONException
index - The subscript.value - The Map value.JSONException - If the index is negative or if the the value is
an invalid number.public JSONArray put(int index, java.lang.Object value) throws JSONException
index - The subscript.value - The value to put into the array. The value should be a
Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the
JSONObject.NULL object.JSONException - If the index is negative or if the the value is
an invalid number.public java.lang.Object remove(int index)
index - The index of the element to be removed.public void addAll(JSONArray other) throws JSONException
JSONExceptionpublic java.util.List<JSONObject> getJSONObjectList() throws java.lang.Exception
A convenience routine for use with native Java iterations. If the JSONArray is populated exclusively by JSONObjects, then use this method to get a List back, which can be iterated using:
for (JSONObject j : myList.getJSONObjectList()) {
...
}
Returns all the elements as JSONObject in the same order they are in the array. Does not convert data from other data types. Will throw an exception if any element is NOT a JSONObject
java.lang.Exceptionpublic java.util.List<java.lang.String> getStringList()
throws java.lang.Exception
A convenience routine for use with native Java iterations. If the JSONArray is populated exclusively by Strings, then use this method to get a List back, which can be iterated using:
for (String s : myList.getStringList()) {
...
}
Returns all the elements as Strings in the same order they are in the array. Does not convert data from other data types. Will throw an exception if any element is NOT a String
java.lang.Exceptionpublic JSONObject toJSONObject(JSONArray names) throws JSONException
Produce a JSONObject by combining a JSONArray of names with the values of this JSONArray.
names - A JSONArray containing a list of key strings. These will be
paired with the values.JSONException - If any of the names are null.public java.lang.String toString()
Make a JSON text of this JSONArray. For compactness, no unnecessary whitespace is added.
This method swallows exceptions. If it is not possible to produce a syntactically correct JSON text, any exception that occurs during the processing, then null will be returned instead.
Warning: This method assumes that the data structure is acyclical.
toString in class java.lang.Objectpublic java.lang.String toString(int indentFactor)
throws JSONException
Make a formatted JSON text of this JSONArray.
Think carefully before using this method! Do you really need a String in memory? Since JSON is used as a data transport format normally you are going to write the String out to some destination.
It is far more efficient to use the write operation
on this array directly. Think about it: you have an array of JSON
objects in memory. This method will make a copy of all that data
into a single string -- a second copy of the data in memory.
If all you are going to do is to write that string out to a file,
then use the write method to stream it directly to the file.
If you are going to send the data from a server to client browser,
the write directly to the output stream. This reduces memory usage.
Sometimes you really do need a String, so the method is provided,
but use it sparingly.
The JSON is produced indented by an indentFactor amount specified. If you specify zero indent, the output will be all on a single line. The elements are alphabetized only if a positive indent is specified.
Warning: This method assumes that the data structure is acyclical.
indentFactor - The number of spaces to add to each level of
indentation.[ (left bracket) and ending
with ] (right bracket).JSONExceptionpublic java.io.Writer write(java.io.Writer writer)
throws JSONException
Write the contents of the JSONArray as JSON text to a writer. For compactness, no whitespace is added, and members are not put in alphabetical order.
Warning: This method assumes that the data structure is acyclical.
JSONExceptionpublic java.io.Writer write(java.io.Writer writer,
int indentFactor,
int indent)
throws JSONException
Write the contents of the JSONArray as JSON text to a writer with sub elements indented by the amount specified. Array elements are written in the order that they appear in the array (that is, array order is preserved). Members of objects within the array will have the members sorted alphabetically so that a given JSON tree in memory will always produce the same output.
Warning: This method assumes that the data structure is acyclical.
indentFactor - The number of spaces to add to each level of indentation.indent - The indention of the top level.JSONException