Update *object* with the key-value pairs from *other*, overwriting
existing keys. Returns 0 on success or -1 on error.
+.. function:: int json_object_update_existing(json_t *object, json_t *other)
+
+ Like :func:`json_object_update()`, but only the values of existing
+ keys are updated. No new keys are created. Returns 0 on success or
+ -1 on error.
+
+ .. versionadded:: 2.3
+
+.. function:: int json_object_update_missing(json_t *object, json_t *other)
+
+ Like :func:`json_object_update()`, but only new keys are created.
+ The value of any existing key is not changed. Returns 0 on success
+ or -1 on error.
+
+ .. 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
+ of code that follows each time with the proper values set to
+ variables ``key`` and ``value``, of types :type:`const char *` and
+ :type:`json_t *` respectively. Example::
+
+ /* obj is a JSON object */
+ const char *key;
+ json_t *value;
+
+ json_object_foreach(obj, key, value) {
+ /* block of code that uses key and value */
+ }
+
+ The items are not returned in any particular order.
+
+ This macro expands to an ordinary ``for`` statement upon
+ 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.
+
+ .. versionadded:: 2.3
+
The following functions implement an iteration protocol for objects,
allowing to iterate through all key-value pairs in an object. The
*value*. This is useful when *value* is newly created and not used
after the call.
+.. function:: void *json_object_key_to_iter(const char *key)
+
+ 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`.
+
+ .. 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)
{
}
Also note that if the call succeeded (``json != NULL`` in the above
-example), the contents of ``error`` are unspecified.
+example), the contents of ``error`` are generally left unspecified.
+The decoding functions write to the ``position`` member also on
+success. See :ref:`apiref-decoding` for more info.
All functions also accept *NULL* as the :type:`json_error_t` pointer,
in which case no error information is returned to the caller.
.. versionadded:: 2.1
+``JSON_DECODE_ANY``
+ By default, the decoder expects an array or object as the input.
+ With this flag enabled, the decoder accepts any valid JSON value.
+
+ **Note:** Decoding any value may be useful in some scenarios, but
+ it's generally discouraged as it violates strict compatiblity with
+ :rfc:`4627`. If you use this flag, don't expect interoperatibility
+ with other JSON systems.
+
+ .. versionadded:: 2.3
+
``JSON_DISABLE_EOF_CHECK``
By default, the decoder expects that its whole input constitutes a
valid JSON text, and issues an error if there's extra data after
stops after decoding a valid JSON array or object, and thus allows
extra data after the JSON text.
+ Normally, reading will stop when the last ``]`` or ``}`` in the
+ JSON input is encountered. If both ``JSON_DISABLE_EOF_CHECK`` and
+ ``JSON_DECODE_ANY`` flags are used, the decoder may read one extra
+ UTF-8 code unit (up to 4 bytes of input). For example, decoding
+ ``4true`` correctly decodes the integer 4, but also reads the
+ ``t``. For this reason, if reading multiple consecutive values that
+ are not arrays or objects, they should be separated by at least one
+ whitespace character.
+
.. versionadded:: 2.1
-``JSON_DECODE_ANY``
- By default, the decoder expects an array or object as the input.
- With this flag enabled, the decoder accepts any valid JSON value.
+Each function also takes an optional :type:`json_error_t` parameter
+that is filled with error information if decoding fails. It's also
+updated on success; the number of bytes of input read is written to
+its ``position`` field. This is especially useful when using
+``JSON_DISABLE_EOF_CHECK`` to read multiple consecutive JSON texts.
- **Note:** Decoding any value may be useful in some scenarios, but
- it's generally discouraged as it violates strict compatiblity with
- :rfc:`4627`. If you use this flag, don't expect interoperatibility
- with other JSON systems.
+.. versionadded:: 2.3
+ Number of bytes of input read is written to the ``position`` field
+ of the :type:`json_error_t` structure.
- .. versionadded:: 2.3
+If no error or position information is needed, you can pass *NULL*.
The following functions perform the actual JSON decoding.
multiple times, if the input consists of consecutive JSON texts,
possibly separated by whitespace.
- If both ``JSON_DISABLE_EOF_CHECK`` and ``JSON_DECODE_ANY`` flags
- are used, the decoder may read one extra UTF-8 code unit (up to 4
- bytes of input). For example, decoding ``4true`` correctly decodes
- the integer 4, but leaves the file position pointing at ``r``
- instead of ``t``. For this reason, if reading multiple consecutive
- values that are not arrays and objects, they should be separated by
- at least one whitespace character.
-
.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
.. refcounting:: new