mirror/json-c
1
0
Fork 0
mirror of https://github.com/json-c/json-c.git synced 2026-04-05 05:19:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add some more detail about how to use json-c in README.md.

Browse Source
This commit is contained in:
Eric Haszlakiewicz
2020-07-17 03:42:38 +00:00
parent cb10a13e94
commit 9a7de35b92
1 changed files with 31 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@@ -238,8 +238,38 @@ following more specific header files:
* json_tokener.h - Methods for parsing and serializing json-c object trees. * json_tokener.h - Methods for parsing and serializing json-c object trees.
* json_pointer.h - JSON Pointer (RFC 6901) implementation for retrieving * json_pointer.h - JSON Pointer (RFC 6901) implementation for retrieving
objects from a json-c object tree. 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_visit.h - Methods for walking a tree of json-c objects.
* json_util.h - Miscelleanous utility functions. * 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) 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.