org.json.JSONArray Class Reference

List of all members.

Public Member Functions
	JSONArray ()
	JSONArray (JSONTokener x) throws JSONException
	JSONArray (String source) throws JSONException
	JSONArray (Collection collection)
	JSONArray (Object array) throws JSONException
Object	get (int index) throws JSONException
boolean	getBoolean (int index) throws JSONException
double	getDouble (int index) throws JSONException
int	getInt (int index) throws JSONException
JSONArray	getJSONArray (int index) throws JSONException
JSONObject	getJSONObject (int index) throws JSONException
long	getLong (int index) throws JSONException
String	getString (int index) throws JSONException
boolean	isNull (int index)
String	join (String separator) throws JSONException
int	length ()
Object	opt (int index)
boolean	optBoolean (int index)
boolean	optBoolean (int index, boolean defaultValue)
double	optDouble (int index)
double	optDouble (int index, double defaultValue)
int	optInt (int index)
int	optInt (int index, int defaultValue)
JSONArray	optJSONArray (int index)
JSONObject	optJSONObject (int index)
long	optLong (int index)
long	optLong (int index, long defaultValue)
String	optString (int index)
String	optString (int index, String defaultValue)
JSONArray	put (boolean value)
JSONArray	put (Collection value)
JSONArray	put (double value) throws JSONException
JSONArray	put (int value)
JSONArray	put (long value)
JSONArray	put (Map value)
JSONArray	put (Object value)
JSONArray	put (int index, boolean value) throws JSONException
JSONArray	put (int index, Collection value) throws JSONException
JSONArray	put (int index, double value) throws JSONException
JSONArray	put (int index, int value) throws JSONException
JSONArray	put (int index, long value) throws JSONException
JSONArray	put (int index, Map value) throws JSONException
JSONArray	put (int index, Object value) throws JSONException
Object	remove (int index)
JSONObject	toJSONObject (JSONArray names) throws JSONException
String	toString ()
String	toString (int indentFactor) throws JSONException
Writer	write (Writer writer) throws JSONException
Package Functions
String	toString (int indentFactor, int indent) throws JSONException

---

Detailed Description

A JSONArray is an ordered sequence of values. Its external text form is a string wrapped in square brackets with commas separating the values. The internal form is an object having 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:

• An extra , (comma) may appear just before the closing bracket.
• The null value will be inserted when there is , (comma) elision.
• Strings may be quoted with ' (single quote).
• Strings do not need to be quoted at all if they do not begin with a quote or single quote, and if they do not contain leading or trailing spaces, and if they do not contain any of these characters: { } [ ] / \ : , = ; # and if they do not look like numbers and if they are not the reserved words true, false, or null.
• Values can be separated by ; (semicolon) as well as by , (comma).
• Numbers may have the 0x- (hex) prefix.

Author:

JSON.org

Version:

2009-04-14

---

Constructor & Destructor Documentation

org.json.JSONArray.JSONArray

(

)

Construct an empty JSONArray.

org.json.JSONArray.JSONArray

(

JSONTokener

x

)

throws JSONException

Construct a JSONArray from a JSONTokener.

Parameters:

x

A JSONTokener

Exceptions:

JSONException

If there is a syntax error.

org.json.JSONArray.JSONArray

(

String

source

)

throws JSONException

Construct a JSONArray from a source JSON text.

Parameters:

source

A string that begins with [ (left bracket) and ends with ] (right bracket).

Exceptions:

JSONException

If there is a syntax error.

org.json.JSONArray.JSONArray

(

Collection

collection

)

Construct a JSONArray from a Collection.

Parameters:

collection

A Collection.

org.json.JSONArray.JSONArray

(

Object

array

)

throws JSONException

Construct a JSONArray from an array

Exceptions:

JSONException

If not an array.

---

Member Function Documentation

Object org.json.JSONArray.get

(

int

index

)

throws JSONException

Get the object value associated with an index.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

An object value.

Exceptions:

JSONException

If there is no value for the index.

boolean org.json.JSONArray.getBoolean

(

int

index

)

throws JSONException

Get the boolean value associated with an index. The string values "true" and "false" are converted to boolean.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The truth.

Exceptions:

JSONException

If there is no value for the index or if the value is not convertable to boolean.

double org.json.JSONArray.getDouble

(

int

index

)

throws JSONException

Get the double value associated with an index.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The value.

Exceptions:

JSONException

If the key is not found or if the value cannot be converted to a number.

int org.json.JSONArray.getInt

(

int

index

)

throws JSONException

Get the int value associated with an index.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The value.

Exceptions:

JSONException

If the key is not found or if the value cannot be converted to a number. if the value cannot be converted to a number.

JSONArray org.json.JSONArray.getJSONArray

(

int

index

)

throws JSONException

Get the JSONArray associated with an index.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

A JSONArray value.

Exceptions:

JSONException

If there is no value for the index. or if the value is not a JSONArray

JSONObject org.json.JSONArray.getJSONObject

(

int

index

)

throws JSONException

Get the JSONObject associated with an index.

Parameters:

index

subscript

Returns:

