.. _apiref:

*************

API Reference

*************

.. highlight:: c

Preliminaries

=============

All declarations are in :file:`jansson.h`, so it's enough to

::

   #include <jansson.h>

in each source file.

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

====================

The JSON specification (:rfc:`4627`) defines the following data types:

*object*, *array*, *string*, *number*, *boolean*, and *null*. JSON

types are used dynamically; arrays and objects can hold any other data

type, including themselves. For this reason, Jansson's type system is

also dynamic in nature. There's one C type to represent all JSON

values, and this structure knows the type of the JSON value it holds.

.. type:: json_t

  This data structure is used throughout the library to represent all

  JSON values. It always contains the type of the JSON value it holds

  and the value's reference count. The rest depends on the type of the

  value.

Objects of :type:`json_t` are always used through a pointer. There

are APIs for querying the type, manipulating the reference count, and

for constructing and manipulating values of different types.

Unless noted otherwise, all API functions return an error value if an

error occurs. Depending on the function's signature, the error value

is either *NULL* or -1. Invalid arguments or invalid input are

apparent sources for errors. Memory allocation and I/O operations may

also cause errors.

Type

----

The type of a JSON value is queried and tested using the following

functions:

.. type:: enum json_type

   The type of a JSON value. The following members are defined:

   +--------------------+

   | ``JSON_OBJECT``    |

   +--------------------+

   | ``JSON_ARRAY``     |

   +--------------------+

   | ``JSON_STRING``    |

   +--------------------+

   | ``JSON_INTEGER``   |

   +--------------------+

   | ``JSON_REAL``      |

   +--------------------+

   | ``JSON_TRUE``      |

   +--------------------+

   | ``JSON_FALSE``     |

   +--------------------+

   | ``JSON_NULL``      |

   +--------------------+

   These correspond to JSON object, array, string, number, boolean and

   null. A number is represented by either a value of the type

   ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value

   is represented by a value of the type ``JSON_TRUE`` and false by a

   value of the type ``JSON_FALSE``.

.. function:: int json_typeof(const json_t *json)

   Return the type of the JSON value (a :type:`json_type` cast to

   :type:`int`). *json* MUST NOT be *NULL*. This function is actually

   implemented as a macro for speed.

.. function:: json_is_object(const json_t *json)

               json_is_array(const json_t *json)

               json_is_string(const json_t *json)

               json_is_integer(const json_t *json)

               json_is_real(const json_t *json)

               json_is_true(const json_t *json)

               json_is_false(const json_t *json)

               json_is_null(const json_t *json)

   These functions (actually macros) return true (non-zero) for values

   of the given type, and false (zero) for values of other types and

   for *NULL*.

.. function:: json_is_number(const json_t *json)

   Returns true for values of types ``JSON_INTEGER`` and

   ``JSON_REAL``, and false for other types and for *NULL*.

.. function:: json_is_boolean(const json_t *json)

   Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false

   for values of other types and for *NULL*.

.. function:: json_boolean_value(const json_t *json)

   Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE``

   and 0 otherwise.

   .. versionadded:: 2.7

.. _apiref-reference-count:

Reference Count

---------------

The reference count is used to track whether a value is still in use

or not. When a value is created, it's reference count is set to 1. If

a reference to a value is kept (e.g. a value is stored somewhere for

later use), its reference count is incremented, and when the value is

no longer needed, the reference count is decremented. When the

reference count drops to zero, there are no references left, and the

value can be destroyed.

The following functions are used to manipulate the reference count.

.. function:: json_t *json_incref(json_t *json)

   Increment the reference count of *json* if it's not *NULL*.

   Returns *json*.

.. function:: void json_decref(json_t *json)

   Decrement the reference count of *json*. As soon as a call to

   :func:`json_decref()` drops the reference count to zero, the value

   is destroyed and it can no longer be used.

Functions creating new JSON values set the reference count to 1. These

functions are said to return a **new reference**. Other functions

returning (existing) JSON values do not normally increase the

reference count. These functions are said to return a **borrowed

reference**. So, if the user will hold a reference to a value returned

as a borrowed reference, he must call :func:`json_incref`. As soon as

the value is no longer needed, :func:`json_decref` should be called

to release the reference.

Normally, all functions accepting a JSON value as an argument will

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 :func:`json_decref()` on

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 :func:`json_decref()`. By using a reference stealing

function :func:`json_array_append_new()` instead of

:func:`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 :func:`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

argument.

Circular References

-------------------

A circular reference is created when an object or an array is,

directly or indirectly, inserted inside itself. The direct case is

simple::

  json_t *obj = json_object();

  json_object_set(obj, "foo", obj);

Jansson will refuse to do this, and :func:`json_object_set()` (and

all the other such functions for objects and arrays) will return with

an error status. The indirect case is the dangerous one::

  json_t *arr1 = json_array(), *arr2 = json_array();

  json_array_append(arr1, arr2);

  json_array_append(arr2, arr1);

In this example, the array ``arr2`` is contained in the array

``arr1``, and vice versa. Jansson cannot check for this kind of

