Operations

JSONXOP_AddTree

Creates objects for the full location path in the JSON text:

JSONXOP_AddTree [/Q[=q] /Z[=z]] /T=type jsonId, jsonPath

The JSONXOP_AddTree operation takes a location string jsonPath and a JSON text jsonId and creates objects for all path elements that are not already present. The last element in jsonPath must be either an object or an array.

Parameters

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

Flags

/T=type

Defines the type of the last created entity. type must be either 0 or 1.

/T=0:

Last created element is an object.

/T=1:

Last created element is an array.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

Existing jsonPath elements are left unchanged.

A runtime error is generated if an element of jsonPath exists but is not an array or object.

If an element of jsonPath is a non-empty array, an index specification must follow, e.g. /nonEmptyArray/3/myNewObject.

If an element of jsonPath is an empty array, /0 is allowed as an index specification but is not required.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples

Creates a new JSON text, creates the path to two objects and one array, and shows the textual representation:

Function JSONXOP_AddTree_example1()

    variable jsonId

    JSONXOP_New
    jsonId = V_value
    JSONXOP_AddTree/T=0 jsonId, "/Movies/Action/Arnold"
    JSONXOP_AddTree/T=0 jsonId, "/Movies/Action/!Arnold"
    JSONXOP_AddTree/T=1 jsonId, "/Movies/Rating"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Movies": {
    "Action": {
      "!Arnold": {},
      "Arnold": {}
    },
    "Rating": []
  }
}

Creates a new JSON text, creates the path to an array, then creates objects in the array and shows the textual representation:

Function JSONXOP_AddTree_example2()

    variable jsonId

    JSONXOP_New
    jsonId = V_value
    JSONXOP_AddTree/T=1 jsonId, "/Movies/Rating"
    JSONXOP_AddTree/T=0 jsonId, "/Movies/Rating/0/RottenPotatoes" // implicit object creation
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Movies": {
    "Rating": [
      {
        "RottenPotatoes": {}
      }
    ]
  }
}

Creates objects and arrays with a path that contains an array index:

Function JSONXOP_AddTree_example3()

    variable jsonId

    JSONXOP_New
    jsonId = V_value

    JSONXOP_AddTree/T=1 jsonId, "/Movies"
    JSONXOP_AddValue/OBJ=2 jsonId, "/Movies"

    JSONXOP_AddTree/T=1 jsonId, "/Movies/0/Titanic/year"
    Make/FREE/I years = {1997, 2011}
    JSONXOP_AddValue/WAVE=years/O jsonId, "/Movies/0/Titanic/year"

    JSONXOP_AddTree/T=1 jsonId, "/Movies/1/Solaris/year"
    Make/FREE/I years = {1972, 2002}
    JSONXOP_AddValue/WAVE=years/O jsonId, "/Movies/1/Solaris/year"

    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Movies": [
    {
      "Titanic": {
        "year": [
          1997,
          2011
        ]
      }
    },
    {
      "Solaris": {
        "year": [
          1972,
          2002
        ]
      }
    }
  ]
}

See Also

JSONXOP_AddValue

JSONXOP_AddValue

Adds a value to the JSON text:

JSONXOP_AddValue [/Q[=q] /Z[=z] /O /JOIN=childId /OBJ[=objNr] /WAVE=waveIn /L=waveI64 /B=boolVal /I=intVal /N /S=sigNr /T=text /V=value] jsonId, jsonPath

The JSONXOP_AddValue operation adds values, arrays or objects to the JSON text.

Parameters

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

Flags

/B=boolVal

Adds a boolean value. A value of 0 represents false, other values true. Values of NaN or +/-Inf result in a runtime error.

/I=intVal

Adds a numeric value as an integer. The type of intVal is a standard Igor Pro variable with double precision. It is truncated towards the closest integer value to zero. Values of NaN or +/-Inf result in a runtime error. The lowest intVal allowed is -2^63 and the highest 2^63 - 2^10.

/JOIN=childId

Places the content of the JSON text referenced by childId at the location at jsonPath in the JSON text jsonId. The caller keeps ownership of childId. It is NOT freed by this call.

/L=waveI64

Adds a signed or unsigned 64 bit integer value. waveI64 must be a wave of signed/unsigned 64 bit integer type and must have exactly one point.

/N

Adds a null value.

/O

Overwrites the element in the JSON text instead of adding a new value.

/OBJ=objNr

Adds one or more empty objects {}. objNr sets the number of objects that are added. objNr must be >= 1. /OBJ is identical to /OBJ=1. Multiple objects can only be added to arrays, thus jsonPath must point to an array when objNr is greater than one.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/S=sigNr

When adding floating point values with /V or /WAVE, set the number of significant digits after the decimal point with this flag. sigNr must be >= 0. The maximum of significant digits is limited to 15.

