in each source file.
-All constants are prefixed ``JSON_`` and other identifiers with
-``json_``. Type names are suffixed with ``_t`` and ``typedef``\ 'd so
-that the ``struct`` keyword need not be used.
+All constants are prefixed with ``JSON_`` (except for those describing
+the library version, prefixed with ``JANSSON_``). Other identifiers
+are prefixed with ``json_``. Type names are suffixed with ``_t`` and
+``typedef``\ 'd so that the ``struct`` keyword need not be used.
+
+
+Library Version
+===============
+
+The Jansson version is of the form *A.B.C*, where *A* is the major
+version, *B* is the minor version and *C* is the micro version. If the
+micro version is zero, it's omitted from the version string, i.e. the
+version string is just *A.B*.
+
+When a new release only fixes bugs and doesn't add new features or
+functionality, the micro version is incremented. When new features are
+added in a backwards compatible way, the minor version is incremented
+and the micro version is set to zero. When there are backwards
+incompatible changes, the major version is incremented and others are
+set to zero.
+
+The following preprocessor constants specify the current version of
+the library:
+
+``JANSSON_MAJOR_VERSION``, ``JANSSON_MINOR_VERSION``, ``JANSSON_MICRO_VERSION``
+ Integers specifying the major, minor and micro versions,
+ respectively.
+
+``JANSSON_VERSION``
+ A string representation of the current version, e.g. ``"1.2.1"`` or
+ ``"1.3"``.
+
+``JANSSON_VERSION_HEX``
+ A 3-byte hexadecimal representation of the version, e.g.
+ ``0x010201`` for version 1.2.1 and ``0x010300`` for version 1.3.
+ This is useful in numeric comparisions, e.g.::
+
+ #if JANSSON_VERSION_HEX >= 0x010300
+ /* Code specific to version 1.3 and above */
+ #endif
Value Representation
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 means).
- .. versionadded:: 1.2
-
.. function:: const char *json_string_value(const json_t *string)
Returns the associated value of *string* as a null terminated UTF-8
encoded string, or *NULL* if *string* is not a JSON string.
+ The retuned value is read-only and must not be modified or freed by
+ the user. It is valid as long as *string* exists, i.e. as long as
+ its reference count has not dropped to zero.
+
.. function:: int json_string_set(const json_t *string, const char *value)
Sets the associated value of *string* to *value*. *value* must be a
valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
error.
- .. versionadded:: 1.1
-
.. function:: int json_string_set_nocheck(const json_t *string, const char *value)
Like :func:`json_string_set`, but doesn't check that *value* is
really is the case (e.g. you have already checked it by other
means).
- .. versionadded:: 1.2
-
Number
======
Sets the associated value of *integer* to *value*. Returns 0 on
success and -1 if *integer* is not a JSON integer.
- .. versionadded:: 1.1
-
.. function:: json_t *json_real(double value)
.. refcounting:: new
Sets the associated value of *real* to *value*. Returns 0 on
success and -1 if *real* is not a JSON real.
- .. versionadded:: 1.1
-
In addition to the functions above, there's a common query function
for integers and reals:
This is useful when *value* is newly created and not used after
the call.
- .. versionadded:: 1.1
-
.. function:: int json_array_append(json_t *array, json_t *value)
Appends *value* to the end of *array*, growing the size of *array*
*value*. This is useful when *value* is newly created and not used
after the call.
- .. versionadded:: 1.1
-
.. function:: int json_array_insert(json_t *array, size_t index, json_t *value)
Inserts *value* to *array* at position *index*, shifting the
elements at *index* and after it one position towards the end of
the array. Returns 0 on success and -1 on error.
- .. versionadded:: 1.1
-
.. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value)
Like :func:`json_array_insert()` but steals the reference to
*value*. This is useful when *value* is newly created and not used
after the call.
- .. versionadded:: 1.1
-
.. function:: int json_array_remove(json_t *array, size_t index)
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.
-
- .. versionadded:: 1.1
+ 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.
-
- .. versionadded:: 1.1
+ error. The reference count of all removed values are decremented.
.. function:: int json_array_extend(json_t *array, json_t *other_array)
Appends all elements in *other_array* to the end of *array*.
Returns 0 on success and -1 on error.
- .. versionadded:: 1.1
-
Object
======
Returns the number of elements in *object*, or 0 if *object* is not
a JSON object.
- .. versionadded:: 1.1
-
.. function:: json_t *json_object_get(const json_t *object, const char *key)
.. refcounting:: borrow
really is the case (e.g. you have already checked it by other
means).
- .. versionadded:: 1.2
-
.. function:: int json_object_set_new(json_t *object, const char *key, json_t *value)
Like :func:`json_object_set()` but steals the reference to
*value*. This is useful when *value* is newly created and not used
after the call.
- .. versionadded:: 1.1
-
.. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
Like :func:`json_object_set_new`, but doesn't check that *key* is
really is the case (e.g. you have already checked it by other
means).
- .. versionadded:: 1.2
-
.. 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.
-
- .. versionadded:: 1.1
+ *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)
Update *object* with the key-value pairs from *other*, overwriting
existing keys. Returns 0 on success or -1 on error.
- .. versionadded:: 1.1
+.. 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)
-The following functions implement an iteration protocol for objects:
+ 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
+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)
*object* only yields all key-value pairs of the object if *key*
happens to be the first key in the underlying hash table.
- .. versionadded:: 1.3
-
.. function:: void *json_object_iter_next(json_t *object, void *iter)
Returns an iterator pointing to the next key-value pair in *object*
Set the value of the key-value pair in *object*, that is pointed to
by *iter*, to *value*.
- .. versionadded:: 1.3
-
.. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
Like :func:`json_object_iter_set()`, but steals the reference to
*value*. This is useful when *value* is newly created and not used
after the call.
- .. versionadded:: 1.3
+.. 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)
{
}
+Error reporting
+===============
+
+Jansson uses a single struct type to pass error information to the
+user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
+:ref:`apiref-unpack` for functions that pass error information using
+this struct.
+
+.. type:: json_error_t
+
+ .. member:: char text[]
+
+ The error message (in UTF-8), or an empty string if a message is
+ not available.
+
+ .. member:: char source[]
+
+ Source of the error. This can be (a part of) the file name or a
+ special identifier in angle brackers (e.g. ``<string>``).
+
+ .. member:: int line
+
+ The line number on which the error occurred.
+
+ .. member:: int column
+
+ The column on which the error occurred. Note that this is the
+ *character column*, not the byte column, i.e. a multibyte UTF-8
+ character counts as one column.
+
+ .. member:: size_t position
+
+ The position in bytes from the start of the input. This is
+ useful for debugging Unicode encoding problems.
+
+The normal use of :type:`json_error_t` is to allocate it on the stack,
+and pass a pointer to a function. Example::
+
+ int main() {
+ json_t *json;
+ json_error_t error;
+
+ json = json_load_file("/path/to/file.json", 0, &error);
+ if(!json) {
+ /* the error variable contains error information */
+ }
+ ...
+ }
+
+Also note that if the call succeeded (``json != NULL`` in the above
+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.
+
+
Encoding
========
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
and values to ``":"``. Without this flag, the corresponding
separators are ``", "`` and ``": "`` for more readable output.
- .. versionadded:: 1.2
-
``JSON_ENSURE_ASCII``
If this flag is used, the output is guaranteed to consist only of
ASCII characters. This is achived by escaping all Unicode
characters outside the ASCII range.
- .. versionadded:: 1.2
-
``JSON_SORT_KEYS``
If this flag is used, all the objects in output are sorted by key.
This is useful e.g. if two JSON texts are diffed or visually
compared.
- .. versionadded:: 1.2
-
``JSON_PRESERVE_ORDER``
If this flag is used, object keys in the output are sorted into the
same order in which they were first inserted to the object. For
example, decoding a JSON text and then encoding with this flag
preserves the order of object keys.
- .. versionadded:: 1.3
+``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:
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.
-.. type:: json_error_t
+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.
- This data structure is used to return information on decoding
- errors from the decoding functions. Its definition is repeated
- here::
+ .. versionadded:: 2.1
- #define JSON_ERROR_TEXT_LENGTH 160
+``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.
- typedef struct {
- char text[JSON_ERROR_TEXT_LENGTH];
- int line;
- } json_error_t;
+ **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.
- *line* is the line number on which the error occurred, or -1 if
- this information is not available. *text* contains the error
- message (in UTF-8), or an empty string if a message is not
- available.
+ .. versionadded:: 2.3
- The normal usef of :type:`json_error_t` is to allocate it normally
- on the stack, and pass a pointer to a decoding function. Example::
+``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.
- int main() {
- json_t *json;
- json_error_t error;
+ 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.
- json = json_load_file("/path/to/file.json", 0, &error);
- if(!json) {
- /* the error variable contains error information */
- }
- ...
- }
+ .. versionadded:: 2.1
- Also note that if the decoding succeeded (``json != NULL`` in the
- above example), the contents of ``error`` are unspecified.
+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.
- All decoding functions also accept *NULL* as the
- :type:`json_error_t` pointer, in which case no error information
- is returned to the caller.
+.. versionadded:: 2.3
+ Number of bytes of input read is written to the ``position`` field
+ of the :type:`json_error_t` structure.
+
+If no error or position information is needed, you can pass *NULL*.
The following functions perform the actual JSON decoding.
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. See above for discussion on the
- *error* parameter. *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. See above for discussion
- on the *error* parameter. *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.
.. 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. See above for discussion
- on the *error* parameter. *flags* is currently unused, and should
- be set to 0.
+ filled with information about the error. *flags* is described
+ above.
+
+.. type:: json_load_callback_t
+
+ A typedef for a function that's called by
+ :func:`json_load_callback()` to read a chunk of input data::
+
+ typedef size_t (*json_load_callback_t)(void *buffer, size_t buflen, void *data);
+
+ *buffer* points to a buffer of *buflen* bytes, and *data* is the
+ corresponding :func:`json_load_callback()` argument passed through.
+
+ On error, the function should return ``(size_t)-1`` to abort the
+ decoding process. When there's no data left, it should return 0 to
+ report that the end of input has been reached.
+
+ .. versionadded:: 2.4
+
+.. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error)
+
+ .. refcounting:: new
+
+ Decodes the JSON text produced by repeated calls to *callback*, and
+ returns the array or object it contains, or *NULL* on error, in
+ which case *error* is filled with information about the error.
+ *data* is passed through to *callback* on each call. *flags* is
+ described above.
+
+ .. versionadded:: 2.4
+
+
+.. _apiref-pack:
+
+Building Values
+===============
+
+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 strings and a boolean as its
+items::
+
+ /* Create the JSON integer 42 */
+ json_pack("i", 42);
+
+ /* Create the JSON array ["foo", "bar", true] */
+ json_pack("[ssb]", "foo", "bar", 1);
+
+Here's the full list of format characters. The type in parentheses
+denotes the resulting JSON type, and the type in brackets (if any)
+denotes the C type that is expected as the corresponding argument.
+
+``s`` (string) [const char \*]
+ Convert a NULL terminated UTF-8 string to a JSON string.
+
+``n`` (null)
+ Output a JSON null value. No argument is consumed.
+
+``b`` (boolean) [int]
+ Convert a C :type:`int` to JSON boolean value. Zero is converted
+ to ``false`` and non-zero to ``true``.
+
+``i`` (integer) [int]
+ Convert a C :type:`int` to JSON integer.
+
+``I`` (integer) [json_int_t]
+ Convert a C :type:`json_int_t` to JSON integer.
+
+``f`` (real) [double]
+ Convert a C :type:`double` to JSON real.
+
+``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
+ 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 into an array or object and want to
+ keep the reference for the JSON value consumed by ``O`` to
+ yourself.
+
+``[fmt]`` (array)
+ Build an array with contents from the inner format string. ``fmt``
+ may contain objects and arrays, i.e. recursive value building is
+ supported.
+
+``{fmt}`` (object)
+ Build an object with contents from the inner format string
+ ``fmt``. The first, third, etc. format character represent a key,
+ and must be ``s`` (as object keys are always strings). The second,
+ fourth, etc. format character represent a value. Any value may be
+ an object or array, i.e. recursive value building is supported.
+
+Whitespace, ``:`` and ``,`` are ignored.
+
+The following functions compose the value building API:
+
+.. function:: json_t *json_pack(const char *fmt, ...)
+
+ .. refcounting:: new
+
+ Build a new JSON value according to the format string *fmt*. For
+ each format character (except for ``{}[]n``), one argument is
+ consumed and used to build the corresponding value. Returns *NULL*
+ on error.
+
+.. function:: json_t *json_pack_ex(json_error_t *error, size_t flags, const char *fmt, ...)
+ json_t *json_vpack_ex(json_error_t *error, size_t flags, const char *fmt, va_list ap)
+
+ .. refcounting:: new
+
+ Like :func:`json_pack()`, but an in the case of an error, an error
+ message is written to *error*, if it's not *NULL*. The *flags*
+ parameter is currently unused and should be set to 0.
+
+ As only the errors in format string (and out-of-memory errors) can
+ be caught by the packer, these two functions are most likely only
+ useful for debugging format strings.
+
+More examples::
+
+ /* Build an empty JSON object */
+ json_pack("{}");
+
+ /* Build the JSON object {"foo": 42, "bar": 7} */
+ json_pack("{sisi}", "foo", 42, "bar", 7);
+
+ /* Like above, ':', ',' and whitespace are ignored */
+ 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
+=============================
+
+This sectinon describes functions that help to validate complex values
+and extract, or *unpack*, data from them. Like :ref:`building values
+<apiref-pack>`, this is also based on format strings.
+
+While a JSON value is unpacked, the type specified in the format
+string is checked to match that of the JSON value. This is the
+validation part of the process. In addition to this, the unpacking
+functions can also check that all items of arrays and objects are
+unpacked. This check be enabled with the format character ``!`` or by
+using the flag ``JSON_STRICT``. See below for details.
+
+Here's the full list of format characters. The type in parentheses
+denotes the JSON type, and the type in brackets (if any) denotes the C
+type whose address should be passed.
+
+``s`` (string) [const char \*]
+ Convert a JSON string to a pointer to a NULL terminated UTF-8
+ 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.
+
+``b`` (boolean) [int]
+ Convert a JSON boolean value to a C :type:`int`, so that ``true``
+ is converted to 1 and ``false`` to 0.
+
+``i`` (integer) [int]
+ Convert a JSON integer to C :type:`int`.
+
+``I`` (integer) [json_int_t]
+ Convert a JSON integer to C :type:`json_int_t`.
+
+``f`` (real) [double]
+ Convert a JSON real to C :type:`double`.
+
+``F`` (integer or real) [double]
+ Convert a JSON number (integer or real) to C :type:`double`.
+
+``o`` (any value) [json_t \*]
+ Store a JSON value with no conversion to a :type:`json_t` pointer.
+
+``O`` (any value) [json_t \*]
+ Like ``O``, but the JSON value's reference count is incremented.
+
+``[fmt]`` (array)
+ Convert each item in the JSON array according to the inner format
+ string. ``fmt`` may contain objects and arrays, i.e. recursive
+ value extraction is supporetd.
+
+``{fmt}`` (object)
+ Convert each item in the JSON object according to the inner format
+ string ``fmt``. The first, third, etc. format character represent
+ a key, and must be ``s``. The corresponding argument to unpack
+ functions is read as the object key. The second fourth, etc.
+ format character represent a value and is written to the address
+ given as the corresponding argument. **Note** that every other
+ argument is read from and every other is written to.
+
+ ``fmt`` may contain objects and arrays as values, i.e. recursive
+ value extraction is supporetd.
+
+ .. versionadded:: 2.3
+ Any ``s`` representing a key may be suffixed with a ``?`` to
+ make the key optional. If the key is not found, nothing is
+ extracted. See below for an example.
+
+``!``
+ This special format character is used to enable the check that
+ all object and array items are accessed, on a per-value basis. It
+ must appear inside an array or object as the last format character
+ before the closing bracket or brace. To enable the check globally,
+ use the ``JSON_STRICT`` unpacking flag.
+
+``*``
+ This special format character is the opposite of ``!``. If the
+ ``JSON_STRICT`` flag is used, ``*`` can be used to disable the
+ strict check on a per-value basis. It must appear inside an array
+ or object as the last format character before the closing bracket
+ or brace.
+
+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
+ string *fmt*. Returns 0 on success and -1 on failure.
+
+.. function:: int json_unpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, ...)
+ int json_vunpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, va_list ap)
+
+ Validate and unpack the JSON value *root* according to the format
+ string *fmt*. If an error occurs and *error* is not *NULL*, write
+ error information to *error*. *flags* can be used to control the
+ 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``
+ Enable the extra validation step checking that all object and
+ array items are unpacked. This is equivalent to appending the
+ format character ``!`` to the end of every array and object in the
+ format string.
+
+``JSON_VALIDATE_ONLY``
+ Don't extract any data, just validate the JSON value against the
+ given format string. Note that object keys must still be specified
+ after the format string.
+
+Examples::
+
+ /* root is the JSON integer 42 */
+ int myint;
+ json_unpack(root, "i", &myint);
+ assert(myint == 42);
+
+ /* root is the JSON object {"foo": "bar", "quux": true} */
+ const char *str;
+ int boolean;
+ json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean);
+ assert(strcmp(str, "bar") == 0 && boolean == 1);
+
+ /* root is the JSON array [[1, 2], {"baz": null} */
+ json_error_t error;
+ json_unpack_ex(root, &error, JSON_VALIDATE_ONLY, "[[i,i], {s:n}]", "baz");
+ /* returns 0 for validation success, nothing is extracted */
+
+ /* root is the JSON array [1, 2, 3, 4, 5] */
+ int myint1, myint2;
+ json_unpack(root, "[ii!]", &myint1, &myint2);
+ /* returns -1 for failed validation */
+
+ /* root is an empty JSON object */
+ int myint = 0, myint2 = 0;
+ json_unpack(root, "{s?i, s?[ii]}",
+ "foo", &myint1,
+ "bar", &myint2, &myint3);
+ /* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */
Equality
Returns 0 if they are inequal or one or both of the pointers are
*NULL*.
- .. versionadded:: 1.2
-
Copying
=======
Returns a shallow copy of *value*, or *NULL* on error.
- .. versionadded:: 1.2
-
.. function:: json_t *json_deep_copy(json_t *value)
.. refcounting:: new
Returns a deep copy of *value*, or *NULL* on error.
- .. versionadded:: 1.2
+
+.. _apiref-custom-memory-allocation:
+
+Custom Memory Allocation
+========================
+
+By default, Jansson uses :func:`malloc()` and :func:`free()` for
+memory allocation. These functions can be overridden if custom
+behavior is needed.
+
+.. type:: json_malloc_t
+
+ A typedef for a function pointer with :func:`malloc()`'s
+ signature::
+
+ typedef void *(*json_malloc_t)(size_t);
+
+.. type:: json_free_t
+
+ A typedef for a function pointer with :func:`free()`'s
+ signature::
+
+ typedef void (*json_free_t)(void *);
+
+.. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn)
+
+ Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead
+ of :func:`free()`. This function has to be called before any other
+ Jansson's API functions to ensure that all memory operations use
+ the same functions.
+
+Examples:
+
+Use the `Boehm's conservative garbage collector`_ for memory
+operations::
+
+ json_set_alloc_funcs(GC_malloc, GC_free);
+
+.. _Boehm's conservative garbage collector: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
+
+Allow storing sensitive data (e.g. passwords or encryption keys) in
+JSON structures by zeroing all memory when freed::
+
+ static void *secure_malloc(size_t size)
+ {
+ /* Store the memory area size in the beginning of the block */
+ void *ptr = malloc(size + 8);
+ *((size_t *)ptr) = size;
+ return ptr + 8;
+ }
+
+ static void secure_free(void *ptr)
+ {
+ size_t size;
+
+ ptr -= 8;
+ size = *((size_t *)ptr);
+
+ guaranteed_memset(ptr, 0, size);
+ free(ptr);
+ }
+
+ int main()
+ {
+ json_set_alloc_funcs(secure_malloc, secure_free);
+ /* ... */
+ }
+
+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 explains the :func:`guaranteed_memset()` function used
+in the example and gives a sample implementation for it.
projects / jansson.git / blobdiff