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_VERSION_MAJOR``, ``JANSSON_VERSION_MINOR``, ``JANSSON_VERSION_MICRO``
+ 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
-
.. function:: int json_array_clear(json_t *array)
Removes all elements from *array*. Returns 0 on sucess and -1 on
error.
- .. versionadded:: 1.1
-
.. 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
Remove all elements from *object*. Returns 0 on success and -1 if
*object* is not a JSON object.
- .. versionadded:: 1.1
-
.. 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
-
The following functions implement an iteration protocol for objects:
*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
-
The iteration protocol can be used for example as follows::
/* obj is a JSON object */
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.
to the JSON specification. It explains many design decisions that
affect especially the behavior of the decoder.
-.. type:: json_error_t
-
- This opaque structure is used to return information on errors from
- the decoding functions. See below for more discussion on error
- reporting.
-
-The following functions perform the JSON decoding:
-
-.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t **error)
+.. 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. If *error* is non-*NULL*, it's used
- to return error information. See below for more discussion on error
- reporting. *flags* is currently unused, and should be set to 0.
+ 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.
-.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t **error)
+.. function:: 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. If *error* is non-*NULL*,
- it's used to return error information. See below for more
- discussion on error reporting. *flags* is currently unused, and
- should be set to 0.
+ 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.
-.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t **error)
+.. function:: 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. If *error* is non-*NULL*,
- it's used to return error information. See below for more
- discussion on error reporting. *flags* is currently unused, and
- should be set to 0.
-
-
-The :type:`json_error_t` parameter, that all decoding function accept
-as their last parameter, is used to return information on decoding
-errors to the caller. It is used by having a ``json_error_t *``
-variable and passing a pointer to this variable to a decoding
-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 */
- fprintf(stderr, "Decoding error occured on line %d: %s\n", json_error_line(error), json_error_msg(error));
- free(error);
- }
-
- /* ... */
- }
+ 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.
-Note that **the caller must free the error structure** after use if a
-decoding error occurs. If decoding is succesfully finished, *error* is
-simply set to *NULL* by the decoding function.
+.. type:: json_error_t
-All decoding functions also accept *NULL* as the :type:`json_error_t`
-pointer, in which case no error information is returned to the caller.
-Example::
+ This data structure is used to return information on decoding
+ errors from the decoding functions.
- int main() {
- json_t *json;
+ .. member:: const char *text
- json = json_load_file("/path/to/file.json", 0, NULL);
- if(!json) {
- /* A decoding error occured but no error information is available */
- }
+ The error message (in UTF-8), or an empty string if a message is
+ not available.
- /* ... */
- }
+ .. member:: int line
+
+ The line number on which the error occurred, or -1 if this
+ information is not available.
+
+ .. member:: int column
+
+ The character column on which the error occurred, or -1 if this
+ information is not available.
+
+ .. member:: const char *source
+
+ Source of the error. This is (a part of) the file name when
+ using :func:`json_load_file()`, or a special identifier in angle
+ brackets otherwise (e.g. ``<string>``).
+
+ The normal use of :type:`json_error_t` is to allocate it on the
+ stack, and pass a pointer to a decoding 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 decoding succeeded (``json != NULL`` in the
+ above example), the contents of ``error`` are unspecified.
+
+ All decoding functions also accept *NULL* as the
+ :type:`json_error_t` pointer, in which case no error information
+ is returned to the caller.
+
+
+.. _apiref-building-values:
+
+Building values
+===============
+
+This sectinon 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
+items::
-:type:`json_error_t` is totally opaque and must be queried using the
-following functions:
+ /* Create the JSON integer 42 */
+ json_pack("i", 42);
-.. function:: const char *json_error_msg(const json_error_t *error)
+ /* Create the JSON array ["foo", "bar", true] */
+ json_pack("[ssb]", "foo", "bar", 1);
- Return a pointer to an UTF-8 encoded string that describes the
- error in human-readable text, or *NULL* if *error* is *NULL*.
+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.
-.. function:: int json_error_line(const json_error_t *error)
+``s`` (string) [const char \*]
+ Convert a NULL terminated UTF-8 string to a JSON string.
- Return the line numer on which the error occurred, or -1 if this
- information is not available or if *error* is *NULL*.
+``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
+ stealed 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
+ 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.
+
+
+.. 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("{sisb}", "foo", 42, "bar", 7);
+
+ /* Like above, ':', ',' and whitespace are ignored */
+ json_pack("{s:i, s:b}", "foo", 42, "bar", 7);
+
+ /* Build the JSON array [[1, 2], {"cool": true}] */
+ json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
+
+
+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-building-values>`, 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. By default, the unpacking functions
+also check that all items of arrays and objects are unpacked. This
+check be disabled with the format character ``*`` or by using the flag
+``JSON_UNPACK_ONLY``.
+
+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.
+
+``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.
+
+``*``
+ This special format character is used to disable 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.
+
+
+.. 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.
+
+The following unpacking flags are available:
+
+``JSON_UNPACK_ONLY``
+ Disable the 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, ret;
+ ret = json_unpack(root, "[ii*]", &myint1, &myint2);
+ assert(ret == 0 && myint1 == 1 && myint2 == 2);
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
projects / jansson.git / blobdiff