/T=text

Adds a string value.

/V=value

Adds a numeric value as floating point. This flag can be combined with /S to limit the significant digits after the decimal point.

/WAVE=waveIn

Adds a wave as an array. The type of the array elements in the JSON object is derived from the wave type. Waves with complex numbers are not supported. When waves of floating point number type are added, the flag can be combined with the /S flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

Only one of /B, /I, /L, /N, /T, /V, /JOIN, /OBJ or /WAVE is allowed per operation call.

The last element of jsonPath specifies the name of the possibly created object. Thus, a typical form of jsonPath when used with JSONXOP_AddValue is /basePath/newKey where /basePath is an existing location. Empty strings are also valid object names, such that a location specification of /path/ refers to a new object "" at /path. A special case is adding values to arrays in the JSON text. When the location referenced by jsonPath is an array, a new element is appended to that array. Indexing into array elements is done via zero-based indices, e.g. the second element of the array arr is at /arr/1.

When JSON text elements are overwritten with /O, jsonPath must point to an existing location.

The special floating point values NaN or +/-Inf are added to the JSON text as the strings "NaN", "Inf" or "-Inf". When retrieved as number with JSONXOP_GetValue, these strings are converted back to NaN or +/-Inf.

Adding a wave with zero elements, creates a JSON array with zero size at the given path.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples

Adds primitive types to a new JSON text, then dumps and displays it:

Function JSONXOP_AddValue_example1()

    variable jsonId

    JSONXOP_New
    jsonId = V_value
    JSONXOP_AddValue/V=12.34 jsonId, "/FloatingPointValue"
    JSONXOP_AddValue/I=1234 jsonId, "/IntegerValue"
    JSONXOP_AddValue/B=1 jsonId, "/Boolean"
    JSONXOP_AddValue/N jsonId, "/Null"
    JSONXOP_AddValue/T="Igor Pro" jsonId, "/String"
    JSONXOP_AddValue/OBJ jsonId, "/NewEmptyObject"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Boolean": true,
  "FloatingPointValue": 12.34,
  "IntegerValue": 1234,
  "NewEmptyObject": {},
  "Null": null,
  "String": "Igor Pro"
}

Adds a 1d and a 2d integer wave to a new JSON text, then dumps and displays it:

Function JSONXOP_AddValue_example2()

    variable jsonId

    Make/O/I wave1d = {1, 2, 3, 4}
    Make/O/I wave2d = {{1, 2}, {3, 4}}

    JSONXOP_New
    jsonId = V_value
    JSONXOP_AddValue/WAVE=wave1d jsonId, "/Wave1d"
    JSONXOP_AddValue/WAVE=wave2d jsonId, "/Wave2d"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Wave1d": [
    1,
    2,
    3,
    4
  ],
  "Wave2d": [
    [
      1,
      3
    ],
    [
      2,
      4
    ]
  ]
}

Adds floating point numbers with special values to a new JSON text, then dumps and displays it:

Function JSONXOP_AddValue_example3()

    variable jsonId

    Make/O wave1d = {1, NaN, Inf, -Inf, 2}

    JSONXOP_New
    jsonId = V_value
    JSONXOP_AddValue/V=(NaN) jsonId, "/SpecialNaNValue"
    JSONXOP_AddValue/V=(Inf) jsonId, "/SpecialInfValue"
    JSONXOP_AddValue/V=(-Inf) jsonId, "/SpecialNegInfValue"
    JSONXOP_AddValue/WAVE=wave1d jsonId, "/Wave1dSpecial"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "SpecialInfValue": "Inf",
  "SpecialNaNValue": "NaN",
  "SpecialNegInfValue": "-Inf",
  "Wave1dSpecial": [
    1.0,
    "NaN",
    "Inf",
    "-Inf",
    2.0
  ]
}

Add values to a 1d and 2d array in JSON object, then dumps and displays it:

Function JSONXOP_AddValue_example4()

    variable jsonId

    Make/O/I wave1d = {1, 2, 3}
    Make/O/I wave2d = {{1, 2}, {3, 4}}

    JSONXOP_New
    jsonId = V_value
    JSONXOP_AddValue/WAVE=wave1d jsonId, "/Array1d"
    JSONXOP_AddValue/WAVE=wave2d jsonId, "/Array2d"
    JSONXOP_AddValue/V=5 jsonId, "/Array1d"
    JSONXOP_AddValue/V=6 jsonId, "/Array2d"
    JSONXOP_AddValue/V=7 jsonId, "/Array2d/1" // specify sub array
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Array1d": [
    1,
    2,
    3,
    5.0
  ],
  "Array2d": [
    [
      1,
      3
    ],
    [
      2,
      4,
      7.0
    ],
    6.0
  ]
}

