Module json_values
Package jsonvalues

Class JsArray

java.lang.Object
jsonvalues.JsArray
All Implemented Interfaces:
Iterable<JsValue>, Json<JsArray>, JsValue
public final class JsArray extends Object implements Json<JsArray>, Iterable<JsValue>
Represents a JSON array in a persistent data structure.

A JsArray is a collection of JSON values arranged in an ordered sequence. It allows for easy manipulation of JSON arrays, such as adding, updating, or removing elements, while preserving immutability. This class is designed to be used for creating and working with JSON arrays in a functional and safe manner.

JsArray implements the Json interface, which allows it to seamlessly integrate with other JSON-related classes and operations.

As a persistent data structure, modifications to a JsArray result in a new instance being created, leaving the original array unchanged. This immutability ensures safe concurrent access and simplifies handling of JSON data.

  • Field Details

    • lens

      public static final JsOptics.JsArrayLenses lens
      Provides a set of optics (lenses) for working with JSON arrays.

      The JsArrayLenses class offers a collection of optics that allow you to focus on specific elements within a JSON array, making it easier to perform targeted modifications and transformations. These optics are designed to work seamlessly with the JsArray class, enabling precise handling of JSON array data.

    • optional

      public static final JsOptics.JsArrayOptionals optional
      Provides a set of optional optics for working with JSON arrays.

      The JsArrayOptionals class offers a collection of optional optics that allow you to work with JSON arrays more flexibly. These optics provide ways to safely access and manipulate elements within a JSON array, taking into account the possibility of absent or missing elements.

    • prism

      public static final fun.optic.Prism<JsValue,JsArray> prism
      A prism for safely converting a JsValue to a JsArray.

      The prism field provides a way to safely attempt the conversion of a JsValue into a JsArray. It checks whether the given JsValue is actually an array and performs the conversion if it is. Otherwise, it returns an empty Optional.

  • Method Details

    • empty

      public static JsArray empty()
      Returns the singleton empty JSON array
      Returns:
      the singleton empty JSON array

    • of

      public static JsArray of(JsValue e, JsValue... rest)
      Creates a new JsArray containing the specified elements.

      The of method returns a new JsArray instance with the specified elements in the order they appear in the method's argument list. You can provide one or more JsValue elements to include in the resulting array.

      Parameters:
      e - The first JsValue element to include in the array.
      rest - Additional JsValue elements to include in the array (optional).
      Returns:
      A new JsArray containing the specified elements.
      Throws:
      NullPointerException - if any of the provided elements (including e and rest) are null.

    • of

      public static JsArray of(String str, String... others)
      Creates a new JsArray containing the specified string elements.

      The of method returns a new JsArray instance with the specified string elements in the order they appear in the method's argument list. You can provide one or more strings to include in the resulting array.

      Example usage: 

      
 // Creating a JsArray with specified string elements
 JsArray array = JsArray.of("Hello", "World");
      Parameters:
      str - The first string element to include in the array.
      others - Additional string elements to include in the array (optional).
      Returns:
      A new JsArray containing the specified string elements.
      Throws:
      NullPointerException - if any of the provided string elements (including str and others) are null.

    • of

      public static JsArray of(int number, int... others)
      Creates a new JsArray containing the specified integer elements.

      The of method returns a new JsArray instance with the specified integer elements in the order they appear in the method's argument list. You can provide one or more integers to include in the resulting array.

      Parameters:
      number - The first integer element to include in the array.
      others - Additional integer elements to include in the array (optional).
      Returns:
      A new JsArray containing the specified integer elements.

    • of

      public static JsArray of(boolean bool, boolean... others)
      Creates a new JsArray containing the specified boolean elements.

      The of method returns a new JsArray instance with the specified boolean elements in the order they appear in the method's argument list. You can provide one or more boolean values to include in the resulting array.

      Parameters:
      bool - The first boolean element to include in the array.
      others - Additional boolean elements to include in the array (optional).
      Returns:
      A new JsArray containing the specified boolean elements.

    • of

      public static JsArray of(long number, long... others)
      Creates a new JsArray containing the specified long elements.

      The of method returns a new JsArray instance with the specified long elements in the order they appear in the method's argument list. You can provide one or more long values to include in the resulting array.

      Parameters:
      number - The first long element to include in the array.
      others - Additional long elements to include in the array (optional).
      Returns:
      A new JsArray containing the specified long elements.

    • of

      public static JsArray of(BigInteger number, BigInteger... others)
      Creates a new JsArray containing the specified BigInteger elements.

      The of method returns a new JsArray instance with the specified BigInteger elements in the order they appear in the method's argument list. You can provide one or more BigInteger values to include in the resulting array.

      Parameters:
      number - The first BigInteger element to include in the array.
      others - Additional BigInteger elements to include in the array (optional).
      Returns:
      A new JsArray containing the specified BigInteger elements.

    • of

      public static JsArray of(double number, double... others)
      Creates a new JsArray containing the specified double elements.

      The of method returns a new JsArray instance with the specified double elements in the order they appear in the method's argument list. You can provide one or more double values to include in the resulting array.

      Parameters:
      number - The first double element to include in the array.
      others - Additional double elements to include in the array (optional).
      Returns:
      A new JsArray containing the specified double elements.

    • ofIterable

      public static JsArray ofIterable(Iterable<? extends JsValue> iterable)
      Creates a new JsArray from an Iterable of JsValue elements.

      The ofIterable method returns a new JsArray instance containing the elements provided by the specified Iterable. This allows you to convert an existing collection of JsValue objects into a JsArray.

      Parameters:
      iterable - The Iterable containing JsValue elements to include in the array.
      Returns:
      A new JsArray containing the elements from the specified Iterable.

    • parse

      public static JsArray parse(String str) throws JsParserException
      Parses a JSON array represented as a string and returns a new JsArray instance.

      The parse method takes a JSON array string as input, parses it, and returns a new JsArray containing the parsed JSON values. If the input string is not a valid JSON array representation, a JsParserException is thrown.

      Parameters:
      str - The JSON array string to parse.
      Returns:
      A new JsArray containing the parsed JSON values.
      Throws:
      JsParserException - If the input string is not a valid JSON array representation.
      See Also:

    • parse

      public static JsArray parse(byte[] bytes) throws JsParserException
      Parses a JSON array represented as a byte array and returns a new JsArray instance.

      The parse method takes a JSON array represented as a byte array, parses it, and returns a new JsArray containing the parsed JSON values. If the input byte array does not represent a valid JSON array, a JsParserException is thrown.

      Parameters:
      bytes - The byte array representing the JSON array to parse.
      Returns:
      A new JsArray containing the parsed JSON values.
      Throws:
      JsParserException - If the input byte array does not represent a valid JSON array.
      See Also:

    • append

      public JsArray append(JsValue e, JsValue... others)
      Appends one or more JsValue elements to the end of this JSON array.

      The append method allows you to add one or more JsValue elements to the end of this JSON array. The elements are added in the order they appear in the argument list.

      Parameters:
      e - The first JsValue element to append.
      others - Additional JsValue elements to append (optional).
      Returns:
      A new JsArray containing the elements of this array followed by the appended elements.

    • appendAll

      public JsArray appendAll(JsArray array)
      Appends all elements from another JsArray to the end of this JSON array.

      The appendAll method allows you to add all elements from another JsArray to the end of this JSON array. The elements are added in the order they appear in the source array.

      Parameters:
      array - The JsArray containing elements to append to this array.
      Returns:
      A new JsArray containing the elements of this array followed by the elements from the source array.
      See Also:

    • equals

      public boolean equals(JsArray array, JsArray.TYPE ARRAY_AS)
      Checks if this JSON array is equal to another JSON array.

      The equals method compares this JSON array to another JSON array to determine if they are equal. Equality is defined based on the specified JsArray.TYPE of array comparison. If ARRAY_AS is JsArray.TYPE.SET, both arrays must contain the same elements (order doesn't matter, duplicates are ignored). If ARRAY_AS is JsArray.TYPE.LIST, both arrays must have the same elements in the same order. If ARRAY_AS is JsArray.TYPE.MULTISET, both arrays must contain the same elements (order doesn't matter, duplicates are counted).

      Parameters:
      array - The JsArray to compare to this array.
      ARRAY_AS - The JsArray.TYPE specifying the type of array comparison (SET, LIST, or MULTISET).
      Returns:
      true if the arrays are equal according to the specified type, false otherwise.
      See Also:

    • getInt

      public Integer getInt(int index)
      Returns the integral number located at the given index as an integer or null if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in an integer.

      This method retrieves the JSON value at the specified index in the array and attempts to parse it as an integral number. If the value at the index is a valid integral number that can be represented as an integer, it is returned as an Integer. If the value is not an integral number or cannot fit in an integer, this method returns null.

      Example usage: 

      
 // Create a JSON array and retrieve an integral number as an integer
 JsArray array = JsArray.of(1, 2, 3);
 Integer value = array.getInt(1); // Returns 2
      Parameters:
      index - The index of the JSON value to retrieve as an integer.
      Returns:
      The integral number located at the given index as an Integer, or null if it doesn't exist or is not a valid integral number.

    • getInt

      public Integer getInt(int index, Supplier<Integer> orElse)
      Returns the integral number located at the given index as an integer or a default value if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in an integer.

      This method retrieves the JSON value at the specified index in the array and attempts to parse it as an integral number. If the value at the index is a valid integral number that can be represented as an integer, it is returned as an Integer. If the value is not an integral number or cannot fit in an integer, the default value provided by the orElse supplier is returned.

      Parameters:
      index - The index of the JSON value to retrieve as an integer.
      orElse - A supplier that provides a default integer value to return if the JSON value at the index is not a valid integral number or cannot fit in an integer.
      Returns:
      The integral number located at the given index as an Integer, or the default value provided by orElse if it doesn't exist or is not a valid integral number.
      See Also:

    • getLong

      public Long getLong(int index)
      Returns the integral number located at the given index as a long or null if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in a long.

      This method retrieves the JSON value at the specified index in the array and attempts to parse it as an integral number. If the value at the index is a valid integral number that can be represented as a long, it is returned as a Long. If the value is not an integral number or cannot fit in a long, null is returned.

      Parameters:
      index - The index of the JSON value to retrieve as a long.
      Returns:
      The integral number located at the given index as a Long, or null if it doesn't exist or is not a valid integral number.

    • getLong

      public Long getLong(int index, Supplier<Long> orElse)
      Returns the integral number located at the given index as a long or a default value provided by the orElse supplier if it doesn't exist or it's not an integral number or it's an integral number but doesn't fit in a long.

      This method retrieves the JSON value at the specified index in the array and attempts to parse it as an integral number. If the value at the index is a valid integral number that can be represented as a long, it is returned as a Long. If the value is not an integral number or cannot fit in a long, the orElse supplier is used to provide a default value.

      Parameters:
      index - The index of the JSON value to retrieve as a long.
      orElse - A Supplier that provides the default value to return if the value at the given index is not a valid integral number or cannot fit in a long.
      Returns:
      The integral number located at the given index as a Long, or the default value provided by orElse if it doesn't exist or is not a valid integral number.

    • getStr

      public String getStr(int index)
      Returns the string located at the given index or null if it doesn't exist or it's not a string.

      This method retrieves the JSON value at the specified index in the array and attempts to interpret it as a string. If the value at the index is a string, it is returned as a String. If the value is not a string, or if it doesn't exist at the specified index, null is returned.

      Parameters:
      index - The index of the JSON value to retrieve as a string.
      Returns:
      The string located at the given index, or null if it doesn't exist or is not a string.

    • getStr

      public String getStr(int index, Supplier<String> orElse)
      Returns the string located at the given index or a default value supplied by the provided orElse function if it doesn't exist or is not a string.

      This method retrieves the JSON value at the specified index in the array and attempts to interpret it as a string. If the value at the index is a string, it is returned as a String. If the value is not a string, or if it doesn't exist at the specified index, the orElse function is invoked to provide a default value.

      Parameters:
      index - The index of the JSON value to retrieve as a string.
      orElse - A Supplier<String> providing a default value if the value is not a string or doesn't exist.
      Returns:
      The string located at the given index, or the result of invoking orElse if it doesn't exist or is not a string.

    • getInstant

      public Instant getInstant(int index)
      Returns the instant located at the given index as an Instant or null if it doesn't exist or is not a valid instant representation.

      This method retrieves the JSON value at the specified index in the array and attempts to interpret it as an instant. If the value at the index is a valid instant representation, it is returned as an Instant. If the value is not a valid instant representation, or if it doesn't exist at the specified index, null is returned.

      Parameters:
      index - The index of the JSON value to retrieve as an Instant.
      Returns:
      The instant located at the given index as an Instant, or null if it doesn't exist or is not a valid instant representation.

    • getInstant

      public Instant getInstant(int index, Supplier<Instant> orElse)
      Returns the instant located at the given index as an Instant or a default Instant provided by the orElse supplier if it doesn't exist or is not a valid instant representation.

      This method retrieves the JSON value at the specified index in the array and attempts to interpret it as an instant. If the value at the index is a valid instant representation, it is returned as an Instant. If the value is not a valid instant representation, or if it doesn't exist at the specified index, the default Instant provided by the orElse supplier is returned.

      Parameters:
      index - The index of the JSON value to retrieve as an Instant.
      orElse - A Supplier providing the default Instant to return if the value at the specified index is not a valid instant representation or doesn't exist.
      Returns:
      The instant located at the given index as an Instant, or the default Instant provided by the orElse supplier if it doesn't exist or is not a valid instant representation.

    • getBinary

      public byte[] getBinary(int index)
      Retrieves the binary data located at the specified index within the JSON-like array and returns it as an array of bytes. If the element at the given index is either a binary array or a string encoded in Base64, it is converted into an array of bytes and returned. If the element does not exist at the specified index or is not a valid binary representation, this method returns null.
      Parameters:
      index - The index at which to retrieve the binary data.
      Returns:
      An array of bytes representing the binary data at the specified index, or null if the data does not exist or is not a valid binary representation.

    • getBinary

      public byte[] getBinary(int index, Supplier<byte[]> orElse)
      Retrieves the binary data located at the specified index within the JSON-like array and returns it as an array of bytes. If the element at the given index is either a binary array or a string encoded in Base64, it is converted into an array of bytes and returned. If the element does not exist at the specified index or is not a valid binary representation, this method returns the result obtained from the provided default value supplier.
      Parameters:
      index - The index at which to retrieve the binary data.
      orElse - A supplier function that provides a default value (an array of bytes) to be returned when the data does not exist at the specified index or is not a valid binary representation.
      Returns:
      An array of bytes representing the binary data at the specified index, or the default value provided by the supplier if the data does not exist or is not a valid binary representation.

    • getBool

      public Boolean getBool(int index)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a boolean. If the value at the given index is a boolean, it returns the boolean value; otherwise, it returns null.
      Parameters:
      index - The index at which to retrieve the value.
      Returns:
      The boolean value located at the given index, or null if it doesn't exist or the value at the index is not a boolean.

    • getBool

      public Boolean getBool(int index, Supplier<Boolean> orElse)
      Retrieves the boolean value located at the specified index within the JSON-like array and returns it. If the element at the given index is a valid boolean value, it is returned. If the element does not exist at the specified index or is not a valid boolean representation, this method returns the result obtained from the provided default value supplier.
      Parameters:
      index - The index at which to retrieve the boolean value.
      orElse - A supplier function that provides a default boolean value to be returned when the value does not exist at the specified index or is not a valid boolean representation.
      Returns:
      The boolean value located at the given index, or the default value provided by the supplier if the value does not exist or is not a valid boolean representation.

    • getDouble

      public Double getDouble(int index)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a decimal number, converting it to a double. If the value at the given index is a decimal number (either a double or a BigDecimal), it returns the corresponding double value. If the value is not a decimal number or the index doesn't exist, it returns null.

      The conversion process is designed to handle decimal numbers, but it's important to note that if the value is a BigDecimal, the conversion to a double may result in a potential loss of precision. BigDecimal numbers can represent decimal values with high precision, whereas double has limited precision. Therefore, when converting a BigDecimal to a double, there may be a loss of information beyond the double's precision, potentially leading to rounding or truncation.

      Parameters:
      index - The index at which to retrieve the value.
      Returns:
      The double value located at the given index, or null if it doesn't exist, or the value at the index is not a decimal number.

    • getDouble

      public Double getDouble(int index, Supplier<Double> orElse)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a decimal number, converting it to a double. If the value at the given index is a decimal number (either a double or a BigDecimal), it returns the corresponding double value. If the value is not a decimal number or the index doesn't exist, it returns the default value provided by the orElse supplier.

      The conversion process is designed to handle decimal numbers, but it's important to note that if the value is a BigDecimal, the conversion to a double may result in a potential loss of precision. BigDecimal numbers can represent decimal values with high precision, whereas double has limited precision. Therefore, when converting a BigDecimal to a double, there may be a loss of information beyond the double's precision, potentially leading to rounding or truncation.

      Parameters:
      index - The index at which to retrieve the value.
      orElse - A supplier providing the default double value to return if the value is not a decimal number or the index doesn't exist.
      Returns:
      The double value located at the given index, or the default value provided by orElse if it doesn't exist or the value at the index is not a decimal number.

    • getBigDec

      public BigDecimal getBigDec(int index)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a decimal number, returning it as a BigDecimal. If the value at the given index is a decimal number (either a BigDecimal or a double), it returns the corresponding BigDecimal value. If the value is not a decimal number or the index doesn't exist, it returns null.
      Parameters:
      index - The index at which to retrieve the value.
      Returns:
      The BigDecimal value located at the given index, or null if it doesn't exist or the value at the index is not a decimal number.

    • getBigDec

      public BigDecimal getBigDec(int index, Supplier<BigDecimal> orElse)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a decimal number, returning it as a BigDecimal. If the value at the given index is a decimal number (either a BigDecimal or a double), it returns the corresponding BigDecimal value. If the value is not a decimal number or the index doesn't exist, it returns the default BigDecimal value provided by the specified supplier.
      Parameters:
      index - The index at which to retrieve the value.
      orElse - A supplier function that provides a default BigDecimal value if the value at the index is not a decimal number or the index doesn't exist.
      Returns:
      The BigDecimal value located at the given index, or the default value provided by the supplier if it doesn't exist or the value at the index is not a decimal number.

    • getBigInt

      public BigInteger getBigInt(int index)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as an integral number, returning it as a BigInteger. If the value at the given index is an integral number (either a BigInteger, long, or int), it returns the corresponding BigInteger value. If the value is not an integral number or the index doesn't exist, it returns null.
      Parameters:
      index - The index at which to retrieve the value.
      Returns:
      The BigInteger value located at the given index, or null if it doesn't exist or the value at the index is not an integral number.

    • getBigInt

      public BigInteger getBigInt(int index, Supplier<BigInteger> orElse)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as an integral number, returning it as a BigInteger. If the value at the given index is an integral number (either a BigInteger, long, or int), it returns the corresponding BigInteger value. If the value is not an integral number or the index doesn't exist, it returns the default value provided.
      Parameters:
      index - The index at which to retrieve the value.
      orElse - The default value to return if the value at the index is not an integral number or if the index doesn't exist.
      Returns:
      The integral number located at the given index, or the default value if it doesn't exist or the value at the index is not an integral number.

    • getObj

      public JsObj getObj(int index)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a JSON object (JsObj). If the value at the given index is a JSON object, it returns the corresponding JsObj. If the value is not a JSON object or the index doesn't exist, it returns null.
      Parameters:
      index - The index at which to retrieve the value.
      Returns:
      The JsObj located at the given index, or null if it doesn't exist or the value at the index is not a JSON object.

    • getObj

      public JsObj getObj(int index, Supplier<JsObj> orElse)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a JSON object (JsObj). If the value at the given index is a JSON object, it returns the corresponding JsObj. If the value is not a JSON object or the index doesn't exist, it returns the default JsObj provided by the `orElse` supplier.
      Parameters:
      index - The index at which to retrieve the value.
      orElse - A supplier that provides the default JsObj if the index is out of bounds or the value at the index is not a JSON object.
      Returns:
      The JsObj located at the given index or the default JsObj provided by `orElse`.

    • getArray

      public JsArray getArray(int index)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a JSON array (JsArray). If the value at the given index is a JSON array, it returns the corresponding JsArray. If the value is not a JSON array or the index doesn't exist, it returns null.
      Parameters:
      index - The index at which to retrieve the value.
      Returns:
      The JsArray located at the given index or null if it doesn't exist or is not a JSON array.

    • getArray

      public JsArray getArray(int index, Supplier<JsArray> orElse)
      Retrieves the value located at the specified index within the JSON-like array and attempts to interpret it as a JSON array (JsArray). If the value at the given index is a JSON array, it returns the corresponding JsArray. If the value is not a JSON array or the index doesn't exist, it returns the default value provided by the specified Supplier.
      Parameters:
      index - The index at which to retrieve the value.
      orElse - A Supplier that provides the default JsArray value if the index doesn't exist or the value is not a JSON array.
      Returns:
      The JsArray located at the given index or the default value provided by orElse.

    • containsValue

      public boolean containsValue(JsValue el)
      Description copied from interface: Json
      Checks if this JSON contains the given value in its first level.
      Specified by:
      containsValue in interface Json<JsArray>
      Parameters:
      el - The value to check for.
      Returns:
      True if this JSON contains the value, otherwise false.

    • get

      public JsValue get(JsPath path)
      Description copied from interface: Json
      Gets the value located at the given path or JsNothing if it doesn't exist.
      Specified by:
      get in interface Json<JsArray>
      Parameters:
      path - The path to the desired value.
      Returns:
      The value at the given path or JsNothing if it doesn't exist.

    • filterValues

      public JsArray filterValues(BiPredicate<? super JsPath,? super JsPrimitive> filter)
      Description copied from interface: Json
      Filters all the pairs of elements of this json, removing those that don't satisfy the given predicate.
      Specified by:
      filterValues in interface Json<JsArray>
      Parameters:
      filter - the predicate which takes as input every JsPair of this json
      Returns:
      this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

    • filterValues

      public JsArray filterValues(Predicate<? super JsPrimitive> filter)
      Description copied from interface: Json
      Filters all the pairs of elements of this json, removing those that don't ifPredicateElse the predicate.
      Specified by:
      filterValues in interface Json<JsArray>
      Parameters:
      filter - the predicate which takes as the input every JsPair of this json
      Returns:
      same this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

    • filterKeys

      public JsArray filterKeys(BiPredicate<? super JsPath,? super JsValue> filter)
      Description copied from interface: Json
      Filters all the keys of this json, removing those that don't satisfy the given predicate.
      Specified by:
      filterKeys in interface Json<JsArray>
      Parameters:
      filter - the predicate which takes as input every JsPair of this json
      Returns:
      this instance if all the keys satisfy the predicate or a new filtered json of the same type T

    • filterKeys

      public JsArray filterKeys(Predicate<? super String> filter)
      Description copied from interface: Json
      Filters all the keys of this json, removing those that don't ifPredicateElse the predicate.
      Specified by:
      filterKeys in interface Json<JsArray>
      Parameters:
      filter - the predicate which takes as the input every JsPair of this json
      Returns:
      same this instance if all the keys satisfy the predicate or a new filtered json of the same type T

    • filterObjs

      public JsArray filterObjs(BiPredicate<? super JsPath,? super JsObj> filter)
      Description copied from interface: Json
      Filters all the pair of jsons of this json, removing those that don't satisfy the given predicate.
      Specified by:
      filterObjs in interface Json<JsArray>
      Parameters:
      filter - the predicate which takes as input every JsPair of this json
      Returns:
      this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

    • filterObjs

      public JsArray filterObjs(Predicate<? super JsObj> filter)
      Description copied from interface: Json
      Filters all the pair of jsons of this json, removing those that don't ifPredicateElse the predicate.
      Specified by:
      filterObjs in interface Json<JsArray>
      Parameters:
      filter - the predicate which takes as the input every JsPair of this json
      Returns:
      same this instance if all the pairs satisfy the predicate or a new filtered json of the same type T

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: Json
      Determines whether this Json instance is empty, i.e., it contains no elements.
      Specified by:
      isEmpty in interface Json<JsArray>
      Returns:
      true if empty, false otherwise

    • mapValues

      public JsArray mapValues(BiFunction<? super JsPath,? super JsPrimitive,? extends JsValue> fn)
      Description copied from interface: Json
      Recursively maps all the values of this JSON, replacing each value with the result of applying the given mapping function. This operation traverses the entire JSON structure.
      Specified by:
      mapValues in interface Json<JsArray>
      Parameters:
      fn - the mapping function that transforms each value
      Returns:
      a new JSON object of the same type T with the mapped values

    • mapValues

      public JsArray mapValues(Function<? super JsPrimitive,? extends JsValue> fn)
      Description copied from interface: Json
      Recursively maps all the values of this JSON, replacing each value with the result of applying the given mapping function. This operation traverses the entire JSON structure.
      Specified by:
      mapValues in interface Json<JsArray>
      Parameters:
      fn - the mapping function that transforms each value
      Returns:
      a new JSON object of the same type T with the mapped values

    • mapKeys

      public JsArray mapKeys(BiFunction<? super JsPath,? super JsValue,String> fn)
      Description copied from interface: Json
      Maps all the keys of this JSON object, recursively traversing the entire JSON structure.
      Specified by:
      mapKeys in interface Json<JsArray>
      Parameters:
      fn - the mapping function that transforms each key
      Returns:
      a new JSON object of the same type T with the mapped keys

    • mapKeys

      public JsArray mapKeys(Function<? super String,String> fn)
      Description copied from interface: Json
      Maps all the keys of this JSON object, recursively traversing the entire JSON structure.
      Specified by:
      mapKeys in interface Json<JsArray>
      Parameters:
      fn - the mapping function that transforms each key
      Returns:
      a new JSON object of the same type T with the mapped keys

    • mapObjs

      public JsArray mapObjs(BiFunction<? super JsPath,? super JsObj,? extends JsValue> fn)
      Description copied from interface: Json
      Maps all the JSON objects of this JSON, traversing the entire JSON if necessary.
      Specified by:
      mapObjs in interface Json<JsArray>
      Parameters:
      fn - the mapping function that transforms each JSON object
      Returns:
      a new JSON object of the same type T with the mapped objects, or the same instance if no objects are found

    • mapObjs

      public JsArray mapObjs(Function<? super JsObj,? extends JsValue> fn)
      Description copied from interface: Json
      Maps all the JSON objects of this JSON, traversing the entire JSON if necessary.
      Specified by:
      mapObjs in interface Json<JsArray>
      Parameters:
      fn - the mapping function that transforms each JSON object
      Returns:
      a new JSON object of the same type T with the mapped objects, or the same instance if no objects are found

    • set

      public JsArray set(JsPath path, JsValue element)
      Description copied from interface: Json
      Inserts the given element at the specified path in this JSON, replacing any existing element. If necessary, it fills empty indexes in arrays with JsNull. You have the option to use Json.set(JsPath, JsValue, JsValue) to specify a custom padding element.
      Specified by:
      set in interface Json<JsArray>
      Parameters:
      path - the path where the element will be inserted
      element - the element to be inserted
      Returns:
      a JSON object of the same type with the new element, or the same instance if the path is invalid

    • set

      public JsArray set(int index, JsValue element)

    • set

      public JsArray set(int index, JsValue value, JsValue padElement)
      Sets the value at the specified index within the JSON-like array to the provided JsValue. If the array size is less than the specified index, it will be padded with the given padElement to accommodate the new value.
      Parameters:
      index - The index at which to set the value.
      value - The JsValue to set at the specified index.
      padElement - The JsValue to use for padding the array if necessary.
      Returns:
      The modified JsArray with the updated value at the specified index.

    • set

      public JsArray set(JsPath path, JsValue value, JsValue padElement)
      Description copied from interface: Json
      Inserts an element at the specified path in this JSON, replacing any existing element.
      Specified by:
      set in interface Json<JsArray>
      Parameters:
      path - The path to insert the element.
      value - The element to insert.
      padElement - The element to use for padding in arrays when necessary.
      Returns:
      A new JSON with the inserted element, or this instance if the head of the path is incompatible.

    • reduce

      public <R> Optional<R> reduce(BinaryOperator<R> op, BiFunction<? super JsPath,? super JsPrimitive,R> map, BiPredicate<? super JsPath,? super JsPrimitive> predicate)
      Description copied from interface: Json
      Reduces the values of this JSON object that satisfy the given predicate, allowing access to the element's path. This reduction traverses the entire JSON recursively if necessary.
      Specified by:
      reduce in interface Json<JsArray>
      Type Parameters:
      R - the type of the reduction result
      Parameters:
      op - the operator to apply to values of type R
      map - the mapping function to convert JsPath and JsPrimitive to type R
      predicate - the predicate that determines which values are included in the reduction
      Returns:
      an Optional describing the result of the reduction, or empty if no values satisfy the predicate

    • reduce

      public <R> Optional<R> reduce(BinaryOperator<R> op, Function<? super JsPrimitive,R> map, Predicate<? super JsPrimitive> predicate)
      Description copied from interface: Json
      Reduces the values of this JSON object that satisfy the given predicate. This reduction traverses the entire JSON recursively if necessary.
      Specified by:
      reduce in interface Json<JsArray>
      Type Parameters:
      R - the type of the reduction result
      Parameters:
      op - the operator to apply to values of type R
      map - the mapping function to convert JsValue to type R
      predicate - the predicate that determines which values are included in the reduction
      Returns:
      an Optional describing the result of the reduction, or empty if no values satisfy the predicate

    • delete

      public JsArray delete(JsPath path)
      Description copied from interface: Json
      Removes the element at the specified path within this immutable JSON object, if it exists. Returns a new JSON object with the element removed, or the original JSON object if the element does not exist.
      Specified by:
      delete in interface Json<JsArray>
      Parameters:
      path - the path specifying the element to be removed
      Returns:
      a new JSON object with the specified element removed, or the original JSON object if the element does not exist

    • size

      public int size()
      Description copied from interface: Json
      Returns the number of elements in the first level of this JSON object or array. This method provides the count of elements directly contained in the JSON object or array.
      Specified by:
      size in interface Json<JsArray>
      Returns:
      the number of elements in the first level of this JSON object or array

    • stream

      public Stream<JsPair> stream()
      Description copied from interface: Json
      Returns a stream over all the key-value pairs JsPair of elements in this JSON object. This method provides a way to traverse and operate on the key-value pairs within the JSON object.
      Specified by:
      stream in interface Json<JsArray>
      Returns:
      a Stream over all the key-value pairs (JsPairs) in this JSON object

    • streamOfValues

      public Stream<JsValue> streamOfValues()
      Returns a non-recursive stream of values contained within the JSON-like array. This stream allows for sequential processing of the immediate values in the array without recursively traversing nested objects or arrays.
      Returns:
      A stream of JsValue objects representing the immediate values in the array.
      See Also:

    • get

      public JsValue get(int i)
      Returns the element located at the specified index or JsNothing if it doesn't exist. This method is a total function and never throws exceptions.
      Parameters:
      i - The index of the element to retrieve.
      Returns:
      A JsValue representing the element at the specified index, or JsNothing if it doesn't exist.

    • hashCode

      public int hashCode()
      equals method is inherited, so it's implemented. The purpose of this method is to cache the hashcode once calculated. the object is immutable and it won't change Single-check idiom Item 83 from Effective Java
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object that)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      // Single-check idiom Item 83 from effective java
      Overrides:
      toString in class Object

    • head

      public JsValue head()
      Returns the first element of this array.
      Returns:
      The first JsValue of this JsArray.
      Throws:
      UserError - If this JsArray is empty.

    • tail

      public JsArray tail()
      Returns a JSON array consisting of all elements of this array except the first one.
      Returns:
      A JsArray consisting of all the elements of this JsArray except the head.
      Throws:
      UserError - If this JsArray is empty.

    • init

      public JsArray init()
      Returns all the elements of this array except the last one.
      Returns:
      A JsArray containing all the JsValue elements except the last one.
      Throws:
      UserError - If this JsArray is empty.

    • intersection

      public JsArray intersection(JsArray that, JsArray.TYPE ARRAY_AS)
      this.union(that, SET) returns this plus those elements from that that don't exist in this. this.union(that, MULTISET) returns this plus those elements from that appended to the back. this.union(that, LIST) returns this plus those elements from that which position is >= this.size(). For those elements that are containers of the same type and are located at the same position, the result is their intersection. So this operation is kind of a recursive intersection
      Specified by:
      intersection in interface Json<JsArray>
      Parameters:
      that - the other array
      ARRAY_AS - the array merging strategy, either 'MERGE' or 'REPLACE'
      Returns:
      a JsArray of the same type as the inputs

    • isArray

      public boolean isArray()
      Description copied from interface: JsValue
      Returns true if this JsValue is a JsArray.
      Specified by:
      isArray in interface JsValue
      Returns:
      True if this JsValue is a JsArray.

    • iterator

      public Iterator<JsValue> iterator()
      Specified by:
      iterator in interface Iterable<JsValue>

    • last

      public JsValue last()
      Returns the last element of this array.
      Returns:
      The last JsValue of this JsArray.
      Throws:
      UserError - If this JsArray is empty.

    • prepend

      public JsArray prepend(JsValue e, JsValue... others)
      Adds one or more elements, starting from the last, to the front of this array.
      Parameters:
      e - The JsValue to be added to the front.
      others - More optional JsValue elements to be added to the front.
      Returns:
      A new JsArray containing the elements added to the front.

    • prependAll

      public JsArray prependAll(JsArray array)
      Adds all the elements of the JsArray, starting from the last, to the front of this array.
      Parameters:
      array - The JsArray of elements to be added to the front.
      Returns:
      A new JsArray containing all the elements added to the front.

    • delete

      public JsArray delete(int index)
      Deletes the element at the specified index from this JsArray.
      Parameters:
      index - The index of the element to be deleted.
      Returns:
      A new JsArray with the element at the specified index removed.
      Throws:
      IllegalArgumentException - if the index is negative.

    • union

      public JsArray union(JsArray that, JsArray.TYPE ARRAY_AS)
      Description copied from interface: Json
      Computes the union of this JSON and another JSON object 'that' with respect to the given array merging strategy. The union of two JSON objects is another JSON object that contains all the key-value pairs present in either 'this' or 'that'. If a key is present in both JSON objects, the value from 'this' will be used. Array merging strategy 'ARRAY_AS' determines how arrays are merged during the union operation. If 'ARRAY_AS' is 'MERGE', arrays are merged by concatenating elements. If 'ARRAY_AS' is 'REPLACE', arrays in 'this' will be replaced with arrays from 'that'.
      Specified by:
      union in interface Json<JsArray>
      Parameters:
      that - the other JSON object to compute the union with
      ARRAY_AS - the array merging strategy, either 'MERGE' or 'REPLACE'
      Returns:
      a new JSON object representing the union of 'this' and 'that'