Make integer, real and string mutable

[jansson.git] / doc / apiref.rst

diff --git a/doc/apiref.rst b/doc/apiref.rst
index 8623623..cc36117 100644 (file)
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -194,11 +194,18 @@ 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)
+.. 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
@@ -210,10 +217,17 @@ 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)
 
@@ -221,10 +235,17 @@ Number
 
    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.
 
-   Returns the associated value of the JSON real *json*. If *json* is
-   *NULL* or not a JSON real, 0.0 is returned.
+.. cfunction:: int json_real_set(const json_t *real, double value)
+
+   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:
@@ -291,6 +312,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
 ======
@@ -305,6 +364,13 @@ 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)
+
+   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
@@ -333,6 +399,21 @@ Unicode string and the value is any JSON value.
    -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)