Overwrites values in a JSON text, then dumps and displays it:

Function JSONXOP_AddValue_example5()

    variable jsonId

    Make/O/I wave1d = {1, 2, 3}

    JSONXOP_New
    jsonId = V_value
    JSONXOP_AddValue/WAVE=wave1d jsonId, "/Array1d"
    JSONXOP_AddValue/I=1 jsonId, "/data"
    // Overwrite some values
    JSONXOP_AddValue/O/T="two" jsonId, "/Array1d/1"
    JSONXOP_AddValue/O/T="one" jsonId, "/data"

    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Array1d": [
    1,
    "two",
    3
  ],
  "data": "one"
}

Demonstrates various more specific cases for JSONXOP_AddValue:

Function JSONXOP_AddValue_example6()

    variable jsonId, jsonId2

    JSONXOP_New
    jsonId = V_value
    // Add floating point value with two significant digits after the dot
    JSONXOP_AddValue/V=1.234567 /S=2 jsonId, "TwoDigitsSignificance"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value

    JSONXOP_New
    jsonId = V_value
    // Add a 64 bit integer value
    Make/O/N=1/L/U int64Number
    int64Number[0] = 0xFFFFFFFFFFFFFFFF
    JSONXOP_AddValue/L=int64Number jsonId, "/64 bit unsigned Integer"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value

    JSONXOP_New
    jsonId = V_value
    // Add an anonymous value to the root
    JSONXOP_AddValue/T="String data in root" jsonId, ""
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value

    JSONXOP_New
    jsonId = V_value
    // Add a key value pair where the key is an empty string
    JSONXOP_AddValue/T="has an empty key" jsonId, "/"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value

    JSONXOP_Parse "{\"object array\":[]}"
    jsonId = V_value
    // Add multiple objects to an array
    JSONXOP_AddValue/OBJ=3 jsonId, "/object array"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value

    JSONXOP_Parse "{\"first part of data\":1}"
    jsonId = V_value
    JSONXOP_Parse "2"
    jsonId2 = V_value
    // Join two JSON objects
    JSONXOP_AddValue/JOIN=(jsonId2) jsonId, "/second part of data"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value

    JSONXOP_Release/A
End

Output:

Full textual representation:
{
  "TwoDigitsSignificance": 1.23
}
Full textual representation:
{
  "64 bit unsigned Integer": 18446744073709551615
}
Full textual representation:
"String data in root"
Full textual representation:
{
  "": "has an empty key"
}
Full textual representation:
{
  "object array": [
    {},
    {},
    {}
  ]
}
Full textual representation:
{
  "first part of data": 1,
  "second part of data": 2
}

See Also

JSONXOP_GetValue, JSONXOP_AddTree

JSONXOP_Dump

Dumps a JSON text to its textual representation:

JSONXOP_Dump [/Q[=q] /Z[=z] /IND=indent] jsonId

The JSONXOP_Dump operation returns the textual representation of a JSON text in S_value.

Parameters

jsonId

Identifier of the JSON text.

Flags

/IND=indent

Based on the structure of the JSON text, the key value pairs in the textual output are indented by indent spaces. Valid values for indent are -1 to 10. The value is truncated towards the closest integer to zero.

/IND=-1:

Outputs the compact form without any additional newlines or spaces.

/IND=0:

Outputs with a newline after each key value pair and object begin. This is the same as omitting the flag.

/IND=1:

Outputs with a newline after each key value pair and object begin. For each level into the JSON text structure one space is added after each newline.

/IND=>1:

For indent values greater than one indent spaces are added after each newline.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The JSON text is not changed by this operation.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

S_value

Textual representation of the JSON text.

Examples

Parses a string to a new JSON text, dumps its content to textual representation with indentation two, outputs and releases it:

Function JSONXOP_Dump_example1()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Fridge\":{"
    jsonStr += "\"Milk\":\"half empty\","
    jsonStr += "\"Batteries\":2},"
    jsonStr += "\"Freezer\":{"
    jsonStr += "\"FishSticks\":15,"
    jsonStr += "\"Straciatella\":\"Big Box\"}"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Freezer": {
    "FishSticks": 15,
    "Straciatella": "Big Box"
  },
  "Fridge": {
    "Batteries": 2,
    "Milk": "half empty"
  }
}

See Also

JSONXOP_New, JSONXOP_Parse, JSONXOP_Release

JSONXOP_GetArraySize

Returns the array size of a JSON array at a given location:

JSONXOP_GetArraySize [/Q[=q] /Z[=z]] jsonId, jsonPath

The JSONXOP_GetArraySize operation returns the size of the array at the specified location in the JSON text.

Parameters

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

Flags

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The specified location must point to an array. For other types the operation returns a runtime error.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

V_value

Returns the size of the array.

Examples

