10.7.12 Json

Functions for working with JSON strings.

Usage of this class to manipulate hierarchical JSON objects is a bit different from the way that most of the other functions in the expression language are used. The main function provided by this class is jsonObject, which can be applied to a string value containing a JSON object (legal JSON object strings are enclosed in curly brackets), and returns a JSONObject instance. This JSONObject cannot be used on its own in the rest of the application, but various methods can be applied to it to extract information from its structure. These methods are applied by writing jsonObject.method(arg,arg,...) rather than function(jsonObject,arg,arg,...).

Methods you can apply to a JSONObject include:

• getString(key)
• getInt(key)
• getDouble(key)
• getBoolean(key)
• getJSONObject(key)
• getJSONArray(key)

where key is a string giving the name with which the member of the JSON object is associated. The first four of the above methods give you string, numeric, or boolean values that you can use in the application for plotting etc. getJSONObject returns another JSONObject that you can interrogate with further methods. getJSONArray gives you a JSONArray.

You can apply a different set of methods to a JSONArray, including:

• getString(index)
• getInt(index)
• getDouble(index)
• getBoolean(index)
• getJSONObject(index)
• getJSONArray(index)

where index is an integer giving the (zero-based) index of the element in the array that you want.

Using these methods you can drill down into the hierarchical structure of a JSON string to retrieve the string, numeric or boolean values that you need. If you are not familiar with this syntax, an example is the best way to illustrate it. Consider the following JSON string, which may be the value in a column named txt:

    {
       "sequence": 23,
       "temperature": {
          "value": 278.5,
          "units": "Kelvin"
       },
       "operational": true,
       "readings": [12, null, 23.2, 441, 0]
    }
 

    jsonObject(txt).getInt("sequence")
 

    jsonObject(txt).getJSONObject("temperature").getDouble("value")
 

    jsonObject(txt).getJSONArray("readings").getDouble(0)
 

Other methods are available on JSONObject and JSONArray; you can currently find documentation on them at https://stleary.github.io/JSON-java/. Note in particular that each of the JSONObject.get*(key) and JSONArray.get*(index) methods is accompanied by a corresponding opt* method; where the key/index may not exist, this will probably give effectively the same behaviour (generating a blank result) but may be considerably faster.

This class also contains some other utility functions for working with JSONObjects and JSONArrays; see the function documentation below for details.

Note: This class is somewhat experimental, and the functions and methods may change in future. An attempt will be made to retain the functions and methods described in this section, but those described in the external JSON-java javadocs may be subject to change.

jsonObject( txt )

Converts the supplied string to a JSONObject which can be interrogated further. If the input string doesn't have the syntax of a JSON object, an empty JSONObject will be returned.

The JSON parsing is currently somewhat lenient, for instance allowing a comma before a closing curly bracket.

• Parameters:
  • txt (String): string assumed to contain a JSON object
• Return value
  • (JSONObject): JSON object value on which further methods can be called

jsonArray( txt )

Converts the supplied string to a JSONArray which can be interrogated further. If the input string doesn't have the syntax of a JSON array, a zero-length JSONArray will be returned.

The JSON parsing is currently somewhat lenient, for instance allowing a comma before a closing square bracket.

• Parameters:
  • txt (String): string assumed to contain a JSON array
• Return value
  • (JSONArray): JSON array value on which further methods can be called

jsonObjectOpt( txt )

Converts the supplied string to a JSON object which can be interrogated further. If the input doesn't have the syntax of a JSON object, null will be returned.

For most purposes this will behave the same as the jsonObject function, but it may be slower if there are many invalid or empty JSON strings.

• Parameters:
  • txt (String): JSON object text
• Return value
  • (JSONObject): JSON object value on which further methods can be called, or null

jsonArrayOpt( txt )

Converts the supplied string to a JSONArray which can be interrogated further. If the input string doesn't have the syntax of a JSON array, null will be returned.

• Parameters:
  • txt (String): JSON object text
• Return value
  • (JSONArray): JSON array value on which further methods can be called, or null

jsonToDoubles( jsonArray )

Converts a JSONArray to an array of floating point values. The result will be the same length as the supplied JSONArray, and any element in the JSONArray which cannot be interpreted as a floating point value is represented by a NaN.

• Parameters:
  • jsonArray (JSONArray): JSON Array
• Return value
  • (array of floating point): floating point array the same length as the input array
• Example:
  • jsonToDoubles(jsonArray("[true, \"two\", 3.0, 4, null"])) = [NaN, NaN, 3.0, 4.0, NaN]

jsonToStrings( jsonArray )

Converts a JSONArray to an array of string values.

• Parameters:
  • jsonArray (JSONArray): JSON Array
• Return value
  • (array of String): string array the same length as the input array
• Example:
  • jsonToStrings(jsonArray("[true, \"two\", 3.0, 4, null]")) = ["true", "two", "3.0", "4", null]

jsonGetKeys( jsonObject )

Returns an array giving keys for each key-value pair in a JSON object. The members of a JSON object are not ordered, so no order can be guaranteed in the output array.

• Parameters:
  • jsonObject (JSONObject): JSON object
• Return value
  • (array of String): string array containing keys of object
• Example:
  • jsonGetKeys(jsonObject("{\"one\", 1, \"two\", 2, \"three\", 3}")) = ["one", "two", "three"]