.. type:: json_error_t
- This data structure is used to return information on decoding
- errors from the decoding functions. Its definition is repeated
- here::
+ This opaque structure is used to return information on errors from
+ the decoding functions. See below for more discussion on error
+ reporting.
- #define JSON_ERROR_TEXT_LENGTH 160
+The following functions perform the JSON decoding:
- typedef struct {
- char text[JSON_ERROR_TEXT_LENGTH];
- int line;
- } json_error_t;
+.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t **error)
- *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.
+ .. refcounting:: new
- 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::
+ 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.
- int main() {
- json_t *json;
- json_error_t error;
+.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t **error)
- json = json_load_file("/path/to/file.json", 0, &error);
- if(!json) {
- /* the error variable contains error information */
- }
- ...
- }
+ .. refcounting:: new
- Also note that if the decoding succeeded (``json != NULL`` in the
- above example), the contents of ``error`` are unspecified.
+ 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.
- All decoding functions also accept *NULL* as the
- :type:`json_error_t` pointer, in which case no error information
- is returned to the caller.
+.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t **error)
-The following functions perform the actual JSON decoding.
+ .. refcounting:: new
-.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
+ 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);
+ }
+
+ /* ... */
+ }
- .. refcounting:: new
+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.
- Decodes the JSON string *input* and returns the array or 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.
+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::
-.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
+ int main() {
+ json_t *json;
- .. refcounting:: new
+ json = json_load_file("/path/to/file.json", 0, NULL);
+ if(!json) {
+ /* A decoding error occured but no error information is available */
+ }
- Decodes the JSON text in stream *input* and returns the array or
- 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)
+:type:`json_error_t` is totally opaque and must be queried using the
+following functions:
- .. refcounting:: new
+.. function:: const char *json_error_msg(const json_error_t *error)
- Decodes the JSON text in file *path* and returns the array or
- 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.
+ Return a pointer to an UTF-8 encoded string that describes the
+ error in human-readable text, or *NULL* if *error* is *NULL*.
+
+.. function:: int json_error_line(const json_error_t *error)
+
+ Return the line numer on which the error occurred, or -1 if this
+ information is not available or if *error* is *NULL*.
Equality
projects / jansson.git / blobdiff