Parses a JSON object from a string, shows the arrays sizes:

Function JSONXOP_GetArraySize_example1()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Array\":["
    jsonStr += "0, [0, 1], 2, [0, 1, 2], 4, 5"
    jsonStr += "]"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetArraySize jsonId, "/Array"
    print "Array size at /Array :", V_value
    JSONXOP_GetArraySize jsonId, "/Array/1"
    print "Array size at /Array/1 :", V_value
    JSONXOP_GetArraySize jsonId, "/Array/3"
    print "Array size at /Array/3 :", V_value
    JSONXOP_Release jsonId
End

Output:

Array size at /Array :  6
Array size at /Array/1 :  2
Array size at /Array/3 :  3

See Also

JSONXOP_GetValue, JSONXOP_GetMaxArraySize

JSONXOP_GetKeys

Returns the keys of objects at the given location:

JSONXOP_GetKeys [/Q[=q] /Z[=z] /ESC[=e] /FREE] jsonId, jsonPath, textWave

The JSONXOP_GetKeys operation retrieves all names from all objects at a specified location in the JSON text and stores them in textWave.

Parameters

textWave

References a 1d text wave that is created if it does not exist. It holds the list of keys on sucessfull return.

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

Flags

/ESC=e

Sets escaping of the special characters ~ and / in the returned keys.

/ESC=1:

Enables escaping. This is the same as omitting the flag.

/ESC:

Identical to /ESC=1.

/ESC=0:

Disables escaping.

/FREE

textWave is created as a free wave.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The keys of objects in the JSON text can contain any UTF8 character. When building a jsonPath referring to a location in the JSON text, mind that ~ and / are reserved characters. By default, this operation escapes these characters to ~0 and ~1 respectively such that the returned keys can be directly used to build a location string.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples

Parses a JSON text from a string and retrieves the keys from the given location:

Function JSONXOP_GetKeys_example1()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Fridge\":{"
    jsonStr += "\"Milk\":\"half empty\","
    jsonStr += "\"Batteries\":2},"
    jsonStr += "\"Freezer\":{"
    jsonStr += "\"FishSticks\":15,"
    jsonStr += "\"Straciatella\":\"Big Box\"}"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetKeys jsonId, "/Freezer", keyWave
    print "Keys at /Freezer:\r", keyWave
    JSONXOP_Release jsonId
End

Output:

Keys at /Freezer:
keyWave[0]= {"FishSticks","Straciatella"}

See Also

JSONXOP_GetValue, JSONXOP_GetType, JSONXOP_GetMaxArraySize

JSONXOP_GetMaxArraySize

Returns the maxium array sizes of an array at a given location:

JSONXOP_GetMaxArraySize [/Q[=q] /Z[=z] /FREE] jsonId, jsonPath, numWave

The JSONXOP_GetMaxArraySize operation returns the maximum size of all arrays contained in the array at the specified location in the JSON text. The result is returned in numWave which is a 1D wave with as many entries as the array at jsonPath.

Parameters

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

numWave

Returned numerical 1D wave with maximum array dimension(s).

Flags

/FREE

numWave is created as a free wave.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The specified location must point to an array. For other types the operation returns a runtime error.

Arrays in a JSON text can not only contain different types per element; multidimensional arrays can also have different sizes for each sub array. A simple multidimensional array with different sizes for its sub arrays can be defined in JSON as follows: [[0], [1, 0]]. In this example the first sub array contains one element and the second two elements. For reading such an array into Igor Pro, a corresponding wave size is (2, 2). In this case only three elements get read and one stays at the default value. The default value is NaN for floating point waves, 0 for integer waves and an empty string for text waves. JSONXOP_GetMaxArraySize allows one to determine the appropriate wave size without reading the entire array.

The number of elements returned in numWave equals the number of dimensions of the array. Arrays in a JSON text can have more than four dimensions.

For one dimensional arrays or for retrieving the size of a single sub array of a multidimensional array, JSONXOP_GetArraySize is easier to use.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples

Parses a JSON text from a string and outputs the maximum array sizes:

Function JSONXOP_GetMaxArraySize_example1()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Array\":["
    jsonStr += "[0], [0, 1]"
    jsonStr += "]"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetMaxArraySize jsonId, "/Array", maxArraySizes
    print "Maximum array sizes of /Array :", maxArraySizes // 2, 2
    JSONXOP_Release jsonId
End

Output:

Maximum array sizes of /Array :
maxArraySizes[0]= {2,2}

Parses a JSON text from a string and outputs the maximum array sizes:

Function JSONXOP_GetMaxArraySize_example2()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Array\":["
    jsonStr += "[[0], [0, 1], [0, 1, 2]],"
    jsonStr += "[[0, 1, 2, 3]]"
    jsonStr += "]"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetMaxArraySize jsonId, "/Array", maxArraySizes
    print "Maximum array sizes of /Array :", maxArraySizes // 2, 3, 4
    JSONXOP_Release jsonId
