From f241e14cab9b664be4a9c9f187c1e71aa25fc30f Mon Sep 17 00:00:00 2001 From: Petri Lehtinen Date: Mon, 8 Aug 2011 20:59:10 +0300 Subject: [PATCH] doc: Explain the non-constness of the first parameter of json_unpack() et al Fixes GH-30. --- doc/apiref.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/apiref.rst b/doc/apiref.rst index 4051b38..16da5f2 100644 --- a/doc/apiref.rst +++ b/doc/apiref.rst @@ -1047,6 +1047,20 @@ The following functions compose the parsing and validation API: behaviour of the unpacker, see below for the flags. Returns 0 on success and -1 on failure. +.. note:: + + The first argument of all unpack functions is ``json_t *root`` + instead of ``const json_t *root``, because the use of ``O`` format + character causes the reference count of ``root``, or some value + reachable from ``root``, to be increased. Furthermore, the ``o`` + format character may be used to extract a value as-is, which allows + modifying the structure or contents of a value reachable from + ``root``. + + If the ``O`` and ``o`` format character are not used, it's + perfectly safe to cast a ``const json_t *`` variable to plain + ``json_t *`` when used with these functions. + The following unpacking flags are available: ``JSON_STRICT``