in each source file.
-All constants are prefixed ``JSON_`` and other identifiers with
-``json_``. Type names are suffixed with ``_t`` and ``typedef``\ 'd so
-that the ``struct`` keyword need not be used.
+All constants are prefixed with ``JSON_`` (except for those describing
+the library version, prefixed with ``JANSSON_``). Other identifiers
+are prefixed with ``json_``. Type names are suffixed with ``_t`` and
+``typedef``\ 'd so that the ``struct`` keyword need not be used.
+
+
+Library Version
+===============
+
+The Jansson version is of the form *A.B.C*, where *A* is the major
+version, *B* is the minor version and *C* is the micro version. If the
+micro version is zero, it's omitted from the version string, i.e. the
+version string is just *A.B*.
+
+When a new release only fixes bugs and doesn't add new features or
+functionality, the micro version is incremented. When new features are
+added in a backwards compatible way, the minor version is incremented
+and the micro version is set to zero. When there are backwards
+incompatible changes, the major version is incremented and others are
+set to zero.
+
+The following preprocessor constants specify the current version of
+the library:
+
+``JANSSON_VERSION_MAJOR``, ``JANSSON_VERSION_MINOR``, ``JANSSON_VERSION_MICRO``
+ Integers specifying the major, minor and micro versions,
+ respectively.
+
+``JANSSON_VERSION``
+ A string representation of the current version, e.g. ``"1.2.1"`` or
+ ``"1.3"``.
+
+``JANSSON_VERSION_HEX``
+ A 3-byte hexadecimal representation of the version, e.g.
+ ``0x010201`` for version 1.2.1 and ``0x010300`` for version 1.3.
+ This is useful in numeric comparisions, e.g.::
+
+ #if JANSSON_VERSION_HEX >= 0x010300
+ /* Code specific to version 1.3 and above */
+ #endif
Value Representation
to the JSON specification. It explains many design decisions that
affect especially the behavior of the decoder.
-.. type:: json_error_t
-
- This data structure is used to return information on decoding
- errors from the decoding functions. Its definition is repeated
- here::
-
- #define JSON_ERROR_TEXT_LENGTH 160
-
- typedef struct {
- char text[JSON_ERROR_TEXT_LENGTH];
- int line;
- } json_error_t;
-
- *line* is the line number on which the error occurred, or -1 if
- this information is not available. *text* contains the error
- message (in UTF-8), or an empty string if a message is not
- available.
-
- The normal usef of :type:`json_error_t` is to allocate it normally
- 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.
-
-The following functions perform the actual JSON decoding.
-
.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
.. refcounting:: new
on the *error* parameter. *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
+
+ 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.
+
Equality
========