End

Output:

Maximum array sizes of /Array :
maxArraySizes[0]= {2,3,4}

See Also

JSONXOP_GetValue, JSONXOP_GetArraySize

JSONXOP_GetType

Returns the type of a value at the given location:

JSONXOP_GetType [/Q[=q] /Z[=z]] jsonId, jsonPath

The JSONXOP_GetType operation returns the type of the value at the specified location in the JSON text.

Parameters

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

Flags

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The following value types are as follows:

0:

Object

1:

Array

2:

Numeric

3:

String

4:

Boolean

5:

Null

When special floating point numbers like NaN or +/-Inf are added with JSONXOP_AddValue, the values are written as the strings "NaN", "Inf" or "-Inf" into the JSON text. Retrieving the type of these values with JSONXOP_GetType returns the type string.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

V_value

The type of the value.

Examples

Parses a JSON text from a string, retrieves the keys and outputs the type of each value:

Function JSONXOP_GetType_example1()

    variable jsonId, i
    string jsonStr, locStr

    Make/FREE/T typeTable = {"Object", "Array", "Numeric", \
                             "String", "Boolean", "Null"}

    jsonStr = "{"
    jsonStr += "\"Object\":{},"
    jsonStr += "\"Array\":[0, 1],"
    jsonStr += "\"Numeric\":2,"
    jsonStr += "\"String\":\"three\","
    jsonStr += "\"Boolean\":true,"
    jsonStr += "\"Null\":null"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetKeys/FREE jsonId, "", keyWave
    for(i = 0; i < DimSize(keyWave, 0); i += 1)
        locStr = "/" + keyWave[i]
        JSONXOP_GetType jsonId, locStr
        print "Type of value at " + locStr + " : ", typeTable[V_value]
    endfor
    JSONXOP_Release jsonId
End

Output:

Type of value at /Array :   Array
Type of value at /Boolean :   Boolean
Type of value at /Null :   Null
Type of value at /Numeric :   Numeric
Type of value at /Object :   Object
Type of value at /String :   String

Parses a JSON text from a string, runs through the array and outputs the type of each value:

Function JSONXOP_GetType_example2()

    variable jsonId, i, arraySize
    string jsonStr, locStr

    Make/FREE/T typeTable = {"Object", "Array", "Numeric", \
                             "String", "Boolean", "Null"}

    jsonStr = "{"
    jsonStr += "\"Array\":["
    jsonStr += "{}, [0, 1], 2, \"three\", true, null"
    jsonStr += "]"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetArraySize jsonId, "/Array"
    arraySize = V_value
    for(i = 0; i < arraySize; i += 1)
        locStr = "/Array/" + num2str(i)
        JSONXOP_GetType jsonId, locStr
        print "Type of value at " + locStr + " : ", typeTable[V_value]
    endfor
    JSONXOP_Release jsonId
End

Output:

Type of value at /Array/0 :   Object
Type of value at /Array/1 :   Array
Type of value at /Array/2 :   Numeric
Type of value at /Array/3 :   String
Type of value at /Array/4 :   Boolean
Type of value at /Array/5 :   Null

See Also

JSONXOP_GetValue, JSONXOP_GetKeys

JSONXOP_GetValue

Reads value(s) from the given location in the JSON text:

JSONXOP_GetValue [/Q[=q] /Z[=z] /FREE /V /T /TWAV=textWave /WAVE=numWave /WM=waveMode /L=i64Wave] jsonId, jsonPath

The JSONXOP_GetValue operation reads values from the JSON text.

Parameters

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

Flags

/FREE

Returned waves are created as free waves. Can only be combined with /WAV or /TWAV. The wave type for created numeric waves is double precision floating point. There are only new waves created if no error occurred. In the case of an error no new wave is created and the wave reference and wave itself is returned unchanged.

/J

Creates a copy of the JSON object from the object referenced by jsonPath in jsonId and returns the new jsonId in V_value.

/L=i64Wave

Reads a single numeric value as 64 bit integer and returns it in i64Wave.

/T

Reads a string value and returns it in S_value.

/TWAV=textWave

Reads an array containing strings to textWave.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/V

Reads a numeric value and returns it in V_value.

/WAVE=numWave

Reads an array containing numeric values to numWave.

/WM=waveMode

Controls the behavior when a JSON element could not be converted to the element type of the wave. For text waves there is always a null wave returned if an element could not be converted. For numeric waves by default NaN is placed if a JSON element could not be converted to the target number type (derived from the wave type). This allows to retrieve convertible elements after that position.

/WM=1:

Return a null wave if an element could not be converted.

/WM:

Is identical to /WM=1.

