Add functions json_object_iter_{at,set,set_new}

[jansson.git] / doc / apiref.rst

diff --git a/doc/apiref.rst b/doc/apiref.rst
index bf22466..0a96999 100644 (file)
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -493,6 +493,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*
@@ -509,6 +519,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 */
@@ -713,3 +738,35 @@ equal.
    *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