uk.ac.starlink.ttools.func

Class Json

java.lang.Object

uk.ac.starlink.ttools.func.Json

public class Json
extends Object

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]
    }
 

To obtain the sequence value, you can write:

    jsonObject(txt).getInt("sequence")
 

to obtain the numeric temperature value, you can write:

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

and to obtain the first element of the readings array, you can write:

    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.

Since:

21 Nov 2023

Author:

Mark Taylor

Method Summary

Modifier and Type	Method and Description
static org.json.JSONArray	jsonArray(String txt) Converts the supplied string to a JSONArray which can be interrogated further.
static org.json.JSONArray	jsonArrayOpt(String txt) Converts the supplied string to a JSONArray which can be interrogated further.
static String[]	jsonGetKeys(org.json.JSONObject jsonObject) Returns an array giving keys for each key-value pair in a JSON object.
static org.json.JSONObject	jsonObject(String txt) Converts the supplied string to a JSONObject which can be interrogated further.
static org.json.JSONObject	jsonObjectOpt(String txt) Converts the supplied string to a JSON object which can be interrogated further.
static double[]	jsonToDoubles(org.json.JSONArray jsonArray) Converts a JSONArray to an array of floating point values.
static String[]	jsonToStrings(org.json.JSONArray jsonArray) Converts a JSONArray to an array of string values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

jsonObject

public static org.json.JSONObject jsonObject(String 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 assumed to contain a JSON object

Returns:

JSON object value on which further methods can be called

jsonArray

public static org.json.JSONArray jsonArray(String 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 assumed to contain a JSON array

Returns:

JSON array value on which further methods can be called

jsonObjectOpt

public static org.json.JSONObject jsonObjectOpt(String 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 - JSON object text

Returns:

JSON object value on which further methods can be called, or null

jsonArrayOpt

public static org.json.JSONArray jsonArrayOpt(String 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 - JSON object text

Returns:

JSON array value on which further methods can be called, or null

jsonToDoubles

public static double[] jsonToDoubles(org.json.JSONArray 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 - JSON Array

Returns:

floating point array the same length as the input array

jsonToStrings

public static String[] jsonToStrings(org.json.JSONArray jsonArray)

Converts a JSONArray to an array of string values.

Parameters:

jsonArray - JSON Array

Returns:

string array the same length as the input array

jsonGetKeys

public static String[] jsonGetKeys(org.json.JSONObject 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 - JSON object

Returns:

string array containing keys of object