Package io.vertx.core.json

## Class JsonArray

- java.lang.Object
- - io.vertx.core.json.JsonArray

- All Implemented Interfaces:
    `ClusterSerializable`, `Shareable`, `Iterable<Object>`

      public class JsonArray
      extends Object
      implements Iterable<Object>, ClusterSerializable, Shareable

  A representation of a JSON array in Java. Unlike some other languages Java does not have a native understanding of JSON. To enable JSON to be used easily in Vert.x code we use this class to encapsulate the notion of a JSON array. The implementation adheres to the RFC-7493 to support Temporal data types as well as binary data. Please see the documentation for more information.
  Author:
    Tim Fox

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JsonArray()` | Create an empty instance
    `JsonArray​(Buffer buf)` | Create an instance from a Buffer of JSON.
    `JsonArray​(String json)` | Create an instance from a String of JSON, this string must be a valid array otherwise an exception will be thrown.
    `JsonArray​(List list)` | Create an instance from a List.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `JsonArray` | `add​(int pos, Object value)` | Add an Object to the JSON array at given position `pos`.
    `JsonArray` | `add​(Object value)` | Add an Object to the JSON array.
    `JsonArray` | `addAll​(JsonArray array)` | Appends all of the elements in the specified array to the end of this JSON array.
    `JsonArray` | `addNull()` | Add a null value to the JSON array.
    `JsonArray` | `clear()` | Remove all entries from the JSON array
    `boolean` | `contains​(Object value)` | Returns `true` if this JSON Array contains the specified value.
    `JsonArray` | `copy()` | Deep copy of the JSON array.
    `JsonArray` | `copy​(java.util.function.Function<Object,​?> cloner)` | Deep copy of the JSON array.
    `String` | `encode()` | Encode the JSON array to a string
    `String` | `encodePrettily()` | Encode the JSON array prettily as a string
    `boolean` | `equals​(Object o)` |
    `byte[]` | `getBinary​(int pos)` | Get the byte[] at position `pos` in the array.
    `Boolean` | `getBoolean​(int pos)` | Get the Boolean at position `pos` in the array,
    `Buffer` | `getBuffer​(int pos)` | Get the Buffer at position `pos` in the array.
    `Double` | `getDouble​(int pos)` | Get the Double at position `pos` in the array,
    `Float` | `getFloat​(int pos)` | Get the Float at position `pos` in the array,
    `java.time.Instant` | `getInstant​(int pos)` | Get the Instant at position `pos` in the array.
    `Integer` | `getInteger​(int pos)` | Get the Integer at position `pos` in the array,
    `JsonArray` | `getJsonArray​(int pos)` | Get the JsonArray at position `pos` in the array.
    `JsonObject` | `getJsonObject​(int pos)` | Get the JsonObject at position `pos` in the array.
    `List` | `getList()` | Get the underlying `List` as is.
    `Long` | `getLong​(int pos)` | Get the Long at position `pos` in the array,
    `Number` | `getNumber​(int pos)` | Get the Number at position `pos` in the array,
    `String` | `getString​(int pos)` | Get the String at position `pos` in the array,
    `Object` | `getValue​(int pos)` | Get the value with the specified key, as an Object with types respecting the limitations of JSON.
    `int` | `hashCode()` |
    `boolean` | `hasNull​(int pos)` | Is there a null value at position pos?
    `int` | `indexOf​(Object value)` | Returns the index of the last occurrence of the specified value in this JSON array, or -1 if this JSON array does not contain the value.
    `boolean` | `isEmpty()` | Are there zero items in this JSON array?
    `Iterator<Object>` | `iterator()` | Get an Iterator over the values in the JSON array
    `static JsonArray` | `of​(Object... values)` | Create a JsonArray containing an arbitrary number of values.
    `int` | `readFromBuffer​(int pos, Buffer buffer)` | Method invoked when deserializing bytes to this instance.
    `Object` | `remove​(int pos)` | Remove the value at the specified position in the JSON array.
    `boolean` | `remove​(Object value)` | Remove the specified value from the JSON array.
    `JsonArray` | `set​(int pos, Object value)` | Set an Object to the JSON array at position `pos`.
    `JsonArray` | `setNull​(int pos)` | Set a null value to the JSON array at position `pos`.
    `int` | `size()` | Get the number of values in this JSON array
    `java.util.stream.Stream<Object>` | `stream()` | Get a Stream over the entries in the JSON array.
    `Buffer` | `toBuffer()` | Encode this JSON object as buffer.
    `String` | `toString()` |
    `void` | `writeToBuffer​(Buffer buffer)` | Method invoked when serializing this instance.

    - ### 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​(String json)

      Create an instance from a String of JSON, this string must be a valid array otherwise an exception will be thrown.

      If you are unsure of the value, you should use instead `Json.decodeValue(String)` and check the result is a JSON array.
      Parameters:
        `json` - the string of JSON

    - #### JsonArray

          public JsonArray()

      Create an empty instance

    - #### JsonArray

          public JsonArray​(List list)

      Create an instance from a List. The List is not copied.
      Parameters:
        `list` - the underlying backing list

    - #### JsonArray

          public JsonArray​(Buffer buf)

      Create an instance from a Buffer of JSON.
      Parameters:
        `buf` - the buffer of JSON.

  - ### Method Detail

    - #### of

          public static JsonArray of​(Object... values)

      Create a JsonArray containing an arbitrary number of values.
      Parameters:
        `values` - The objects into JsonArray.
      Throws:
        `NullPointerException` - if the args is null.

    - #### getString

          public String getString​(int pos)

      Get the String at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the String (or String representation), or null if a null value present

    - #### getNumber

          public Number getNumber​(int pos)

      Get the Number at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Number, or null if a null value present
      Throws:
        `ClassCastException` - if the value is not a Number

    - #### getInteger

          public Integer getInteger​(int pos)

      Get the Integer at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Integer, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Integer

    - #### getLong

          public Long getLong​(int pos)

      Get the Long at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Long, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Long

    - #### getDouble

          public Double getDouble​(int pos)

      Get the Double at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Double, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Double

    - #### getFloat

          public Float getFloat​(int pos)

      Get the Float at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Float, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Float

    - #### getBoolean

          public Boolean getBoolean​(int pos)

      Get the Boolean at position `pos` in the array,
      Parameters:
        `pos` - the position in the array
      Returns:
        the Boolean, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to Integer

    - #### getJsonObject

          public JsonObject getJsonObject​(int pos)

      Get the JsonObject at position `pos` in the array.
      Parameters:
        `pos` - the position in the array
      Returns:
        the JsonObject, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to JsonObject

    - #### getJsonArray

          public JsonArray getJsonArray​(int pos)

      Get the JsonArray at position `pos` in the array.
      Parameters:
        `pos` - the position in the array
      Returns:
        the Integer, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to JsonArray

    - #### getBinary

          public byte[] getBinary​(int pos)

      Get the byte[] at position `pos` in the array. JSON itself has no notion of a binary, so this method assumes there is a String value and it contains a Base64 encoded binary, which it decodes if found and returns.
      Parameters:
        `pos` - the position in the array
      Returns:
        the byte[], or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to String
        `IllegalArgumentException` - if the String value is not a legal Base64 encoded value

    - #### getBuffer

          public Buffer getBuffer​(int pos)

      Get the Buffer at position `pos` in the array. JSON itself has no notion of a binary, so this method assumes there is a String value and it contains a Base64 encoded binary, which it decodes if found and returns.
      Parameters:
        `pos` - the position in the array
      Returns:
        the byte[], or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to String
        `IllegalArgumentException` - if the String value is not a legal Base64 encoded value

    - #### getInstant

          public java.time.Instant getInstant​(int pos)

      Get the Instant at position `pos` in the array. JSON itself has no notion of a temporal types, this extension allows ISO 8601 string formatted dates with timezone always set to zero UTC offset, as denoted by the suffix "Z" to be parsed as a instant value. `YYYY-MM-DDTHH:mm:ss.sssZ` is the default format used by web browser scripting. This extension complies to the RFC-7493 with all the restrictions mentioned before. The method will then decode and return a instant value.
      Parameters:
        `pos` - the position in the array
      Returns:
        the Instant, or null if a null value present
      Throws:
        `ClassCastException` - if the value cannot be converted to String
        `java.time.format.DateTimeParseException` - if the String value is not a legal ISO 8601 encoded value

    - #### getValue

          public Object getValue​(int pos)

      Get the value with the specified key, as an Object with types respecting the limitations of JSON.
      - `Map` will be wrapped to `JsonObject`
      - `List` will be wrapped to `JsonArray`
      - `Instant` will be converted to `String`
      - `byte[]` will be converted to `String`
      - `Buffer` will be converted to `String`
      - `Enum` will be converted to `String`
      Parameters:
        `pos` - the position in the array
      Returns:
        the Integer, or null if a null value present

    - #### hasNull

          public boolean hasNull​(int pos)

      Is there a null value at position pos?
      Parameters:
        `pos` - the position in the array
      Returns:
        true if null value present, false otherwise

    - #### addNull

          public JsonArray addNull()

      Add a null value to the JSON array.
      Returns:
        a reference to this, so the API can be used fluently

    - #### add

          public JsonArray add​(Object value)

      Add an Object to the JSON array.
      Parameters:
        `value` - the value
      Returns:
        a reference to this, so the API can be used fluently

    - #### add

          public JsonArray add​(int pos,
                               Object value)

      Add an Object to the JSON array at given position `pos`.
      Parameters:
        `pos` - the position
        `value` - the value
      Returns:
        a reference to this, so the API can be used fluently

    - #### addAll

          public JsonArray addAll​(JsonArray array)

      Appends all of the elements in the specified array to the end of this JSON array.
      Parameters:
        `array` - the array
      Returns:
        a reference to this, so the API can be used fluently

    - #### setNull

          public JsonArray setNull​(int pos)

      Set a null value to the JSON array at position `pos`.
      Returns:
        a reference to this, so the API can be used fluently

    - #### set

          public JsonArray set​(int pos,
                               Object value)

      Set an Object to the JSON array at position `pos`.
      Parameters:
        `pos` - position in the array
        `value` - the value
      Returns:
        a reference to this, so the API can be used fluently

    - #### contains

          public boolean contains​(Object value)

      Returns `true` if this JSON Array contains the specified value. More formally, returns `true` if and only if this JSON array contains at least one entry `entry` such that `Objects.equals(value, entry)`.
      Parameters:
        `value` - the value whose presence in this JSON array is to be tested
      Returns:
        true if it contains the value, false if not

    - #### indexOf

          public int indexOf​(Object value)

      Returns the index of the last occurrence of the specified value in this JSON array, or -1 if this JSON array does not contain the value. More formally, returns the highest index `i` such that `Objects.equals(value, get(i))`, or -1 if there is no such index.
      Parameters:
        `value` - the value whose index in this JSON array is to be returned
      Returns:
        the index of the value in the array, or -1 if the value is not in the array

    - #### remove

          public boolean remove​(Object value)

      Remove the specified value from the JSON array. This method will scan the entire array until it finds a value or reaches the end.
      Parameters:
        `value` - the value to remove
      Returns:
        true if it removed it, false if not found

    - #### remove

          public Object remove​(int pos)

      Remove the value at the specified position in the JSON array.
      Parameters:
        `pos` - the position to remove the value at
      Returns:
        the removed value if removed, null otherwise. If the value is a Map, a `JsonObject` is built from this Map and returned. It the value is a List, a `JsonArray` is built form this List and returned.

    - #### size

          public int size()

      Get the number of values in this JSON array
      Returns:
        the number of items

    - #### isEmpty

          public boolean isEmpty()

      Are there zero items in this JSON array?
      Returns:
        true if zero, false otherwise

    - #### getList

          public List getList()

      Get the underlying `List` as is. This list may contain values that are not the types returned by the `JsonArray` and with an unpredictable representation of the value, e.g you might get a JSON object as a `JsonObject` or as a `Map`.
      Returns:
        the underlying List.

    - #### clear

          public JsonArray clear()

      Remove all entries from the JSON array
      Returns:
        a reference to this, so the API can be used fluently

    - #### iterator

          public Iterator<Object> iterator()

      Get an Iterator over the values in the JSON array
      Specified by:
        `iterator` in interface `Iterable<Object>`
      Returns:
        an iterator

    - #### encode

          public String encode()

      Encode the JSON array to a string
      Returns:
        the string encoding

    - #### toBuffer

          public Buffer toBuffer()

      Encode this JSON object as buffer.
      Returns:
        the buffer encoding.

    - #### encodePrettily

          public String encodePrettily()

      Encode the JSON array prettily as a string
      Returns:
        the string encoding

    - #### copy

          public JsonArray copy()

      Deep copy of the JSON array.
      Specified by:
        `copy` in interface `Shareable`
      Returns:
        a copy where all elements have been copied recursively
      Throws:
        `IllegalStateException` - when a nested element cannot be copied

    - #### copy

          public JsonArray copy​(java.util.function.Function<Object,​?> cloner)

      Deep copy of the JSON array.

      Unlike `copy()` that can fail when an unknown element cannot be copied, this method delegates the copy of such element to the `cloner` function and will not fail.

      Parameters:
        `cloner` - a function that copies custom values not supported by the JSON implementation
      Returns:
        a copy where all elements have been copied recursively

    - #### stream

          public java.util.stream.Stream<Object> stream()

      Get a Stream over the entries in the JSON array. The values in the stream will follow the same rules as defined in `getValue(int)`, respecting the JSON requirements. To stream the raw values, use the storage object stream instead:

             jsonArray
               .getList()
               .stream()

      Returns:
        a Stream

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### equals

          public boolean equals​(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### writeToBuffer

          public void writeToBuffer​(Buffer buffer)

      Description copied from interface: `ClusterSerializable`
      Method invoked when serializing this instance.
      Specified by:
        `writeToBuffer` in interface `ClusterSerializable`
      Parameters:
        `buffer` - the `Buffer` where the serialized bytes must be written to

    - #### readFromBuffer

          public int readFromBuffer​(int pos,
                                    Buffer buffer)

      Description copied from interface: `ClusterSerializable`
      Method invoked when deserializing bytes to this instance.
      Specified by:
        `readFromBuffer` in interface `ClusterSerializable`
      Parameters:
        `pos` - the position where to start reading the `buffer`
        `buffer` - the `Buffer` where the serialized bytes must be read from
      Returns:
        the position after the last serialized byte