Clarify the documentation

[jansson.git] / doc / apiref.rst

diff --git a/doc/apiref.rst b/doc/apiref.rst
index 0db662d..2c6cf3b 100644 (file)
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -244,6 +244,12 @@ returns the same value each time.
 String
 ======
 
+Jansson uses UTF-8 as the character encoding. All JSON strings must be
+valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null
+terminated C strings are used, so JSON strings may not contain
+embedded null characters. All other Unicode codepoints U+0001 through
+U+10FFFF are allowed.
+
 .. cfunction:: json_t *json_string(const char *value)
 
    .. refcounting:: new
@@ -287,6 +293,12 @@ String
 Number
 ======
 
+The JSON specification only contains one numeric type, "number". The C
+programming language has distinct types for integer and floating-point
+numbers, so for practical reasons Jansson also has distinct types for
+the two. They are called "integer" and "real", respectively. For more
+information, see :ref:`rfc-conformance`.
+
 .. cfunction:: json_t *json_integer(int value)
 
    .. refcounting:: new
@@ -515,6 +527,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*
@@ -531,6 +553,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 */
@@ -592,6 +629,14 @@ can be ORed together to obtain *flags*.
 
    .. versionadded:: 1.2
 
+``JSON_PRESERVE_ORDER``
+   If this flag is used, object keys in the output are sorted into the
+   same order in which they were first inserted to the object. For
+   example, decoding a JSON text and then encoding with this flag
+   preserves the order of object keys.
+
+   .. versionadded:: 1.3
+
 The following functions perform the actual JSON encoding. The result
 is in UTF-8.
 
@@ -623,10 +668,12 @@ This sections describes the functions that can be used to decode JSON
 text to the Jansson representation of JSON data. The JSON
 specification requires that a JSON text is either a serialized array
 or object, and this requirement is also enforced with the following
-functions.
+functions. In other words, the top level value in the JSON text being
+decoded must be either array or object.
 
-The only supported character encoding is UTF-8 (which ASCII is a
-subset of).
+See :ref:`rfc-conformance` for a discussion on Jansson's conformance
+to the JSON specification. It explains many design decisions that
+affect especially the behavior of the decoder.
 
 .. ctype:: json_error_t
 
@@ -711,7 +758,8 @@ only if they are exactly the same value, but also if they have equal
   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 strings are equal if their contained UTF-8 strings are equal,
+  byte by byte. Unicode comparison algorithms are not implemented.
 
 * Two arrays are equal if they have the same number of elements and
   each element in the first array is equal to the corresponding