``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
**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. Even Jansson itself doesn't have any means
- to decode JSON texts whose root value is not object or array.
+ with other JSON systems.
.. versionadded:: 2.1
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
.. 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)
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)
.. refcounting:: new
Returns a deep copy of *value*, or *NULL* on error.
+.. _apiref-custom-memory-allocation:
+
Custom Memory Allocation
========================
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.