indirect circular references without a performance hit, so it's up to

the user to avoid them.

If a circular reference is created, the memory consumed by the values

cannot be freed by :func:`json_decref()`. The reference counts never

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

====================

These three values are implemented as singletons, so the returned

pointers won't change between invocations of these functions.

.. function:: json_t *json_true(void)

   .. refcounting:: new

   Returns the JSON true value.

.. function:: json_t *json_false(void)

   .. refcounting:: new

   Returns the JSON false value.

.. function:: json_t *json_boolean(val)

   .. refcounting:: new

   Returns JSON false if ``val`` is zero, and JSON true otherwise.

   This is a macro, and equivalent to ``val ? json_true() :

   json_false()``.

   .. versionadded:: 2.4

.. function:: json_t *json_null(void)

   .. refcounting:: new

   Returns the JSON null value.

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). All Unicode

codepoints U+0000 through U+10FFFF are allowed, but you must use

length-aware functions if you wish to embed NUL bytes in strings.

.. function:: json_t *json_string(const char *value)

   .. refcounting:: new

   Returns a new JSON string, or *NULL* on error. *value* must be a

   valid null terminated UTF-8 encoded Unicode string.

.. function:: json_t *json_stringn(const char *value, size_t len)

   .. refcounting:: new

   Like :func:`json_string`, but with explicit length, so *value* may

   contain null characters or not be null terminated.

.. function:: json_t *json_string_nocheck(const char *value)

   .. refcounting:: new

   Like :func:`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).

.. function:: json_t *json_stringn_nocheck(const char *value, size_t len)

   .. refcounting:: new

   Like :func:`json_string_nocheck`, but with explicit length, so

   *value* may contain null characters or not be null terminated.

.. 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:: size_t json_string_length(const json_t *string)

   Returns the length of *string* in its UTF-8 presentation, or zero

   if *string* is not a JSON string.

.. 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.

.. function:: int json_string_setn(json_t *string, const char *value, size_t len)

   Like :func:`json_string_set`, but with explicit length, so *value*

   may contain null characters or not be null terminated.

.. 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

   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).

.. function:: int json_string_setn_nocheck(json_t *string, const char *value, size_t len)

   Like :func:`json_string_set_nocheck`, but with explicit length,

   so *value* may contain null characters or not be null terminated.

Number

======

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`.

.. type:: 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

   :type:`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 :func:`printf()` conversion

   specifier that corresponds to :type:`json_int_t`, without the

   leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro

   is required because the actual type of :type:`json_int_t` can be

   either ``long`` or ``long long``, and :func:`printf()` reuiqres

   different length modifiers for the two.

   Example::

       json_int_t x = 123123123;

       printf("x is %" JSON_INTEGER_FORMAT "\n", x);

.. function:: json_t *json_integer(json_int_t value)

   .. refcounting:: new

   Returns a new JSON integer, or *NULL* on error.

.. function:: 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.

.. function:: 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.

.. function:: json_t *json_real(double value)

   .. refcounting:: new

   Returns a new JSON real, or *NULL* on error.

.. function:: double json_real_value(const json_t *real)

   Returns the associated value of *real*, or 0.0 if *real* is not a

   JSON real.

.. function:: int json_real_set(const json_t *real, double value)

   Sets the associated value of *real* to *value*. Returns 0 on

   success and -1 if *real* is not a JSON real.

In addition to the functions above, there's a common query function

for integers and reals:

.. function:: double json_number_value(const json_t *json)

   Returns the associated value of the JSON integer or JSON real

   *json*, cast to double regardless of the actual type. If *json* is

   neither JSON real nor JSON integer, 0.0 is returned.

Array

=====

A JSON array is an ordered collection of other JSON values.

.. function:: json_t *json_array(void)

   .. refcounting:: new

   Returns a new JSON array, or *NULL* on error. Initially, the array

   is empty.

.. function:: 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.

.. function:: json_t *json_array_get(const json_t *array, size_t index)

   .. refcounting:: borrow

   Returns the element in *array* at position *index*. The valid range

   for *index* is from 0 to the return value of

   :func:`json_array_size()` minus 1. If *array* is not a JSON array,

   if *array* is *NULL*, or if *index* is out of range, *NULL* is

   returned.

.. function:: 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

   :func:`json_array_size()` minus 1. Returns 0 on success and -1 on

   error.

.. function:: int json_array_set_new(json_t *array, size_t index, json_t *value)

   Like :func:`json_array_set()` but steals the reference to *value*.

   This is useful when *value* is newly created and not used after

   the call.

.. function:: int json_array_append(json_t *array, json_t *value)

   Appends *value* to the end of *array*, growing the size of *array*

   by 1. Returns 0 on success and -1 on error.

.. function:: int json_array_append_new(json_t *array, json_t *value)

   Like :func:`json_array_append()` but steals the reference to

   *value*. This is useful when *value* is newly created and not used

   after the call.

.. 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.

.. 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.

.. 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. The reference count of the

   removed value is decremented.