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
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.
+
+.. type:: json_error_t
-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.
+ This data structure is used to return information on decoding
+ errors from the decoding functions.
-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::
+ .. member:: const char *text
- int main() {
- json_t *json;
+ The error message (in UTF-8), or an empty string if a message is
+ not available.
- json = json_load_file("/path/to/file.json", 0, NULL);
- if(!json) {
- /* A decoding error occured but no error information is available */
- }
+ .. member:: int line
- /* ... */
- }
+ The line number on which the error occurred, or -1 if this
+ information is not available.
+
+ .. member:: int column
-:type:`json_error_t` is totally opaque and must be queried using the
-following functions:
+ The character column on which the error occurred, or -1 if this
+ information is not available.
-.. function:: const char *json_error_msg(const json_error_t *error)
+ .. member:: const char *source
- Return a pointer to an UTF-8 encoded string that describes the
- error in human-readable text, or *NULL* if *error* is *NULL*.
+ 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>``).
-.. function:: int json_error_line(const json_error_t *error)
+ The normal use of :type:`json_error_t` is to allocate it on the
+ stack, and pass a pointer to a decoding function. Example::
- Return the line numer on which the error occurred, or -1 if this
- information is not available or if *error* is *NULL*.
+ 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.
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