X-Git-Url: http://www.project-moonshot.org/gitweb/?p=jansson.git;a=blobdiff_plain;f=doc%2Fapiref.rst;h=c3a055436bf60d719ead90780addd6bf620dd413;hp=2c6cf3bee848ea1372b083f5db5baa4e7de74779;hb=56643d4311ecb26001527520da6264d92eab3d76;hpb=145032a57f7844c29f2c40415b46338ac3445207

diff --git a/doc/apiref.rst b/doc/apiref.rst
index 2c6cf3b..c3a0554 100644
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -210,10 +210,10 @@ the user to avoid them.
 
 If a circular reference is created, the memory consumed by the values
 cannot be freed by :cfunc:`json_decref()`. The reference counts never
-drops to zero because the values are keeping the circular reference to
-themselves. Moreover, trying to encode the values with any of the
-encoding functions will fail. The encoder detects circular references
-and returns an error status.
+drops to zero because the values are keeping the references to each
+other. Moreover, trying to encode the values with any of the encoding
+functions will fail. The encoder detects circular references and
+returns an error status.
 
 
 True, False and Null
@@ -299,18 +299,57 @@ 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)
+.. ctype:: json_int_t
+
+   This is the C type that is used to store JSON integer values. It
+   represents the widest integer type available on your system. In
+   practice it's just a typedef of ``long long`` if your compiler
+   supports it, otherwise ``long``.
+
+   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 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
+   specifier that corresponds to :ctype:`json_int_t`, without the
+   leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro
+   is required because the actual type of :ctype:`json_int_t` can be
+   either ``long`` or ``long long``, and :cfunc:`printf()` reuiqres
+   different length modifiers for the two.
+
+   Example::
+
+       json_int_t x = 123123123;
+       printf("x is %" JSON_INTEGER_FORMAT "\n", x);
+
+
+.. cfunction:: json_t *json_integer(json_int_t value)
 
    .. refcounting:: new
 
    Returns a new JSON integer, or *NULL* on error.
 
-.. cfunction:: int json_integer_value(const json_t *integer)
+.. cfunction:: json_int_t 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)
+.. cfunction:: int json_integer_set(const json_t *integer, json_int_t value)
 
    Sets the associated value of *integer* to *value*. Returns 0 on
    success and -1 if *integer* is not a JSON integer.
@@ -357,12 +396,12 @@ A JSON array is an ordered collection of other JSON values.
    Returns a new JSON array, or *NULL* on error. Initially, the array
    is empty.
 
-.. cfunction:: unsigned int json_array_size(const json_t *array)
+.. cfunction:: size_t json_array_size(const json_t *array)
 
    Returns the number of elements in *array*, or 0 if *array* is NULL
    or not a JSON array.
 
-.. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index)
+.. cfunction:: json_t *json_array_get(const json_t *array, size_t index)
 
    .. refcounting:: borrow
 
@@ -372,14 +411,14 @@ A JSON array is an ordered collection of other JSON values.
    if *array* is *NULL*, or if *index* is out of range, *NULL* is
    returned.
 
-.. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value)
+.. cfunction:: int json_array_set(json_t *array, size_t index, json_t *value)
 
    Replaces the element in *array* at position *index* with *value*.
    The valid range for *index* is from 0 to the return value of
    :cfunc:`json_array_size()` minus 1. Returns 0 on success and -1 on
    error.
 
-.. cfunction:: int json_array_set_new(json_t *array, unsigned int index, json_t *value)
+.. cfunction:: int json_array_set_new(json_t *array, size_t index, json_t *value)
 
    Like :cfunc:`json_array_set()` but steals the reference to *value*.
    This is useful when *value* is newly created and not used after
@@ -400,7 +439,7 @@ 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)
+.. cfunction:: int json_array_insert(json_t *array, size_t 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
@@ -408,7 +447,7 @@ A JSON array is an ordered collection of other JSON values.
 
    .. versionadded:: 1.1
 
-.. cfunction:: int json_array_insert_new(json_t *array, unsigned int index, json_t *value)
+.. cfunction:: int json_array_insert_new(json_t *array, size_t 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
@@ -416,7 +455,7 @@ A JSON array is an ordered collection of other JSON values.
 
    .. versionadded:: 1.1
 
-.. cfunction:: int json_array_remove(json_t *array, unsigned int index)
+.. cfunction:: int json_array_remove(json_t *array, size_t index)
 
    Removes the element in *array* at position *index*, shifting the
    elements after *index* one position towards the start of the array.
@@ -452,7 +491,7 @@ 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)
+.. cfunction:: size_t json_object_size(const json_t *object)
 
    Returns the number of elements in *object*, or 0 if *object* is not
    a JSON object.
@@ -603,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.
 
@@ -640,13 +679,13 @@ can be ORed together to obtain *flags*.
 The following functions perform the actual JSON encoding. The result
 is in UTF-8.
 
-.. cfunction:: char *json_dumps(const json_t *root, unsigned long flags)
+.. cfunction:: char *json_dumps(const json_t *root, size_t flags)
 
    Returns the JSON representation of *root* as a string, or *NULL* on
    error. *flags* is described above. The return value must be freed
    by the caller using :cfunc:`free()`.
 
-.. cfunction:: int json_dumpf(const json_t *root, FILE *output, unsigned long flags)
+.. cfunction:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
 
    Write the JSON representation of *root* to the stream *output*.
    *flags* is described above. Returns 0 on success and -1 on error.
@@ -654,7 +693,7 @@ is in UTF-8.
    *output*. In this case, the output is undefined and most likely not
    valid JSON.
 
-.. cfunction:: int json_dump_file(const json_t *json, const char *path, unsigned long flags)
+.. cfunction:: int json_dump_file(const json_t *json, const char *path, size_t flags)
 
    Write the JSON representation of *root* to the file *path*. If
    *path* already exists, it is overwritten. *flags* is described
@@ -700,7 +739,7 @@ affect especially the behavior of the decoder.
           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 */
           }
@@ -716,32 +755,35 @@ affect especially the behavior of the decoder.
 
 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