Add equality test for JSON values

[jansson.git] / doc / apiref.rst

diff --git a/doc/apiref.rst b/doc/apiref.rst
index fd2a7c9..bf22466 100644 (file)
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -229,6 +229,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 +252,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
 ======
@@ -420,6 +439,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 +456,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
@@ -636,3 +673,43 @@ 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