Class JSArray

java.lang.Object
org.bzdev.util.JSArray
All Implemented Interfaces:
Iterable<Object>, JSOps
Direct Known Subclasses:
ExpressionParser.ESPArray, NJSArray

public class JSArray extends Object implements Iterable<Object>, JSOps
Simplified JavaScript-like array (or list) class. Formats such as JSON are syntactically similar to the source code for JavaScript arrays and JavaScript objects that contain properties but not methods, to the source code for JavaScript arrays, and the source code for numbers, strings, boolean values, and (of course) the value null. The types of the values that can be inserted into this object are JSObject, JSArray, Boolean, Number, and String.

The class JSUtilities.JSON can be used to create instances of JSObject and JSArray, given a variety of sources, and these instances can then be used as the input for various computation.

This class is based on the ArrayList class, but with some run-time type checking. Only a subset of the methods for ArrayList are implemented. In addition to primitive values, entries in the list can be other instances of this class or instances of JSArray, allowing trees or directed graphs to be constructed. Iterators will list the values in the order of their indices.

See Also:
  • Constructor Details

    • JSArray

      public JSArray()
      Constructor.
    • JSArray

      protected JSArray(JSArray base)
      Constructor sharing the same tables. This is used by NJSArray.
      Parameters:
      base - the JSArray whose tables should be used
  • Method Details

    • identity

      public long identity()
      Description copied from interface: JSOps
      Get an integer identifying an instance of a class.
      Specified by:
      identity in interface JSOps
      Returns:
      the identity
    • add

      public boolean add(JSObject object)
      Add an instance of JSObject.
      Parameters:
      object - the object to append to this array/list
      Returns:
      true (as specified by Collection.add(E)).
    • add

      public boolean add(JSArray array)
      Add an instance of JSArray.
      Parameters:
      array - the object to append to this array/list
      Returns:
      true (as specified by Collection.add(E)).
    • add

      public boolean add(Number value)
      Add an instance of Number.
      Parameters:
      value - the number to append to this array/list
      Returns:
      true (as specified by Collection.add(E)).
    • add

      public boolean add(String string)
      Add an instance of String.
      Parameters:
      string - the string to append to this array/list
      Returns:
      true (as specified by Collection.add(E)).
    • add

      public boolean add(Boolean value)
      Add an instance of Boolean.
      Parameters:
      value - the boolean value to append to this array/list
      Returns:
      true (as specified by Collection.add(E)).
    • add

      public boolean add(Object object) throws IllegalArgumentException
      Add any allowed object. The object's type must be assignable
      Parameters:
      object - the object to append to this array/list
      Returns:
      true (as specified by Collection.add(E)).
      Throws:
      IllegalArgumentException - if the object has the wrong type
    • addObject

      public boolean addObject(Object object)
      Add any allowed object. This is used by NJSArray and ObjectNamerLauncher.
      Parameters:
      object - the object to append to this array/list
      Returns:
      true (as specified by Collection.add(E)).
    • get

      public Object get(int index)
      Get the value stored in this object for a specified index.
      Parameters:
      index - the index
      Returns:
      the object stored at the specified index
    • set

      public Object set(int index, Object object) throws IllegalArgumentException, IndexOutOfBoundsException
      Set any allowed object at a specified index. This is used by NJSArray.
      Parameters:
      index - the index
      object - the object to insert at the specified index
      Returns:
      the previous object stored at the specified index
      Throws:
      IndexOutOfBoundsException - if index < 0 or index ≥ size()
      IllegalArgumentException - if the object has the wrong type
    • setObject

      public Object setObject(int index, Object object)
      Set any object at a specified index. This is used by NJSArray and ObjectNamerLauncher.
      Parameters:
      index - the index
      object - the object to insert at the specified index
      Returns:
      the previous object stored at the specified index
      Throws:
      IndexOutOfBoundsException - if index < 0 or index ≥ size()
    • size

      public int size()
      Get the number of elements in this array.
      Specified by:
      size in interface JSOps
      Returns:
      the number of elements
    • stream

      public Stream<Object> stream()
      Get a stream with this array as its source.
      Returns:
      a stream with this array as its source
    • iterator

      public Iterator<Object> iterator()
      Specified by:
      iterator in interface Iterable<Object>
    • spliterator

      public Spliterator<Object> spliterator()
      Specified by:
      spliterator in interface Iterable<Object>
    • toArray

      public Object[] toArray()
      Convert this object to an array.
      Returns:
      the array
    • toArray

      public <T> T[] toArray(Class<T> clasz)
      Convert this object to an array, storing it in an array with a specified component type.
      Type Parameters:
      T - the type provided by the class clasz
      Parameters:
      clasz - the class of the array components
      Returns:
      the array
      Throws:
      ArrayStoreException - if the argument is not a superclass of the runtime type of this object's elements
    • toDoubleArray

      public double[] toDoubleArray() throws IllegalStateException
      Convert this object to an array of double.
      Returns:
      the array
      Throws:
      IllegalStateException - the conversion failed
    • toLongArray

      public long[] toLongArray() throws IllegalStateException
      Convert this object to an array of long.
      Returns:
      the array
      Throws:
      IllegalStateException - the conversion failed
    • toIntArray

      public int[] toIntArray() throws IllegalStateException
      Convert this object to an array of int.
      Returns:
      the array
      Throws:
      IllegalStateException - the conversion failed
    • toBooleanArray

      public boolean[] toBooleanArray() throws IllegalStateException
      Convert this object to an array of boolean.
      Returns:
      the array
      Throws:
      IllegalStateException - the conversion failed
    • toMatrix

      public Object[][] toMatrix() throws IllegalStateException
      Convert this object to a matrix of type double. A matrix is represented by a two-dimensional Java array where each row has the same number of elements.
      Returns:
      the matrix.
      Throws:
      IllegalStateException - the conversion failed
    • toMatrix

      public <T> T[][] toMatrix(Class<T> clasz) throws IllegalStateException
      Convert this object to an matrix, storing it in a matrix with a specified component type. The matrix is represented by a two-dimensional Java array and all rows must have the same number of elements.
      Type Parameters:
      T - the type provided by the class clasz
      Parameters:
      clasz - the class of the matrix components
      Returns:
      the array
      Throws:
      IllegalStateException - the conversion failed
    • toDoubleMatrix

      public double[][] toDoubleMatrix() throws IllegalStateException
      Convert this object to a matrix whose components are of the primitive type double. A matrix is represented by a two-dimensional Java array where each row has the same number of elements.
      Returns:
      the matrix.
      Throws:
      IllegalStateException - the conversion failed
    • toLongMatrix

      public long[][] toLongMatrix() throws IllegalStateException
      Convert this object to a matrix whose components are of the primitive type long. A matrix is represented by a two-dimensional Java array where each row has the same number of elements.
      Returns:
      the matrix.
      Throws:
      IllegalStateException - the conversion failed
    • toIntMatrix

      public int[][] toIntMatrix() throws IllegalStateException
      Convert this object to a matrix whose components are of the primitive type int. A matrix is represented by a two-dimensional Java array where each row has the same number of elements.
      Returns:
      the matrix.
      Throws:
      IllegalStateException - the conversion failed
    • toBooleanMatrix

      public boolean[][] toBooleanMatrix() throws IllegalStateException
      Convert this object to a matrix whose components are of the primitive type boolean. A matrix is represented by a two-dimensional Java array where each row has the same number of elements.
      Returns:
      the matrix.
      Throws:
      IllegalStateException - the conversion failed
    • parallelStream

      public Stream<Object> parallelStream()
      Get a possibly parallel stream with this array as its source.
      Returns:
      a stream with this array as its source
    • forEach

      public void forEach(Consumer<? super Object> action)
      Performs the given action for each element of the array until all elements have been processed or the action throws an exception. Actions are performed in the order of iteration, if that order is specified. Exceptions thrown by the action are relayed to the caller.

      Note: the description is copied from the ArrayList documentation.

      Specified by:
      forEach in interface Iterable<Object>
      Parameters:
      action - the action to be performed for each element
    • get

      public <T> T get(int index, Class<T> clasz)
      Get the value stored in this object for a specified index, cast to a specified type.
      Type Parameters:
      T - the type provided by the class clasz
      Parameters:
      index - the index
      clasz - the class of the result
      Returns:
      the object stored at the specified index
    • toKeyMapList

      public TemplateProcessor.KeyMapList toKeyMapList(String defaultKey) throws JSArray.ConversionException
      Convert this JSArray to a TemplateProcessor.KeyMapList. The elements of this list are processed as follows:
      • if the element is an instance of JSObject, that instance is converted to a key map by using the method JSObject.toKeyMap().
      • if the element is an instance of JSArray, the conversion proceeds as follows:
        1. A new key-map list will be created by calling the element's method toKeyMapList(defaultKey), where defaultKey is the argument to this method.
        2. The element will be replaced with a new key map that contains a single entry. That entry's key is defaultKey and its value is the new key-map list created in step 1.
        3. The modified element is added to the resulting key-map list.
      • if the element is not an instance of JSObject and not an instance of JSArray, a new key map will be added and a single entry will be added to that new key map with a key equal to the default key and its value equal to the element itself.
      There is one constraint: if the JSArray contains another JSArray, all the elements that are not instances of JSObject must be instances of JSArray.

      This method is used internally for the case where an element in a JSArray is another JSArray.

      Parameters:
      defaultKey - the key to use in single-entry key maps
      Returns:
      a key-map list containing those list elements that are instances of JSObject
      Throws:
      JSArray.ConversionException - the list contained elements that are instances of JSArray and also elements that are not instances of JSObject
      See Also:
    • toKeyMapList

      public TemplateProcessor.KeyMapList toKeyMapList()
      Convert this JSArray to a TemplateProcessor.KeyMapList. Elements in the list that are not instances of JSObject are ignored.
      Returns:
      a key-map list containing those list elements that are instances of JSObject.