A JSONObject value.

Exceptions:

JSONException

If there is no value for the index or if the value is not a JSONObject

long org.json.JSONArray.getLong

(

int

index

)

throws JSONException

Get the long value associated with an index.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The value.

Exceptions:

JSONException

If the key is not found or if the value cannot be converted to a number.

String org.json.JSONArray.getString

(

int

index

)

throws JSONException

Get the string associated with an index.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

A string value.

Exceptions:

JSONException

If there is no value for the index.

boolean org.json.JSONArray.isNull

(

int

index

)

Determine if the value is null.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

true if the value at the index is null, or if there is no value.

String org.json.JSONArray.join

(

String

separator

)

throws JSONException

Make a string from the contents of this JSONArray. The separator string is inserted between each element. Warning: This method assumes that the data structure is acyclical.

Parameters:

separator

A string that will be inserted between the elements.

Returns:

a string.

Exceptions:

JSONException

If the array contains an invalid number.

int org.json.JSONArray.length

(

)

Get the number of elements in the JSONArray, included nulls.

Returns:

The length (or size).

Object org.json.JSONArray.opt

(

int

index

)

Get the optional object value associated with an index.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

An object value, or null if there is no object at that index.

boolean org.json.JSONArray.optBoolean	(	int	index,
		boolean	defaultValue
	)

Get the optional boolean value associated with an index. It returns the defaultValue if there is no value at that index or if it is not a Boolean or the String "true" or "false" (case insensitive).

Parameters:

	index	The index must be between 0 and length() - 1.
	defaultValue	A boolean default.

Returns:

The truth.

boolean org.json.JSONArray.optBoolean

(

int

index

)

Get the optional boolean value associated with an index. It returns false if there is no value at that index, or if the value is not Boolean.TRUE or the String "true".

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The truth.

double org.json.JSONArray.optDouble	(	int	index,
		double	defaultValue
	)

Get the optional double value associated with an index. The defaultValue is returned if there is no value for the index, or if the value is not a number and cannot be converted to a number.

Parameters:

	index	subscript
	defaultValue	The default value.

Returns:

The value.

double org.json.JSONArray.optDouble

(

int

index

)

Get the optional double value associated with an index. NaN is returned if there is no value for the index, or if the value is not a number and cannot be converted to a number.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The value.

int org.json.JSONArray.optInt	(	int	index,
		int	defaultValue
	)

Get the optional int value associated with an index. The defaultValue is returned if there is no value for the index, or if the value is not a number and cannot be converted to a number.

Parameters:

	index	The index must be between 0 and length() - 1.
	defaultValue	The default value.

Returns:

The value.

int org.json.JSONArray.optInt

(

int

index

)

Get the optional int value associated with an index. Zero is returned if there is no value for the index, or if the value is not a number and cannot be converted to a number.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The value.

JSONArray org.json.JSONArray.optJSONArray

(

int

index

)

Get the optional JSONArray associated with an index.

Parameters:

index

subscript

Returns:

A JSONArray value, or null if the index has no value, or if the value is not a JSONArray.

JSONObject org.json.JSONArray.optJSONObject

(

int

index

)

Get the optional JSONObject associated with an index. Null is returned if the key is not found, or null if the index has no value, or if the value is not a JSONObject.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

A JSONObject value.

long org.json.JSONArray.optLong	(	int	index,
		long	defaultValue
	)

Get the optional long value associated with an index. The defaultValue is returned if there is no value for the index, or if the value is not a number and cannot be converted to a number.

Parameters:

	index	The index must be between 0 and length() - 1.
	defaultValue	The default value.

Returns:

The value.

long org.json.JSONArray.optLong

(

int

index

)

Get the optional long value associated with an index. Zero is returned if there is no value for the index, or if the value is not a number and cannot be converted to a number.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

The value.

String org.json.JSONArray.optString	(	int	index,
		String	defaultValue
	)

Get the optional string associated with an index. The defaultValue is returned if the key is not found.

Parameters:

	index	The index must be between 0 and length() - 1.
	defaultValue	The default value.

Returns:

A String value.

String org.json.JSONArray.optString

(

int

index

)

Get the optional string value associated with an index. It returns an empty string if there is no value at that index. If the value is not a string and is not null, then it is coverted to a string.

Parameters:

index

The index must be between 0 and length() - 1.

Returns:

A String value.

JSONArray org.json.JSONArray.put	(	int	index,
		Object	value
	)			throws JSONException

Put or replace an object value in the JSONArray. If the index is greater than the length of the JSONArray, then null elements will be added as necessary to pad it out.

Parameters:

	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.

Returns:

this.

Exceptions:

JSONException

If the index is negative or if the the value is an invalid number.

JSONArray org.json.JSONArray.put	(	int	index,
		Map	value
	)			throws JSONException

Put a value in the JSONArray, where the value will be a JSONObject which is produced from a Map.

Parameters:

	index	The subscript.
	value	The Map value.

Returns:

this.

Exceptions:

JSONException

If the index is negative or if the the value is an invalid number.

JSONArray org.json.JSONArray.put	(	int	index,
		long	value
	)			throws JSONException

