Added in API level 1

JSONArray

open class JSONArray
kotlin.Any
   ↳ org.json.JSONArray

A dense indexed sequence of values. Values may be any mix of JSONObjects, other JSONArrays, Strings, Booleans, Integers, Longs, Doubles, null or JSONObject.NULL. Values may not be NaNs, infinities, or of any type not listed here.

JSONArray has the same type coercion behavior and optional/mandatory accessors as JSONObject. See that class' documentation for details.

Warning: this class represents null in two incompatible ways: the standard Java null reference, and the sentinel value JSONObject.NULL. In particular, get fails if the requested index holds the null reference, but succeeds if it holds JSONObject.NULL.

Instances of this class are not thread safe. Although this class is nonfinal, it was not designed for inheritance and should not be subclassed. In particular, self-use by overridable methods is not specified. See Effective Java Item 17, "Design and Document or inheritance or else prohibit it" for further information.

Summary

Public constructors

Creates a JSONArray with no values.
JSONArray(array: Any!)

Creates a new JSONArray with values from the given primitive array.
JSONArray(json: String!)

Creates a new JSONArray with values from the JSON string.

Creates a new JSONArray by copying all values from the given collection.
JSONArray(readFrom: JSONTokener!)

Creates a new JSONArray with values from the next array in the tokener.
Public methods
open Boolean
equals(other: Any?)

Indicates whether some other object is "equal to" this one.
open Any!
get(index: Int)

Returns the value at index.
open Boolean
getBoolean(index: Int)

Returns the value at index if it exists and is a boolean or can be coerced to a boolean.
open Double
getDouble(index: Int)

Returns the value at index if it exists and is a double or can be coerced to a double.
open Int
getInt(index: Int)

Returns the value at index if it exists and is an int or can be coerced to an int.
open JSONArray!
getJSONArray(index: Int)

Returns the value at index if it exists and is a JSONArray.
open JSONObject!

Returns the value at index if it exists and is a JSONObject.
open Long
getLong(index: Int)

Returns the value at index if it exists and is a long or can be coerced to a long.
open String!
getString(index: Int)

Returns the value at index if it exists, coercing it if necessary.
open Int

Returns a hash code value for the object.
open Boolean
isNull(index: Int)

Returns true if this array has no value at index, or if its value is the null reference or JSONObject.NULL.
open String!
join(separator: String!)

Returns a new string by alternating this array's values with separator.
open Int

Returns the number of values in this array.
open Any!
opt(index: Int)

Returns the value at index, or null if the array has no value at index.
open Boolean
optBoolean(index: Int)

Returns the value at index if it exists and is a boolean or can be coerced to a boolean.
open Boolean
optBoolean(index: Int, fallback: Boolean)

Returns the value at index if it exists and is a boolean or can be coerced to a boolean.
open Double
optDouble(index: Int)

Returns the value at index if it exists and is a double or can be coerced to a double.
open Double
optDouble(index: Int, fallback: Double)

Returns the value at index if it exists and is a double or can be coerced to a double.
open Int
optInt(index: Int)

Returns the value at index if it exists and is an int or can be coerced to an int.
open Int
optInt(index: Int, fallback: Int)

Returns the value at index if it exists and is an int or can be coerced to an int.
open JSONArray!
optJSONArray(index: Int)

Returns the value at index if it exists and is a JSONArray.
open JSONObject!

Returns the value at index if it exists and is a JSONObject.
open Long
optLong(index: Int)

Returns the value at index if it exists and is a long or can be coerced to a long.
open Long
optLong(index: Int, fallback: Long)

Returns the value at index if it exists and is a long or can be coerced to a long.
open String!
optString(index: Int)

Returns the value at index if it exists, coercing it if necessary.
open String!
optString(index: Int, fallback: String!)

Returns the value at index if it exists, coercing it if necessary.
open JSONArray!
put(value: Boolean)

Appends value to the end of this array.
open JSONArray!
put(value: Double)

Appends value to the end of this array.
open JSONArray!
put(value: Int)

Appends value to the end of this array.
open JSONArray!
put(index: Int, value: Boolean)

Sets the value at index to value, null padding this array to the required length if necessary.
open JSONArray!
put(index: Int, value: Double)

Sets the value at index to value, null padding this array to the required length if necessary.
open JSONArray!
put(index: Int, value: Int)

Sets the value at index to value, null padding this array to the required length if necessary.
open JSONArray!
put(index: Int, value: Any!)

Sets the value at index to value, null padding this array to the required length if necessary.
open JSONArray!
put(index: Int, value: Long)

Sets the value at index to value, null padding this array to the required length if necessary.
open JSONArray!
put(value: Any!)

Appends value to the end of this array.
open JSONArray!
put(value: Long)

Appends value to the end of this array.
open Any!
remove(index: Int)

