Removes the element in *array* at position *index*, shifting the
elements after *index* one position towards the start of the array.
- Returns 0 on success and -1 on error.
+ Returns 0 on success and -1 on error. The reference count of the
+ removed value is decremented.
.. function:: int json_array_clear(json_t *array)
Removes all elements from *array*. Returns 0 on sucess and -1 on
- error.
+ 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_object_del(json_t *object, const char *key)
Delete *key* from *object* if it exists. Returns 0 on success, or
- -1 if *key* was not found.
-
+ -1 if *key* was not found. The reference count of the removed value
+ is decremented.
.. function:: int json_object_clear(json_t *object)
Remove all elements from *object*. Returns 0 on success and -1 if
- *object* is not a JSON object.
+ *object* is not a JSON object. The reference count of all removed
+ values are decremented.
.. function:: int json_object_update(json_t *object, json_t *other)
existing keys. Returns 0 on success or -1 on error.
-The following functions implement an iteration protocol for objects:
+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.
.. function:: void *json_object_iter(json_t *object)
========
This sections describes the functions that can be used to encode
-values to JSON. Only objects and arrays can be encoded, since they are
-the only valid "root" values of a JSON text.
+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.
+To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see
+below).
By default, the output has no newlines, and spaces are used between
array and object elements for a readable output. This behavior can be
``JSON_INDENT(n)``
Pretty-print the result, using newlines between array and object
items, and indenting with *n* spaces. The valid range for *n* is
- between 0 and 32, other values result in an undefined output. If
- ``JSON_INDENT`` is not used or *n* is 0, no newlines are inserted
- between array and object items.
+ between 0 and 31 (inclusive), other values result in an undefined
+ output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are
+ inserted between array and object items.
``JSON_COMPACT``
This flag enables a compact representation, i.e. sets the separator
example, decoding a JSON text and then encoding with this flag
preserves the order of object keys.
+``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.
+
+ **Note:** Encoding 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.1
+
The following functions perform the actual JSON encoding. The result
is in UTF-8.
*path* already exists, it is overwritten. *flags* is described
above. Returns 0 on success and -1 on error.
+.. type:: json_dump_callback_t
+
+ A typedef for a function that's called by
+ :func:`json_dump_callback()`::
+
+ typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data);
+
+ *buffer* points to a buffer containing a chunk of output, *size* is
+ the length of the buffer, and *data* is the corresponding
+ :func:`json_dump_callback()` argument passed through.
+
+ On error, the function should return -1 to stop the encoding
+ process. On success, it should return 0.
+
+ .. versionadded:: 2.2
+
+.. 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.
+ Returns 0 on success and -1 on error.
+
+ .. versionadded:: 2.2
+
.. _apiref-decoding:
specification requires that a JSON text is either a serialized array
or object, and this requirement is also enforced with the following
functions. In other words, the top level value in the JSON text being
-decoded must be either array or object.
+decoded must be either array or object. To decode any JSON value, use
+the ``JSON_DECODE_ANY`` flag (see below).
See :ref:`rfc-conformance` for a discussion on Jansson's conformance
to the JSON specification. It explains many design decisions that
affect especially the behavior of the decoder.
+Each function takes a *flags* parameter that can be used to control
+the behavior of the decoder. Its default value is 0. The following
+macros can be ORed together to obtain *flags*.
+
+``JSON_REJECT_DUPLICATES``
+ Issue a decoding error if any JSON object in the input text
+ contains duplicate keys. Without this flag, the value of the last
+ occurence of each key ends up in the result. Key equivalence is
+ checked byte-by-byte, without special Unicode comparison
+ algorithms.
+
+ .. versionadded:: 2.1
+
+``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
+ the otherwise valid JSON input. With this flag enabled, the decoder
+ stops after decoding a valid JSON array or object, and thus allows
+ extra data after the JSON text.
+
+ .. 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
+
+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
Decodes the JSON string *input* and returns the array or object it
contains, or *NULL* on error, in which case *error* is filled with
- information about the error. *flags* is currently unused, and
- should be set to 0.
+ information about the error. *flags* is described above.
+
+.. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)
+
+ .. refcounting:: new
+
+ Decodes the JSON string *buffer*, whose length is *buflen*, and
+ returns the array or object it contains, or *NULL* on error, in
+ which case *error* is filled with information about the error. This
+ is similar to :func:`json_loads()` except that the string doesn't
+ need to be null-terminated. *flags* is described above.
+
+ .. versionadded:: 2.1
.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
Decodes the JSON text in stream *input* and returns the array or
object it contains, or *NULL* on error, in which case *error* is
- filled with information about the error. *flags* is currently
- unused, and should be set to 0.
+ filled with information about the error. *flags* is described
+ above.
+
+ This function will start reading the input from whatever position
+ the input file was, without attempting to seek first. If an error
+ occurs, the file position will be left indeterminate. On success,
+ the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK``
+ flag was used. In this case, the file position will be at the first
+ character after the last ``]`` or ``}`` in the JSON input. This
+ allows calling :func:`json_loadf()` on the same ``FILE`` object
+ 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)
Decodes the JSON text in file *path* and returns the array or
object it contains, or *NULL* on error, in which case *error* is
- filled with information about the error. *flags* is currently
- unused, and should be set to 0.
+ filled with information about the error. *flags* is described
+ above.
.. _apiref-pack:
-Building values
+Building Values
===============
-This sectinon describes functions that help to create, or *pack*,
+This section describes functions that help to create, or *pack*,
complex JSON values, especially nested objects and arrays. Value
building is based on a *format string* that is used to tell the
functions about the expected arguments.
For example, the format string ``"i"`` specifies a single integer
value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s,
-b]"`` specifies an array value with two integers and a boolean as its
+b]"`` specifies an array value with two strings and a boolean as its
items::
/* Create the JSON integer 42 */
``o`` (any value) [json_t \*]
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
- stealed by the container.
+ stolen by the container.
``O`` (any value) [json_t \*]
Like ``o``, but the argument's reference count is incremented.
- This is useful if you pack and array an array or object and want
- to keep the reference for the JSON value consumed by ``O`` 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
yourself.
``[fmt]`` (array)
json_pack("{}");
/* Build the JSON object {"foo": 42, "bar": 7} */
- json_pack("{sisb}", "foo", 42, "bar", 7);
+ json_pack("{sisi}", "foo", 42, "bar", 7);
/* Like above, ':', ',' and whitespace are ignored */
- json_pack("{s:i, s:b}", "foo", 42, "bar", 7);
+ json_pack("{s:i, s:i}", "foo", 42, "bar", 7);
/* Build the JSON array [[1, 2], {"cool": true}] */
json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
.. _apiref-unpack:
-Parsing and validating values
+Parsing and Validating Values
=============================
This sectinon describes functions that help to validate complex values
``s`` (string) [const char \*]
Convert a JSON string to a pointer to a NULL terminated UTF-8
- string.
+ string. The resulting string is extracted by using
+ :func:`json_string_value()` internally, so it exists as long as
+ there are still references to the corresponding JSON string.
``n`` (null)
Expect a JSON null value. Nothing is extracted.
behaviour of the unpacker, see below for the flags. Returns 0 on
success and -1 on failure.
+.. note::
+
+ The first argument of all unpack functions is ``json_t *root``
+ instead of ``const json_t *root``, because the use of ``O`` format
+ character causes the reference count of ``root``, or some value
+ reachable from ``root``, to be increased. Furthermore, the ``o``
+ format character may be used to extract a value as-is, which allows
+ modifying the structure or contents of a value reachable from
+ ``root``.
+
+ If the ``O`` and ``o`` format character are not used, it's
+ perfectly safe to cast a ``const json_t *`` variable to plain
+ ``json_t *`` when used with these functions.
+
The following unpacking flags are available:
``JSON_STRICT``
Returns a deep copy of *value*, or *NULL* on error.
-Custom memory allocation
+.. _apiref-custom-memory-allocation:
+
+Custom Memory Allocation
========================
By default, Jansson uses :func:`malloc()` and :func:`free()` for
For more information about the issues of storing sensitive data in
memory, see
http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html.
-The page also examplains 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.
projects / jansson.git / blobdiff