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
.. 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
======
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
.. 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
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*
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 */
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
projects / jansson.git / blobdiff