X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=doc%2Fapiref.rst;h=cc6b1f1381a52ebba000362c01368946adad9282;hb=cbacac597516b3d7309bf0811ea18cd43870bce4;hp=57b5e3145e31c42f0362e554a8cfa02e32b4fdb2;hpb=fd259ff68c095c613acf952cc63407f294241923;p=jansson.git diff --git a/doc/apiref.rst b/doc/apiref.rst index 57b5e31..cc6b1f1 100644 --- a/doc/apiref.rst +++ b/doc/apiref.rst @@ -41,6 +41,12 @@ Objects of :ctype:`json_t` are always used through a pointer. There are APIs for querying the type, manipulating the reference count, and for constructing and manipulating values of different types. +Unless noted otherwise, all API functions return an error value if an +error occurs. Depending on the function's signature, the error value +is either *NULL* or -1. Invalid arguments or invalid input are +apparent sources for errors. Memory allocation and I/O operations may +also cause errors. + Type ---- @@ -80,8 +86,8 @@ functions: .. cfunction:: int json_typeof(const json_t *json) Return the type of the JSON value (a :ctype:`json_type` cast to - :ctype:`int`). This function is actually implemented as a macro for - speed. + :ctype:`int`). *json* MUST NOT be *NULL*. This function is actually + implemented as a macro for speed. .. cfunction:: json_is_object(const json_t *json) json_is_array(const json_t *json) @@ -93,17 +99,18 @@ functions: json_is_null(const json_t *json) These functions (actually macros) return true (non-zero) for values - of the given type, and false (zero) for values of other types. + of the given type, and false (zero) for values of other types and + for *NULL*. .. cfunction:: json_is_number(const json_t *json) Returns true for values of types :const:`JSON_INTEGER` and - :const:`JSON_REAL`, and false for other types. + :const:`JSON_REAL`, and false for other types and for *NULL*. .. cfunction:: json_is_boolean(const json_t *json) Returns true for types :const:`JSON_TRUE` and :const:`JSON_FALSE`, - and false for values of other types. + and false for values of other types and for *NULL*. Reference Count @@ -121,7 +128,8 @@ The following functions are used to manipulate the reference count. .. cfunction:: json_t *json_incref(json_t *json) - Increment the reference count of *json*. + Increment the reference count of *json* if it's not non-*NULL*. + Returns *json*. .. cfunction:: void json_decref(json_t *json) @@ -139,7 +147,7 @@ the value is no longer needed, :cfunc:`json_decref` should be called to release the reference. Normally, all functions accepting a JSON value as an argument will -manage the reference, i.e. increase and decrease the reference count +nmanage the reference, i.e. increase and decrease the reference count as needed. However, some functions **steal** the reference, i.e. they have the same result as if the user called :cfunc:`json_decref()` on the argument right after calling the function. These are usually @@ -154,26 +162,26 @@ argument. True, False and Null ==================== +These values are implemented as singletons, so each of these functions +returns the same value each time. + .. cfunction:: json_t *json_true(void) .. refcounting:: new - Returns a value of the type :const:`JSON_TRUE`, or *NULL* on - error. + Returns the JSON true value. .. cfunction:: json_t *json_false(void) .. refcounting:: new - Returns a value of the type :const:`JSON_FALSE`, or *NULL* on - error. + Returns the JSON false value. .. cfunction:: json_t *json_null(void) .. refcounting:: new - Returns a value of the type :const:`JSON_NULL`, or *NULL* on - error. + Returns the JSON null value. String @@ -183,13 +191,14 @@ String .. refcounting:: new - Returns a new value of the type :const:`JSON_STRING`, or *NULL* on - error. *value* must be a valid UTF-8 encoded Unicode string. + Returns a new JSON string, or *NULL* on error. *value* must be a + valid UTF-8 encoded Unicode string. .. cfunction:: const char *json_string_value(const json_t *json) - Returns the associated value of a :const:`JSON_STRING` value as a - null terminated UTF-8 encoded string. + Returns the associated value of the JSON string *json* as a null + terminated UTF-8 encoded string, or *NULL* if *json* is not a JSON + string. Number @@ -199,33 +208,32 @@ Number .. refcounting:: new - Returns a new value of the type :const:`JSON_INTEGER`, or *NULL* on - error. + Returns a new JSON integer, or *NULL* on error. .. cfunction:: int json_integer_value(const json_t *json) - Returns the associated integer value of values of the type - :const:`JSON_INTEGER`, or 0 for values of other types. + Returns the associated value the JSON integer *json*. If *json* is + *NULL* or not a JSON integer, 0 is returned. .. cfunction:: json_t *json_real(double value) .. refcounting:: new - Returns a new value of the type :const:`JSON_REAL`, or *NULL* on - error. + Returns a new JSON real, or *NULL* on error. .. cfunction:: double json_real_value(const json_t *json) - Returns the associated real value of values of the type - :const:`JSON_INTEGER`, or 0 for values of other types. + Returns the associated value of the JSON real *json*. If *json* is + *NULL* or not a JSON real, 0.0 is returned. In addition to the functions above, there's a common query function for integers and reals: .. cfunction:: double json_number_value(const json_t *json) - Returns the value of either ``JSON_INTEGER`` or ``JSON_REAL``, cast - to double regardless of the actual type. + Returns the associated value of the JSON integer or JSON real + *json*, cast to double regardless of the actual type. If *json* is + neither JSON real nor JSON integer, 0.0 is returned. Array @@ -237,27 +245,30 @@ A JSON array is an ordered collection of other JSON values. .. refcounting:: new - Returns a new value of the type :const:`JSON_ARRAY`, or *NULL* on - error. Initially, the array is empty. + Returns a new JSON array, or *NULL* on error. Initially, the array + is empty. .. cfunction:: unsigned int json_array_size(const json_t *array) - Returns the number of elements in *array*. + Returns the number of elements in *array*, or 0 if *array* is NULL + or not a JSON array. .. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index) .. refcounting:: borrow - Returns the element in *array* at position *index*, or *NULL* if - *index* is out of range. The valid range for *index* is from 0 to - the return value of :cfunc:`json_array_size()` minus 1. + Returns the element in *array* at position *index*. The valid range + for *index* is from 0 to the return value of + :cfunc:`json_array_size()` minus 1. If *array* is not a JSON array, + if *array* is *NULL*, or if *index* is out of range, *NULL* is + returned. .. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value) Replaces the element in *array* at position *index* with *value*. - Returns 0 on success, or -1 if *index* is out of range. The valid - range for *index* is from 0 to the return value of - :cfunc:`json_array_size()` minus 1. + The valid range for *index* is from 0 to the return value of + :cfunc:`json_array_size()` minus 1. Returns 0 on success and -1 on + error. .. cfunction:: int json_array_set_new(json_t *array, unsigned int index, json_t *value) @@ -280,6 +291,44 @@ A JSON array is an ordered collection of other JSON values. .. versionadded:: 1.1 +.. cfunction:: int json_array_insert(json_t *array, unsigned int 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 + +.. cfunction:: int json_array_insert_new(json_t *array, unsigned int index, json_t *value) + + Like :cfunc:`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 + +.. cfunction:: int json_array_remove(json_t *array, unsigned int 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 + +.. cfunction:: int json_array_clear(json_t *array) + + Removes all elements from *array*. Returns 0 on sucess and -1 on + error. + + .. versionadded:: 1.1 + +.. cfunction:: 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 ====== @@ -291,8 +340,8 @@ Unicode string and the value is any JSON value. .. refcounting:: new - Returns a new value of the type :const:`JSON_OBJECT`, or *NULL* on - error. Initially, the object is empty. + Returns a new JSON object, or *NULL* on error. Initially, the + object is empty. .. cfunction:: json_t *json_object_get(const json_t *object, const char *key) @@ -345,6 +394,20 @@ The following functions implement an iteration protocol for objects: Extract the associated value from *iter*. +The iteration protocol can be used for example as follows:: + + /* obj is a JSON object */ + const char *key; + json_t *value; + void *iter = json_object_iter(obj); + while(iter) + { + key = json_object_iter_key(iter); + value = json_object_iter_value(iter); + /* use key and value ... */ + iter = json_object_iter_next(obj, iter); + } + Encoding ======== @@ -367,18 +430,18 @@ can be ORed together to obtain *flags*. The following functions perform the actual JSON encoding. The result is in UTF-8. -.. cfunction:: char *json_dumps(const json_t *root, uint32_t flags) +.. cfunction:: char *json_dumps(const json_t *root, unsigned long flags) Returns the JSON representation of *root* as a string, or *NULL* on error. *flags* is described above. The return value must be freed by the caller using :cfunc:`free()`. -.. cfunction:: int json_dumpf(const json_t *root, FILE *output, uint32_t flags) +.. cfunction:: int json_dumpf(const json_t *root, FILE *output, unsigned long flags) Write the JSON representation of *root* to the stream *output*. *flags* is described above. Returns 0 on success and -1 on error. -.. cfunction:: int json_dump_file(const json_t *json, const char *path, uint32_t flags) +.. cfunction:: int json_dump_file(const json_t *json, const char *path, unsigned long flags) Write the JSON representation of *root* to the file *path*. If *path* already exists, it is overwritten. *flags* is described