Removes and returns the value at index, or null if the array has no value at index.
open JSONObject!

Returns a new object whose values are the values in this array, and whose names are the values in names.
open String

Encodes this array as a compact JSON string, such as: 

[94043,90210]

open String!
toString(indentSpaces: Int)

Encodes this array as a human readable JSON string for debugging, such as: 

[
      94043,
      90210
  ]

Public constructors

JSONArray

Added in API level 1
JSONArray()

Creates a JSONArray with no values.

JSONArray

Added in API level 19
JSONArray(array: Any!)

Creates a new JSONArray with values from the given primitive array.

JSONArray

Added in API level 1
JSONArray(json: String!)

Creates a new JSONArray with values from the JSON string.

Parameters
json String!: a JSON-encoded string containing an array.
Exceptions
org.json.JSONException if the parse fails or doesn't yield a JSONArray.

JSONArray

Added in API level 1
JSONArray(copyFrom: MutableCollection<Any?>!)

Creates a new JSONArray by copying all values from the given collection.

Parameters
copyFrom MutableCollection<Any?>!: a collection whose values are of supported types. Unsupported values are not permitted and will yield an array in an inconsistent state.

JSONArray

Added in API level 1
JSONArray(readFrom: JSONTokener!)

Creates a new JSONArray with values from the next array in the tokener.

Parameters
readFrom JSONTokener!: a tokener whose nextValue() method will yield a JSONArray.
Exceptions
org.json.JSONException if the parse fails or doesn't yield a JSONArray.

Public methods

equals

Added in API level 1
open fun equals(other: Any?): Boolean

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
obj the reference object with which to compare.
Return
Boolean true if this object is the same as the obj argument; false otherwise.

get

Added in API level 1
open fun get(index: Int): Any!

Returns the value at index.

Exceptions
org.json.JSONException if this array has no value at index, or if that value is the null reference. This method returns normally if the value is JSONObject#NULL.

getBoolean

Added in API level 1
open fun getBoolean(index: Int): Boolean

Returns the value at index if it exists and is a boolean or can be coerced to a boolean.

Exceptions
org.json.JSONException if the value at index doesn't exist or cannot be coerced to a boolean.

getDouble

Added in API level 1
open fun getDouble(index: Int): Double

Returns the value at index if it exists and is a double or can be coerced to a double.

Exceptions
org.json.JSONException if the value at index doesn't exist or cannot be coerced to a double.

getInt

Added in API level 1
open fun getInt(index: Int): Int

Returns the value at index if it exists and is an int or can be coerced to an int.

Exceptions
org.json.JSONException if the value at index doesn't exist or cannot be coerced to a int.

getJSONArray

Added in API level 1
open fun getJSONArray(index: Int): JSONArray!

Returns the value at index if it exists and is a JSONArray.

Exceptions
org.json.JSONException if the value doesn't exist or is not a JSONArray.

getJSONObject

Added in API level 1
open fun getJSONObject(index: Int): JSONObject!

Returns the value at index if it exists and is a JSONObject.

Exceptions
org.json.JSONException if the value doesn't exist or is not a JSONObject.

getLong

Added in API level 1
open fun getLong(index: Int): Long

Returns the value at index if it exists and is a long or can be coerced to a long.

Exceptions
org.json.JSONException if the value at index doesn't exist or cannot be coerced to a long.

getString

Added in API level 1
open fun getString(index: Int): String!

Returns the value at index if it exists, coercing it if necessary.

Exceptions
org.json.JSONException if no such value exists.

hashCode

Added in API level 1
open fun hashCode(): Int

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Return
Int a hash code value for this object.

isNull

Added in API level 1
open fun isNull(index: Int): Boolean

Returns true if this array has no value at index, or if its value is the null reference or JSONObject.NULL.

join

Added in API level 1
open fun join(separator: String!): String!

Returns a new string by alternating this array's values with separator. This array's string values are quoted and have their special characters escaped. For example, the array containing the strings '12" pizza', 'taco' and 'soda' joined on '+' returns this: 

"12\" pizza"+"taco"+"soda"

length

Added in API level 1
open fun length(): Int

Returns the number of values in this array.

opt

Added in API level 1
open fun opt(index: Int): Any!

Returns the value at index, or null if the array has no value at index.

optBoolean

Added in API level 1
open fun optBoolean(index: Int): Boolean

Returns the value at index if it exists and is a boolean or can be coerced to a boolean. Returns false otherwise.

optBoolean

Added in API level 1
open fun optBoolean(
    index: Int, 
    fallback: Boolean
): Boolean

Returns the value at index if it exists and is a boolean or can be coerced to a boolean. Returns fallback otherwise.

optDouble

Added in API level 1
open fun optDouble(index: Int): Double

Returns the value at index if it exists and is a double or can be coerced to a double. Returns NaN otherwise.

