Class JSONArray

  • All Implemented Interfaces:
    Iterable<Object>

    public class JSONArray
    extends JSONElement
    implements Iterable<Object>
    https://json.org/ https://tools.ietf.org/html/rfc7159#section-4 Represents a JSON Array
    • Constructor Summary

      Constructors 
      Constructor Description
      JSONArray()
      construct a empty JSONArray
      JSONArray​(Object array)
      Construct a JSONArray from a typed array (int[]).
      JSONArray​(String jsonString)
      construct a JSONArray from a String
      JSONArray​(Collection<?> collection)
      Construct a JSONArray from a collection.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(Object o)  
      Object get​(int index)
      get the element at the index
      BigDecimal getBigDecimal​(int index)
      get a BigDecimal at a specified index
      BigInteger getBigInteger​(int index)
      get a BigInteger at a specified index
      boolean getBoolean​(int index)
      get a boolean at a specified index
      double getDouble​(int index)
      get a Double at a specified index
      <T extends Enum<T>>
      T
      getEnum​(Class<T> enumClass, int index)
      get a enum value based on name from a specific index
      float getFloat​(int index)
      get a Float at a specified index
      int getInt​(int index)
      get a int at a specified index
      JSONArray getJSONArray​(int index)
      get a JSONArray at a specified index
      JSONObject getJSONObject​(int index)
      get a JSONObject at a specified index
      long getLong​(int index)
      get a long at a specified index
      Number getNumber​(int index)
      get a Number at a specified index
      String getString​(int index)
      get a String at a specified index
      int hashCode()  
      boolean isEmpty()
      returns if the array is empty
      boolean isNull​(int index)
      Indicates if the index does not exist or it's contents are null
      Iterator<Object> iterator()  
      String join​(String token)
      return the array as a string delimited by a specific token
      int length()  
      Object opt​(int index)
      get the element at the index
      BigDecimal optBigDecimal​(int index, BigDecimal defaultValue)
      get a BigDecimal at a specified index, or a default value if the value does not exist or is not a BigDecimal
      BigInteger optBigInteger​(int index, BigInteger defaultValue)
      get a BigInteger at a specified index, or a default value if the value does not exist or is not a BigInteger
      boolean optBoolean​(int index)
      get a boolean at a specified index
      boolean optBoolean​(int index, boolean defaultValue)
      get a boolean at a specified index
      double optDouble​(int index)
      get a Double at a specified index
      double optDouble​(int index, double defaultValue)
      get a Double at a specified index, or a default value if the value does not exist or is not a double
      <T extends Enum<T>>
      T
      optEnum​(Class<T> enumClass, int index)  
      <T extends Enum<T>>
      T
      optEnum​(Class<T> enumClass, int index, T defaultValue)  
      float optFloat​(int index)
      get a Float at a specified index, or a NaN value if the value does not exist or is not a Float
      float optFloat​(int index, float defaultValue)
      get a Float at a specified index, or a default value if the value does not exist or is not a Float
      int optInt​(int index)
      get a int at a specified index, or 0 if the value does not exist or is not a int
      int optInt​(int index, int defaultValue)
      get a int at a specified index, or a default value if the value does not exist or is not a int
      JSONArray optJSONArray​(int index)
      get a String at a specified index, or null if the value does not exist or is not a JSONArray
      JSONObject optJSONObject​(int index)
      get a JSONObject at a specified index or null if it does not exist or is not a valid JSONObject
      long optLong​(int index)
      get a long at a specified index, or 0 if the value does not exist or is not a long
      long optLong​(int index, long defaultValue)
      get a long at a specified index, or a default value if the value does not exist or is not a long
      Number optNumber​(int index)
      get a Number at a specified index
      Number optNumber​(int index, Number defaultValue)
      get a Number at a specified index
      String optString​(int index)
      get a String at a specified index, or an empty string if the value does not exist or is not a String
      String optString​(int index, String defaultValue)
      get a String at a specified index, or a default value if the value does not exist or is not a String
      JSONArray put​(boolean bool)
      add a Boolean to the array
      JSONArray put​(double num)
      add a double to the array
      JSONArray put​(float num)
      add a float to the array
      JSONArray put​(int num)
      add a int to the array
      JSONArray put​(int index, boolean bool)
      put a boolean at a specific index
      JSONArray put​(int index, double number)
      put a double at a specific instance if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, float number)
      put a float at a specific instance if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, int number)
      put a int at a specific instance if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, long number)
      put a long at a specific instance if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, Number number)
      put a Number at a specific instance if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, Object object)
      put a object at a specific instance if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, String string)
      put a String at a specific index if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, Collection collection)
      put a JSONArray at a specific index as a Collection if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(int index, Map map)
      put a JSONObject as a map at a specific index if the index is beyond the currently length the array will be buffered with nulls
      <T extends Enum>
      JSONArray
      put​(int index, T enumValue)
      put a Enum name at a specific index as a string if the index is beyond the currently length the array will be buffered with nulls
      JSONArray put​(long num)
      add a long to the array
      JSONArray put​(Number num)
      add a Number to the array
      JSONArray put​(Object object)
      add a Object to the array Must be a valid JSON type or else it will be turned into a string
      JSONArray put​(String str)
      add a String to the array
      JSONArray put​(Collection collection)
      add a JSONArray to the array
      JSONArray put​(Map map)
      add a JSONObject to the array as a map
      JSONArray put​(JSONArray array)
      append a JSONArray as an element to the end of the array
      JSONArray put​(JSONObject object)
      append a JSONObject to the end of the array
      <T extends Enum>
      JSONArray
      put​(T enumValue)
      put a enum which will be put as the string name
      Object remove​(int index)
      Removes the element at the specified position in this array.
      boolean similar​(Object o)
      indicates if a JSONArray has the same elements as another JSONArray
      JSONObject toJSONObject​(JSONArray names)
      Produce a JSONObject by combining a JSONArray of names with the values of this JSONArray.
      List toList()
      Converts the JSONArray to a List
      String toString()
      returns the String representation of the JSONArray
      String toString​(int indent)
      returns the String representation of the JSONArray
    • Constructor Detail

      • JSONArray

        public JSONArray()
        construct a empty JSONArray
      • JSONArray

        public JSONArray​(String jsonString)
        construct a JSONArray from a String
        Parameters:
        jsonString - a JSON String
      • JSONArray

        public JSONArray​(Collection<?> collection)
        Construct a JSONArray from a collection.
        Parameters:
        collection - a collection which contains json types
      • JSONArray

        public JSONArray​(Object array)
        Construct a JSONArray from a typed array (int[]).
        Parameters:
        array - an array type which may be typed (e.g. Object[], String[], JSONObject[])
    • Method Detail

      • length

        public int length()
        Returns:
        The length of the array
      • put

        public JSONArray put​(JSONObject object)
        append a JSONObject to the end of the array
        Parameters:
        object - a JSONObject
        Returns:
        this JSONArray
      • put

        public JSONArray put​(JSONArray array)
        append a JSONArray as an element to the end of the array
        Parameters:
        array - a JSONArray
        Returns:
        this JSONArray
      • put

        public JSONArray put​(int num)
        add a int to the array
        Parameters:
        num - a int
        Returns:
        this JSONArray
      • put

        public JSONArray put​(long num)
        add a long to the array
        Parameters:
        num - a long
        Returns:
        this JSONArray
      • put

        public JSONArray put​(Number num)
        add a Number to the array
        Parameters:
        num - a Number
        Returns:
        this JSONArray
      • put

        public JSONArray put​(boolean bool)
        add a Boolean to the array
        Parameters:
        bool - a Boolean
        Returns:
        this JSONArray
      • put

        public JSONArray put​(String str)
        add a String to the array
        Parameters:
        str - a String
        Returns:
        this JSONArray
      • put

        public JSONArray put​(Map map)
        add a JSONObject to the array as a map
        Parameters:
        map - a Map which should contain String keys and JSON types for values
        Returns:
        this JSONArray
      • put

        public JSONArray put​(Collection collection)
        add a JSONArray to the array
        Parameters:
        collection - a Collection of JSON Types
        Returns:
        this JSONArray
      • put

        public <T extends EnumJSONArray put​(T enumValue)
        put a enum which will be put as the string name
        Type Parameters:
        T - a enum type
        Parameters:
        enumValue - a enum
        Returns:
        this JSONArray
      • put

        public JSONArray put​(int index,
                             long number)
                      throws JSONException
        put a long at a specific instance if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        number - a long
        Returns:
        this JSONArray
        Throws:
        JSONException
      • put

        public JSONArray put​(int index,
                             double number)
                      throws JSONException
        put a double at a specific instance if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        number - a double
        Returns:
        this JSONArray
        Throws:
        JSONException
      • put

        public JSONArray put​(int index,
                             boolean bool)
                      throws JSONException
        put a boolean at a specific index
        Parameters:
        index - the index position to put to
        bool - a bool value
        Returns:
        this JSONArray
        Throws:
        JSONException
      • put

        public JSONArray put​(int index,
                             Object object)
                      throws JSONException
        put a object at a specific instance if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        object - a long
        Returns:
        this JSONArray
        Throws:
        JSONException - if something goes wrong
      • put

        public JSONArray put​(int index,
                             float number)
                      throws JSONException
        put a float at a specific instance if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        number - a Number
        Returns:
        this JSONArray
        Throws:
        JSONException
      • put

        public JSONArray put​(int index,
                             int number)
                      throws JSONException
        put a int at a specific instance if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        number - a int
        Returns:
        this JSONArray
        Throws:
        JSONException
      • put

        public JSONArray put​(int index,
                             Number number)
        put a Number at a specific instance if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        number - a Number
        Returns:
        this JSONArray
      • put

        public JSONArray put​(int index,
                             String string)
        put a String at a specific index if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        string - a String
        Returns:
        this JSONArray
      • put

        public JSONArray put​(int index,
                             Map map)
                      throws JSONException
        put a JSONObject as a map at a specific index if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - index of the element to replace
        map - a Map of String keys and values of JSON Types
        Returns:
        this JSONArray
        Throws:
        JSONException
      • put

        public JSONArray put​(int index,
                             Collection collection)
                      throws JSONException
        put a JSONArray at a specific index as a Collection if the index is beyond the currently length the array will be buffered with nulls
        Parameters:
        index - the index position to put to
        collection - a Collection of JSON types
        Returns:
        this JSONArray
        Throws:
        JSONException
      • put

        public <T extends EnumJSONArray put​(int index,
                                              T enumValue)
        put a Enum name at a specific index as a string if the index is beyond the currently length the array will be buffered with nulls
        Type Parameters:
        T - a type of enum
        Parameters:
        index - the index position to put to
        enumValue - a enum value to put
        Returns:
        this JSONArray
      • put

        public JSONArray put​(Object object)
        add a Object to the array Must be a valid JSON type or else it will be turned into a string
        Parameters:
        object - the JSON Typed object
        Returns:
        this JSONArray
      • remove

        public Object remove​(int index)
        Removes the element at the specified position in this array. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the array.
        Parameters:
        index - index the index of the element to be removed
        Returns:
        the element previously at the specified position or null if the index did not exist.
      • getBoolean

        public boolean getBoolean​(int index)
                           throws JSONException
        get a boolean at a specified index
        Parameters:
        index - the array index position
        Returns:
        a boolean
        Throws:
        JSONException - if the element is not a boolean or index is out of bounds
      • optBoolean

        public boolean optBoolean​(int index)
        get a boolean at a specified index
        Parameters:
        index - the array index position
        Returns:
        a boolean
      • optBoolean

        public boolean optBoolean​(int index,
                                  boolean defaultValue)
        get a boolean at a specified index
        Parameters:
        index - the array index position
        defaultValue - a default value if the index position does not exist or is not a boolean
        Returns:
        a boolean
      • getJSONObject

        public JSONObject getJSONObject​(int index)
                                 throws JSONException
        get a JSONObject at a specified index
        Parameters:
        index - the array index position
        Returns:
        a JSONObject
        Throws:
        JSONException - if the element is not a JSONObject or index is out of bounds
      • optJSONObject

        public JSONObject optJSONObject​(int index)
        get a JSONObject at a specified index or null if it does not exist or is not a valid JSONObject
        Parameters:
        index - the array index position
        Returns:
        a JSONObject
      • getDouble

        public double getDouble​(int index)
                         throws JSONException
        get a Double at a specified index
        Parameters:
        index - the array index position
        Returns:
        a Double
        Throws:
        JSONException - if the element is not a Double or index is out of bounds
      • optDouble

        public double optDouble​(int index)
        get a Double at a specified index
        Parameters:
        index - the array index position
        Returns:
        a Double
      • optDouble

        public double optDouble​(int index,
                                double defaultValue)
        get a Double at a specified index, or a default value if the value does not exist or is not a double
        Parameters:
        index - the array index position
        defaultValue - the default value to return if the index or value type are not valid
        Returns:
        a Double
      • getFloat

        public float getFloat​(int index)
                       throws JSONException
        get a Float at a specified index
        Parameters:
        index - the array index position
        Returns:
        a Float
        Throws:
        JSONException - if the element is not a Float or index is out of bounds
      • optFloat

        public float optFloat​(int index)
        get a Float at a specified index, or a NaN value if the value does not exist or is not a Float
        Parameters:
        index - the array index position
        Returns:
        a Float
      • optFloat

        public float optFloat​(int index,
                              float defaultValue)
        get a Float at a specified index, or a default value if the value does not exist or is not a Float
        Parameters:
        index - the array index position
        defaultValue - the default value to return if the index or value type are not valid
        Returns:
        a Float
      • getLong

        public long getLong​(int index)
                     throws JSONException
        get a long at a specified index
        Parameters:
        index - the array index position
        Returns:
        a long
        Throws:
        JSONException - if the element is not a long or index is out of bounds
      • optLong

        public long optLong​(int index)
        get a long at a specified index, or 0 if the value does not exist or is not a long
        Parameters:
        index - the array index position
        Returns:
        a long
      • optLong

        public long optLong​(int index,
                            long defaultValue)
        get a long at a specified index, or a default value if the value does not exist or is not a long
        Parameters:
        index - the array index position
        defaultValue - the default value to return if the index or value type are not valid
        Returns:
        a long
      • getNumber

        public Number getNumber​(int index)
                         throws JSONException
        get a Number at a specified index
        Parameters:
        index - the array index position
        Returns:
        a Number
        Throws:
        JSONException - if the element is not a Number or index is out of bounds
      • optNumber

        public Number optNumber​(int index)
        get a Number at a specified index
        Parameters:
        index - the array index position
        Returns:
        a int
      • optNumber

        public Number optNumber​(int index,
                                Number defaultValue)
        get a Number at a specified index
        Parameters:
        index - the array index position
        defaultValue - the default value if the index does not exist or is not a number
        Returns:
        a Number
      • getInt

        public int getInt​(int index)
                   throws JSONException
        get a int at a specified index
        Parameters:
        index - the array index position
        Returns:
        a int
        Throws:
        JSONException - if the element is not a int or index is out of bounds
      • optInt

        public int optInt​(int index)
        get a int at a specified index, or 0 if the value does not exist or is not a int
        Parameters:
        index - the array index position
        Returns:
        a int
      • optInt

        public int optInt​(int index,
                          int defaultValue)
        get a int at a specified index, or a default value if the value does not exist or is not a int
        Parameters:
        index - the array index position
        defaultValue - the default value to return if the index or value type are not valid
        Returns:
        a int
      • getBigInteger

        public BigInteger getBigInteger​(int index)
                                 throws JSONException
        get a BigInteger at a specified index
        Parameters:
        index - the array index position
        Returns:
        a BigInteger
        Throws:
        JSONException - if the element is not a BigInteger or index is out of bounds
      • optBigInteger

        public BigInteger optBigInteger​(int index,
                                        BigInteger defaultValue)
        get a BigInteger at a specified index, or a default value if the value does not exist or is not a BigInteger
        Parameters:
        index - the array index position
        defaultValue - the default value to return if the index or value type are not valid
        Returns:
        a BigInteger
      • getBigDecimal

        public BigDecimal getBigDecimal​(int index)
                                 throws JSONException
        get a BigDecimal at a specified index
        Parameters:
        index - the array index position
        Returns:
        a BigDecimal
        Throws:
        JSONException - if the element is not a BigDecimal or index is out of bounds
      • optBigDecimal

        public BigDecimal optBigDecimal​(int index,
                                        BigDecimal defaultValue)
        get a BigDecimal at a specified index, or a default value if the value does not exist or is not a BigDecimal
        Parameters:
        index - the array index position
        defaultValue - the default value to return if the index or value type are not valid
        Returns:
        a BigDecimal
      • getString

        public String getString​(int index)
                         throws JSONException
        get a String at a specified index
        Parameters:
        index - the array index position
        Returns:
        a String
        Throws:
        JSONException - if the element is not a String or index is out of bounds
      • optString

        public String optString​(int index)
        get a String at a specified index, or an empty string if the value does not exist or is not a String
        Parameters:
        index - the array index position
        Returns:
        a String
      • optString

        public String optString​(int index,
                                String defaultValue)
        get a String at a specified index, or a default value if the value does not exist or is not a String
        Parameters:
        index - the array index position
        defaultValue - the default value to return if the index or value type are not valid
        Returns:
        a String
      • getJSONArray

        public JSONArray getJSONArray​(int index)
                               throws JSONException
        get a JSONArray at a specified index
        Parameters:
        index - the array index position
        Returns:
        a JSONArray
        Throws:
        JSONException - if the element is not a JSONArray or index is out of bounds
      • optJSONArray

        public JSONArray optJSONArray​(int index)
        get a String at a specified index, or null if the value does not exist or is not a JSONArray
        Parameters:
        index - the array index position
        Returns:
        a JSONArray
      • getEnum

        public <T extends Enum<T>> T getEnum​(Class<T> enumClass,
                                             int index)
                                      throws JSONException
        get a enum value based on name from a specific index
        Type Parameters:
        T - the type of enum
        Parameters:
        enumClass - the enum type
        index - the index
        Returns:
        a enum value
        Throws:
        JSONException - if the index is out of bounds or the value cannot be converted to the enum type
      • optEnum

        public <T extends Enum<T>> T optEnum​(Class<T> enumClass,
                                             int index)
      • optEnum

        public <T extends Enum<T>> T optEnum​(Class<T> enumClass,
                                             int index,
                                             T defaultValue)
      • get

        public Object get​(int index)
                   throws JSONException
        get the element at the index
        Parameters:
        index - the index number
        Returns:
        the object at that position
        Throws:
        JSONException - if index is out of bounds
      • opt

        public Object opt​(int index)
        get the element at the index
        Parameters:
        index - the index number
        Returns:
        the object at that position
      • toString

        public String toString()
        returns the String representation of the JSONArray
        Overrides:
        toString in class Object
        Returns:
        string json
      • toString

        public String toString​(int indent)
                        throws JSONException
        returns the String representation of the JSONArray
        Parameters:
        indent - currently ignored until this is addressed by GSON
        Returns:
        string json
        Throws:
        JSONException - if something goes wrong
      • join

        public String join​(String token)
                    throws JSONException
        return the array as a string delimited by a specific token
        Parameters:
        token - the delimitation token
        Returns:
        a token delimited array
        Throws:
        JSONException - if something goes wrong
      • similar

        public boolean similar​(Object o)
        indicates if a JSONArray has the same elements as another JSONArray
        Parameters:
        o - the other object
        Returns:
        a bool
      • toList

        public List toList()
        Converts the JSONArray to a List
        Returns:
        a List
      • isNull

        public boolean isNull​(int index)
        Indicates if the index does not exist or it's contents are null
        Parameters:
        index - the index poisition to test
        Returns:
        boolean if the index exists
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • toJSONObject

        public JSONObject 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.
        Throws:
        JSONException - If any of the names are null.
      • isEmpty

        public boolean isEmpty()
        returns if the array is empty
        Returns:
        bool if it be empty