cJSON review

The JSON logo.

On my first Library Review, I’d talk about Dave Gamble’s JSON parsing system for C, the cJSON library.

The JSON logo.

1.0 Usability

Well, the reason I’m posting this cJSON review is that I’ve been using it for too long, and now I can say that it’s one of the best JSON parsers for C out there (and obviously the easiest to use). It’s incredibly easy to setup, just compile cJSON.c with your other projects, and include cJSON.h in the files you need to use the library in. That’s all. To the extent of my knowledge, it’s in standard C language, which means you’d be able to use this in C++ projects as well; just compile the main library source alongside your project sources, and include the header file wherever needed.

The project is hosted on GitHub.

2.0 Who should use this?

This library is simply Ideal for network developers, and for other developers who are creating networking applications. JSON is the new XML. It’s a more convenient way of airing data over the internet; The simplicity of the JSON format and predefined support for it in many languages has therefore made it the most popular data-exchange format for the web these days. If you, for example, are creating a chat application, then you obviously need to exchange data online. Be it text messages, new notifications, or other such stuff. In those cases, JSON is the way to go. And, if you are programming your software in C, cJSON should be fairly easy to set up. Take my word, if you use it for some days, you’d fall in love with it.

3.0 An Example

Suppose that you are given a JSON string like this:

   "uid": 1,
   "name": "Scooby Doo",
   "age": 15,
   "married": "No"

This kind of JSON data are very common these days. As you can see, This JSON data represents the information about a family member. This JSON data is nothing but a plain string, so it should be very easy for you to use this code in networking applications.

To use this data with JSON, first we need to parse this  whole data. Suppose you have your JSON data in a string called ‘mystring‘. Then, to parse the string, do this:

3.1 Parsing the data

cJSON * root = cJSON_Parse(mystring);

This will parse your JSON data present in ‘mystring‘, and store the information in a struct named ‘root‘. The ‘root‘ variable now represents the root element of your data.

3.2 Getting the value of an element

Now, if you need to get the name of the family member, just run:

cJSON *name_json = cJSON_GetObjectItem(root, "name");
char *name = NULL;
if (cJSON_IsString(name_json)) {
    name = name_json->valuestring;
    // Now the variable "name" should contain the string value of the element.

This would be the proper way of doing that, see This issue.

valuedouble is also supported for integer and double values. Since 2 April 2017, valueint is deprecated.

3.3 Saving the data

So If you are done with all your editing, you might want to write the data back to somewhere safe? Simply save the edited root element back to a sting, do it like this:

char *finalize = cJSON_Print(root);

This would save your data back to a string called ‘finalize’.

3.4 Creating your own Dataset

Now suppose, instead of opening a JSON data set, you want to create a JSON data set yourself. here’s what you have to do:

cJSON *root = cJSON_CreateObject();
if (root == NULL) {
      /*If control comes here, it means that some kind of error happened
         while creating the root JSON object. Handle this error ASAP. */
cJSON_AddNumberToObject(root, "uid", 1920);
cJSON_AddStringToObject(root, "name", "Scooby Doo");
cJSON_AddNumberToObject(root, "age", 15);
cJSON_AddStringToObject(root, "married", "No");

FSMaxB helped me sort this out.
The cJSON_AddNumberToObject and cJSON_AddStringToObject functions create elements with integer value and string value respectively. Both the functions take the element in which to write data in the first argument, the name of the element in the second argument, and the value of the data in the last argument.

Running the following code will produce a resulting JSON structure identical to the one shown above.

3.5 Creating a set, inside a set?

In some cases, you might need to create a dataset inside an already existing dataset. For example, look at this:

   "uid": 1,
   "name": "Scooby Doo",
   "age": 15,
   "married": "No"
   "siblings" {
      "Sisters": 0,
      "Brothers": 0

In this data set, we have declared an element called ‘siblings’, which, in itself, holds some data. We can put that data set inside our already existing root element like this:
cJSON *new_data = cJSON_CreateObject();
cJSON_AddNumberToObject(new_data, "Sisters", 0);
cJSON_AddNumberToObject(new_data, "Brothers", 0);
cJSON_AddItemToObject(root, "siblings", new_data);

So, that should tell you all you need to know about this library. If you feel like something is wrong, feel free to leave me a comment.

Leave a Reply

Be the First to Comment!

Notify of