+.. _apiref:
+
*************
API Reference
*************
and false for values of other types and for *NULL*.
+.. _apiref-reference-count:
+
Reference Count
---------------
manage the reference, i.e. increase and decrease the reference count
as needed. However, some functions **steal** the reference, i.e. they
have the same result as if the user called :cfunc:`json_decref()` on
-the argument right after calling the function. These are usually
-convenience functions for adding new references to containers and not
-to worry about the reference count.
+the argument right after calling the function. These functions are
+suffixed with ``_new`` or have ``_new_`` somewhere in their name.
+
+For example, the following code creates a new JSON array and appends
+an integer to it::
+
+ json_t *array, *integer;
+
+ array = json_array();
+ integer = json_integer(42);
+
+ json_array_append(array, integer);
+ json_decref(integer);
+
+Note how the caller has to release the reference to the integer value
+by calling :cfunc:`json_decref()`. By using a reference stealing
+function :cfunc:`json_array_append_new()` instead of
+:cfunc:`json_array_append()`, the code becomes much simpler::
+
+ json_t *array = json_array();
+ json_array_append_new(array, json_integer(42));
+
+In this case, the user doesn't have to explicitly release the
+reference to the integer value, as :cfunc:`json_array_append_new()`
+steals the reference when appending the value to the array.
In the following sections it is clearly documented whether a function
will return a new or borrowed reference or steal a reference to its
If a circular reference is created, the memory consumed by the values
cannot be freed by :cfunc:`json_decref()`. The reference counts never
-drops to zero because the values are keeping the circular reference to
-themselves. Moreover, trying to encode the values with any of the
-encoding functions will fail. The encoder detects circular references
-and returns an error status.
+drops to zero because the values are keeping the references to each
+other. Moreover, trying to encode the values with any of the encoding
+functions will fail. The encoder detects circular references and
+returns an error status.
True, False and Null
String
======
+Jansson uses UTF-8 as the character encoding. All JSON strings must be
+valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null
+terminated C strings are used, so JSON strings may not contain
+embedded null characters. All other Unicode codepoints U+0001 through
+U+10FFFF are allowed.
+
.. cfunction:: json_t *json_string(const char *value)
.. refcounting:: new
Returns a new JSON string, or *NULL* on error. *value* must be a
valid UTF-8 encoded Unicode string.
+.. cfunction:: json_t *json_string_nocheck(const char *value)
+
+ .. refcounting:: new
+
+ Like :cfunc:`json_string`, but doesn't check that *value* is 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 means).
+
+ .. versionadded:: 1.2
+
.. cfunction:: const char *json_string_value(const json_t *string)
Returns the associated value of *string* as a null terminated UTF-8
.. versionadded:: 1.1
+.. cfunction:: int json_string_set_nocheck(const json_t *string, const char *value)
+
+ Like :cfunc:`json_string_set`, but doesn't check that *value* is
+ 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
+ means).
+
+ .. versionadded:: 1.2
+
Number
======
-.. cfunction:: json_t *json_integer(int value)
+The JSON specification only contains one numeric type, "number". The C
+programming language has distinct types for integer and floating-point
+numbers, so for practical reasons Jansson also has distinct types for
+the two. They are called "integer" and "real", respectively. For more
+information, see :ref:`rfc-conformance`.
+
+.. ctype:: json_int_t
+
+ This is the C type that is used to store JSON integer values. It
+ represents the widest integer type available on your system. In
+ practice it's just a typedef of ``long long`` if your compiler
+ supports it, otherwise ``long``.
+
+ Usually, you can safely use plain ``int`` in place of
+ ``json_int_t``, and the implicit C integer conversion handles the
+ rest. Only when you know that you need the full 64-bit range, you
+ should use ``json_int_t`` explicitly.
+
+``JSON_INTEGER_IS_LONG_LONG``
+
+ This is a preprocessor variable that holds the value 1 if
+ :ctype:`json_int_t` is ``long long``, and 0 if it's ``long``. It
+ can be used as follows::
+
+ #if JSON_INTEGER_IS_LONG_LONG
+ /* Code specific for long long */
+ #else
+ /* Code specific for long */
+ #endif
+
+``JSON_INTEGER_FORMAT``
+
+ This is a macro that expands to a :cfunc:`printf()` conversion
+ specifier that corresponds to :ctype:`json_int_t`, without the
+ leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro
+ is required because the actual type of :ctype:`json_int_t` can be
+ either ``long`` or ``long long``, and :cfunc:`printf()` reuiqres
+ different length modifiers for the two.
+
+ Example::
+
+ json_int_t x = 123123123;
+ printf("x is %" JSON_INTEGER_FORMAT "\n", x);
+
+
+.. cfunction:: json_t *json_integer(json_int_t value)
.. refcounting:: new
Returns a new JSON integer, or *NULL* on error.
-.. cfunction:: int json_integer_value(const json_t *integer)
+.. cfunction:: json_int_t json_integer_value(const json_t *integer)
Returns the associated value of *integer*, or 0 if *json* is not a
JSON integer.
-.. cfunction:: int json_integer_set(const json_t *integer, int value)
+.. cfunction:: int json_integer_set(const json_t *integer, json_int_t value)
Sets the associated value of *integer* to *value*. Returns 0 on
success and -1 if *integer* is not a JSON integer.
Returns a new JSON array, or *NULL* on error. Initially, the array
is empty.
-.. cfunction:: unsigned int json_array_size(const json_t *array)
+.. cfunction:: size_t json_array_size(const json_t *array)
Returns the number of elements in *array*, or 0 if *array* is NULL
or not a JSON array.
-.. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index)
+.. cfunction:: json_t *json_array_get(const json_t *array, size_t index)
.. refcounting:: borrow
if *array* is *NULL*, or if *index* is out of range, *NULL* is
returned.
-.. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value)
+.. cfunction:: int json_array_set(json_t *array, size_t index, json_t *value)
Replaces the element in *array* at position *index* with *value*.
The valid range for *index* is from 0 to the return value of
:cfunc:`json_array_size()` minus 1. Returns 0 on success and -1 on
error.
-.. cfunction:: int json_array_set_new(json_t *array, unsigned int index, json_t *value)
+.. cfunction:: int json_array_set_new(json_t *array, size_t index, json_t *value)
Like :cfunc:`json_array_set()` but steals the reference to *value*.
This is useful when *value* is newly created and not used after
.. versionadded:: 1.1
-.. cfunction:: int json_array_insert(json_t *array, unsigned int index, json_t *value)
+.. cfunction:: 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
.. versionadded:: 1.1
-.. cfunction:: int json_array_insert_new(json_t *array, unsigned int index, json_t *value)
+.. cfunction:: int json_array_insert_new(json_t *array, size_t index, json_t *value)
Like :cfunc:`json_array_insert()` but steals the reference to
*value*. This is useful when *value* is newly created and not used
.. versionadded:: 1.1
-.. cfunction:: int json_array_remove(json_t *array, unsigned int index)
+.. cfunction:: 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 a new JSON object, or *NULL* on error. Initially, the
object is empty.
-.. cfunction:: unsigned int json_object_size(const json_t *object)
+.. cfunction:: size_t json_object_size(const json_t *object)
Returns the number of elements in *object*, or 0 if *object* is not
a JSON object.
already is a value for *key*, it is replaced by the new value.
Returns 0 on success and -1 on error.
+.. cfunction:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value)
+
+ Like :cfunc:`json_object_set`, but doesn't check that *key* is
+ 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
+ means).
+
+ .. versionadded:: 1.2
+
.. cfunction:: int json_object_set_new(json_t *object, const char *key, json_t *value)
Like :cfunc:`json_object_set()` but steals the reference to
.. versionadded:: 1.1
+.. cfunction:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
+
+ Like :cfunc:`json_object_set_new`, but doesn't check that *key* is
+ 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
+ means).
+
+ .. versionadded:: 1.2
+
.. cfunction:: int json_object_del(json_t *object, const char *key)
Delete *key* from *object* if it exists. Returns 0 on success, or
Returns an opaque iterator which can be used to iterate over all
key-value pairs in *object*, or *NULL* if *object* is empty.
+.. cfunction:: void *json_object_iter_at(json_t *object, const char *key)
+
+ Like :cfunc:`json_object_iter()`, but returns an iterator to the
+ key-value pair in *object* whose key is equal to *key*, or NULL if
+ *key* is not found in *object*. Iterating forward to the end of
+ *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
+
.. cfunction:: void *json_object_iter_next(json_t *object, void *iter)
Returns an iterator pointing to the next key-value pair in *object*
Extract the associated value from *iter*.
+.. cfunction:: 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
+ by *iter*, to *value*.
+
+ .. versionadded:: 1.3
+
+.. cfunction:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
+
+ Like :cfunc:`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
+
The iteration protocol can be used for example as follows::
/* obj is a JSON object */
values to JSON. Only objects and arrays can be encoded, since they are
the only valid "root" values of a JSON text.
+By default, the output has no newlines, and spaces are used between
+array and object elements for a readable output. This behavior can be
+altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags
+described below. A newline is never appended to the end of the encoded
+JSON data.
+
Each function takes a *flags* parameter that controls some aspects of
how the data is encoded. Its default value is 0. The following macros
can be ORed together to obtain *flags*.
``JSON_INDENT(n)``
- Pretty-print the result, indenting arrays and objects by *n*
- spaces. The valid range for *n* is between 0 and 255, other values
- result in an undefined output. If ``JSON_INDENT`` is not used or
- *n* is 0, no pretty-printing is done and the result is a compact
- representation.
+ 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.
+
+``JSON_COMPACT``
+ This flag enables a compact representation, i.e. sets the separator
+ between array and object items to ``","`` and between object keys
+ 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
The following functions perform the actual JSON encoding. The result
is in UTF-8.
-.. cfunction:: char *json_dumps(const json_t *root, unsigned long flags)
+.. cfunction:: char *json_dumps(const json_t *root, size_t flags)
Returns the JSON representation of *root* as a string, or *NULL* on
error. *flags* is described above. The return value must be freed
by the caller using :cfunc:`free()`.
-.. cfunction:: int json_dumpf(const json_t *root, FILE *output, unsigned long flags)
+.. cfunction:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
Write the JSON representation of *root* to the stream *output*.
*flags* is described above. Returns 0 on success and -1 on error.
*output*. In this case, the output is undefined and most likely not
valid JSON.
-.. cfunction:: int json_dump_file(const json_t *json, const char *path, unsigned long flags)
+.. cfunction:: int json_dump_file(const json_t *json, const char *path, size_t flags)
Write the JSON representation of *root* to the file *path*. If
*path* already exists, it is overwritten. *flags* is described
text to the Jansson representation of JSON data. The JSON
specification requires that a JSON text is either a serialized array
or object, and this requirement is also enforced with the following
-functions.
+functions. In other words, the top level value in the JSON text being
+decoded must be either array or object.
-The only supported character encoding is UTF-8 (which ASCII is a
-subset of).
+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.
.. ctype:: json_error_t
json_t *json;
json_error_t error;
- json = json_load_file("/path/to/file.json", &error);
+ json = json_load_file("/path/to/file.json", 0, &error);
if(!json) {
/* the error variable contains error information */
}
The following functions perform the actual JSON decoding.
-.. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
+.. cfunction:: 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. See above for discussion on the
- *error* parameter.
+ *error* parameter. *flags* is currently unused, and should be set
+ to 0.
-.. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
+.. cfunction:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
.. refcounting:: new
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.
+ on the *error* parameter. *flags* is currently unused, and should
+ be set to 0.
-.. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
+.. cfunction:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
.. refcounting:: new
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.
+ on the *error* parameter. *flags* is currently unused, and should
+ be set to 0.
+
+
+Equality
+========
+
+Testing for equality of two JSON values cannot, in general, be
+achieved using the ``==`` operator. Equality in the terms of the
+``==`` operator states that the two :ctype:`json_t` pointers point to
+exactly the same JSON value. However, two JSON values can be equal not
+only if they are exactly the same value, but also if they have equal
+"contents":
+
+* Two integer or real values are equal if their contained numeric
+ values are equal. An integer value is never equal to a real value,
+ though.
+
+* Two strings are equal if their contained UTF-8 strings are equal,
+ byte by byte. Unicode comparison algorithms are not implemented.
+
+* Two arrays are equal if they have the same number of elements and
+ each element in the first array is equal to the corresponding
+ element in the second array.
+
+* Two objects are equal if they have exactly the same keys and the
+ value for each key in the first object is equal to the value of the
+ corresponding key in the second object.
+
+* Two true, false or null values have no "contents", so they are equal
+ if their types are equal. (Because these values are singletons,
+ their equality can actually be tested with ``==``.)
+
+The following function can be used to test whether two JSON values are
+equal.
+
+.. cfunction:: int json_equal(json_t *value1, json_t *value2)
+
+ Returns 1 if *value1* and *value2* are equal, as defined above.
+ Returns 0 if they are inequal or one or both of the pointers are
+ *NULL*.
+
+ .. versionadded:: 1.2
+
+
+Copying
+=======
+
+Because of reference counting, passing JSON values around doesn't
+require copying them. But sometimes a fresh copy of a JSON value is
+needed. For example, if you need to modify an array, but still want to
+use the original afterwards, you should take a copy of it first.
+
+Jansson supports two kinds of copying: shallow and deep. There is a
+difference between these methods only for arrays and objects. Shallow
+copying only copies the first level value (array or object) and uses
+the same child values in the copied value. Deep copying makes a fresh
+copy of the child values, too. Moreover, all the child values are deep
+copied in a recursive fashion.
+
+.. cfunction:: json_t *json_copy(json_t *value)
+
+ .. refcounting:: new
+
+ Returns a shallow copy of *value*, or *NULL* on error.
+
+ .. versionadded:: 1.2
+
+.. cfunction:: json_t *json_deep_copy(json_t *value)
+
+ .. refcounting:: new
+
+ Returns a deep copy of *value*, or *NULL* on error.
+
+ .. versionadded:: 1.2