existing keys. Returns 0 on success or -1 on error.
-The following functions implement an iteration protocol for objects:
+The following functions implement an iteration protocol for objects,
+allowing to iterate through all key-value pairs in an object. The
+items are not returned in any particular order, as this would require
+sorting due to the internal object representation.
.. function:: void *json_object_iter(json_t *object)
}
+Error reporting
+===============
+
+Jansson uses a single struct type to pass error information to the
+user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
+:ref:`apiref-unpack` for functions that pass error information using
+this struct.
+
+.. type:: json_error_t
+
+ .. member:: char text[]
+
+ The error message (in UTF-8), or an empty string if a message is
+ not available.
+
+ .. member:: char source[]
+
+ Source of the error. This can be (a part of) the file name or a
+ special identifier in angle brackers (e.g. ``<string>``).
+
+ .. member:: int line
+
+ The line number on which the error occurred.
+
+ .. member:: int column
+
+ The column on which the error occurred. Note that this is the
+ *character column*, not the byte column, i.e. a multibyte UTF-8
+ character counts as one column.
+
+ .. member:: size_t position
+
+ The position in bytes from the start of the input. This is
+ useful for debugging Unicode encoding problems.
+
+The normal use of :type:`json_error_t` is to allocate it on the stack,
+and pass a pointer to a function. Example::
+
+ int main() {
+ json_t *json;
+ json_error_t error;
+
+ json = json_load_file("/path/to/file.json", 0, &error);
+ if(!json) {
+ /* the error variable contains error information */
+ }
+ ...
+ }
+
+Also note that if the call succeeded (``json != NULL`` in the above
+example), the contents of ``error`` are unspecified.
+
+All functions also accept *NULL* as the :type:`json_error_t` pointer,
+in which case no error information is returned to the caller.
+
+
Encoding
========
This sections describes the functions that can be used to encode
-values to JSON. Only objects and arrays can be encoded, since they are
-the only valid "root" values of a JSON text.
+values to JSON. By default, only objects and arrays can be encoded
+directly, since they are the only valid *root* values of a JSON text.
+To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see
+below).
By default, the output has no newlines, and spaces are used between
array and object elements for a readable output. This behavior can be
example, decoding a JSON text and then encoding with this flag
preserves the order of object keys.
+``JSON_ENCODE_ANY``
+ Specifying this flag makes it possible to encode any JSON value on
+ its own. Without it, only objects and arrays can be passed as the
+ *root* value to the encoding functions.
+
+ **Note:** Encoding any value may be useful in some scenarios, but
+ it's generally discouraged as it violates strict compatiblity with
+ :rfc:`4627`. If you use this flag, don't expect interoperatibility
+ with other JSON systems. Even Jansson itself doesn't have any means
+ to decode JSON texts whose root value is not object or array.
+
+ .. versionadded:: 2.1
+
The following functions perform the actual JSON encoding. The result
is in UTF-8.
above. Returns 0 on success and -1 on error.
+.. _apiref-decoding:
+
Decoding
========
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. *flags* is currently unused, and should be set
- to 0.
+ information about the error. *flags* is currently unused, and
+ should be set to 0.
+
+.. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)
+
+ .. refcounting:: new
+
+ Decodes the JSON string *buffer*, whose length is *buflen*, and
+ returns the array or object it contains, or *NULL* on error, in
+ which case *error* is filled with information about the error. This
+ is similar to :func:`json_loads()` except that the string doesn't
+ need to be null-terminated. *flags* is currently unused, and should
+ be set to 0.
+
+ .. versionadded:: 2.1
.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
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. *flags* is currently unused, and should
- be set to 0.
+ filled with information about the error. *flags* is currently
+ unused, and should be set to 0.
.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
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. *flags* is currently unused, and should
- be set to 0.
+ filled with information about the error. *flags* is currently
+ unused, and should be set to 0.
-.. type:: json_error_t
-
- This data structure is used to return information on decoding
- errors from the decoding functions.
- .. member:: const char *text
-
- The error message (in UTF-8), or an empty string if a message is
- not available.
-
- .. member:: int line
+.. _apiref-pack:
- The line number on which the error occurred, or -1 if this
- information is not available.
-
- .. member:: int column
-
- The character column on which the error occurred, or -1 if this
- information is not available.
-
- .. member:: const char *source
-
- Source of the error. This is (a part of) the file name when
- using :func:`json_load_file()`, or a special identifier in angle
- brackets otherwise (e.g. ``<string>``).
-
- The normal use of :type:`json_error_t` is to allocate it on the
- stack, and pass a pointer to a decoding function. Example::
-
- int main() {
- json_t *json;
- json_error_t error;
-
- json = json_load_file("/path/to/file.json", 0, &error);
- if(!json) {
- /* the error variable contains error information */
- }
- ...
- }
-
- Also note that if the decoding succeeded (``json != NULL`` in the
- above example), the contents of ``error`` are unspecified.
-
- All decoding functions also accept *NULL* as the
- :type:`json_error_t` pointer, in which case no error information
- is returned to the caller.
-
-
-.. _apiref-building-values:
-
-Building values
+Building Values
===============
This sectinon describes functions that help to create, or *pack*,
``O`` (any value) [json_t \*]
Like ``o``, but the argument's reference count is incremented.
- This is useful if you pack and array an array or object and want
- to keep the reference for the JSON value consumed by ``O`` to
+ This is useful if you pack into an array or object and want to
+ keep the reference for the JSON value consumed by ``O`` to
yourself.
``[fmt]`` (array)
json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
-Parsing and validating values
+.. _apiref-unpack:
+
+Parsing and Validating Values
=============================
This sectinon describes functions that help to validate complex values
and extract, or *unpack*, data from them. Like :ref:`building values
-<apiref-building-values>`, this is also based on format strings.
+<apiref-pack>`, this is also based on format strings.
While a JSON value is unpacked, the type specified in the format
string is checked to match that of the JSON value. This is the
Returns a deep copy of *value*, or *NULL* on error.
-Custom memory allocation
+Custom Memory Allocation
========================
By default, Jansson uses :func:`malloc()` and :func:`free()` for
projects / jansson.git / blobdiff