Add support for optional object keys for json_unpack() and friends

[jansson.git] / doc / apiref.rst

diff --git a/doc/apiref.rst b/doc/apiref.rst
index f65dc5d..0657edb 100644 (file)
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -1035,6 +1035,8 @@ denotes the C type that is expected as the corresponding argument.
     fourth, etc. format character represent a value. Any value may be
     an object or array, i.e. recursive value building is supported.
 
+Whitespace, ``:`` and ``,`` are ignored.
+
 The following functions compose the value building API:
 
 .. function:: json_t *json_pack(const char *fmt, ...)
@@ -1142,6 +1144,11 @@ type whose address should be passed.
     ``fmt`` may contain objects and arrays as values, i.e. recursive
     value extraction is supporetd.
 
+    .. versionadded:: 2.3
+       Any ``s`` representing a key may be suffixed with a ``?`` to
+       make the key optional. If the key is not found, nothing is
+       extracted. See below for an example.
+
 ``!``
     This special format character is used to enable the check that
     all object and array items are accessed, on a per-value basis. It
@@ -1156,6 +1163,8 @@ type whose address should be passed.
     or object as the last format character before the closing bracket
     or brace.
 
+Whitespace, ``:`` and ``,`` are ignored.
+
 The following functions compose the parsing and validation API:
 
 .. function:: int json_unpack(json_t *root, const char *fmt, ...)
@@ -1222,6 +1231,13 @@ Examples::
     json_unpack(root, "[ii!]", &myint1, &myint2);
     /* returns -1 for failed validation */
 
+    /* root is an empty JSON object */
+    int myint = 0, myint2 = 0;
+    json_unpack(root, "{s?i, s?[ii]}",
+                "foo", &myint1,
+                "bar", &myint2, &myint3);
+    /* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */
+
 
 Equality
 ========