mirror of
https://github.com/akheron/jansson.git
synced 2025-04-06 05:55:05 +00:00
Merge pull request #290 from Thynix/documentation
Polish API documentation
This commit is contained in:
Petri Lehtinen
GitHub
commit
8f067962f6
1 changed files with 29 additions and 56 deletions
|
|
@ -90,9 +90,6 @@ also cause errors.
|
|||
Type
|
||||
----
|
||||
|
||||
The type of a JSON value is queried and tested using the following
|
||||
functions:
|
||||
|
||||
.. type:: enum json_type
|
||||
|
||||
The type of a JSON value. The following members are defined:
|
||||
|
|
@ -171,8 +168,6 @@ no longer needed, the reference count is decremented. When the
|
|||
reference count drops to zero, there are no references left, and the
|
||||
value can be destroyed.
|
||||
|
||||
The following functions are used to manipulate the reference count.
|
||||
|
||||
.. function:: json_t *json_incref(json_t *json)
|
||||
|
||||
Increment the reference count of *json* if it's not *NULL*.
|
||||
|
|
@ -448,9 +443,6 @@ information, see :ref:`rfc-conformance`.
|
|||
Sets the associated value of *real* to *value*. Returns 0 on
|
||||
success and -1 if *real* is not a JSON real.
|
||||
|
||||
In addition to the functions above, there's a common query function
|
||||
for integers and reals:
|
||||
|
||||
.. function:: double json_number_value(const json_t *json)
|
||||
|
||||
Returns the associated value of the JSON integer or JSON real
|
||||
|
|
@ -538,9 +530,6 @@ A JSON array is an ordered collection of other JSON values.
|
|||
Appends all elements in *other_array* to the end of *array*.
|
||||
Returns 0 on success and -1 on error.
|
||||
|
||||
The following macro can be used to iterate through all elements
|
||||
in an array.
|
||||
|
||||
.. function:: json_array_foreach(array, index, value)
|
||||
|
||||
Iterate over every element of ``array``, running the block
|
||||
|
|
@ -562,8 +551,7 @@ in an array.
|
|||
preprocessing, so its performance is equivalent to that of
|
||||
hand-written code using the array access functions.
|
||||
The main advantage of this macro is that it abstracts
|
||||
away the complexity, and makes for shorter, more
|
||||
concise code.
|
||||
away the complexity, and makes for more concise and readable code.
|
||||
|
||||
.. versionadded:: 2.5
|
||||
|
||||
|
|
@ -656,9 +644,6 @@ allowed in object keys.
|
|||
|
||||
.. versionadded:: 2.3
|
||||
|
||||
The following macro can be used to iterate through all key-value pairs
|
||||
in an object.
|
||||
|
||||
.. function:: json_object_foreach(object, key, value)
|
||||
|
||||
Iterate over every key-value pair of ``object``, running the block
|
||||
|
|
@ -684,8 +669,8 @@ in an object.
|
|||
preprocessing, so its performance is equivalent to that of
|
||||
hand-written iteration code using the object iteration protocol
|
||||
(see below). The main advantage of this macro is that it abstracts
|
||||
away the complexity behind iteration, and makes for shorter, more
|
||||
concise code.
|
||||
away the complexity behind iteration, and makes for more concise and
|
||||
readable code.
|
||||
|
||||
.. versionadded:: 2.3
|
||||
|
||||
|
|
@ -699,10 +684,10 @@ in an object.
|
|||
.. versionadded:: 2.8
|
||||
|
||||
|
||||
The following functions implement an iteration protocol for objects,
|
||||
allowing to iterate through all key-value pairs in an object. The
|
||||
items are not returned in any particular order, as this would require
|
||||
sorting due to the internal hashtable implementation.
|
||||
The following functions can be used to iterate through all key-value
|
||||
pairs in an object. The items are not returned in any particular order,
|
||||
as this would require sorting due to the internal hashtable
|
||||
implementation.
|
||||
|
||||
.. function:: void *json_object_iter(json_t *object)
|
||||
|
||||
|
|
@ -749,25 +734,23 @@ sorting due to the internal hashtable implementation.
|
|||
Like :func:`json_object_iter_at()`, but much faster. Only works for
|
||||
values returned by :func:`json_object_iter_key()`. Using other keys
|
||||
will lead to segfaults. This function is used internally to
|
||||
implement :func:`json_object_foreach`.
|
||||
implement :func:`json_object_foreach`. Example::
|
||||
|
||||
/* obj is a JSON object */
|
||||
const char *key;
|
||||
json_t *value;
|
||||
|
||||
void *iter = json_object_iter(obj);
|
||||
while(iter)
|
||||
{
|
||||
key = json_object_iter_key(iter);
|
||||
value = json_object_iter_value(iter);
|
||||
/* use key and value ... */
|
||||
iter = json_object_iter_next(obj, iter);
|
||||
}
|
||||
|
||||
.. versionadded:: 2.3
|
||||
|
||||
The iteration protocol can be used for example as follows::
|
||||
|
||||
/* obj is a JSON object */
|
||||
const char *key;
|
||||
json_t *value;
|
||||
|
||||
void *iter = json_object_iter(obj);
|
||||
while(iter)
|
||||
{
|
||||
key = json_object_iter_key(iter);
|
||||
value = json_object_iter_value(iter);
|
||||
/* use key and value ... */
|
||||
iter = json_object_iter_next(obj, iter);
|
||||
}
|
||||
|
||||
.. function:: void json_object_seed(size_t seed)
|
||||
|
||||
Seed the hash function used in Jansson's hashtable implementation.
|
||||
|
|
@ -910,7 +893,7 @@ can be ORed together to obtain *flags*.
|
|||
``JSON_ENCODE_ANY``
|
||||
Specifying this flag makes it possible to encode any JSON value on
|
||||
its own. Without it, only objects and arrays can be passed as the
|
||||
*root* value to the encoding functions.
|
||||
*json* value to the encoding functions.
|
||||
|
||||
**Note:** Encoding any value may be useful in some scenarios, but
|
||||
it's generally discouraged as it violates strict compatibility with
|
||||
|
|
@ -934,18 +917,17 @@ can be ORed together to obtain *flags*.
|
|||
|
||||
.. versionadded:: 2.7
|
||||
|
||||
The following functions perform the actual JSON encoding. The result
|
||||
is in UTF-8.
|
||||
These functions output UTF-8:
|
||||
|
||||
.. function:: char *json_dumps(const json_t *root, size_t flags)
|
||||
.. function:: char *json_dumps(const json_t *json, size_t flags)
|
||||
|
||||
Returns the JSON representation of *root* as a string, or *NULL* on
|
||||
Returns the JSON representation of *json* as a string, or *NULL* on
|
||||
error. *flags* is described above. The return value must be freed
|
||||
by the caller using :func:`free()`.
|
||||
|
||||
.. function:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
|
||||
.. function:: int json_dumpf(const json_t *json, FILE *output, size_t flags)
|
||||
|
||||
Write the JSON representation of *root* to the stream *output*.
|
||||
Write the JSON representation of *json* to the stream *output*.
|
||||
*flags* is described above. Returns 0 on success and -1 on error.
|
||||
If an error occurs, something may have already been written to
|
||||
*output*. In this case, the output is undefined and most likely not
|
||||
|
|
@ -953,7 +935,7 @@ is in UTF-8.
|
|||
|
||||
.. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
|
||||
|
||||
Write the JSON representation of *root* to the file *path*. If
|
||||
Write the JSON representation of *json* to the file *path*. If
|
||||
*path* already exists, it is overwritten. *flags* is described
|
||||
above. Returns 0 on success and -1 on error.
|
||||
|
||||
|
|
@ -976,7 +958,7 @@ is in UTF-8.
|
|||
.. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags)
|
||||
|
||||
Call *callback* repeatedly, passing a chunk of the JSON
|
||||
representation of *root* each time. *flags* is described above.
|
||||
representation of *json* each time. *flags* is described above.
|
||||
Returns 0 on success and -1 on error.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
|
@ -1076,8 +1058,6 @@ its ``position`` field. This is especially useful when using
|
|||
|
||||
If no error or position information is needed, you can pass *NULL*.
|
||||
|
||||
The following functions perform the actual JSON decoding.
|
||||
|
||||
.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
|
||||
|
||||
.. refcounting:: new
|
||||
|
|
@ -1266,8 +1246,6 @@ arguments.
|
|||
|
||||
Whitespace, ``:`` and ``,`` are ignored.
|
||||
|
||||
The following functions compose the value building API:
|
||||
|
||||
.. function:: json_t *json_pack(const char *fmt, ...)
|
||||
|
||||
.. refcounting:: new
|
||||
|
|
@ -1407,8 +1385,6 @@ type whose address should be passed.
|
|||
|
||||
Whitespace, ``:`` and ``,`` are ignored.
|
||||
|
||||
The following functions compose the parsing and validation API:
|
||||
|
||||
.. function:: int json_unpack(json_t *root, const char *fmt, ...)
|
||||
|
||||
Validate and unpack the JSON value *root* according to the format
|
||||
|
|
@ -1510,9 +1486,6 @@ only if they are exactly the same value, but also if they have equal
|
|||
if their types are equal. (Because these values are singletons,
|
||||
their equality can actually be tested with ``==``.)
|
||||
|
||||
The following function can be used to test whether two JSON values are
|
||||
equal.
|
||||
|
||||
.. function:: int json_equal(json_t *value1, json_t *value2)
|
||||
|
||||
Returns 1 if *value1* and *value2* are equal, as defined above.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue