X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=doc%2Fapiref.rst;h=11a24c17bca47e980345f40842c384d6e9cb6a5f;hb=68f2861e92e08eb5e2af51c026981bc1e990e1eb;hp=cf8842d9bf54020176c98fbbb7f73c486a6307b2;hpb=e0a88d19d1f103c32bbaf4c20a83575413c4bf80;p=jansson.git diff --git a/doc/apiref.rst b/doc/apiref.rst index cf8842d..11a24c1 100644 --- a/doc/apiref.rst +++ b/doc/apiref.rst @@ -154,9 +154,31 @@ Normally, all functions accepting a JSON value as an argument will manage 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 -convenience functions for adding new references to containers and not -to worry about the reference count. +the argument right after calling the function. These functions are +suffixed with ``_new`` or have ``_new_`` somewhere in their name. + +For example, the following code creates a new JSON array and appends +an integer to it:: + + json_t *array, *integer; + + array = json_array(); + integer = json_integer(42); + + json_array_append(array, integer); + json_decref(integer); + +Note how the caller has to release the reference to the integer value +by calling :cfunc:`json_decref()`. By using a reference stealing +function :cfunc:`json_array_append_new()` instead of +:cfunc:`json_array_append()`, the code becomes much simpler:: + + json_t *array = json_array(); + json_array_append_new(array, json_integer(42)); + +In this case, the user doesn't have to explicitly release the +reference to the integer value, as :cfunc:`json_array_append_new()` +steals the reference when appending the value to the array. In the following sections it is clearly documented whether a function will return a new or borrowed reference or steal a reference to its @@ -229,6 +251,16 @@ String Returns a new JSON string, or *NULL* on error. *value* must be a valid UTF-8 encoded Unicode string. +.. cfunction:: json_t *json_string_nocheck(const char *value) + + .. refcounting:: new + + Like :cfunc:`json_string`, but doesn't check that *value* is valid + 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 + .. cfunction:: const char *json_string_value(const json_t *string) Returns the associated value of *string* as a null terminated UTF-8 @@ -242,6 +274,15 @@ String .. versionadded:: 1.1 +.. cfunction:: int json_string_set_nocheck(const json_t *string, const char *value) + + Like :cfunc:`json_string_set`, but doesn't check that *value* is + valid 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 + Number ====== @@ -304,12 +345,12 @@ A JSON array is an ordered collection of other JSON values. Returns a new JSON array, or *NULL* on error. Initially, the array is empty. -.. cfunction:: unsigned int json_array_size(const json_t *array) +.. cfunction:: size_t json_array_size(const json_t *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) +.. cfunction:: json_t *json_array_get(const json_t *array, size_t index) .. refcounting:: borrow @@ -319,14 +360,14 @@ A JSON array is an ordered collection of other JSON values. 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) +.. cfunction:: int json_array_set(json_t *array, size_t index, json_t *value) Replaces the element in *array* at position *index* with *value*. 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) +.. cfunction:: int json_array_set_new(json_t *array, size_t index, json_t *value) Like :cfunc:`json_array_set()` but steals the reference to *value*. This is useful when *value* is newly created and not used after @@ -347,7 +388,7 @@ 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) +.. cfunction:: 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 @@ -355,7 +396,7 @@ A JSON array is an ordered collection of other JSON values. .. versionadded:: 1.1 -.. cfunction:: int json_array_insert_new(json_t *array, unsigned int index, json_t *value) +.. cfunction:: int json_array_insert_new(json_t *array, size_t 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 @@ -363,7 +404,7 @@ A JSON array is an ordered collection of other JSON values. .. versionadded:: 1.1 -.. cfunction:: int json_array_remove(json_t *array, unsigned int index) +.. cfunction:: 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. @@ -399,7 +440,7 @@ Unicode string and the value is any JSON value. Returns a new JSON object, or *NULL* on error. Initially, the object is empty. -.. cfunction:: unsigned int json_object_size(const json_t *object) +.. cfunction:: size_t json_object_size(const json_t *object) Returns the number of elements in *object*, or 0 if *object* is not a JSON object. @@ -420,6 +461,15 @@ Unicode string and the value is any JSON value. already is a value for *key*, it is replaced by the new value. Returns 0 on success and -1 on error. +.. cfunction:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value) + + Like :cfunc:`json_object_set`, but doesn't check that *key* is + valid 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 + .. cfunction:: int json_object_set_new(json_t *object, const char *key, json_t *value) Like :cfunc:`json_object_set()` but steals the reference to @@ -428,6 +478,15 @@ Unicode string and the value is any JSON value. .. versionadded:: 1.1 +.. cfunction:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value) + + Like :cfunc:`json_object_set_new`, but doesn't check that *key* is + valid 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 + .. cfunction:: int json_object_del(json_t *object, const char *key) Delete *key* from *object* if it exists. Returns 0 on success, or @@ -456,6 +515,16 @@ The following functions implement an iteration protocol for objects: Returns an opaque iterator which can be used to iterate over all key-value pairs in *object*, or *NULL* if *object* is empty. +.. cfunction:: void *json_object_iter_at(json_t *object, const char *key) + + Like :cfunc:`json_object_iter()`, but returns an iterator to the + key-value pair in *object* whose key is equal to *key*, or NULL if + *key* is not found in *object*. Iterating forward to the end of + *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 + .. cfunction:: void *json_object_iter_next(json_t *object, void *iter) Returns an iterator pointing to the next key-value pair in *object* @@ -472,6 +541,21 @@ The following functions implement an iteration protocol for objects: Extract the associated value from *iter*. +.. cfunction:: int json_object_iter_set(json_t *object, void *iter, json_t *value) + + Set the value of the key-value pair in *object*, that is pointed to + by *iter*, to *value*. + + .. versionadded:: 1.3 + +.. cfunction:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value) + + Like :cfunc:`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 */ @@ -519,16 +603,38 @@ can be ORed together to obtain *flags*. .. 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. -.. cfunction:: char *json_dumps(const json_t *root, unsigned long flags) +.. cfunction:: char *json_dumps(const json_t *root, size_t 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, unsigned long flags) +.. cfunction:: int json_dumpf(const json_t *root, FILE *output, size_t flags) Write the JSON representation of *root* to the stream *output*. *flags* is described above. Returns 0 on success and -1 on error. @@ -536,7 +642,7 @@ is in UTF-8. *output*. In this case, the output is undefined and most likely not valid JSON. -.. cfunction:: int json_dump_file(const json_t *json, const char *path, unsigned long flags) +.. cfunction:: int json_dump_file(const json_t *json, const char *path, size_t flags) Write the JSON representation of *root* to the file *path*. If *path* already exists, it is overwritten. *flags* is described @@ -622,3 +728,75 @@ The following functions perform the actual JSON decoding. 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. + + +Equality +======== + +Testing for equality of two JSON values cannot, in general, be +achieved using the ``==`` operator. Equality in the terms of the +``==`` operator states that the two :ctype:`json_t` pointers point to +exactly the same JSON value. However, two JSON values can be equal not +only if they are exactly the same value, but also if they have equal +"contents": + +* Two integer or real values are equal if their contained numeric + values are equal. An integer value is never equal to a real value, + though. + +* Two strings are equal if their contained UTF-8 strings are equal. + +* Two arrays are equal if they have the same number of elements and + each element in the first array is equal to the corresponding + element in the second array. + +* Two objects are equal if they have exactly the same keys and the + value for each key in the first object is equal to the value of the + corresponding key in the second object. + +* Two true, false or null values have no "contents", so they are equal + if their types are equal. (Because these values are singletons, + their equality can actually be tested with ``==``.) + +The following function can be used to test whether two JSON values are +equal. + +.. cfunction:: int json_equal(json_t *value1, json_t *value2) + + Returns 1 if *value1* and *value2* are equal, as defined above. + Returns 0 if they are inequal or one or both of the pointers are + *NULL*. + + .. versionadded:: 1.2 + + +Copying +======= + +Because of reference counting, passing JSON values around doesn't +require copying them. But sometimes a fresh copy of a JSON value is +needed. For example, if you need to modify an array, but still want to +use the original afterwards, you should take a copy of it first. + +Jansson supports two kinds of copying: shallow and deep. There is a +difference between these methods only for arrays and objects. Shallow +copying only copies the first level value (array or object) and uses +the same child values in the copied value. Deep copying makes a fresh +copy of the child values, too. Moreover, all the child values are deep +copied in a recursive fashion. + +.. cfunction:: json_t *json_copy(json_t *value) + + .. refcounting:: new + + Returns a shallow copy of *value*, or *NULL* on error. + + .. versionadded:: 1.2 + +.. cfunction:: json_t *json_deep_copy(json_t *value) + + .. refcounting:: new + + Returns a deep copy of *value*, or *NULL* on error. + + .. versionadded:: 1.2