+ 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);
+
+
+.. _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-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
+validation part of the process. In addition to this, the unpacking
+functions can also check that all items of arrays and objects are
+unpacked. This check be enabled with the format character ``!`` or by
+using the flag ``JSON_STRICT``. See below for details.
+
+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 enable 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. To enable the check globally,
+ use the ``JSON_STRICT`` unpacking flag.
+
+``*``
+ This special format character is the opposite of ``!``. If the
+ ``JSON_STRICT`` flag is used, ``*`` can be used to disable the
+ strict check on a per-value basis. It must appear inside an array
+ or object as the last format character before the closing bracket
+ or brace.
+
+The following functions compose the parsing and validation API:
+
+.. 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_STRICT``
+ Enable the extra 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;
+ json_unpack(root, "[ii!]", &myint1, &myint2);
+ /* returns -1 for failed validation */
projects / jansson.git / blobdiff