"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/apiref.rst" between
jansson-2.13.1.tar.bz2 and jansson-2.14.tar.bz2

About: Jansson is a C library for encoding, decoding and manipulating JSON data.

[ To the main jansson source changes report ]

apiref.rst  (jansson-2.13.1.tar.bz2):apiref.rst  (jansson-2.14.tar.bz2)
skipping to change at line 114 skipping to change at line 114
Unless noted otherwise, all API functions return an error value if an Unless noted otherwise, all API functions return an error value if an
error occurs. Depending on the function's signature, the error value error occurs. Depending on the function's signature, the error value
is either *NULL* or -1. Invalid arguments or invalid input are is either *NULL* or -1. Invalid arguments or invalid input are
apparent sources for errors. Memory allocation and I/O operations may apparent sources for errors. Memory allocation and I/O operations may
also cause errors. also cause errors.
Type Type
---- ----
.. type:: enum json_type .. c:enum:: json_type
The type of a JSON value. The following members are defined: The type of a JSON value. The following members are defined:
+--------------------+ +--------------------+
| ``JSON_OBJECT`` | | ``JSON_OBJECT`` |
+--------------------+ +--------------------+
| ``JSON_ARRAY`` | | ``JSON_ARRAY`` |
+--------------------+ +--------------------+
| ``JSON_STRING`` | | ``JSON_STRING`` |
+--------------------+ +--------------------+
skipping to change at line 145 skipping to change at line 145
These correspond to JSON object, array, string, number, boolean and These correspond to JSON object, array, string, number, boolean and
null. A number is represented by either a value of the type null. A number is represented by either a value of the type
``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value
is represented by a value of the type ``JSON_TRUE`` and false by a is represented by a value of the type ``JSON_TRUE`` and false by a
value of the type ``JSON_FALSE``. value of the type ``JSON_FALSE``.
.. function:: int json_typeof(const json_t *json) .. function:: int json_typeof(const json_t *json)
Return the type of the JSON value (a :type:`json_type` cast to Return the type of the JSON value (a :type:`json_type` cast to
:type:`int`). *json* MUST NOT be *NULL*. This function is actually ``int``). *json* MUST NOT be *NULL*. This function is actually
implemented as a macro for speed. implemented as a macro for speed.
.. function:: json_is_object(const json_t *json) .. function:: int json_is_object(const json_t *json)
json_is_array(const json_t *json) int json_is_array(const json_t *json)
json_is_string(const json_t *json) int json_is_string(const json_t *json)
json_is_integer(const json_t *json) int json_is_integer(const json_t *json)
json_is_real(const json_t *json) int json_is_real(const json_t *json)
json_is_true(const json_t *json) int json_is_true(const json_t *json)
json_is_false(const json_t *json) int json_is_false(const json_t *json)
json_is_null(const json_t *json) int json_is_null(const json_t *json)
These functions (actually macros) return true (non-zero) for values These functions (actually macros) return true (non-zero) for values
of the given type, and false (zero) for values of other types and of the given type, and false (zero) for values of other types and
for *NULL*. for *NULL*.
.. function:: json_is_number(const json_t *json) .. function:: int json_is_number(const json_t *json)
Returns true for values of types ``JSON_INTEGER`` and Returns true for values of types ``JSON_INTEGER`` and
``JSON_REAL``, and false for other types and for *NULL*. ``JSON_REAL``, and false for other types and for *NULL*.
.. function:: json_is_boolean(const json_t *json) .. function:: int json_is_boolean(const json_t *json)
Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
for values of other types and for *NULL*. for values of other types and for *NULL*.
.. function:: json_boolean_value(const json_t *json) .. function:: int json_boolean_value(const json_t *json)
Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE`` Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE``
and 0 otherwise. and 0 otherwise.
.. versionadded:: 2.7 .. versionadded:: 2.7
.. _apiref-reference-count: .. _apiref-reference-count:
Reference Count Reference Count
--------------- ---------------
skipping to change at line 587 skipping to change at line 587
.. function:: int json_array_clear(json_t *array) .. function:: int json_array_clear(json_t *array)
Removes all elements from *array*. Returns 0 on success and -1 on Removes all elements from *array*. Returns 0 on success and -1 on
error. The reference count of all removed values are decremented. error. The reference count of all removed values are decremented.
.. function:: int json_array_extend(json_t *array, json_t *other_array) .. function:: int json_array_extend(json_t *array, json_t *other_array)
Appends all elements in *other_array* to the end of *array*. Appends all elements in *other_array* to the end of *array*.
Returns 0 on success and -1 on error. Returns 0 on success and -1 on error.
.. function:: json_array_foreach(array, index, value) .. function:: void json_array_foreach(array, index, value)
Iterate over every element of ``array``, running the block Iterate over every element of ``array``, running the block
of code that follows each time with the proper values set to of code that follows each time with the proper values set to
variables ``index`` and ``value``, of types :type:`size_t` and variables ``index`` and ``value``, of types :type:`size_t` and
:type:`json_t *` respectively. Example:: :type:`json_t` pointer respectively. Example::
/* array is a JSON array */ /* array is a JSON array */
size_t index; size_t index;
json_t *value; json_t *value;
json_array_foreach(array, index, value) { json_array_foreach(array, index, value) {
/* block of code that uses index and value */ /* block of code that uses index and value */
} }
The items are returned in increasing index order. The items are returned in increasing index order.
skipping to change at line 640 skipping to change at line 640
Returns the number of elements in *object*, or 0 if *object* is not Returns the number of elements in *object*, or 0 if *object* is not
a JSON object. a JSON object.
.. function:: json_t *json_object_get(const json_t *object, const char *key) .. function:: json_t *json_object_get(const json_t *object, const char *key)
.. refcounting:: borrow .. refcounting:: borrow
Get a value corresponding to *key* from *object*. Returns *NULL* if Get a value corresponding to *key* from *object*. Returns *NULL* if
*key* is not found and on error. *key* is not found and on error.
.. function:: json_t *json_object_getn(const json_t *object, const char *key, si
ze_t key_len)
.. refcounting:: borrow
Like :func:`json_object_get`, but give the fixed-length *key* with length *ke
y_len*.
See :ref:`fixed_length_keys` for details.
.. versionadded:: 2.14
.. function:: int json_object_set(json_t *object, const char *key, json_t *value ) .. function:: int json_object_set(json_t *object, const char *key, json_t *value )
Set the value of *key* to *value* in *object*. *key* must be a Set the value of *key* to *value* in *object*. *key* must be a
valid null terminated UTF-8 encoded Unicode string. If there valid null terminated UTF-8 encoded Unicode string. If there
already is a value for *key*, it is replaced by the new value. already is a value for *key*, it is replaced by the new value.
Returns 0 on success and -1 on error. Returns 0 on success and -1 on error.
.. function:: int json_object_setn(json_t *object, const char *key, size_t key_l
en, json_t *value)
Like :func:`json_object_set`, but give the fixed-length *key* with length *ke
y_len*.
See :ref:`fixed_length_keys` for details.
.. versionadded:: 2.14
.. function:: int json_object_set_nocheck(json_t *object, const char *key, json_ t *value) .. function:: int json_object_set_nocheck(json_t *object, const char *key, json_ t *value)
Like :func:`json_object_set`, but doesn't check that *key* is Like :func:`json_object_set`, but doesn't check that *key* is
valid UTF-8. Use this function only if you are certain that this valid UTF-8. Use this function only if you are certain that this
really is the case (e.g. you have already checked it by other really is the case (e.g. you have already checked it by other
means). means).
.. function:: int json_object_setn_nocheck(json_t *object, const char *key, size
_t key_len, json_t *value)
Like :func:`json_object_set_nocheck`, but give the fixed-length *key* with le
ngth *key_len*.
See :ref:`fixed_length_keys` for details.
.. versionadded:: 2.14
.. function:: int json_object_set_new(json_t *object, const char *key, json_t *v alue) .. function:: int json_object_set_new(json_t *object, const char *key, json_t *v alue)
Like :func:`json_object_set()` but steals the reference to Like :func:`json_object_set()` but steals the reference to
*value*. This is useful when *value* is newly created and not used *value*. This is useful when *value* is newly created and not used
after the call. after the call.
.. function:: int json_object_setn_new(json_t *object, const char *key, size_t k
ey_len, json_t *value)
Like :func:`json_object_set_new`, but give the fixed-length *key* with length
*key_len*.
See :ref:`fixed_length_keys` for details.
.. versionadded:: 2.14
.. function:: int json_object_set_new_nocheck(json_t *object, const char *key, j son_t *value) .. function:: int json_object_set_new_nocheck(json_t *object, const char *key, j son_t *value)
Like :func:`json_object_set_new`, but doesn't check that *key* is Like :func:`json_object_set_new`, but doesn't check that *key* is
valid UTF-8. Use this function only if you are certain that this valid UTF-8. Use this function only if you are certain that this
really is the case (e.g. you have already checked it by other really is the case (e.g. you have already checked it by other
means). means).
.. function:: int json_object_setn_new_nocheck(json_t *object, const char *key,
size_t key_len, json_t *value)
Like :func:`json_object_set_new_nocheck`, but give the fixed-length *key* wit
h length *key_len*.
See :ref:`fixed_length_keys` for details.
.. versionadded:: 2.14
.. function:: int json_object_del(json_t *object, const char *key) .. function:: int json_object_del(json_t *object, const char *key)
Delete *key* from *object* if it exists. Returns 0 on success, or Delete *key* from *object* if it exists. Returns 0 on success, or
-1 if *key* was not found. The reference count of the removed value -1 if *key* was not found. The reference count of the removed value
is decremented. is decremented.
.. function:: int json_object_deln(json_t *object, const char *key, size_t key_l
en)
Like :func:`json_object_del`, but give the fixed-length *key* with length *ke
y_len*.
See :ref:`fixed_length_keys` for details.
.. versionadded:: 2.14
.. function:: int json_object_clear(json_t *object) .. function:: int json_object_clear(json_t *object)
Remove all elements from *object*. Returns 0 on success and -1 if Remove all elements from *object*. Returns 0 on success and -1 if
*object* is not a JSON object. The reference count of all removed *object* is not a JSON object. The reference count of all removed
values are decremented. values are decremented.
.. function:: int json_object_update(json_t *object, json_t *other) .. function:: int json_object_update(json_t *object, json_t *other)
Update *object* with the key-value pairs from *other*, overwriting Update *object* with the key-value pairs from *other*, overwriting
existing keys. Returns 0 on success or -1 on error. existing keys. Returns 0 on success or -1 on error.
skipping to change at line 724 skipping to change at line 768
Like :func:`json_object_update_new()`, but only new keys are created. Like :func:`json_object_update_new()`, but only new keys are created.
The value of any existing key is not changed. Returns 0 on success The value of any existing key is not changed. Returns 0 on success
or -1 on error. or -1 on error.
.. function:: int json_object_update_recursive(json_t *object, json_t *other) .. function:: int json_object_update_recursive(json_t *object, json_t *other)
Like :func:`json_object_update()`, but object values in *other* are Like :func:`json_object_update()`, but object values in *other* are
recursively merged with the corresponding values in *object* if they are also recursively merged with the corresponding values in *object* if they are also
objects, instead of overwriting them. Returns 0 on success or -1 on error. objects, instead of overwriting them. Returns 0 on success or -1 on error.
.. function:: json_object_foreach(object, key, value) .. function:: void json_object_foreach(object, key, value)
Iterate over every key-value pair of ``object``, running the block Iterate over every key-value pair of ``object``, running the block
of code that follows each time with the proper values set to of code that follows each time with the proper values set to
variables ``key`` and ``value``, of types :type:`const char *` and variables ``key`` and ``value``, of types ``const char *`` and
:type:`json_t *` respectively. Example:: :type:`json_t` pointer respectively. Example::
/* obj is a JSON object */ /* obj is a JSON object */
const char *key; const char *key;
json_t *value; json_t *value;
json_object_foreach(obj, key, value) { json_object_foreach(obj, key, value) {
/* block of code that uses key and value */ /* block of code that uses key and value */
} }
The items are returned in the order they were inserted to the The items are returned in the order they were inserted to the
object. object.
**Note:** It's not safe to call ``json_object_del(object, key)`` **Note:** It's not safe to call ``json_object_del(object, key)`` or ``json_ob ject_deln(object, key, key_len)``
during iteration. If you need to, use during iteration. If you need to, use
:func:`json_object_foreach_safe` instead. :func:`json_object_foreach_safe` instead.
This macro expands to an ordinary ``for`` statement upon This macro expands to an ordinary ``for`` statement upon
preprocessing, so its performance is equivalent to that of preprocessing, so its performance is equivalent to that of
hand-written iteration code using the object iteration protocol hand-written iteration code using the object iteration protocol
(see below). The main advantage of this macro is that it abstracts (see below). The main advantage of this macro is that it abstracts
away the complexity behind iteration, and makes for more concise and away the complexity behind iteration, and makes for more concise and
readable code. readable code.
.. versionadded:: 2.3 .. versionadded:: 2.3
.. function:: json_object_foreach_safe(object, tmp, key, value) .. function:: void json_object_foreach_safe(object, tmp, key, value)
Like :func:`json_object_foreach()`, but it's safe to call Like :func:`json_object_foreach()`, but it's safe to call
``json_object_del(object, key)`` during iteration. You need to pass ``json_object_del(object, key)`` or ``json_object_deln(object, key, key_len)`
an extra ``void *`` parameter ``tmp`` that is used for temporary storage. ` during iteration.
You need to pass an extra ``void *`` parameter ``tmp`` that is used for tempo
rary storage.
.. versionadded:: 2.8 .. versionadded:: 2.8
.. function:: void json_object_keylen_foreach(object, key, key_len, value)
Like :c:func:`json_object_foreach`, but in *key_len* stored length of the *ke
y*.
Example::
/* obj is a JSON object */
const char *key;
json_t *value;
size_t len;
json_object_keylen_foreach(obj, key, len, value) {
printf("got key %s with length %zu\n", key, len);
}
**Note:** It's not safe to call ``json_object_deln(object, key, key_len)``
during iteration. If you need to, use
:func:`json_object_keylen_foreach_safe` instead.
.. versionadded:: 2.14
.. function:: void json_object_keylen_foreach_safe(object, tmp, key, key_len, va
lue)
Like :func:`json_object_keylen_foreach()`, but it's safe to call
``json_object_deln(object, key, key_len)`` during iteration.
You need to pass an extra ``void *`` parameter ``tmp`` that is used for tempo
rary storage.
.. versionadded:: 2.14
The following functions can be used to iterate through all key-value The following functions can be used to iterate through all key-value
pairs in an object. The items are returned in the order they were pairs in an object. The items are returned in the order they were
inserted to the object. inserted to the object.
.. function:: void *json_object_iter(json_t *object) .. function:: void *json_object_iter(json_t *object)
Returns an opaque iterator which can be used to iterate over all Returns an opaque iterator which can be used to iterate over all
key-value pairs in *object*, or *NULL* if *object* is empty. key-value pairs in *object*, or *NULL* if *object* is empty.
.. function:: void *json_object_iter_at(json_t *object, const char *key) .. function:: void *json_object_iter_at(json_t *object, const char *key)
skipping to change at line 790 skipping to change at line 862
.. function:: void *json_object_iter_next(json_t *object, void *iter) .. function:: void *json_object_iter_next(json_t *object, void *iter)
Returns an iterator pointing to the next key-value pair in *object* Returns an iterator pointing to the next key-value pair in *object*
after *iter*, or *NULL* if the whole object has been iterated after *iter*, or *NULL* if the whole object has been iterated
through. through.
.. function:: const char *json_object_iter_key(void *iter) .. function:: const char *json_object_iter_key(void *iter)
Extract the associated key from *iter*. Extract the associated key from *iter*.
.. function:: size_t json_object_iter_key_len(void *iter)
Extract the associated key length from *iter*.
.. versionadded:: 2.14
.. function:: json_t *json_object_iter_value(void *iter) .. function:: json_t *json_object_iter_value(void *iter)
.. refcounting:: borrow .. refcounting:: borrow
Extract the associated value from *iter*. Extract the associated value from *iter*.
.. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value ) .. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value )
Set the value of the key-value pair in *object*, that is pointed to Set the value of the key-value pair in *object*, that is pointed to
by *iter*, to *value*. by *iter*, to *value*.
skipping to change at line 845 skipping to change at line 923
If *seed* is 0, Jansson generates the seed itself by reading If *seed* is 0, Jansson generates the seed itself by reading
random data from the operating system's entropy sources. If no random data from the operating system's entropy sources. If no
entropy sources are available, falls back to using a combination entropy sources are available, falls back to using a combination
of the current timestamp (with microsecond precision if possible) of the current timestamp (with microsecond precision if possible)
and the process ID. and the process ID.
If called at all, this function must be called before any calls to If called at all, this function must be called before any calls to
:func:`json_object()`, either explicit or implicit. If this :func:`json_object()`, either explicit or implicit. If this
function is not called by the user, the first call to function is not called by the user, the first call to
:func:`json_object()` (either explicit or implicit) seeds the hash :func:`json_object()` (either explicit or implicit) seeds the hash
function. See :ref:`portability-thread-safety` for notes on thread function. See :ref:`thread-safety` for notes on thread safety.
safety.
If repeatable results are required, for e.g. unit tests, the hash If repeatable results are required, for e.g. unit tests, the hash
function can be "unrandomized" by calling :func:`json_object_seed` function can be "unrandomized" by calling :func:`json_object_seed`
with a constant value on program startup, e.g. with a constant value on program startup, e.g.
``json_object_seed(1)``. ``json_object_seed(1)``.
.. versionadded:: 2.6 .. versionadded:: 2.6
Error reporting Error reporting
=============== ===============
skipping to change at line 915 skipping to change at line 992
} }
Also note that if the call succeeded (``json != NULL`` in the above Also note that if the call succeeded (``json != NULL`` in the above
example), the contents of ``error`` are generally left unspecified. example), the contents of ``error`` are generally left unspecified.
The decoding functions write to the ``position`` member also on The decoding functions write to the ``position`` member also on
success. See :ref:`apiref-decoding` for more info. success. See :ref:`apiref-decoding` for more info.
All functions also accept *NULL* as the :type:`json_error_t` pointer, All functions also accept *NULL* as the :type:`json_error_t` pointer,
in which case no error information is returned to the caller. in which case no error information is returned to the caller.
.. type:: enum json_error_code .. c:enum:: json_error_code
An enumeration containing numeric error codes. The following errors are An enumeration containing numeric error codes. The following errors are
currently defined: currently defined:
``json_error_unknown`` ``json_error_unknown``
Unknown error. This should only be returned for non-errorneous Unknown error. This should only be returned for non-errorneous
:type:`json_error_t` structures. :type:`json_error_t` structures.
``json_error_out_of_memory`` ``json_error_out_of_memory``
skipping to change at line 1009 skipping to change at line 1086
.. function:: enum json_error_code json_error_code(const json_error_t *error) .. function:: enum json_error_code json_error_code(const json_error_t *error)
Returns the error code embedded in ``error->text``. Returns the error code embedded in ``error->text``.
.. versionadded:: 2.11 .. versionadded:: 2.11
Encoding Encoding
======== ========
This sections describes the functions that can be used to encode This section describes the functions that can be used to encode
values to JSON. By default, only objects and arrays can be encoded values to JSON. By default, only objects and arrays can be encoded
directly, since they are the only valid *root* values of a JSON text. directly, since they are the only valid *root* values of a JSON text.
To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see
below). below).
By default, the output has no newlines, and spaces are used between By default, the output has no newlines, and spaces are used between
array and object elements for a readable output. This behavior can be array and object elements for a readable output. This behavior can be
altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags
described below. A newline is never appended to the end of the encoded described below. A newline is never appended to the end of the encoded
JSON data. JSON data.
skipping to change at line 1193 skipping to change at line 1270
representation of *json* each time. *flags* is described above. representation of *json* each time. *flags* is described above.
Returns 0 on success and -1 on error. Returns 0 on success and -1 on error.
.. versionadded:: 2.2 .. versionadded:: 2.2
.. _apiref-decoding: .. _apiref-decoding:
Decoding Decoding
======== ========
This sections describes the functions that can be used to decode JSON This section describes the functions that can be used to decode JSON
text to the Jansson representation of JSON data. The JSON text to the Jansson representation of JSON data. The JSON
specification requires that a JSON text is either a serialized array specification requires that a JSON text is either a serialized array
or object, and this requirement is also enforced with the following or object, and this requirement is also enforced with the following
functions. In other words, the top level value in the JSON text being functions. In other words, the top level value in the JSON text being
decoded must be either array or object. To decode any JSON value, use decoded must be either array or object. To decode any JSON value, use
the ``JSON_DECODE_ANY`` flag (see below). the ``JSON_DECODE_ANY`` flag (see below).
See :ref:`rfc-conformance` for a discussion on Jansson's conformance See :ref:`rfc-conformance` for a discussion on Jansson's conformance
to the JSON specification. It explains many design decisions that to the JSON specification. It explains many design decisions that
affect especially the behavior of the decoder. affect especially the behavior of the decoder.
skipping to change at line 1474 skipping to change at line 1551
``+%`` (string) [const char \*, size_t] ``+%`` (string) [const char \*, size_t]
Like ``+#`` but the length argument is of type :type:`size_t`. Like ``+#`` but the length argument is of type :type:`size_t`.
.. versionadded:: 2.6 .. versionadded:: 2.6
``n`` (null) ``n`` (null)
Output a JSON null value. No argument is consumed. Output a JSON null value. No argument is consumed.
``b`` (boolean) [int] ``b`` (boolean) [int]
Convert a C :type:`int` to JSON boolean value. Zero is converted Convert a C ``int`` to JSON boolean value. Zero is converted
to ``false`` and non-zero to ``true``. to ``false`` and non-zero to ``true``.
``i`` (integer) [int] ``i`` (integer) [int]
Convert a C :type:`int` to JSON integer. Convert a C ``int`` to JSON integer.
``I`` (integer) [json_int_t] ``I`` (integer) [json_int_t]
Convert a C :type:`json_int_t` to JSON integer. Convert a C :type:`json_int_t` to JSON integer.
``f`` (real) [double] ``f`` (real) [double]
Convert a C :type:`double` to JSON real. Convert a C ``double`` to JSON real.
``o`` (any value) [json_t \*] ``o`` (any value) [json_t \*]
Output any given JSON value as-is. If the value is added to an Output any given JSON value as-is. If the value is added to an
array or object, the reference to the value passed to ``o`` is array or object, the reference to the value passed to ``o`` is
stolen by the container. stolen by the container.
``O`` (any value) [json_t \*] ``O`` (any value) [json_t \*]
Like ``o``, but the argument's reference count is incremented. Like ``o``, but the argument's reference count is incremented.
This is useful if you pack into an array or object and want to This is useful if you pack into an array or object and want to
keep the reference for the JSON value consumed by ``O`` to keep the reference for the JSON value consumed by ``O`` to
skipping to change at line 1610 skipping to change at line 1687
``s%`` (string) [const char \*, size_t \*] ``s%`` (string) [const char \*, size_t \*]
Convert a JSON string to a pointer to a null terminated UTF-8 Convert a JSON string to a pointer to a null terminated UTF-8
string and its length. string and its length.
.. versionadded:: 2.6 .. versionadded:: 2.6
``n`` (null) ``n`` (null)
Expect a JSON null value. Nothing is extracted. Expect a JSON null value. Nothing is extracted.
``b`` (boolean) [int] ``b`` (boolean) [int]
Convert a JSON boolean value to a C :type:`int`, so that ``true`` Convert a JSON boolean value to a C ``int``, so that ``true``
is converted to 1 and ``false`` to 0. is converted to 1 and ``false`` to 0.
``i`` (integer) [int] ``i`` (integer) [int]
Convert a JSON integer to C :type:`int`. Convert a JSON integer to C ``int``.
``I`` (integer) [json_int_t] ``I`` (integer) [json_int_t]
Convert a JSON integer to C :type:`json_int_t`. Convert a JSON integer to C :type:`json_int_t`.
``f`` (real) [double] ``f`` (real) [double]
Convert a JSON real to C :type:`double`. Convert a JSON real to C ``double``.
``F`` (integer or real) [double] ``F`` (integer or real) [double]
Convert a JSON number (integer or real) to C :type:`double`. Convert a JSON number (integer or real) to C ``double``.
``o`` (any value) [json_t \*] ``o`` (any value) [json_t \*]
Store a JSON value with no conversion to a :type:`json_t` pointer. Store a JSON value with no conversion to a :type:`json_t` pointer.
``O`` (any value) [json_t \*] ``O`` (any value) [json_t \*]
Like ``o``, but the JSON value's reference count is incremented. Like ``o``, but the JSON value's reference count is incremented.
Storage pointers should be initialized NULL before using unpack. Storage pointers should be initialized NULL before using unpack.
The caller is responsible for releasing all references incremented The caller is responsible for releasing all references incremented
by unpack, even when an error occurs. by unpack, even when an error occurs.
skipping to change at line 1891 skipping to change at line 1968
{ {
json_set_alloc_funcs(secure_malloc, secure_free); json_set_alloc_funcs(secure_malloc, secure_free);
/* ... */ /* ... */
} }
For more information about the issues of storing sensitive data in For more information about the issues of storing sensitive data in
memory, see memory, see
http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.ht ml. http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.ht ml.
The page also explains the :func:`guaranteed_memset()` function used The page also explains the :func:`guaranteed_memset()` function used
in the example and gives a sample implementation for it. in the example and gives a sample implementation for it.
.. _fixed_length_keys:
Fixed-Length keys
=================
The Jansson API allows work with fixed-length keys. This can be useful in the fo
llowing cases:
* The key is contained inside a buffer and is not null-terminated. In this case
creating a new temporary buffer is not needed.
* The key contains U+0000 inside it.
List of API for fixed-length keys:
* :c:func:`json_object_getn`
* :c:func:`json_object_setn`
* :c:func:`json_object_setn_nocheck`
* :c:func:`json_object_setn_new`
* :c:func:`json_object_setn_new_nocheck`
* :c:func:`json_object_deln`
* :c:func:`json_object_iter_key_len`
* :c:func:`json_object_keylen_foreach`
* :c:func:`json_object_keylen_foreach_safe`
**Examples:**
Try to write a new function to get :c:struct:`json_t` by path separated by ``.``
This requires:
* string iterator (no need to modify the input for better performance)
* API for working with fixed-size keys
The iterator::
struct string {
const char *string;
size_t length;
};
size_t string_try_next(struct string *str, const char *delimiter) {
str->string += strspn(str->string, delimiter);
str->length = strcspn(str->string, delimiter);
return str->length;
}
#define string_foreach(_string, _delimiter) \
for (; string_try_next(&(_string), _delimiter); (_string).string +=
(_string).length)
The function::
json_t *json_object_get_by_path(json_t *object, const char *path) {
struct string str;
json_t *out = object;
str.string = path;
string_foreach(str, ".") {
out = json_object_getn(out, str.string, str.length);
if (out == NULL)
return NULL;
}
return out;
}
And usage::
int main(void) {
json_t *obj = json_pack("{s:{s:{s:b}}}", "a", "b", "c", 1);
json_t *c = json_object_get_by_path(obj, "a.b.c");
assert(json_is_true(c));
json_decref(obj);
}
 End of changes. 33 change blocks. 
34 lines changed or deleted 128 lines changed or added
To the RST Files section of the jansson source changes report or the top of this page
Mainly generated by pkgdiff using rfcdiff
Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)