org.apache.tapestry5.json

## Class JSONArray

- java.lang.Object
- - org.apache.tapestry5.json.JSONCollection
  - - org.apache.tapestry5.json.JSONArray

- All Implemented Interfaces:
    Serializable, Iterable<Object>

      public final class JSONArray
      extends JSONCollection
      implements Iterable<Object>

  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.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `JSONArray()` Creates a `JSONArray` with no values.
    `JSONArray(Object... values)` Creates a new `JSONArray` with values from the given primitive array.
    `JSONArray(String json)` Creates a new `JSONArray` with values from the JSON string.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object o)`
    `static JSONArray` | `from(Iterable<?> iterable)` Create a new array, and adds all values fro the iterable to the array (using `putAll(Iterable)`.
    `Object` | `get(int index)` Returns the value at `index`.
    `boolean` | `getBoolean(int index)` Returns the value at `index` if it exists and is a boolean or can be coerced to a boolean.
    `double` | `getDouble(int index)` Returns the value at `index` if it exists and is a double or can be coerced to a double.
    `int` | `getInt(int index)` Returns the value at `index` if it exists and is an int or can be coerced to an int.
    `JSONArray` | `getJSONArray(int index)` Returns the value at `index` if it exists and is a `JSONArray`.
    `JSONObject` | `getJSONObject(int index)` Returns the value at `index` if it exists and is a `JSONObject`.
    `long` | `getLong(int index)` Returns the value at `index` if it exists and is a long or can be coerced to a long.
    `String` | `getString(int index)` Returns the value at `index` if it exists, coercing it if necessary.
    `int` | `hashCode()`
    `boolean` | `isNull(int index)` Returns true if this array has no value at `index`, or if its value is the `null` reference or `JSONObject.NULL`.
    `Iterator<Object>` | `iterator()`
    `int` | `length()`
    `JSONArray` | `put(int index, Object value)` Sets the value at `index` to `value`, null padding this array to the required length if necessary.
    `JSONArray` | `put(Object value)` Appends `value` to the end of this array.
    `JSONArray` | `putAll(Iterable<?> collection)` Puts all objects from the collection into this JSONArray, using `put(Object)`.
    `Object` | `remove(int index)` Removes and returns the value at `index`, or null if the array has no value at `index`.
    `List<Object>` | `toList()` Returns an unmodifiable list of the contents of the array.

    - ### Methods inherited from class org.apache.tapestry5.json.JSONCollection

      `prettyPrint, print, print, toCompactString, toString, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### JSONArray

          public JSONArray()

      Creates a `JSONArray` with no values.

    - #### JSONArray

          public JSONArray(String json)

      Creates a new `JSONArray` with values from the JSON string.
      Parameters:
        `json` - a JSON-encoded string containing an array.
      Throws:
        `RuntimeException` - if the parse fails or doesn't yield a `JSONArray`.

    - #### JSONArray

          public JSONArray(Object... values)

      Creates a new `JSONArray` with values from the given primitive array.
      Parameters:
        `values` - The values to use.
      Throws:
        `RuntimeException` - if any of the values are non-finite double values (i.e. NaN or infinite)

  - ### Method Detail

    - #### from

          public static JSONArray from(Iterable<?> iterable)

      Create a new array, and adds all values fro the iterable to the array (using `putAll(Iterable)`. This is implemented as a static method so as not to break the semantics of the existing `JSONArray(Object...)` constructor. Adding a constructor of type Iterable would change the meaning of `new JSONArray(new JSONArray())`.
      Parameters:
        `iterable` - collection ot value to include, or null
      Since:
        5.4

    - #### length

          public int length()

      Returns:
        Returns the number of values in this array.

    - #### put

          public JSONArray put(Object value)

      Appends `value` to the end of this array.
      Parameters:
        `value` - a `JSONObject`, `JSONArray`, String, Boolean, Integer, Long, Double, or `JSONObject.NULL`}. May not be `NaNs` or `infinities`. Unsupported values are not permitted and will cause the array to be in an inconsistent state.
      Returns:
        this array.

    - #### put

          public JSONArray put(int index,
                               Object value)

      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:
        `index` - Where to put the value.
        `value` - a `JSONObject`, `JSONArray`, String, Boolean, Integer, Long, Double, `JSONObject.NULL`, or `null`. May not be `NaNs` or `infinities`.
      Returns:
        this array.
      Throws:
        `RuntimeException` - If the value cannot be represented as a finite double value.

    - #### isNull

          public boolean isNull(int index)

      Returns true if this array has no value at `index`, or if its value is the `null` reference or `JSONObject.NULL`.
      Parameters:
        `index` - Which value to check.
      Returns:
        true if the value is null.

    - #### get

          public Object get(int index)

      Returns the value at `index`.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - 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`.

    - #### remove

          public Object remove(int index)

      Removes and returns the value at `index`, or null if the array has no value at `index`.
      Parameters:
        `index` - Which value to remove.
      Returns:
        The value previously at the specified location.

    - #### getBoolean

          public boolean getBoolean(int index)

      Returns the value at `index` if it exists and is a boolean or can be coerced to a boolean.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - if the value at `index` doesn't exist or cannot be coerced to a boolean.

    - #### getDouble

          public double getDouble(int index)

      Returns the value at `index` if it exists and is a double or can be coerced to a double.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - if the value at `index` doesn't exist or cannot be coerced to a double.

    - #### getInt

          public int getInt(int index)

      Returns the value at `index` if it exists and is an int or can be coerced to an int.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - if the value at `index` doesn't exist or cannot be coerced to a int.

    - #### getLong

          public long getLong(int index)

      Returns the value at `index` if it exists and is a long or can be coerced to a long.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - if the value at `index` doesn't exist or cannot be coerced to a long.

    - #### getString

          public String getString(int index)

      Returns the value at `index` if it exists, coercing it if necessary.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - if no such value exists.

    - #### getJSONArray

          public JSONArray getJSONArray(int index)

      Returns the value at `index` if it exists and is a `JSONArray`.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - if the value doesn't exist or is not a `JSONArray`.

    - #### getJSONObject

          public JSONObject getJSONObject(int index)

      Returns the value at `index` if it exists and is a `JSONObject`.
      Parameters:
        `index` - Which value to get.
      Returns:
        the value at the specified location.
      Throws:
        `RuntimeException` - if the value doesn't exist or is not a `JSONObject`.

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### putAll

          public JSONArray putAll(Iterable<?> collection)

      Puts all objects from the collection into this JSONArray, using `put(Object)`.
      Parameters:
        `collection` - List, array, JSONArray, or other iterable object, or null
      Returns:
        this JSONArray
      Since:
        5.4

    - #### toList

          public List<Object> toList()

      Returns an unmodifiable list of the contents of the array. This is a wrapper around the list's internal storage and is live (changes to the JSONArray affect the returned List).
      Returns:
        unmodifiable list of array contents
      Since:
        5.4

    - #### iterator

          public Iterator<Object> iterator()

      Specified by:
        `iterator` in interface `Iterable<Object>`

${project.version} - Copyright © 2003-2015 The Apache Software Foundation.