Module com.google.gson
Package com.google.gson

Class JsonArray

java.lang.Object
com.google.gson.JsonElement
com.google.gson.JsonArray
All Implemented Interfaces:
Iterable<JsonElement>
public final class JsonArray extends JsonElement implements Iterable<JsonElement>
A class representing an array type in JSON. An array is a list of JsonElements each of which can be of a different type. This is an ordered list, meaning that the order in which elements are added is preserved. This class does not support null values. If null is provided as element argument to any of the methods, it is converted to a JsonNull.

JsonArray only implements the Iterable interface but not the List interface. A List view of it can be obtained with asList().

Author:
Inderjeet Singh, Joel Leitch

  • Constructor Details

    • JsonArray

      public JsonArray()
      Creates an empty JsonArray.

    • JsonArray

      public JsonArray(int capacity)
      Creates an empty JsonArray with the desired initial capacity.
      Parameters:
      capacity - initial capacity.
      Throws:
      IllegalArgumentException - if the capacity is negative
      Since:
      2.8.1

  • Method Details

    • deepCopy

      public JsonArray deepCopy()
      Creates a deep copy of this element and all its children.
      Specified by:
      deepCopy in class JsonElement
      Since:
      2.8.2

    • add

      public void add(Boolean bool)
      Adds the specified boolean to self.
      Parameters:
      bool - the boolean that needs to be added to the array.
      Since:
      2.4

    • add

      public void add(Character character)
      Adds the specified character to self.
      Parameters:
      character - the character that needs to be added to the array.
      Since:
      2.4

    • add

      public void add(Number number)
      Adds the specified number to self.
      Parameters:
      number - the number that needs to be added to the array.
      Since:
      2.4

    • add

      public void add(String string)
      Adds the specified string to self.
      Parameters:
      string - the string that needs to be added to the array.
      Since:
      2.4

    • add

      public void add(JsonElement element)
      Adds the specified element to self.
      Parameters:
      element - the element that needs to be added to the array.

    • addAll

      public void addAll(JsonArray array)
      Adds all the elements of the specified array to self.
      Parameters:
      array - the array whose elements need to be added to the array.

    • set

      public JsonElement set(int index, JsonElement element)
      Replaces the element at the specified position in this array with the specified element.
      Parameters:
      index - index of the element to replace
      element - element to be stored at the specified position
      Returns:
      the element previously at the specified position
      Throws:
      IndexOutOfBoundsException - if the specified index is outside the array bounds

    • remove

      public boolean remove(JsonElement element)
      Removes the first occurrence of the specified element from this array, if it is present. If the array does not contain the element, it is unchanged.
      Parameters:
      element - element to be removed from this array, if present
      Returns:
      true if this array contained the specified element, false otherwise
      Since:
      2.3

    • remove

      public JsonElement 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
      Throws:
      IndexOutOfBoundsException - if the specified index is outside the array bounds
      Since:
      2.3

    • contains

      public boolean contains(JsonElement element)
      Returns true if this array contains the specified element.
      Parameters:
      element - whose presence in this array is to be tested
      Returns:
      true if this array contains the specified element.
      Since:
      2.3

    • size

      public int size()
      Returns the number of elements in the array.
      Returns:
      the number of elements in the array.

    • isEmpty

      public boolean isEmpty()
      Returns true if the array is empty.
      Returns:
      true if the array is empty.
      Since:
      2.8.7

    • iterator

      public Iterator<JsonElement> iterator()
      Returns an iterator to navigate the elements of the array. Since the array is an ordered list, the iterator navigates the elements in the order they were inserted.
      Specified by:
      iterator in interface Iterable<JsonElement>
      Returns:
      an iterator to navigate the elements of the array.

    • get

      public JsonElement get(int i)
      Returns the i-th element of the array.
      Parameters:
      i - the index of the element that is being sought.
      Returns:
      the element present at the i-th index.
      Throws:
      IndexOutOfBoundsException - if i is negative or greater than or equal to the size() of the array.

    • getAsNumber

      public Number getAsNumber()
      Convenience method to get this array as a Number if it contains a single element. This method calls JsonElement.getAsNumber() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsNumber in class JsonElement
      Returns:
      this element as a number if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsString

      public String getAsString()
      Convenience method to get this array as a String if it contains a single element. This method calls JsonElement.getAsString() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsString in class JsonElement
      Returns:
      this element as a String if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsDouble

      public double getAsDouble()
      Convenience method to get this array as a double if it contains a single element. This method calls JsonElement.getAsDouble() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsDouble in class JsonElement
      Returns:
      this element as a double if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsBigDecimal

      public BigDecimal getAsBigDecimal()
      Convenience method to get this array as a BigDecimal if it contains a single element. This method calls JsonElement.getAsBigDecimal() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsBigDecimal in class JsonElement
      Returns:
      this element as a BigDecimal if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.
      Since:
      1.2

    • getAsBigInteger

      public BigInteger getAsBigInteger()
      Convenience method to get this array as a BigInteger if it contains a single element. This method calls JsonElement.getAsBigInteger() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsBigInteger in class JsonElement
      Returns:
      this element as a BigInteger if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.
      Since:
      1.2

    • getAsFloat

      public float getAsFloat()
      Convenience method to get this array as a float if it contains a single element. This method calls JsonElement.getAsFloat() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsFloat in class JsonElement
      Returns:
      this element as a float if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsLong

      public long getAsLong()
      Convenience method to get this array as a long if it contains a single element. This method calls JsonElement.getAsLong() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsLong in class JsonElement
      Returns:
      this element as a long if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsInt

      public int getAsInt()
      Convenience method to get this array as an integer if it contains a single element. This method calls JsonElement.getAsInt() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsInt in class JsonElement
      Returns:
      this element as an integer if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsByte

      public byte getAsByte()
      Convenience method to get this array as a primitive byte if it contains a single element. This method calls JsonElement.getAsByte() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsByte in class JsonElement
      Returns:
      this element as a primitive byte if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsCharacter

      @Deprecated public char getAsCharacter()
      Deprecated.
      This method is misleading, as it does not get this element as a char but rather as a string's first character.
      Convenience method to get this array as a character if it contains a single element. This method calls JsonElement.getAsCharacter() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsCharacter in class JsonElement
      Returns:
      this element as a primitive short if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsShort

      public short getAsShort()
      Convenience method to get this array as a primitive short if it contains a single element. This method calls JsonElement.getAsShort() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsShort in class JsonElement
      Returns:
      this element as a primitive short if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • getAsBoolean

      public boolean getAsBoolean()
      Convenience method to get this array as a boolean if it contains a single element. This method calls JsonElement.getAsBoolean() on the element, therefore any of the exceptions declared by that method can occur.
      Overrides:
      getAsBoolean in class JsonElement
      Returns:
      this element as a boolean if it is single element array.
      Throws:
      IllegalStateException - if the array is empty or has more than one element.

    • asList

      public List<JsonElement> asList()
      Returns a mutable List view of this JsonArray. Changes to the List are visible in this JsonArray and the other way around.

      The List does not permit null elements. Unlike JsonArray's null handling, a NullPointerException is thrown when trying to add null. Use JsonNull for JSON null values.

      Returns:
      mutable List view
      Since:
      2.10

    • equals

      public boolean equals(Object o)
      Returns whether the other object is equal to this. This method only considers the other object to be equal if it is an instance of JsonArray and has equal elements in the same order.
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Returns the hash code of this array. This method calculates the hash code based on the elements of this array.
      Overrides:
      hashCode in class Object