Page History
...
Syntax
Code Block |
---|
Result = SRP_JSONJson(Handle, Service, Param1, Param2, Param3) |
Returns
The service result.
Parameters
Parameter | Description |
---|---|
Handle | Handle to JSON Entity. Required. |
Service | The service to execute against the given JSON Entity Handle. Required. |
Param1 | Generic parameter show purpose depends upon the Service being used. Optional. |
Param2 | Generic parameter show purpose depends upon the Service being used. Optional. |
Param3 | Generic parameter show purpose depends upon the Service being used. Optional. |
Remarks
With RESTful WebAPI services becoming more prominent, the need to build and parse JSON is ever increasing. SRP_JSON Json provides an API that not only makes this task easier, it also ensures the operations will happen quickly. Like many of our SRP Utilities, this single method provides multiple functions through services.
...
- JSON: JavaScript Object Notation. This is a lightweight interchange format utilized by many modern WebAPIs.
- JSON Entity: SRP_JSON Json creates and manipulates JSON entities. A JSON entity might be one of the following types: Object, Array, Number, String, or Boolean.
- JSON Entity Handle: SRP_JSON Json creates or returns JSON Entity Handles, which are simply numbers that point to a specific entity in memory. These handles are also passed to SRP_JSON Json to manipulate a specific entity. You must never alter a handle yourself.
...
- element: A JSON entity that is a child of a JSON array. An element is identified by an index. The first element in an array is always 1.
QuickStart Guide
The full list of services are provided below, but first lets get a bird's eye view of what it's like to use the API. We'll start with building a JSON from scratch, then we'll show how to parse JSON and extract values. In both cases, we'll use the following sample JSON:
...
Code Block |
---|
// Parse the SampleJSON string ParseResult = SRP_JSONJson(EmployeesHandle, "PARSEParse", SampleJSON) // The result is "" if parsing was successful If ParseResult EQ "" then // Success! Now get the employee array EmployeeArrayHandle = SRP_JSONJson(EmployeesHandle, "GETGet", "employees") If EmployeeArrayHandle NE 0 then // Loop through each employee, extracting first and last name NumEmployees = SRP_JSONJson(EmployeeArrayHandle, "GETCOUNTGetCount") For iEmployee = 1 to NumEmployees FirstName = SRP_JSONJson(EmployeeArrayHandle, "GETVALUEGetValue", "[":i:"].firstName") LastName = SRP_JSONJson(EmployeeArrayHandle, "GETVALUEGetValue", "[":i:"].lastName") Next iEmployee end end else // There was an error in parsing, so show it to the user Msg(@Window, ParseResult:@FM:@FM:@FM:"!") end // We're all done with the JSON entity that was created when parsing SRP_JSONJson(EmployeesHandle, "RELEASERelease") |
Now, let's create the sample JSON from scratch:
Code Block |
---|
// Create the root object, which we'll call employees If SRP_JSONJson(EmployeesHandle, "NEWNew") then // Create a new array If SRP_JSONJson(EmployeeArrayHandle, "NEWNew", "ARRAYArray") then // Add the first employee If SRP_JSONJson(SingleEmployeeHandle, "NEWNew") then SRP_JSONJson(SingleEmployeeHandle, "SETVALUESetValue", "firstName", "John") SRP_JSONJson(SingleEmployeeHandle, "SETVALUESetValue", "lastName", "Doe") SRP_JSONJson(EmployeeArrayHandle, "ADDAdd", SingleEmployeeHandle) SRP_JSONJson(SingleEmployeeHandle, "RELEASERelease") end // Add the second employee If SRP_JSONJson(SingleEmployeeHandle, "NEWNew") then SRP_JSONJson(SingleEmployeeHandle, "SETVALUESetValue", "firstName", "Anna") SRP_JSONJson(SingleEmployeeHandle, "SETVALUESetValue", "lastName", "Smith") SRP_JSONJson(EmployeeArrayHandle, "ADDAdd", SingleEmployeeHandle) SRP_JSONJson(SingleEmployeeHandle, "RELEASERelease") end // Add the third employee If SRP_JSONJson(SingleEmployeeHandle, "NEWNew") then SRP_JSONJson(SingleEmployeeHandle, "SETVALUESetValue", "firstName", "Peter") SRP_JSONJson(SingleEmployeeHandle, "SETVALUESetValue", "lastName", "Jones") SRP_JSONJson(EmployeeArrayHandle, "ADDAdd", SingleEmployeeHandle) SRP_JSONJson(SingleEmployeeHandle, "RELEASERelease") end // Now add the array as a member of the root object SRP_JSONJson(EmployeesHandle, "SETSet", "employees", EmployeeArrayHandle) // All done with the array object SRP_JSONJson(EmployeeArrayHandle, "RELEASERelease") end // Now get the actual JSON SampleJSON = SRP_JSONJson(EmployeesHandle, "STRINGIFYStringify", "STYLED") // All done with the root object SRP_JSONJson(EmployeesHandle, "RELEASERelease") end |
Services
SRP_JSON Json provides the following services. The first parameter is always a handle to an entity. Sometimes this handle is just an empty or unassigned variable, such as when you want to create a new JSON Entity. All other times the handle references a JSON Entity already in memory. The rest of the parameters depend upon the service in question, and if you are using the latest SRP Editor you'll see the tooltips change once you select a service--making it easy to know how to use it.
Service | Description |
---|---|
ADDAdd | Adds a JSON Entity to a JSON array. |
ADDVALUEAddValue | Adds a value to a JSON array. |
AddValueArray | Adds an array of values to a JSON array. New in 2.1.1 |
ContainsCONTAINS | Determines if a JSON object contains the given member or if a JSON array contains the given index. |
GETGet | Returns a descendant JSON Entity within a given JSON Entity. |
GETCOUNTGetCount | Returns the number of members in a JSON object or elements in a JSON array. |
GETMEMBERSGetMembers | Returns a list of a JSON object's members. |
GETVALUEGetValue | Returns a descendant value within a given JSON Entity. |
NEWNew | Creates a new JSON Entity. |
PARSEParse | Parses a standardized JSON string into a new JSON Entity. |
RELEASERelease | Deallocates a JSON Entity from memory. |
REMOVERemove | Removes a member from a JSON object or an element from a JSON array. |
REMOVEALLRemoveAll | Removes all members from a JSON obect or all elements from a JSON array. |
SETSet | Sets a member within a JSON object or element within a JSON array to the given JSON Entity. |
SETVALUESetValue | Sets a member within a JSON object or element within a JSON array to the given value. |
SetValueArray | Sets a member within a JSON object or element within a JSON array to the given array of values. New in 2.1.1 |
STRINGIFYStringify | Formats the given JSON Entity into a standardized JSON string. |
TYPEType | Returns a JSON Entity's type. |
Validate | Validates JSON against a given schema. New in 2.2.1 |
Click on the service above to read more details.
Acknowledgments
SRP_JSON is a wrapper around JSON-CPP.