/WM=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

Only one flag of /J, /L, /T, /TWAV, /WAVE or /V is allowed per operation call.

With /V or /WAVE flags, the strings "NaN", "Inf" or "-Inf" are parsed to NaN, Inf or -Inf respectively.

With /WAVE, the default number type for the returned wave is double precision floating point. If /FREE is omitted, the number type for numWave can be specified before calling JSONXOP_GetValue by creating numWave with the desired type. In case of a possible precision loss on read, e.g. when numWave was created as an integer wave beforehand and a floating point value is read from an array, the operation will print a warning message to the history area and place a 0 value in the wave.

With /J, a copy of the JSON object referenced by jsonPath from jsonId is created. The new json id from the copy is returned in V_value. The original JSON object from jsonId stays unchanged and valid.

With /L, the default data type for the returned wave is signed 64 bit integer. The number type for i64Wave can be specified before calling JSONXOP_GetValue by creating i64Wave with the desired type. Valid types for i64Wave are signed and unsigned 64 bit integer. The created wave must have exactly one element.

Igor Pro supports waves with up to four dimensions. When an array is read with /WAVE or /TWAV and it exceeds four dimensions, a runtime error is generated. JSONXOP_GetMaxArraySize can be used to retrieve the dimensionality and sizes of the array. To read higher dimensional arrays, chunks of sub arrays with a maximum of four dimension have to be read.

Multidimensional arrays in a JSON text can have sub arrays with different sizes. When an array is read with /WAVE or /TWAV, the returned wave’s size is the same as returned by JSONXOP_GetMaxArraySize. Wave elements that do not appear in the array are set to default values in the wave. The default value for floating point waves is NaN, for integer waves 0 and for text waves "".

Arrays in a JSON text can have different types per element. Reading with /WAVE or /TWAV and encountering an invalid type results in a runtime error. Arrays containing different types must therefore be read value by value with /V, /T or /L. The type can be determined with JSONXOP_GetType.

If an empty JSON array is read through /WAVE or /TWAV a double precision wave or text wave with zero elements is returned. Note that for multi-dimensional empty JSON arrays like "array":[[]] only the inner array at /array/0 returns a zero element wave. The outer array at /array returns a wave with one element because the outer JSON array contains one element, that is the inner array. As the inner array is empty the single element is returned with the default fill value, NaN or "".

Reading with /WAVE or /TWAV and encountering an invalid type results in a runtime error unless /Z is set. By default for text waves if a JSON element can not be converted to text the original wave is not changed. For numeric waves the result depends on the /WM flag. If not set (default) wave elements where the JSON element can not be converted to a number are set to NaN or 0 depending on the wave type being floating point or integer. If the /WM flag is set and a JSON element could not be converted to a number then the original wave is returned unchanged. This is the same behavior as for the text wave case.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

S_value

Returns the string value read by using the /T flag.

V_value

Returns the numerical value read by using the /V flag or a new jsonId when using the /J flag.

Examples

Parses a JSON text from a string, retrieves values of various primitive types and outputs them:

Function JSONXOP_GetValue_example1()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Number\":1.23,"
    jsonStr += "\"String\":\"Five\","
    jsonStr += "\"64BitInteger\":18446744073709551615"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetValue/V jsonId, "/Number"
    print "Number:", V_value
    JSONXOP_GetValue/T jsonId, "/String"
    print "String:", S_value
    Make/O/L/U/N=1 uint64Wave // predefine unsigned 64 bit integer type
    JSONXOP_GetValue/L=uint64Wave jsonId, "/64BitInteger"
    printf "64BitInteger:%u\r", uint64Wave[0]
    JSONXOP_Release jsonId
End

Output:

Number:  1.23
String:  Five
64BitInteger:18446744073709551615

Parses a JSON text from a string and retrieves waves from numerical and string arrays:

Function JSONXOP_GetValue_example2()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"numArray\":["
    jsonStr += "[1, 2], [3, 4]"
    jsonStr += "],"
    jsonStr += "\"strArray\":["
    jsonStr += "[\"a\", \"b\"], [\"c\", \"d\"]"
    jsonStr += "]"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetValue/WAVE=numWave jsonId, "/numArray"
    print "numeric array:\r", numWave
    JSONXOP_GetValue/TWAV=textWave jsonId, "/strArray"
    print "string array:\r", textWave
    JSONXOP_Release jsonId
End

Output:

numeric array:
numWave[0][0]= {1,3}
numWave[0][1]= {2,4}
string array:
textWave[0][0]= {"a","c"}
textWave[0][1]= {"b","d"}

Parses a JSON text from a string, retrieves waves from arrays with different sizes and outputs them: Some wave elements have no corresponding array element and are set to default values.

