to release the reference.
Normally, all functions accepting a JSON value as an argument will
-nmanage the reference, i.e. increase and decrease the reference count
+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
argument.
+Circular References
+-------------------
+
+A circular reference is created when an object or an array is,
+directly or indirectly, inserted inside itself. The direct case is
+simple::
+
+ json_t *obj = json_object();
+ json_object_set(obj, "foo", obj);
+
+Jansson will refuse to do this, and :cfunc:`json_object_set()` (and
+all the other such functions for objects and arrays) will return with
+an error status. The indirect case is the dangerous one::
+
+ json_t *arr1 = json_array(), *arr2 = json_array();
+ json_array_append(arr1, arr2);
+ json_array_append(arr2, arr1);
+
+In this example, the array ``arr2`` is contained in the array
+``arr1``, and vice versa. Jansson cannot check for this kind of
+indirect circular references without a performance hit, so it's up to
+the user to avoid them.
+
+If a circular reference is created, the memory consumed by the values
+cannot be freed by :cfunc:`json_decref()`. The reference counts never
+drops to zero because the values are keeping the circular reference to
+themselves. Moreover, trying to encode the values with any of the
+encoding functions will fail. The encoder detects circular references
+and returns an error status.
+
+
True, False and Null
====================
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)
+.. cfunction:: const char *json_string_value(const json_t *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.
+ Returns the associated value of *string* as a null terminated UTF-8
+ encoded string, or *NULL* if *string* is not a JSON string.
+
+.. cfunction:: int json_string_set(const json_t *string, const char *value)
+
+ Sets the associated value of *string* to *value*. *value* must be a
+ valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
+ error.
+
+ .. versionadded:: 1.1
Number
Returns a new JSON integer, or *NULL* on error.
-.. cfunction:: int json_integer_value(const json_t *json)
+.. cfunction:: int json_integer_value(const json_t *integer)
+
+ Returns the associated value of *integer*, or 0 if *json* is not a
+ JSON integer.
+
+.. cfunction:: int json_integer_set(const json_t *integer, int value)
- Returns the associated value the JSON integer *json*. If *json* is
- *NULL* or not a JSON integer, 0 is returned.
+ Sets the associated value of *integer* to *value*. Returns 0 on
+ success and -1 if *integer* is not a JSON integer.
+
+ .. versionadded:: 1.1
.. cfunction:: json_t *json_real(double value)
Returns a new JSON real, or *NULL* on error.
-.. cfunction:: double json_real_value(const json_t *json)
+.. cfunction:: double json_real_value(const json_t *real)
+
+ Returns the associated value of *real*, or 0.0 if *real* is not a
+ JSON real.
+
+.. cfunction:: int json_real_set(const json_t *real, double value)
- Returns the associated value of the JSON real *json*. If *json* is
- *NULL* or not a JSON real, 0.0 is returned.
+ 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:
.. 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
======
Returns a new JSON object, or *NULL* on error. Initially, the
object is empty.
+.. cfunction:: unsigned int json_object_size(const json_t *object)
+
+ Returns the number of elements in *object*, or 0 if *object* is not
+ a JSON object.
+
+ .. versionadded:: 1.1
+
.. cfunction:: json_t *json_object_get(const json_t *object, const char *key)
.. refcounting:: borrow
-1 if *key* was not found.
+.. cfunction:: int json_object_clear(json_t *object)
+
+ Remove all elements from *object*. Returns 0 on success and -1 if
+ *object* is not a JSON object.
+
+ .. versionadded:: 1.1
+
+.. cfunction:: 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:
.. cfunction:: void *json_object_iter(json_t *object)
projects / jansson.git / blobdiff