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.
-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. This is actually a fixed-length character array,
+ but should be considered constant.
- /* ... */
- }
+ .. member:: int line
-:type:`json_error_t` is totally opaque and must be queried using the
-following functions:
+ The line number on which the error occurred, or -1 if this
+ information is not available.
-.. function:: const char *json_error_msg(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 a pointer to an UTF-8 encoded string that describes the
- error in human-readable text, or *NULL* if *error* is *NULL*.
+ int main() {
+ json_t *json;
+ json_error_t error;
-.. function:: int json_error_line(const json_error_t *error)
+ json = json_load_file("/path/to/file.json", 0, &error);
+ if(!json) {
+ /* the error variable contains error information */
+ }
+ ...
+ }
- Return the line numer on which the error occurred, or -1 if this
- information is not available or if *error* is *NULL*.
+ 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