Function JSONXOP_GetValue_example3()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"numArray\":["
    jsonStr += "[1, 2], [3]"
    jsonStr += "],"
    jsonStr += "\"strArray\":["
    jsonStr += "[\"a\", \"b\"], [\"c\"]"
    jsonStr += "]"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetValue/WAVE=numWave jsonId, "/numArray"
    print "numeric array:\r", numWave
    JSONXOP_GetValue/TWAV=textWave jsonId, "/strArray"
    print "string array:\r", textWave
    JSONXOP_Release jsonId
End

Output:

numeric array:
numWave[0][0]= {1,3}
numWave[0][1]= {2,NaN}
string array:
textWave[0][0]= {"a","c"}
textWave[0][1]= {"b",""}

Parses a JSON text from a string, retrieves array values in an integer wave and outputs it: A warning is printed to the history area when JSONXOP_GetValue encounters a floating point value in the array.

Function JSONXOP_GetValue_example4()

    variable jsonId
    string jsonStr

    jsonStr = "[1, 1.5]"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    Make/O/I/N=0 intWave
    JSONXOP_GetValue/WAVE=intWave jsonId, ""
    print "numeric array:\r", intWave
    JSONXOP_Release jsonId
End

Output:

Warning: Attempt to read floating point value to integer at array position [1, 0, 0, 0], put 0 instead in wave.
numeric array:
intWave[0]= {1,0}

Parses a JSON with a text and a numeric entry, the text entry is retrieved through /WAVE with /WM=0 and then with /WM=1: First a wave with NaN is returned because the text element that can not be converted results in placing the default value in the wave. Second a null wave is returned because the text element that can not be converted results in wave mode 1 in a conversion error, where the original wave is not changed.

Function JSONXOP_GetValue_example5()

    variable jsonId
    string jsonStr

    jsonStr = "{\"text\" : [\"a\"], \"num\" : [1]}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_GetValue/FREE/Z=1/WM=0/WAVE=defaultValueWave jsonId, "/text"
    print "1: default value wave:\r", defaultValueWave
    JSONXOP_GetValue/FREE/Z=1/WM=1/WAVE=nullWave jsonId, "/text"
    print "2: null wave:\r", nullWave
    JSONXOP_Release jsonId
End

Output:

Warning: Can not convert string to number at array position [0, 0, 0, 0], put NaN instead in wave. Found string: a
1: default value wave:
'_free_'[0]= {NaN}
Warning: Can not convert string to number at array position [0, 0, 0, 0].
2: null wave:
NULL wave

See Also

JSONXOP_AddValue, JSONXOP_GetType, JSONXOP_GetMaxArraySize

JSONXOP_New

Creates a new JSON text:

JSONXOP_New [/Q[=q] /Z[=z]]

The JSONXOP_New operation creates a new JSON text and returns its identifier in V_Value.

Parameters

This operation has no parameters.

Flags

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The operation creates a new JSON text. The JSON text is empty, representing the value null. The new unique identifier is returned in V_value and is used with all other JSONXOP operations to refer to this JSON text. It stays valid until it is released with JSONXOP_Release.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

V_value

Returns the identifier of the new JSON text.

Examples

Creates a new JSON text and displays its content:

Function JSONXOP_New_example1()

    JSONXOP_New
    JSONXOP_Dump V_value
    print S_value
    JSONXOP_Release V_value
End

Output:

null

See Also

JSONXOP_Release

JSONXOP_Parse

Parses a string to a JSON text:

JSONXOP_Parse [/Q[=q] /Z[=z]] jsonStr

The JSONXOP_Parse operation parses a string with textual representation of data in JSON format to a JSON text.

Parameters

jsonStr

String with the textual representation of data in JSON format.

Flags

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

In case jsonStr does not conform to the JSON format, the operation prints a detailed error message to the history area unless /Q is set.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

V_value

Identifier of the new JSON text.

Examples

Parses a string to a new JSON object, displays its content and releases it:

Function JSONXOP_Parse_example1()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"nameString\":\"Santa Claus\","
    jsonStr += "\"houseNumber\":123,"
    jsonStr += "\"roadString\":\"Elf Road\","
    jsonStr += "\"locationString\":\"North Pole\","
    jsonStr += "\"postCodeNumber\":88888"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_Dump jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
"houseNumber": 123,
"locationString": "North Pole",
"nameString": "Santa Claus",
"postCodeNumber": 88888,
"roadString": "Elf Road"
}

See Also

JSONXOP_New, JSONXOP_Dump, JSONXOP_Release

JSONXOP_Release

Releases the JSON text from memory:

JSONXOP_Release [/Q[=q] /Z[=z] /A] jsonId

The JSONXOP_Release operation releases the JSON text or all JSON texts from memory.

Parameters

jsonId

Identifier of the JSON text.

Flags

/A

