From 9a7de35b922d71f287590e1d0a5b602cdd22a0fa Mon Sep 17 00:00:00 2001 From: Eric Haszlakiewicz Date: Fri, 17 Jul 2020 03:42:38 +0000 Subject: [PATCH] Add some more detail about how to use json-c in README.md. --- README.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ff15eabc..fc128f51 100644 --- a/README.md +++ b/README.md @@ -238,8 +238,38 @@ following more specific header files: * json_tokener.h - Methods for parsing and serializing json-c object trees. * json_pointer.h - JSON Pointer (RFC 6901) implementation for retrieving objects from a json-c object tree. -* json_object_iterator.h - Methods for iterating over single json_object instances. +* json_object_iterator.h - Methods for iterating over single json_object instances. (See also `json_object_object_foreach()` in json_object.h) * json_visit.h - Methods for walking a tree of json-c objects. * json_util.h - Miscelleanous utility functions. For a full list of headers see [files.html](http://json-c.github.io/json-c/json-c-current-release/doc/html/files.html) + +The primary type in json-c is json_object. It describes a reference counted +tree of json objects which are created by either parsing text with a +json_tokener (i.e. `json_tokener_parse_ex()`), or by creating +(with `json_object_new_object()`, `json_object_new_int()`, etc...) and adding +(with `json_object_object_add()`, `json_object_array_add()`, etc...) them +individually. +Typically, every object in the tree will have one reference, from it's parent. +When you are done with the tree of objects, you call json_object_put() on just +the root object to free it, which recurses down through any child objects +calling json_object_put() on each one of those in turn. + +You can get a reference to a single child +(`json_object_object_get()` or `json_object_array_get_idx()`) +and use that object as long as its parent is valid. +If you need a child object to live longer than its parent, you can +increment the child's refcount (`json_object_get()`) to allow it to survive +the parent being freed or it being removed from its parent +(`json_object_object_del()` or `json_object_array_del_idx()`) + +When parsing text, the json_tokener object is independent from the json_object +that it returns. It can be allocated (`json_tokener_new()`) +used ones or multiple times (`json_tokener_parse_ex()`, and +freed (`json_tokener_free()`) while the json_object objects live on. + +A json_object tree can be serialized back into a string with +`json_object_to_json_string_ext()`. The string that is returned +is only valid until the next "to_json_string" call on that same object. +Also, it is freed when the json_object is freed. + -- 2.47.2