organicmaps/jansson
13
Fork 0
mirror of https://github.com/akheron/jansson.git synced 2025-04-06 05:55:05 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions

Move and enhance documentation on json_error_t

Browse source
This commit is contained in:
Petri Lehtinen 2010-10-26 21:17:50 +03:00
parent bb5d4efb2e
commit 818baf5fdb
1 changed files with 37 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
doc/apiref.rst
View file

@ -663,47 +663,6 @@ See :ref:`rfc-conformance` for a discussion on Jansson's conformance
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
@ -734,6 +693,43 @@ The following functions perform the actual JSON decoding.
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. This is actually a fixed-length character array,
but should be considered constant.
.. member:: int line
The line number on which the error occurred, or -1 if this
information is not available.
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
========