Add jansson_config.h.win32

[jansson.git] / doc / apiref.rst

diff --git a/doc/apiref.rst b/doc/apiref.rst
index 91de0c8..c3a0554 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`.
+
 .. ctype:: json_int_t
 
    This is the C type that is used to store JSON integer values. It
@@ -296,9 +308,21 @@ Number
 
    Usually, you can safely use plain ``int`` in place of
    ``json_int_t``, and the implicit C integer conversion handles the
-   rest. Only when you know that you need a full 64-bit range, you
+   rest. Only when you know that you need the full 64-bit range, you
    should use ``json_int_t`` explicitly.
 
+``JSON_INTEGER_IS_LONG_LONG``
+
+   This is a preprocessor variable that holds the value 1 if
+   :ctype:`json_int_t` is ``long long``, and 0 if it's ``long``. It
+   can be used as follows::
+
+       #if JSON_INTEGER_IS_LONG_LONG
+       /* Code specific for long long */
+       #else
+       /* Code specific for long */
+       #endif
+
 ``JSON_INTEGER_FORMAT``
 
    This is a macro that expands to a :cfunc:`printf()` conversion
@@ -618,7 +642,7 @@ can be ORed together to obtain *flags*.
 ``JSON_INDENT(n)``
    Pretty-print the result, using newlines between array and object
    items, and indenting with *n* spaces. The valid range for *n* is
-   between 0 and 255, other values result in an undefined output. If
+   between 0 and 32, other values result in an undefined output. If
    ``JSON_INDENT`` is not used or *n* is 0, no newlines are inserted
    between array and object items.
 
@@ -683,10 +707,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
 
@@ -713,7 +739,7 @@ subset of).
           json_t *json;
           json_error_t error;
 
-          json = json_load_file("/path/to/file.json", &error);
+          json = json_load_file("/path/to/file.json", 0, &error);
           if(!json) {
               /* the error variable contains error information */
           }
@@ -729,32 +755,35 @@ subset of).
 
 The following functions perform the actual JSON decoding.
 
-.. cfunction:: json_t *json_loads(const char *input, json_error_t *error)
+.. cfunction:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
 
    .. refcounting:: new
 
    Decodes the JSON string *input* and returns the array or 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.
+   *error* parameter. *flags* is currently unused, and should be set
+   to 0.
 
-.. cfunction:: json_t *json_loadf(FILE *input, json_error_t *error)
+.. cfunction:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
 
    .. refcounting:: new
 
    Decodes the JSON text in stream *input* and returns the array or
    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.
+   on the *error* parameter. *flags* is currently unused, and should
+   be set to 0.
 
-.. cfunction:: json_t *json_load_file(const char *path, json_error_t *error)
+.. cfunction:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
 
    .. refcounting:: new
 
    Decodes the JSON text in file *path* and returns the array or
    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.
+   on the *error* parameter. *flags* is currently unused, and should
+   be set to 0.
 
 
 Equality
@@ -771,7 +800,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