optDouble

Added in API level 1
open fun optDouble(
    index: Int, 
    fallback: Double
): Double

Returns the value at index if it exists and is a double or can be coerced to a double. Returns fallback otherwise.

optInt

Added in API level 1
open fun optInt(index: Int): Int

Returns the value at index if it exists and is an int or can be coerced to an int. Returns 0 otherwise.

optInt

Added in API level 1
open fun optInt(
    index: Int, 
    fallback: Int
): Int

Returns the value at index if it exists and is an int or can be coerced to an int. Returns fallback otherwise.

optJSONArray

Added in API level 1
open fun optJSONArray(index: Int): JSONArray!

Returns the value at index if it exists and is a JSONArray. Returns null otherwise.

optJSONObject

Added in API level 1
open fun optJSONObject(index: Int): JSONObject!

Returns the value at index if it exists and is a JSONObject. Returns null otherwise.

optLong

Added in API level 1
open fun optLong(index: Int): Long

Returns the value at index if it exists and is a long or can be coerced to a long. Returns 0 otherwise.

optLong

Added in API level 1
open fun optLong(
    index: Int, 
    fallback: Long
): Long

Returns the value at index if it exists and is a long or can be coerced to a long. Returns fallback otherwise.

optString

Added in API level 1
open fun optString(index: Int): String!

Returns the value at index if it exists, coercing it if necessary. Returns the empty string if no such value exists.

optString

Added in API level 1
open fun optString(
    index: Int, 
    fallback: String!
): String!

Returns the value at index if it exists, coercing it if necessary. Returns fallback if no such value exists.

put

Added in API level 1
open fun put(value: Boolean): JSONArray!

Appends value to the end of this array.

Return
JSONArray! this array.

put

Added in API level 1
open fun put(value: Double): JSONArray!

Appends value to the end of this array.

Parameters
value Double: a finite value. May not be NaNs or infinities.
Return
JSONArray! this array.

put

Added in API level 1
open fun put(value: Int): JSONArray!

Appends value to the end of this array.

Return
JSONArray! this array.

put

Added in API level 1
open fun put(
    index: Int, 
    value: Boolean
): JSONArray!

Sets the value at index to value, null padding this array to the required length if necessary. If a value already exists at index, it will be replaced.

Return
JSONArray! this array.

put

Added in API level 1
open fun put(
    index: Int, 
    value: Double
): JSONArray!

Sets the value at index to value, null padding this array to the required length if necessary. If a value already exists at index, it will be replaced.

Parameters
value Double: a finite value. May not be NaNs or infinities.
Return
JSONArray! this array.

put

Added in API level 1
open fun put(
    index: Int, 
    value: Int
): JSONArray!

Sets the value at index to value, null padding this array to the required length if necessary. If a value already exists at index, it will be replaced.

Return
JSONArray! this array.

put

Added in API level 1
open fun put(
    index: Int, 
    value: Any!
): JSONArray!

Sets the value at index to value, null padding this array to the required length if necessary. If a value already exists at index, it will be replaced.

Parameters
value Any!: a JSONObject, JSONArray, String, Boolean, Integer, Long, Double, JSONObject.NULL, or null. May not be NaNs or infinities.
Return
JSONArray! this array.

put

Added in API level 1
open fun put(
    index: Int, 
    value: Long
): JSONArray!

Sets the value at index to value, null padding this array to the required length if necessary. If a value already exists at index, it will be replaced.

Return
JSONArray! this array.

put

Added in API level 1
open fun put(value: Any!): JSONArray!

Appends value to the end of this array.

Parameters
value Any!: a JSONObject, JSONArray, String, Boolean, Integer, Long, Double, JSONObject.NULL, or null. May not be NaNs or infinities. Unsupported values are not permitted and will cause the array to be in an inconsistent state.
Return
JSONArray! this array.

put

Added in API level 1
open fun put(value: Long): JSONArray!

Appends value to the end of this array.

Return
JSONArray! this array.

remove

Added in API level 19
open fun remove(index: Int): Any!

Removes and returns the value at index, or null if the array has no value at index.

toJSONObject

Added in API level 1
open fun toJSONObject(names: JSONArray!): JSONObject!

Returns a new object whose values are the values in this array, and whose names are the values in names. Names and values are paired up by index from 0 through to the shorter array's length. Names that are not strings will be coerced to strings. This method returns null if either array is empty.

toString

Added in API level 1
open fun toString(): String

Encodes this array as a compact JSON string, such as: 

[94043,90210]

Return
String a string representation of the object.

toString

Added in API level 1
open fun toString(indentSpaces: Int): String!

Encodes this array as a human readable JSON string for debugging, such as: 

[
      94043,
      90210
  ]

Parameters
indentSpaces Int: the number of spaces to indent for each level of nesting.