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
Returns the associated value of *string* as a null terminated UTF-8
encoded string, or *NULL* if *string* is not a JSON string.
+ The retuned value is read-only and must not be modified or freed by
+ the user. It is valid as long as *string* exists, i.e. as long as
+ its reference count has not dropped to zero.
+
.. function:: int json_string_set(const json_t *string, const char *value)
Sets the associated value of *string* to *value*. *value* must be a
.. member:: const char *text
The error message (in UTF-8), or an empty string if a message is
- not available. This is actually a fixed-length character array,
- but should be considered constant.
+ 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::
is returned to the caller.
+.. _apiref-building-values:
+
+Building values
+===============
+
+This sectinon describes functions that help to create, or *pack*,
+complex JSON values, especially nested objects and arrays. Value
+building is based on a *format string* that is used to tell the
+functions about the expected arguments.
+
+For example, the format string ``"i"`` specifies a single integer
+value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s,
+b]"`` specifies an array value with two integers and a boolean as its
+items::
+
+ /* Create the JSON integer 42 */
+ json_pack("i", 42);
+
+ /* Create the JSON array ["foo", "bar", true] */
+ json_pack("[ssb]", "foo", "bar", 1);
+
+Here's the full list of format characters. The type in parentheses
+denotes the resulting JSON type, and the type in brackets (if any)
+denotes the C type that is expected as the corresponding argument.
+
+``s`` (string) [const char \*]
+ Convert a NULL terminated UTF-8 string to a JSON string.
+
+``n`` (null)
+ Output a JSON null value. No argument is consumed.
+
+``b`` (boolean) [int]
+ Convert a C :type:`int` to JSON boolean value. Zero is converted
+ to ``false`` and non-zero to ``true``.
+
+``i`` (integer) [int]
+ Convert a C :type:`int` to JSON integer.
+
+``I`` (integer) [json_int_t]
+ Convert a C :type:`json_int_t` to JSON integer.
+
+``f`` (real) [double]
+ Convert a C :type:`double` to JSON real.
+
+``o`` (any value) [json_t \*]
+ Output any given JSON value as-is. If the value is added to an
+ array or object, the reference to the value passed to ``o`` is
+ stealed by the container.
+
+``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
+ yourself.
+
+``[fmt]`` (array)
+ Build an array with contents from the inner format string. ``fmt``
+ may contain objects and arrays, i.e. recursive value building is
+ supported.
+
+``{fmt}`` (object)
+ Build an object with contents from the inner format string
+ ``fmt``. The first, third, etc. format character represent a key,
+ and must be ``s`` (as object keys are always strings). The second,
+ fourth, etc. format character represent a value. Any value may be
+ an object or array, i.e. recursive value building is supported.
+
+
+.. function:: json_t *json_pack(const char *fmt, ...)
+
+ .. refcounting:: new
+
+ Build a new JSON value according to the format string *fmt*. For
+ each format character (except for ``{}[]n``), one argument is
+ consumed and used to build the corresponding value. Returns *NULL*
+ on error.
+
+.. function:: json_t *json_pack_ex(json_error_t *error, size_t flags, const char *fmt, ...)
+ json_t *json_vpack_ex(json_error_t *error, size_t flags, const char *fmt, va_list ap)
+
+ .. refcounting:: new
+
+ Like :func:`json_pack()`, but an in the case of an error, an error
+ message is written to *error*, if it's not *NULL*. The *flags*
+ parameter is currently unused and should be set to 0.
+
+ As only the errors in format string (and out-of-memory errors) can
+ be caught by the packer, these two functions are most likely only
+ useful for debugging format strings.
+
+More examples::
+
+ /* Build an empty JSON object */
+ json_pack("{}");
+
+ /* Build the JSON object {"foo": 42, "bar": 7} */
+ json_pack("{sisb}", "foo", 42, "bar", 7);
+
+ /* Like above, ':', ',' and whitespace are ignored */
+ json_pack("{s:i, s:b}", "foo", 42, "bar", 7);
+
+ /* Build the JSON array [[1, 2], {"cool": true}] */
+ json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
+
+
+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.
+
+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
+validation part of the process. By default, the unpacking functions
+also check that all items of arrays and objects are unpacked. This
+check be disabled with the format character ``*`` or by using the flag
+``JSON_UNPACK_ONLY``.
+
+Here's the full list of format characters. The type in parentheses
+denotes the JSON type, and the type in brackets (if any) denotes the C
+type whose address should be passed.
+
+``s`` (string) [const char \*]
+ Convert a JSON string to a pointer to a NULL terminated UTF-8
+ string.
+
+``n`` (null)
+ Expect a JSON null value. Nothing is extracted.
+
+``b`` (boolean) [int]
+ Convert a JSON boolean value to a C :type:`int`, so that ``true``
+ is converted to 1 and ``false`` to 0.
+
+``i`` (integer) [int]
+ Convert a JSON integer to C :type:`int`.
+
+``I`` (integer) [json_int_t]
+ Convert a JSON integer to C :type:`json_int_t`.
+
+``f`` (real) [double]
+ Convert a JSON real to C :type:`double`.
+
+``F`` (integer or real) [double]
+ Convert a JSON number (integer or real) to C :type:`double`.
+
+``o`` (any value) [json_t \*]
+ Store a JSON value with no conversion to a :type:`json_t` pointer.
+
+``O`` (any value) [json_t \*]
+ Like ``O``, but the JSON value's reference count is incremented.
+
+``[fmt]`` (array)
+ Convert each item in the JSON array according to the inner format
+ string. ``fmt`` may contain objects and arrays, i.e. recursive
+ value extraction is supporetd.
+
+``{fmt}`` (object)
+ Convert each item in the JSON object according to the inner format
+ string ``fmt``. The first, third, etc. format character represent
+ a key, and must be ``s``. The corresponding argument to unpack
+ functions is read as the object key. The second fourth, etc.
+ format character represent a value and is written to the address
+ given as the corresponding argument. **Note** that every other
+ argument is read from and every other is written to.
+
+ ``fmt`` may contain objects and arrays as values, i.e. recursive
+ value extraction is supporetd.
+
+``*``
+ This special format character is used to disable the check that
+ all object and array items are accessed on a per-value basis. It
+ must appear inside an array or object as the last format character
+ before the closing bracket or brace.
+
+
+.. function:: int json_unpack(json_t *root, const char *fmt, ...)
+
+ Validate and unpack the JSON value *root* according to the format
+ string *fmt*. Returns 0 on success and -1 on failure.
+
+.. function:: int json_unpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, ...)
+ int json_vunpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, va_list ap)
+
+ Validate and unpack the JSON value *root* according to the format
+ string *fmt*. If an error occurs and *error* is not *NULL*, write
+ error information to *error*. *flags* can be used to control the
+ behaviour of the unpacker, see below for the flags. Returns 0 on
+ success and -1 on failure.
+
+The following unpacking flags are available:
+
+``JSON_UNPACK_ONLY``
+ Disable the validation step checking that all object and array
+ items are unpacked. This is equivalent to appending the format
+ character ``*`` to the end of every array and object in the format
+ string.
+
+``JSON_VALIDATE_ONLY``
+ Don't extract any data, just validate the JSON value against the
+ given format string. Note that object keys must still be specified
+ after the format string.
+
+Examples::
+
+ /* root is the JSON integer 42 */
+ int myint;
+ json_unpack(root, "i", &myint);
+ assert(myint == 42);
+
+ /* root is the JSON object {"foo": "bar", "quux": true} */
+ const char *str;
+ int boolean;
+ json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean);
+ assert(strcmp(str, "bar") == 0 && boolean == 1);
+
+ /* root is the JSON array [[1, 2], {"baz": null} */
+ json_error_t error;
+ json_unpack_ex(root, &error, JSON_VALIDATE_ONLY, "[[i,i], {s:n}]", "baz");
+ /* returns 0 for validation success, nothing is extracted */
+
+ /* root is the JSON array [1, 2, 3, 4, 5] */
+ int myint1, myint2, ret;
+ ret = json_unpack(root, "[ii*]", &myint1, &myint2);
+ assert(ret == 0 && myint1 == 1 && myint2 == 2);
+
+
Equality
========
projects / jansson.git / blobdiff