The JSON_SERIALIZE function takes an IDL variable and converts it into a JSON (JavaScript Object Notation) string.

This routine is written in the IDL language. Its source code can be found in the file json_serialize.pro in the lib subdirectory of the IDL distribution.

Examples

Convert a LIST of IDL values into a JSON string

mylist = LIST(!TRUE, !NULL, 42, 3.14, "Hello")
json = JSON_SERIALIZE(mylist)
PRINT, json

IDL prints:

[true,null,42,3.14,"Hello"]

Convert a HASH of key-value pairs into a JSON string

myhash = HASH("Planet", "Jupiter", "Index", 5, "Mass", 1.9d27, "Units", "kg")
json = JSON_SERIALIZE(myhash)
PRINT, json

IDL prints:

{"Planet":"Jupiter","Index":5,"Units":"kg","Mass":1.9e27}

Convert an IDL structure into a JSON string

struct = {PLANET: "Jupiter", INDEX: 5, MASS: 1.9d27, UNITS: "kg"}
json = JSON_SERIALIZE(struct)
PRINT, json

IDL prints:

{"PLANET":"Jupiter","INDEX":5,"MASS":1.9e27,"UNITS":"kg"}

Syntax

Result = JSON_SERIALIZE(Value, /LOWERCASE, /NANINF_LITERAL, PRECISION=value, /PRETTY)

Return Value

The result is a string containing the JSON string. When converting IDL variables, the following rules are used:

  • Undefined variables (or !NULL) become "null".
  • Boolean variables are passed as "true" or "false".
  • All bytes and integers are passed unchanged. If these are converted back using JSON_PARSE, they will be type LONG64.
  • All floating-point numbers are passed unchanged, although any trailing zeroes are removed. If these are converted back using JSON_PARSE, they will be type DOUBLE. By default, NaN or Infinity values are converted to string "NaN" or "Infinity", respectively. See NANINF_LITERAL and PRECISION keywords for options.
  • All strings are surrounded by double-quotes. The following special characters will be escaped: \\ (backslash), \" (double quote), \b (backspace 8b), \f (form feed 12b), \n (line feed 10b), \r (carriage return 13b), \t (tab 9b). Note that forward slash characters are not escaped - this allows URL's to still look normal in the resulting JSON. Also note that the string "!NULL" is a special case, and will be converted into the "null" value.
  • Arrays become JSON arrays, with each element being converted using the above rules.
  • LIST values become JSON arrays, with each list element being converted using the above rules.
  • Structure tagname-value pairs become JSON objects, with each value being converted using the above rules. You can use the LOWERCASE keyword to change the tagnames to lowercase.
  • HASH key-value pairs become JSON objects, with each value being converted using the above rules.

Note: Since the HASH stores its key-value pairs in an arbitrary order, the key-value pairs in the resulting JSON string may be in a different order than the order in which the keys were added to the hash.

Arguments

Value

Value must be an IDL scalar, array, HASH, LIST, or structure variable.

Keywords

LOWERCASE

By default, when serializing an IDL structure, all of the structure tag names are in uppercase within the resulting JSON string. Set the LOWERCASE keyword to use lowercase for the structure tag names.

NANINF_LITERAL

By default, when serializing a floating-point value that is NaN or Infinity, the values will be serialized as strings, such as "NaN" or "Infinity". These string values conform to the JSON specification, but will not be converted back to NaN or Infinity when the JSON is parsed. If the NANINF_LITERAL keyword is set to 1, then these values will be serialized as just NaN or Infinity without quotes.

Note: These unquoted values do not conform to the JSON specification, but are supported by some JSON parsers, including JSON_PARSE and Python. These JSON parsers will recognize these values and correctly return NaN and Infinity floating-point numbers.

PRECISION

Set the PRECISION keyword to a number between 1 and 17 to set the number of digits to output for floating-point numbers. By default, the precision is 8 digits for single precision and 17 digits for double precision. A smaller precision will result in a smaller JSON string but may result in a loss of precision when the numbers are converted back.

Note: Unnecessary trailing zeroes are automatically removed from all numbers, regardless of the precision setting.

PRETTY

Set this keyword to output the JSON in a "pretty" format with line breaks and indentation using spaces. The output will still be a scalar string, with embedded line feed characters.

Resources and References

JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write, and for machines to parse and generate. JSON was designed as an alternative to XML, and is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. Further details can be found at http://www.json.org.

Version History

8.2

Introduced
8.4

All byte values are now encoded as integers (instead of true/false).

Added LOWERCASE keyword.

Boolean variables are encoded as true/false.

8.8.3

 Added PRECISION keyword.
8.9 Added PRETTY keyword.
9.1 Added NANINF_LITERAL keyword.

See Also

JSON_PARSE, HASH, LIST, HttpRequest