IgorJSON XOP

IgorJSON is an external operation (XOP) for Igor Pro that provides robust JSON parsing and generation capabilities. It allows you to create, modify, query, and format JSON objects directly from Igor Pro using a set of external functions. It aims to be particularly easy to use.

This XOP makes use of the nlohmann/json library for C++.

Requirements

• Igor Pro 6.20 or later.
• The XOP must be placed in the "Igor Extensions" (or "Igor Extensions (64-bit)") folder or an alias/shortcut must be created there.

Usage Overview

The XOP treats JSON objects primarily as strings. Most functions take a JSON string as input and, for modification operations, return a new JSON string with the requested changes. This means operations are generally non-mutating on the input string itself; you must assign the result back to your variable if you wish to update it.

Example

String jsonStr = IJSONNewObject() // Returns "{}"
jsonStr = IJSONInsertString(jsonStr, "name", "John Doe")
jsonStr = IJSONInsertNumber(jsonStr, "age", 30)

// jsonStr is now: {"name": "John Doe", "age": 30}

Variable age = IJSONGetNumber(jsonStr, "age") // Returns 30

Function Reference

Creation and Validation

• String IJSONNewObject()

  • Returns an empty JSON object {}.

• Variable IJSONIsValidObject(String jsonString)

  • Returns 1 if jsonString is a valid JSON object, 0 otherwise.

• String IJSONPrettyFormat(String jsonString)

  • Returns a formatted (indented) version of the input JSON string for readability.

Inserting Data (Setters)

These functions insert or update a value in a JSON object. Returns: A new JSON string containing the update.

• String IJSONInsertString(String jsonString, String key, String value)
• String IJSONInsertNumber(String jsonString, String key, Variable value)
• String IJSONInsertBoolean(String jsonString, String key, Variable value) (Pass 1 for true, 0 for false)
• String IJSONInsertNull(String jsonString, String key)
• String IJSONInsertObject(String jsonString, String key, String jsonObjectToInsert)
  • Inserts another JSON object (provided as a string) under the specified key.

Array Insertions

These functions insert an Igor Wave as a JSON array.

• String IJSONInsertStringArray(String jsonString, String key, Wave/T textWave)
• String IJSONInsertNumberArray(String jsonString, String key, Wave numericWave)
• String IJSONInsertBooleanArray(String jsonString, String key, Wave numericWave)
  • Non-zero values in the wave are treated as true.
• String IJSONInsertObjectArray(String jsonString, String key, Wave/T jsonObjectsWave)
  • Takes a text wave where each element is a valid JSON string, and inserts them as an array of objects.

Retrieving Data (Getters)

These functions extract values from a JSON object string.

• String IJSONGetString(String jsonString, String key)
• Variable IJSONGetNumber(String jsonString, String key)
• Variable IJSONGetBoolean(String jsonString, String key)
• String IJSONGetObject(String jsonString, String key)
  • Returns the sub-object at key as a JSON string.
• Variable IJSONIsNull(String jsonString, String key)
  • Returns 1 if the value at key is null, 0 otherwise.

Array Retrievals

These functions extract JSON arrays into Igor Waves.

• Wave/T IJSONGetStringArray(String jsonString, String key)
• Wave IJSONGetNumberArray(String jsonString, String key)
• Wave IJSONGetBooleanArray(String jsonString, String key)
• Wave/T IJSONGetObjectArray(String jsonString, String key)
  • Returns a text wave where each element is the string representation of the object in the array.

Utility Functions

• Wave/T IJSONGetTopLevelKeysInObject(String jsonString)
  • Returns a text wave containing all keys at the root level of the object.
• Variable IJSONKeyExists(String jsonString, String key)
  • Returns 1 if the key exists, 0 otherwise.
• Variable IJSONEqualObjects(String jsonString1, String jsonString2)
  • Returns 1 if the two JSON objects are semantically equivalent, 0 otherwise.

Base64 Support

Calculated helpers for handling binary data (often needed alongside JSON).

• String IJSONBase64Encode(Wave dataWave)
  • Encodes the binary data of the wave into a Base64 string.
• Wave IJSONBase64Decode(String base64String)
  • Decodes a Base64 string into a binary wave (unsigned byte wave).

Caveats and Notes

• Immutability: Since Igor strings are passed by value/handle, the "Insert" functions do not modify the input string in place. Instead a new string with the modified content is returned by the function.

Alternatives

There is another JSON XOP available for Igor Pro known as the JSON XOP by Byte Physics. While both extensions enable JSON handling in Igor Pro, they have different design philosophies:

Feature	IgorJSON (This XOP)	JSON XOP (byte physics)
Data Model	Stateless / String-based. JSON objects are passed around as standard Igor Strings. Modifications return a new string.	Stateful / Reference-based. JSON objects are created in memory and referenced by an ID/Handle.
Memory Management	Automatic (handled by Igor's string management). No need to explicitly free objects.	Manual. You must call JSONXOP_Release to free memory when done with an object.
Performance	Good for small to medium objects and simple interactions. Heavy manipulation is slower due to repeated parsing/serializing.	Likely faster for complex manipulation of large datasets, as the object structure persists in memory between calls.
Ease of Use	Simpler for quick scripts due to lack of manual cleanup ("Get a value from this string").	More powerful API for building complex structures step-by-step.
API Style	Functional (String out = Func(String in, ...))	Object-oriented / Operation-based (Func(ID, ...)). Uses specific Igor Operations.

Recommended Use Cases:

• Consider using IgorJSON if: You need to quickly parse a JSON response, extract a few values, or generate simple JSON configuration files, and prefer a functional style without managing object handles.
• Consider using the JSON XOP if: You are building or traversing very large/complex JSON trees, performance is critical for intensive manipulations, or you prefer an object-oriented approach.