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 data structure is used to return information on decoding
- errors from the decoding functions. Its definition is repeated
- here::
-
- #define JSON_ERROR_TEXT_LENGTH 160
-
- typedef struct {
- char text[JSON_ERROR_TEXT_LENGTH];
- int line;
- } json_error_t;
-
- *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.
-
- 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::
-
- 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.
-
-The following functions perform the actual JSON decoding.
-
.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
.. refcounting:: new
on the *error* parameter. *flags* is currently unused, and should
be set to 0.
+.. type:: json_error_t
+
+ This data structure is used to return information on decoding
+ errors from the decoding functions.
+
+ .. member:: const char *text
+
+ 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.
+
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