Put or replace a long value. If the index is greater than the length of the JSONArray, then null elements will be added as necessary to pad it out.

Parameters:

	index	The subscript.
	value	A long value.

Returns:

this.

Exceptions:

JSONException

If the index is negative.

JSONArray org.json.JSONArray.put	(	int	index,
		int	value
	)			throws JSONException

Put or replace an int value. If the index is greater than the length of the JSONArray, then null elements will be added as necessary to pad it out.

Parameters:

	index	The subscript.
	value	An int value.

Returns:

this.

Exceptions:

JSONException

If the index is negative.

JSONArray org.json.JSONArray.put	(	int	index,
		double	value
	)			throws JSONException

Put or replace a double value. If the index is greater than the length of the JSONArray, then null elements will be added as necessary to pad it out.

Parameters:

	index	The subscript.
	value	A double value.

Returns:

this.

Exceptions:

JSONException

If the index is negative or if the value is not finite.

JSONArray org.json.JSONArray.put	(	int	index,
		Collection	value
	)			throws JSONException

Put a value in the JSONArray, where the value will be a JSONArray which is produced from a Collection.

Parameters:

	index	The subscript.
	value	A Collection value.

Returns:

this.

Exceptions:

JSONException

If the index is negative or if the value is not finite.

JSONArray org.json.JSONArray.put	(	int	index,
		boolean	value
	)			throws JSONException

Put or replace a boolean value in the JSONArray. If the index is greater than the length of the JSONArray, then null elements will be added as necessary to pad it out.

Parameters:

	index	The subscript.
	value	A boolean value.

Returns:

this.

Exceptions:

JSONException

If the index is negative.

JSONArray org.json.JSONArray.put

(

Object

value

)

Append an object value. This increases the array's length by one.

Parameters:

value

An object value. The value should be a Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the JSONObject.NULL object.

Returns:

this.

JSONArray org.json.JSONArray.put

(

Map

value

)

Put a value in the JSONArray, where the value will be a JSONObject which is produced from a Map.

Parameters:

value

A Map value.

Returns:

this.

JSONArray org.json.JSONArray.put

(

long

value

)

Append an long value. This increases the array's length by one.

Parameters:

value

A long value.

Returns:

this.

JSONArray org.json.JSONArray.put

(

int

value

)

Append an int value. This increases the array's length by one.

Parameters:

value

An int value.

Returns:

this.

JSONArray org.json.JSONArray.put

(

double

value

)

throws JSONException

Append a double value. This increases the array's length by one.

Parameters:

value

A double value.

Exceptions:

JSONException

if the value is not finite.

Returns:

this.

JSONArray org.json.JSONArray.put

(

Collection

value

)

Put a value in the JSONArray, where the value will be a JSONArray which is produced from a Collection.

Parameters:

value

A Collection value.

Returns:

this.

JSONArray org.json.JSONArray.put

(

boolean

value

)

Append a boolean value. This increases the array's length by one.

Parameters:

value

A boolean value.

Returns:

this.

Object org.json.JSONArray.remove

(

int

index

)

Remove an index and close the hole.

Parameters:

index

The index of the element to be removed.

Returns:

The value that was associated with the index, or null if there was no value.

JSONObject org.json.JSONArray.toJSONObject

(

JSONArray

names

)

throws JSONException

Produce a JSONObject by combining a JSONArray of names with the values of this JSONArray.

Parameters:

names

A JSONArray containing a list of key strings. These will be paired with the values.

Returns:

A JSONObject, or null if there are no names or if this JSONArray has no values.

Exceptions:

JSONException

If any of the names are null.

String org.json.JSONArray.toString	(	int	indentFactor,
		int	indent
	)			throws JSONException [package]

Make a prettyprinted JSON text of this JSONArray. Warning: This method assumes that the data structure is acyclical.

Parameters:

	indentFactor	The number of spaces to add to each level of indentation.
	indent	The indention of the top level.

Returns:

a printable, displayable, transmittable representation of the array.

Exceptions:

JSONException

String org.json.JSONArray.toString

(

int

indentFactor

)

throws JSONException

Make a prettyprinted JSON text of this JSONArray. Warning: This method assumes that the data structure is acyclical.

Parameters:

indentFactor

The number of spaces to add to each level of indentation.

Returns:

a printable, displayable, transmittable representation of the object, beginning with [ (left bracket) and ending with ] (right bracket).

Exceptions:

JSONException

String org.json.JSONArray.toString

(

)

Make a JSON text of this JSONArray. For compactness, no unnecessary whitespace is added. If it is not possible to produce a syntactically correct JSON text then null will be returned instead. This could occur if the array contains an invalid number.

Warning: This method assumes that the data structure is acyclical.

Returns:

a printable, displayable, transmittable representation of the array.

Writer org.json.JSONArray.write

(

Writer

writer

)

throws JSONException

Write the contents of the JSONArray as JSON text to a writer. For compactness, no whitespace is added.

Warning: This method assumes that the data structure is acyclical.

Returns:

The writer.

Exceptions:

JSONException