Class JSONArray

  • All Implemented Interfaces:
    java.lang.Iterable<java.lang.Object>

    public class JSONArray
    extends JSONElement
    implements java.lang.Iterable<java.lang.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​(java.lang.Object array)
      Construct a JSONArray from a typed array (int[]).
      JSONArray​(java.lang.String jsonString)
      construct a JSONArray from a String
      JSONArray​(java.util.Collection<?> collection)
      Construct a JSONArray from a collection.
      JSONArray​(JsonEngine.Array array)  
      JSONArray​(JsonEngine.Element jsonElement)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object o)  
      java.lang.Object get​(int index)
      get the element at the index
      (package private) JsonEngine.Array getArray()  
      java.math.BigDecimal getBigDecimal​(int index)
      get a BigDecimal at a specified index
      java.math.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
      private JsonEngine.Element getElement​(int index)  
      <T extends java.lang.Enum<T>>
      T
      getEnum​(java.lang.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
      java.lang.Number getNumber​(int index)
      get a Number at a specified index
      private <T> T getOrDefault​(java.util.function.Supplier<T> supplier, T defaultValue)  
      java.lang.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
      java.util.Iterator<java.lang.Object> iterator()  
      java.lang.String join​(java.lang.String token)
      return the array as a string delimited by a specific token
      int length()  
      java.lang.Object opt​(int index)
      get the element at the index
      java.math.BigDecimal optBigDecimal​(int index, java.math.BigDecimal defaultValue)
      get a BigDecimal at a specified index, or a default value if the value does not exist or is not a BigDecimal
      java.math.BigInteger optBigInteger​(int index, java.math.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 java.lang.Enum<T>>
      T
      optEnum​(java.lang.Class<T> enumClass, int index)  
      <T extends java.lang.Enum<T>>
      T
      optEnum​(java.lang.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
      java.lang.Number optNumber​(int index)
      get a Number at a specified index
      java.lang.Number optNumber​(int index, java.lang.Number defaultValue)
      get a Number at a specified index
      java.lang.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
      java.lang.String optString​(int index, java.lang.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, java.lang.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, java.lang.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, java.lang.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, java.util.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, java.util.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
      private JSONArray put​(int index, JsonEngine.Element o)  
      <T extends java.lang.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​(java.lang.Number num)
      add a Number to the array
      JSONArray put​(java.lang.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​(java.lang.String str)
      add a String to the array
      JSONArray put​(java.util.Collection collection)
      add a JSONArray to the array
      JSONArray put​(java.util.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 java.lang.Enum>
      JSONArray
      put​(T enumValue)
      put a enum which will be put as the string name
      java.lang.Object remove​(int index)
      Removes the element at the specified position in this array.
      boolean similar​(java.lang.Object o)
      indicates if a JSONArray has the same elements as another JSONArray
      private static JsonEngine.Array toJsonArray​(java.lang.Object thing)  
      JSONObject toJSONObject​(JSONArray names)
      Produce a JSONObject by combining a JSONArray of names with the values of this JSONArray.
      java.util.List toList()
      Converts the JSONArray to a List
      java.lang.String toString()
      returns the String representation of the JSONArray
      java.lang.String toString​(int indent)
      returns the String representation of the JSONArray
      private <T extends java.lang.Number>
      T
      tryNumber​(java.util.function.Supplier<T> supplier, int index)  
      • 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()
        construct a empty JSONArray
      • JSONArray

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

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

        public JSONArray​(java.lang.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

      • toJsonArray

        private static JsonEngine.Array toJsonArray​(java.lang.Object thing)
      • 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​(java.lang.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​(java.lang.String str)
        add a String to the array
        Parameters:
        str - a String
        Returns:
        this JSONArray
      • put

        public JSONArray put​(java.util.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​(java.util.Collection collection)
        add a JSONArray to the array
        Parameters:
        collection - a Collection of JSON Types
        Returns:
        this JSONArray
      • put

        public <T extends java.lang.Enum> JSONArray 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,
                             java.lang.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,
                             java.lang.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,
                             java.lang.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,
                             java.util.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,
                             java.util.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 java.lang.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
        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​(java.lang.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 java.lang.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 java.lang.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 java.lang.Number optNumber​(int index)
        get a Number at a specified index
        Parameters:
        index - the array index position
        Returns:
        a int
      • optNumber

        public java.lang.Number optNumber​(int index,
                                          java.lang.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 java.math.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 java.math.BigInteger optBigInteger​(int index,
                                                  java.math.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 java.math.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 java.math.BigDecimal optBigDecimal​(int index,
                                                  java.math.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 java.lang.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 java.lang.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 java.lang.String optString​(int index,
                                          java.lang.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 java.lang.Enum<T>> T getEnum​(java.lang.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 java.lang.Enum<T>> T optEnum​(java.lang.Class<T> enumClass,
                                                       int index)
      • optEnum

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

        public java.lang.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 java.lang.Object opt​(int index)
        get the element at the index
        Parameters:
        index - the index number
        Returns:
        the object at that position
      • toString

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

        public java.lang.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 java.lang.String join​(java.lang.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
      • iterator

        public java.util.Iterator<java.lang.Object> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<java.lang.Object>
        Returns:
        the iterator for the array
      • similar

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

        public java.util.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
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • getOrDefault

        private <T> T getOrDefault​(java.util.function.Supplier<T> supplier,
                                   T defaultValue)
      • tryNumber

        private <T extends java.lang.Number> T tryNumber​(java.util.function.Supplier<T> supplier,
                                                         int index)
      • 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