Stringify (Json function)
Serialize a JSON object (Json class)
[Introduced in Model 204 7.6]
This function serializes a Json object tree as a unicode JSON string.
Syntax
%unicode = json:Stringify[( [Indent= number])] Throws JsonCircularReference
Syntax terms
| %unicode | A unicode string that contains the JSON format serialization of the Json object tree. |
|---|---|
| Json | Json object, which may be Null or any underlying Json object type (boolean, number, string, array, or object). |
| Indent | The number of space characters to add in front of each line for each nesting level (see below for moe details). The default value of Indent is 0 which means lines won't be indented. |
Usage notes
- The name Stringify derives from the equivalent JavaScript method: JSON.stringify.
- The functionality of Stringify is practically identical to that of ToString. The only difference is that Stringify throws a JsonCircularReferenceException if the Json object leads to a circular reference. Because the JSON specification does not allow for circular references, Stringify is probably the preferred function to use for generating JSON to send to another platform – it's better to request cancel in 204 than to send bad JSON data to someone else.
- If no indentation is used (Indent defaults or is set to 0) no whitespace is added between any of the JSON tokens and separator characters (curly and square braces, commas, and colons). This format is very compact but can be tough for humans to read.
- If indentation is used, a unicode linefeed character (u+000a) is added before each array item or object property and after the last array item or object property. If the unicode data is printed or audited, the unicode linefeed characters will cause a new line to be started on the screen or audit trail. This will make the serialized JSON data much nicer and easier to read.
- The Indent value indicates the number of blank characters per indentation level to place before each new line of data. Every array and object increases the indentation level by one inside its boundaries. So if an array is inside an object which is inside another object that array's indentation level is 3. With an Indent value of 2 each array item in that array will have 6 space characters in front of it.
- If a non-zero Indent value is used, a single space character is always placed after the colon in an object property name.
- If the serialized JSON data is to be sent to another platform, the unicode JSON data generally needs to be UTF-8 or UTF-16 encoded which can be done by using the UnicodeToUtf8 or UnicodeToUtf16 Unicode functions. Even if the data is known to only contain data that is translatable to EBCDIC it is best to avoid converting it to EBCDIC, if possible.
- A null Json object serializes as the unicode literal
null.
Examples
The following example builds a Json object tree then serializes it using Stringify and prints the result:
b %json is object json %title is string len 64 %i is float %json = object %json("Lee") = "To Kill a Mockingbird" %json("Faulkner") = array("As I Lay Dying", "Absalom, Absalom", "The Sound and the Fury") %json("Hurston") = array("Jonah's Gourd Vine", "Their Eyes Were Watching God") %json("Ellison") = "Invisible Man" printText {~=%json:stringify(indent=2)} end
This prints:
%json:stringify(indent=2)={ "Lee": "To Kill a Mockingbird", "Faulkner": [ "As I Lay Dying", "Absalom, Absalom", "The Sound and the Fury" ], "Hurston": [ "Jonah's Gourd Vine", "Their Eyes Were Watching God" ], "Ellison": "Invisible Man" }
If the indent=2 were removed from the above code, it would print (wrapping at column 80):
%json:stringify(indent=0)={"Lee":"To Kill a Mockingbird","Faulkner":["As I Lay - Dying","Absalom, Absalom","The Sound and the Fury"],"Hurston":["Jonah's Gourd V- ine","Their Eyes Were Watching God"],"Ellison":"Invisible Man"}