Releases all JSON texts from memory. When /A is set the jsonId parameter must be omitted.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

After releasing a JSON text, the identifier is invalid for further use with JSONXOP operations.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples

Creates a new JSON object, displays its content and releases it:

Function JSONXOP_Release_example1()

    JSONXOP_New
    JSONXOP_Dump V_value
    print S_value
    JSONXOP_Release V_value
    print "Released JSON id:", V_value
End

Output:

null
Released JSON id:  130

See Also

JSONXOP_New

JSONXOP_Remove

Removes the element in the JSON object at the given location:

JSONXOP_Remove [/Q[=q] /Z[=z]] jsonId, jsonPath

The JSONXOP_Remove operation removes the element at the specified location from the JSON object.

Parameters

jsonId

Identifier of the JSON text.

jsonPath

Path in the JSON text using JSON pointer syntax.

Flags

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:

No error reporting to the history area.

/Q:

Is identical to /Q=1.

/Q=0:

Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The specified location must point to an existing element; otherwise the operation returns a runtime error.

Removing the root of the JSON object at "" resets the JSON object to null.

Output Variables

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples

Parses a JSON text from a string, removes an element and shows the textual representation:

Function JSONXOP_Remove_example1()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Fridge\":{"
    jsonStr += "\"Milk\":\"half empty\","
    jsonStr += "\"Batteries\":2},"
    jsonStr += "\"Freezer\":{"
    jsonStr += "\"FishSticks\":15,"
    jsonStr += "\"Straciatella\":\"Big Box\"}"
    jsonStr += "}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_Remove jsonId, "/Freezer/Straciatella"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Freezer": {
    "FishSticks": 15
  },
  "Fridge": {
    "Batteries": 2,
    "Milk": "half empty"
  }
}

Parses a JSON text from a string, removes two array elements and shows the textual representation:

Function JSONXOP_Remove_example2()

    variable jsonId
    string jsonStr

    jsonStr = "{"
    jsonStr += "\"Movies\":["
    jsonStr += "\"Batman\", \"& Robin\", \"Titanic\", 2"
    jsonStr += "]}"

    JSONXOP_Parse jsonStr
    jsonId = V_value
    JSONXOP_Remove jsonId, "/Movies/1"
    JSONXOP_Remove jsonId, "/Movies/2"
    JSONXOP_Dump/IND=2 jsonId
    print "Full textual representation:\r", S_value
    JSONXOP_Release jsonId
End

Output:

Full textual representation:
{
  "Movies": [
    "Batman",
    "Titanic"
  ]
}

See Also

JSONXOP_AddValue, JSONXOP_AddTree

JSONXOP_Version

Returns version information about the JSON XOP:

JSONXOP_Version [/Z[=z]]

The JSONXOP_Version operation returns version information about the XOP.

Parameters

This operation has no parameters.

Flags

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:

Suppresses generation of runtime errors.

/Z:

Is identical to /Z=1.

/Z=0:

Is the same as omitting the flag.

Details

The operation prints version information to the history area when called from the command line. The version string is in JSON format and contains the keys builddate, compiler, name and version.

Output Variables

S_value

Returns version information of the XOP in JSON format.

V_flag

Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples

Shows JSON XOP version information:

Function JSONXOP_Version_example1()

    JSONXOP_Version
    print S_value
End

Output:

{
  "builddate": "Aug  7 2023 14:16:45",
  "compiler": "Visual Studio 1916",
  "name": "JSON XOP",
  "version": "version-879-ge747620"
}

See Also

JSONXOP_New, JSONXOP_AddValue, JSONXOP_GetValue

Error Codes

The XOP operations can return the following error codes:

XOP error codes:

// Error constants for JSON XOP
Constant JSON_OLD_IGOR = 10001
Constant JSON_UNHANDLED_CPP_EXCEPTION = 10002
Constant JSON_CPP_EXCEPTION = 10003

// ASSERTion encountered.
Constant JSON_ERR_ASSERT = 10004

// Invalid JSON id.
Constant JSON_ERR_INVALID_ID = 10005

// Could not create object in path.
Constant JSON_ERR_INVALID_PATH = 10006

// Exactly one input value of either type /B /I /L /N /T /V /JOIN /OBJ or /WAVE must be specified.
Constant JSON_ERR_NONE_MULTIPLE_INPUT = 10007

// JSON member object already exists
Constant JSON_ERR_OBJECT_EXISTS = 10008

// Error when parsing string to JSON
Constant JSON_ERR_PARSE = 10009

// Dumping JSON to string failed (This may happen if a string in a json value is not UTF8 encoded)
Constant JSON_ERR_DUMP = 10010

// Invalid type specified.
Constant JSON_ERR_INVALID_TYPE = 10011

// Can not convert value to requested type.
Constant JSON_ERR_CONVERT = 10012