ctags.rb 1.0.19 → 1.1.3

data/ext/vendor/jansson-2.5/doc/Makefile.in

@@ -1,401 +0,0 @@
-# Makefile.in generated by automake 1.11.6 from Makefile.am.
-# @configure_input@
-
-# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-# 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software
-# Foundation, Inc.
-# This Makefile.in is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
-# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE.
-
-@SET_MAKE@
-VPATH = @srcdir@
-am__make_dryrun = \
-  { \
-    am__dry=no; \
-    case $$MAKEFLAGS in \
-      *\\[\ \	]*) \
-        echo 'am--echo: ; @echo "AM"  OK' | $(MAKE) -f - 2>/dev/null \
-          | grep '^AM OK$$' >/dev/null || am__dry=yes;; \
-      *) \
-        for am__flg in $$MAKEFLAGS; do \
-          case $$am__flg in \
-            *=*|--*) ;; \
-            *n*) am__dry=yes; break;; \
-          esac; \
-        done;; \
-    esac; \
-    test $$am__dry = yes; \
-  }
-pkgdatadir = $(datadir)/@PACKAGE@
-pkgincludedir = $(includedir)/@PACKAGE@
-pkglibdir = $(libdir)/@PACKAGE@
-pkglibexecdir = $(libexecdir)/@PACKAGE@
-am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
-install_sh_DATA = $(install_sh) -c -m 644
-install_sh_PROGRAM = $(install_sh) -c
-install_sh_SCRIPT = $(install_sh) -c
-INSTALL_HEADER = $(INSTALL_DATA)
-transform = $(program_transform_name)
-NORMAL_INSTALL = :
-PRE_INSTALL = :
-POST_INSTALL = :
-NORMAL_UNINSTALL = :
-PRE_UNINSTALL = :
-POST_UNINSTALL = :
-build_triplet = @build@
-host_triplet = @host@
-subdir = doc
-DIST_COMMON = README $(srcdir)/Makefile.am $(srcdir)/Makefile.in
-ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/configure.ac
-am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
-	$(ACLOCAL_M4)
-mkinstalldirs = $(install_sh) -d
-CONFIG_HEADER = $(top_builddir)/config.h
-CONFIG_CLEAN_FILES =
-CONFIG_CLEAN_VPATH_FILES =
-SOURCES =
-DIST_SOURCES =
-am__can_run_installinfo = \
-  case $$AM_UPDATE_INFO_DIR in \
-    n|no|NO) false;; \
-    *) (install-info --version) >/dev/null 2>&1;; \
-  esac
-DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
-ACLOCAL = @ACLOCAL@
-AMTAR = @AMTAR@
-AR = @AR@
-AUTOCONF = @AUTOCONF@
-AUTOHEADER = @AUTOHEADER@
-AUTOMAKE = @AUTOMAKE@
-AWK = @AWK@
-CC = @CC@
-CCDEPMODE = @CCDEPMODE@
-CFLAGS = @CFLAGS@
-CPP = @CPP@
-CPPFLAGS = @CPPFLAGS@
-CYGPATH_W = @CYGPATH_W@
-DEFS = @DEFS@
-DEPDIR = @DEPDIR@
-DLLTOOL = @DLLTOOL@
-DSYMUTIL = @DSYMUTIL@
-DUMPBIN = @DUMPBIN@
-ECHO_C = @ECHO_C@
-ECHO_N = @ECHO_N@
-ECHO_T = @ECHO_T@
-EGREP = @EGREP@
-EXEEXT = @EXEEXT@
-FGREP = @FGREP@
-GREP = @GREP@
-INSTALL = @INSTALL@
-INSTALL_DATA = @INSTALL_DATA@
-INSTALL_PROGRAM = @INSTALL_PROGRAM@
-INSTALL_SCRIPT = @INSTALL_SCRIPT@
-INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
-LD = @LD@
-LDFLAGS = @LDFLAGS@
-LIBOBJS = @LIBOBJS@
-LIBS = @LIBS@
-LIBTOOL = @LIBTOOL@
-LIPO = @LIPO@
-LN_S = @LN_S@
-LTLIBOBJS = @LTLIBOBJS@
-MAKEINFO = @MAKEINFO@
-MANIFEST_TOOL = @MANIFEST_TOOL@
-MKDIR_P = @MKDIR_P@
-NM = @NM@
-NMEDIT = @NMEDIT@
-OBJDUMP = @OBJDUMP@
-OBJEXT = @OBJEXT@
-OTOOL = @OTOOL@
-OTOOL64 = @OTOOL64@
-PACKAGE = @PACKAGE@
-PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
-PACKAGE_NAME = @PACKAGE_NAME@
-PACKAGE_STRING = @PACKAGE_STRING@
-PACKAGE_TARNAME = @PACKAGE_TARNAME@
-PACKAGE_URL = @PACKAGE_URL@
-PACKAGE_VERSION = @PACKAGE_VERSION@
-PATH_SEPARATOR = @PATH_SEPARATOR@
-RANLIB = @RANLIB@
-SED = @SED@
-SET_MAKE = @SET_MAKE@
-SHELL = @SHELL@
-STRIP = @STRIP@
-VERSION = @VERSION@
-abs_builddir = @abs_builddir@
-abs_srcdir = @abs_srcdir@
-abs_top_builddir = @abs_top_builddir@
-abs_top_srcdir = @abs_top_srcdir@
-ac_ct_AR = @ac_ct_AR@
-ac_ct_CC = @ac_ct_CC@
-ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
-am__include = @am__include@
-am__leading_dot = @am__leading_dot@
-am__quote = @am__quote@
-am__tar = @am__tar@
-am__untar = @am__untar@
-bindir = @bindir@
-build = @build@
-build_alias = @build_alias@
-build_cpu = @build_cpu@
-build_os = @build_os@
-build_vendor = @build_vendor@
-builddir = @builddir@
-datadir = @datadir@
-datarootdir = @datarootdir@
-docdir = @docdir@
-dvidir = @dvidir@
-exec_prefix = @exec_prefix@
-host = @host@
-host_alias = @host_alias@
-host_cpu = @host_cpu@
-host_os = @host_os@
-host_vendor = @host_vendor@
-htmldir = @htmldir@
-includedir = @includedir@
-infodir = @infodir@
-install_sh = @install_sh@
-json_have_localeconv = @json_have_localeconv@
-json_have_long_long = @json_have_long_long@
-json_inline = @json_inline@
-libdir = @libdir@
-libexecdir = @libexecdir@
-localedir = @localedir@
-localstatedir = @localstatedir@
-mandir = @mandir@
-mkdir_p = @mkdir_p@
-oldincludedir = @oldincludedir@
-pdfdir = @pdfdir@
-prefix = @prefix@
-program_transform_name = @program_transform_name@
-psdir = @psdir@
-sbindir = @sbindir@
-sharedstatedir = @sharedstatedir@
-srcdir = @srcdir@
-sysconfdir = @sysconfdir@
-target_alias = @target_alias@
-top_build_prefix = @top_build_prefix@
-top_builddir = @top_builddir@
-top_srcdir = @top_srcdir@
-EXTRA_DIST = conf.py apiref.rst changes.rst conformance.rst		\
-	gettingstarted.rst github_commits.c index.rst portability.rst	\
-	tutorial.rst upgrading.rst ext/refcounting.py
-
-SPHINXBUILD = sphinx-build
-SPHINXOPTS = -d _build/doctrees $(SPHINXOPTS_EXTRA)
-all: all-am
-
-.SUFFIXES:
-$(srcdir)/Makefile.in:  $(srcdir)/Makefile.am  $(am__configure_deps)
-	@for dep in $?; do \
-	  case '$(am__configure_deps)' in \
-	    *$$dep*) \
-	      ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
-	        && { if test -f $@; then exit 0; else break; fi; }; \
-	      exit 1;; \
-	  esac; \
-	done; \
-	echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \
-	$(am__cd) $(top_srcdir) && \
-	  $(AUTOMAKE) --foreign doc/Makefile
-.PRECIOUS: Makefile
-Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
-	@case '$?' in \
-	  *config.status*) \
-	    cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
-	  *) \
-	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
-	    cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
-	esac;
-
-$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
-	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
-
-$(top_srcdir)/configure:  $(am__configure_deps)
-	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
-$(ACLOCAL_M4):  $(am__aclocal_m4_deps)
-	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
-$(am__aclocal_m4_deps):
-
-mostlyclean-libtool:
-	-rm -f *.lo
-
-clean-libtool:
-	-rm -rf .libs _libs
-tags: TAGS
-TAGS:
-
-ctags: CTAGS
-CTAGS:
-
-
-distdir: $(DISTFILES)
-	@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
-	topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
-	list='$(DISTFILES)'; \
-	  dist_files=`for file in $$list; do echo $$file; done | \
-	  sed -e "s|^$$srcdirstrip/||;t" \
-	      -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
-	case $$dist_files in \
-	  */*) $(MKDIR_P) `echo "$$dist_files" | \
-			   sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
-			   sort -u` ;; \
-	esac; \
-	for file in $$dist_files; do \
-	  if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
-	  if test -d $$d/$$file; then \
-	    dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
-	    if test -d "$(distdir)/$$file"; then \
-	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
-	    fi; \
-	    if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
-	      cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
-	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
-	    fi; \
-	    cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
-	  else \
-	    test -f "$(distdir)/$$file" \
-	    || cp -p $$d/$$file "$(distdir)/$$file" \
-	    || exit 1; \
-	  fi; \
-	done
-check-am: all-am
-check: check-am
-all-am: Makefile
-installdirs:
-install: install-am
-install-exec: install-exec-am
-install-data: install-data-am
-uninstall: uninstall-am
-
-install-am: all-am
-	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
-
-installcheck: installcheck-am
-install-strip:
-	if test -z '$(STRIP)'; then \
-	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
-	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
-	      install; \
-	else \
-	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
-	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
-	    "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
-	fi
-mostlyclean-generic:
-
-clean-generic:
-
-distclean-generic:
-	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-	-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
-
-maintainer-clean-generic:
-	@echo "This command is intended for maintainers to use"
-	@echo "it deletes files that may require special tools to rebuild."
-clean: clean-am
-
-clean-am: clean-generic clean-libtool clean-local mostlyclean-am
-
-distclean: distclean-am
-	-rm -f Makefile
-distclean-am: clean-am distclean-generic
-
-dvi: dvi-am
-
-dvi-am:
-
-html: html-am
-
-html-am: html-local
-
-info: info-am
-
-info-am:
-
-install-data-am:
-
-install-dvi: install-dvi-am
-
-install-dvi-am:
-
-install-exec-am:
-
-install-html: install-html-am
-
-install-html-am: install-html-local
-
-install-info: install-info-am
-
-install-info-am:
-
-install-man:
-
-install-pdf: install-pdf-am
-
-install-pdf-am:
-
-install-ps: install-ps-am
-
-install-ps-am:
-
-installcheck-am:
-
-maintainer-clean: maintainer-clean-am
-	-rm -f Makefile
-maintainer-clean-am: distclean-am maintainer-clean-generic
-
-mostlyclean: mostlyclean-am
-
-mostlyclean-am: mostlyclean-generic mostlyclean-libtool
-
-pdf: pdf-am
-
-pdf-am:
-
-ps: ps-am
-
-ps-am:
-
-uninstall-am: uninstall-local
-
-.MAKE: install-am install-strip
-
-.PHONY: all all-am check check-am clean clean-generic clean-libtool \
-	clean-local distclean distclean-generic distclean-libtool \
-	distdir dvi dvi-am html html-am html-local info info-am \
-	install install-am install-data install-data-am install-dvi \
-	install-dvi-am install-exec install-exec-am install-html \
-	install-html-am install-html-local install-info \
-	install-info-am install-man install-pdf install-pdf-am \
-	install-ps install-ps-am install-strip installcheck \
-	installcheck-am installdirs maintainer-clean \
-	maintainer-clean-generic mostlyclean mostlyclean-generic \
-	mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am \
-	uninstall-local
-
-
-html-local:
-	$(SPHINXBUILD) -b html $(SPHINXOPTS) $(srcdir) _build/html
-
-install-html-local: html
-	mkdir -p $(DESTDIR)$(htmldir)
-	cp -r _build/html $(DESTDIR)$(htmldir)
-
-uninstall-local:
-	rm -rf $(DESTDIR)$(htmldir)
-
-clean-local:
-	rm -rf _build
-	rm -f ext/refcounting.pyc
-
-# Tell versions [3.59,3.63) of GNU make to not export all variables.
-# Otherwise a system limit (for SysV at least) may be exceeded.
-.NOEXPORT:

data/ext/vendor/jansson-2.5/doc/apiref.rst

@@ -1,1487 +0,0 @@
-.. _apiref:
-
-*************
-API Reference
-*************
-
-.. highlight:: c
-
-Preliminaries
-=============
-
-All declarations are in :file:`jansson.h`, so it's enough to
-
-::
-
-   #include <jansson.h>
-
-in each source file.
-
-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_MAJOR_VERSION``, ``JANSSON_MINOR_VERSION``, ``JANSSON_MICRO_VERSION``
-  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
-====================
-
-The JSON specification (:rfc:`4627`) defines the following data types:
-*object*, *array*, *string*, *number*, *boolean*, and *null*. JSON
-types are used dynamically; arrays and objects can hold any other data
-type, including themselves. For this reason, Jansson's type system is
-also dynamic in nature. There's one C type to represent all JSON
-values, and this structure knows the type of the JSON value it holds.
-
-.. type:: json_t
-
-  This data structure is used throughout the library to represent all
-  JSON values. It always contains the type of the JSON value it holds
-  and the value's reference count. The rest depends on the type of the
-  value.
-
-Objects of :type:`json_t` are always used through a pointer. There
-are APIs for querying the type, manipulating the reference count, and
-for constructing and manipulating values of different types.
-
-Unless noted otherwise, all API functions return an error value if an
-error occurs. Depending on the function's signature, the error value
-is either *NULL* or -1. Invalid arguments or invalid input are
-apparent sources for errors. Memory allocation and I/O operations may
-also cause errors.
-
-
-Type
-----
-
-The type of a JSON value is queried and tested using the following
-functions:
-
-.. type:: enum json_type
-
-   The type of a JSON value. The following members are defined:
-
-   +--------------------+
-   | ``JSON_OBJECT``    |
-   +--------------------+
-   | ``JSON_ARRAY``     |
-   +--------------------+
-   | ``JSON_STRING``    |
-   +--------------------+
-   | ``JSON_INTEGER``   |
-   +--------------------+
-   | ``JSON_REAL``      |
-   +--------------------+
-   | ``JSON_TRUE``      |
-   +--------------------+
-   | ``JSON_FALSE``     |
-   +--------------------+
-   | ``JSON_NULL``      |
-   +--------------------+
-
-   These correspond to JSON object, array, string, number, boolean and
-   null. A number is represented by either a value of the type
-   ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value
-   is represented by a value of the type ``JSON_TRUE`` and false by a
-   value of the type ``JSON_FALSE``.
-
-.. function:: int json_typeof(const json_t *json)
-
-   Return the type of the JSON value (a :type:`json_type` cast to
-   :type:`int`). *json* MUST NOT be *NULL*. This function is actually
-   implemented as a macro for speed.
-
-.. function:: json_is_object(const json_t *json)
-               json_is_array(const json_t *json)
-               json_is_string(const json_t *json)
-               json_is_integer(const json_t *json)
-               json_is_real(const json_t *json)
-               json_is_true(const json_t *json)
-               json_is_false(const json_t *json)
-               json_is_null(const json_t *json)
-
-   These functions (actually macros) return true (non-zero) for values
-   of the given type, and false (zero) for values of other types and
-   for *NULL*.
-
-.. function:: json_is_number(const json_t *json)
-
-   Returns true for values of types ``JSON_INTEGER`` and
-   ``JSON_REAL``, and false for other types and for *NULL*.
-
-.. function:: json_is_boolean(const json_t *json)
-
-   Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
-   for values of other types and for *NULL*.
-
-
-.. _apiref-reference-count:
-
-Reference Count
----------------
-
-The reference count is used to track whether a value is still in use
-or not. When a value is created, it's reference count is set to 1. If
-a reference to a value is kept (e.g. a value is stored somewhere for
-later use), its reference count is incremented, and when the value is
-no longer needed, the reference count is decremented. When the
-reference count drops to zero, there are no references left, and the
-value can be destroyed.
-
-The following functions are used to manipulate the reference count.
-
-.. function:: json_t *json_incref(json_t *json)
-
-   Increment the reference count of *json* if it's not *NULL*.
-   Returns *json*.
-
-.. function:: void json_decref(json_t *json)
-
-   Decrement the reference count of *json*. As soon as a call to
-   :func:`json_decref()` drops the reference count to zero, the value
-   is destroyed and it can no longer be used.
-
-Functions creating new JSON values set the reference count to 1. These
-functions are said to return a **new reference**. Other functions
-returning (existing) JSON values do not normally increase the
-reference count. These functions are said to return a **borrowed
-reference**. So, if the user will hold a reference to a value returned
-as a borrowed reference, he must call :func:`json_incref`. As soon as
-the value is no longer needed, :func:`json_decref` should be called
-to release the reference.
-
-Normally, all functions accepting a JSON value as an argument will
-manage the reference, i.e. increase and decrease the reference count
-as needed. However, some functions **steal** the reference, i.e. they
-have the same result as if the user called :func:`json_decref()` on
-the argument right after calling the function. These functions are
-suffixed with ``_new`` or have ``_new_`` somewhere in their name.
-
-For example, the following code creates a new JSON array and appends
-an integer to it::
-
-  json_t *array, *integer;
-
-  array = json_array();
-  integer = json_integer(42);
-
-  json_array_append(array, integer);
-  json_decref(integer);
-
-Note how the caller has to release the reference to the integer value
-by calling :func:`json_decref()`. By using a reference stealing
-function :func:`json_array_append_new()` instead of
-:func:`json_array_append()`, the code becomes much simpler::
-
-  json_t *array = json_array();
-  json_array_append_new(array, json_integer(42));
-
-In this case, the user doesn't have to explicitly release the
-reference to the integer value, as :func:`json_array_append_new()`
-steals the reference when appending the value to the array.
-
-In the following sections it is clearly documented whether a function
-will return a new or borrowed reference or steal a reference to its
-argument.
-
-
-Circular References
--------------------
-
-A circular reference is created when an object or an array is,
-directly or indirectly, inserted inside itself. The direct case is
-simple::
-
-  json_t *obj = json_object();
-  json_object_set(obj, "foo", obj);
-
-Jansson will refuse to do this, and :func:`json_object_set()` (and
-all the other such functions for objects and arrays) will return with
-an error status. The indirect case is the dangerous one::
-
-  json_t *arr1 = json_array(), *arr2 = json_array();
-  json_array_append(arr1, arr2);
-  json_array_append(arr2, arr1);
-
-In this example, the array ``arr2`` is contained in the array
-``arr1``, and vice versa. Jansson cannot check for this kind of
-indirect circular references without a performance hit, so it's up to
-the user to avoid them.
-
-If a circular reference is created, the memory consumed by the values
-cannot be freed by :func:`json_decref()`. The reference counts never
-drops to zero because the values are keeping the references to each
-other. Moreover, trying to encode the values with any of the encoding
-functions will fail. The encoder detects circular references and
-returns an error status.
-
-
-True, False and Null
-====================
-
-These three values are implemented as singletons, so the returned
-pointers won't change between invocations of these functions.
-
-.. function:: json_t *json_true(void)
-
-   .. refcounting:: new
-
-   Returns the JSON true value.
-
-.. function:: json_t *json_false(void)
-
-   .. refcounting:: new
-
-   Returns the JSON false value.
-
-.. function:: json_t *json_boolean(val)
-
-   .. refcounting:: new
-
-   Returns JSON false if ``val`` is zero, and JSON true otherwise.
-   This is a macro, and equivalent to ``val ? json_true() :
-   json_false()``.
-
-   .. versionadded:: 2.4
-
-
-.. function:: json_t *json_null(void)
-
-   .. refcounting:: new
-
-   Returns the JSON null value.
-
-
-String
-======
-
-Jansson uses UTF-8 as the character encoding. All JSON strings must be
-valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null
-terminated C strings are used, so JSON strings may not contain
-embedded null characters. All other Unicode codepoints U+0001 through
-U+10FFFF are allowed.
-
-.. function:: json_t *json_string(const char *value)
-
-   .. refcounting:: new
-
-   Returns a new JSON string, or *NULL* on error. *value* must be a
-   valid UTF-8 encoded Unicode string.
-
-.. function:: json_t *json_string_nocheck(const char *value)
-
-   .. refcounting:: new
-
-   Like :func:`json_string`, but doesn't check that *value* is valid
-   UTF-8. Use this function only if you are certain that this really
-   is the case (e.g. you have already checked it by other means).
-
-.. function:: const char *json_string_value(const json_t *string)
-
-   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
-   valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
-   error.
-
-.. function:: int json_string_set_nocheck(const json_t *string, const char *value)
-
-   Like :func:`json_string_set`, but doesn't check that *value* is
-   valid UTF-8. Use this function only if you are certain that this
-   really is the case (e.g. you have already checked it by other
-   means).
-
-
-Number
-======
-
-The JSON specification only contains one numeric type, "number". The C
-programming language has distinct types for integer and floating-point
-numbers, so for practical reasons Jansson also has distinct types for
-the two. They are called "integer" and "real", respectively. For more
-information, see :ref:`rfc-conformance`.
-
-.. type:: json_int_t
-
-   This is the C type that is used to store JSON integer values. It
-   represents the widest integer type available on your system. In
-   practice it's just a typedef of ``long long`` if your compiler
-   supports it, otherwise ``long``.
-
-   Usually, you can safely use plain ``int`` in place of
-   ``json_int_t``, and the implicit C integer conversion handles the
-   rest. Only when you know that you need the full 64-bit range, you
-   should use ``json_int_t`` explicitly.
-
-``JSON_INTEGER_IS_LONG_LONG``
-   This is a preprocessor variable that holds the value 1 if
-   :type:`json_int_t` is ``long long``, and 0 if it's ``long``. It
-   can be used as follows::
-
-       #if JSON_INTEGER_IS_LONG_LONG
-       /* Code specific for long long */
-       #else
-       /* Code specific for long */
-       #endif
-
-``JSON_INTEGER_FORMAT``
-   This is a macro that expands to a :func:`printf()` conversion
-   specifier that corresponds to :type:`json_int_t`, without the
-   leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro
-   is required because the actual type of :type:`json_int_t` can be
-   either ``long`` or ``long long``, and :func:`printf()` reuiqres
-   different length modifiers for the two.
-
-   Example::
-
-       json_int_t x = 123123123;
-       printf("x is %" JSON_INTEGER_FORMAT "\n", x);
-
-
-.. function:: json_t *json_integer(json_int_t value)
-
-   .. refcounting:: new
-
-   Returns a new JSON integer, or *NULL* on error.
-
-.. function:: json_int_t json_integer_value(const json_t *integer)
-
-   Returns the associated value of *integer*, or 0 if *json* is not a
-   JSON integer.
-
-.. function:: int json_integer_set(const json_t *integer, json_int_t value)
-
-   Sets the associated value of *integer* to *value*. Returns 0 on
-   success and -1 if *integer* is not a JSON integer.
-
-.. function:: json_t *json_real(double value)
-
-   .. refcounting:: new
-
-   Returns a new JSON real, or *NULL* on error.
-
-.. function:: double json_real_value(const json_t *real)
-
-   Returns the associated value of *real*, or 0.0 if *real* is not a
-   JSON real.
-
-.. function:: int json_real_set(const json_t *real, double value)
-
-   Sets the associated value of *real* to *value*. Returns 0 on
-   success and -1 if *real* is not a JSON real.
-
-In addition to the functions above, there's a common query function
-for integers and reals:
-
-.. function:: double json_number_value(const json_t *json)
-
-   Returns the associated value of the JSON integer or JSON real
-   *json*, cast to double regardless of the actual type. If *json* is
-   neither JSON real nor JSON integer, 0.0 is returned.
-
-
-Array
-=====
-
-A JSON array is an ordered collection of other JSON values.
-
-.. function:: json_t *json_array(void)
-
-   .. refcounting:: new
-
-   Returns a new JSON array, or *NULL* on error. Initially, the array
-   is empty.
-
-.. function:: size_t json_array_size(const json_t *array)
-
-   Returns the number of elements in *array*, or 0 if *array* is NULL
-   or not a JSON array.
-
-.. function:: json_t *json_array_get(const json_t *array, size_t index)
-
-   .. refcounting:: borrow
-
-   Returns the element in *array* at position *index*. The valid range
-   for *index* is from 0 to the return value of
-   :func:`json_array_size()` minus 1. If *array* is not a JSON array,
-   if *array* is *NULL*, or if *index* is out of range, *NULL* is
-   returned.
-
-.. function:: int json_array_set(json_t *array, size_t index, json_t *value)
-
-   Replaces the element in *array* at position *index* with *value*.
-   The valid range for *index* is from 0 to the return value of
-   :func:`json_array_size()` minus 1. Returns 0 on success and -1 on
-   error.
-
-.. function:: int json_array_set_new(json_t *array, size_t index, json_t *value)
-
-   Like :func:`json_array_set()` but steals the reference to *value*.
-   This is useful when *value* is newly created and not used after
-   the call.
-
-.. function:: int json_array_append(json_t *array, json_t *value)
-
-   Appends *value* to the end of *array*, growing the size of *array*
-   by 1. Returns 0 on success and -1 on error.
-
-.. function:: int json_array_append_new(json_t *array, json_t *value)
-
-   Like :func:`json_array_append()` but steals the reference to
-   *value*. This is useful when *value* is newly created and not used
-   after the call.
-
-.. function:: int json_array_insert(json_t *array, size_t index, json_t *value)
-
-   Inserts *value* to *array* at position *index*, shifting the
-   elements at *index* and after it one position towards the end of
-   the array. Returns 0 on success and -1 on error.
-
-.. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value)
-
-   Like :func:`json_array_insert()` but steals the reference to
-   *value*. This is useful when *value* is newly created and not used
-   after the call.
-
-.. function:: int json_array_remove(json_t *array, size_t index)
-
-   Removes the element in *array* at position *index*, shifting the
-   elements after *index* one position towards the start of the array.
-   Returns 0 on success and -1 on error. The reference count of the
-   removed value is decremented.
-
-.. function:: int json_array_clear(json_t *array)
-
-   Removes all elements from *array*. Returns 0 on sucess and -1 on
-   error. The reference count of all removed values are decremented.
-
-.. function:: int json_array_extend(json_t *array, json_t *other_array)
-
-   Appends all elements in *other_array* to the end of *array*.
-   Returns 0 on success and -1 on error.
-
-The following macro can be used to iterate through all elements
-in an array.
-
-.. function:: json_array_foreach(array, index, value)
-
-   Iterate over every element of ``array``, running the block
-   of code that follows each time with the proper values set to
-   variables ``index`` and ``value``, of types :type:`size_t` and
-   :type:`json_t *` respectively. Example::
-
-       /* array is a JSON array */
-       size_t index;
-       json_t *value;
-
-       json_array_foreach(array, index, value) {
-           /* block of code that uses index and value */
-       }
-
-   The items are returned in increasing index order.
-
-   This macro expands to an ordinary ``for`` statement upon
-   preprocessing, so its performance is equivalent to that of
-   hand-written code using the array access functions.
-   The main advantage of this macro is that it abstracts
-   away the complexity, and makes for shorter, more
-   concise code.
-
-   .. versionadded:: 2.5
-
-
-Object
-======
-
-A JSON object is a dictionary of key-value pairs, where the key is a
-Unicode string and the value is any JSON value.
-
-.. function:: json_t *json_object(void)
-
-   .. refcounting:: new
-
-   Returns a new JSON object, or *NULL* on error. Initially, the
-   object is empty.
-
-.. function:: size_t json_object_size(const json_t *object)
-
-   Returns the number of elements in *object*, or 0 if *object* is not
-   a JSON object.
-
-.. function:: json_t *json_object_get(const json_t *object, const char *key)
-
-   .. refcounting:: borrow
-
-   Get a value corresponding to *key* from *object*. Returns *NULL* if
-   *key* is not found and on error.
-
-.. function:: int json_object_set(json_t *object, const char *key, json_t *value)
-
-   Set the value of *key* to *value* in *object*. *key* must be a
-   valid null terminated UTF-8 encoded Unicode string. If there
-   already is a value for *key*, it is replaced by the new value.
-   Returns 0 on success and -1 on error.
-
-.. function:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value)
-
-   Like :func:`json_object_set`, but doesn't check that *key* is
-   valid UTF-8. Use this function only if you are certain that this
-   really is the case (e.g. you have already checked it by other
-   means).
-
-.. function:: int json_object_set_new(json_t *object, const char *key, json_t *value)
-
-   Like :func:`json_object_set()` but steals the reference to
-   *value*. This is useful when *value* is newly created and not used
-   after the call.
-
-.. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
-
-   Like :func:`json_object_set_new`, but doesn't check that *key* is
-   valid UTF-8. Use this function only if you are certain that this
-   really is the case (e.g. you have already checked it by other
-   means).
-
-.. function:: int json_object_del(json_t *object, const char *key)
-
-   Delete *key* from *object* if it exists. Returns 0 on success, or
-   -1 if *key* was not found. The reference count of the removed value
-   is decremented.
-
-.. function:: int json_object_clear(json_t *object)
-
-   Remove all elements from *object*. Returns 0 on success and -1 if
-   *object* is not a JSON object. The reference count of all removed
-   values are decremented.
-
-.. function:: int json_object_update(json_t *object, json_t *other)
-
-   Update *object* with the key-value pairs from *other*, overwriting
-   existing keys. Returns 0 on success or -1 on error.
-
-.. function:: int json_object_update_existing(json_t *object, json_t *other)
-
-   Like :func:`json_object_update()`, but only the values of existing
-   keys are updated. No new keys are created. Returns 0 on success or
-   -1 on error.
-
-   .. versionadded:: 2.3
-
-.. function:: int json_object_update_missing(json_t *object, json_t *other)
-
-   Like :func:`json_object_update()`, but only new keys are created.
-   The value of any existing key is not changed. Returns 0 on success
-   or -1 on error.
-
-   .. versionadded:: 2.3
-
-The following macro can be used to iterate through all key-value pairs
-in an object.
-
-.. function:: json_object_foreach(object, key, value)
-
-   Iterate over every key-value pair of ``object``, running the block
-   of code that follows each time with the proper values set to
-   variables ``key`` and ``value``, of types :type:`const char *` and
-   :type:`json_t *` respectively. Example::
-
-       /* obj is a JSON object */
-       const char *key;
-       json_t *value;
-
-       json_object_foreach(obj, key, value) {
-           /* block of code that uses key and value */
-       }
-
-   The items are not returned in any particular order.
-
-   This macro expands to an ordinary ``for`` statement upon
-   preprocessing, so its performance is equivalent to that of
-   hand-written iteration code using the object iteration protocol
-   (see below). The main advantage of this macro is that it abstracts
-   away the complexity behind iteration, and makes for shorter, more
-   concise code.
-
-   .. versionadded:: 2.3
-
-
-The following functions implement an iteration protocol for objects,
-allowing to iterate through all key-value pairs in an object. The
-items are not returned in any particular order, as this would require
-sorting due to the internal hashtable implementation.
-
-.. function:: void *json_object_iter(json_t *object)
-
-   Returns an opaque iterator which can be used to iterate over all
-   key-value pairs in *object*, or *NULL* if *object* is empty.
-
-.. function:: void *json_object_iter_at(json_t *object, const char *key)
-
-   Like :func:`json_object_iter()`, but returns an iterator to the
-   key-value pair in *object* whose key is equal to *key*, or NULL if
-   *key* is not found in *object*. Iterating forward to the end of
-   *object* only yields all key-value pairs of the object if *key*
-   happens to be the first key in the underlying hash table.
-
-.. function:: void *json_object_iter_next(json_t *object, void *iter)
-
-   Returns an iterator pointing to the next key-value pair in *object*
-   after *iter*, or *NULL* if the whole object has been iterated
-   through.
-
-.. function:: const char *json_object_iter_key(void *iter)
-
-   Extract the associated key from *iter*.
-
-.. function:: json_t *json_object_iter_value(void *iter)
-
-   .. refcounting:: borrow
-
-   Extract the associated value from *iter*.
-
-.. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value)
-
-   Set the value of the key-value pair in *object*, that is pointed to
-   by *iter*, to *value*.
-
-.. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
-
-   Like :func:`json_object_iter_set()`, but steals the reference to
-   *value*. This is useful when *value* is newly created and not used
-   after the call.
-
-.. function:: void *json_object_key_to_iter(const char *key)
-
-   Like :func:`json_object_iter_at()`, but much faster. Only works for
-   values returned by :func:`json_object_iter_key()`. Using other keys
-   will lead to segfaults. This function is used internally to
-   implement :func:`json_object_foreach`.
-
-   .. versionadded:: 2.3
-
-The iteration protocol can be used for example as follows::
-
-   /* obj is a JSON object */
-   const char *key;
-   json_t *value;
-
-   void *iter = json_object_iter(obj);
-   while(iter)
-   {
-       key = json_object_iter_key(iter);
-       value = json_object_iter_value(iter);
-       /* use key and value ... */
-       iter = json_object_iter_next(obj, iter);
-   }
-
-
-Error reporting
-===============
-
-Jansson uses a single struct type to pass error information to the
-user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
-:ref:`apiref-unpack` for functions that pass error information using
-this struct.
-
-.. type:: json_error_t
-
-   .. member:: char text[]
-
-      The error message (in UTF-8), or an empty string if a message is
-      not available.
-
-   .. member:: char source[]
-
-      Source of the error. This can be (a part of) the file name or a
-      special identifier in angle brackers (e.g. ``<string>``).
-
-   .. member:: int line
-
-      The line number on which the error occurred.
-
-   .. member:: int column
-
-      The column on which the error occurred. Note that this is the
-      *character column*, not the byte column, i.e. a multibyte UTF-8
-      character counts as one column.
-
-   .. member:: size_t position
-
-      The position in bytes from the start of the input. This is
-      useful for debugging Unicode encoding problems.
-
-The normal use of :type:`json_error_t` is to allocate it on the stack,
-and pass a pointer to a 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 call succeeded (``json != NULL`` in the above
-example), the contents of ``error`` are generally left unspecified.
-The decoding functions write to the ``position`` member also on
-success. See :ref:`apiref-decoding` for more info.
-
-All functions also accept *NULL* as the :type:`json_error_t` pointer,
-in which case no error information is returned to the caller.
-
-
-Encoding
-========
-
-This sections describes the functions that can be used to encode
-values to JSON. By default, only objects and arrays can be encoded
-directly, since they are the only valid *root* values of a JSON text.
-To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see
-below).
-
-By default, the output has no newlines, and spaces are used between
-array and object elements for a readable output. This behavior can be
-altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags
-described below. A newline is never appended to the end of the encoded
-JSON data.
-
-Each function takes a *flags* parameter that controls some aspects of
-how the data is encoded. Its default value is 0. The following macros
-can be ORed together to obtain *flags*.
-
-``JSON_INDENT(n)``
-   Pretty-print the result, using newlines between array and object
-   items, and indenting with *n* spaces. The valid range for *n* is
-   between 0 and 31 (inclusive), other values result in an undefined
-   output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are
-   inserted between array and object items.
-
-``JSON_COMPACT``
-   This flag enables a compact representation, i.e. sets the separator
-   between array and object items to ``","`` and between object keys
-   and values to ``":"``. Without this flag, the corresponding
-   separators are ``", "`` and ``": "`` for more readable output.
-
-``JSON_ENSURE_ASCII``
-   If this flag is used, the output is guaranteed to consist only of
-   ASCII characters. This is achived by escaping all Unicode
-   characters outside the ASCII range.
-
-``JSON_SORT_KEYS``
-   If this flag is used, all the objects in output are sorted by key.
-   This is useful e.g. if two JSON texts are diffed or visually
-   compared.
-
-``JSON_PRESERVE_ORDER``
-   If this flag is used, object keys in the output are sorted into the
-   same order in which they were first inserted to the object. For
-   example, decoding a JSON text and then encoding with this flag
-   preserves the order of object keys.
-
-``JSON_ENCODE_ANY``
-   Specifying this flag makes it possible to encode any JSON value on
-   its own. Without it, only objects and arrays can be passed as the
-   *root* value to the encoding functions.
-
-   **Note:** Encoding any value may be useful in some scenarios, but
-   it's generally discouraged as it violates strict compatiblity with
-   :rfc:`4627`. If you use this flag, don't expect interoperatibility
-   with other JSON systems.
-
-   .. versionadded:: 2.1
-
-``JSON_ESCAPE_SLASH``
-   Escape the ``/`` characters in strings with ``\/``.
-
-   .. versionadded:: 2.4
-
-The following functions perform the actual JSON encoding. The result
-is in UTF-8.
-
-.. function:: char *json_dumps(const json_t *root, size_t flags)
-
-   Returns the JSON representation of *root* as a string, or *NULL* on
-   error. *flags* is described above. The return value must be freed
-   by the caller using :func:`free()`.
-
-.. function:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
-
-   Write the JSON representation of *root* to the stream *output*.
-   *flags* is described above. Returns 0 on success and -1 on error.
-   If an error occurs, something may have already been written to
-   *output*. In this case, the output is undefined and most likely not
-   valid JSON.
-
-.. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
-
-   Write the JSON representation of *root* to the file *path*. If
-   *path* already exists, it is overwritten. *flags* is described
-   above. Returns 0 on success and -1 on error.
-
-.. type:: json_dump_callback_t
-
-   A typedef for a function that's called by
-   :func:`json_dump_callback()`::
-
-       typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data);
-
-   *buffer* points to a buffer containing a chunk of output, *size* is
-   the length of the buffer, and *data* is the corresponding
-   :func:`json_dump_callback()` argument passed through.
-
-   On error, the function should return -1 to stop the encoding
-   process. On success, it should return 0.
-
-   .. versionadded:: 2.2
-
-.. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags)
-
-   Call *callback* repeatedly, passing a chunk of the JSON
-   representation of *root* each time. *flags* is described above.
-   Returns 0 on success and -1 on error.
-
-   .. versionadded:: 2.2
-
-
-.. _apiref-decoding:
-
-Decoding
-========
-
-This sections describes the functions that can be used to decode JSON
-text to the Jansson representation of JSON data. The JSON
-specification requires that a JSON text is either a serialized array
-or object, and this requirement is also enforced with the following
-functions. In other words, the top level value in the JSON text being
-decoded must be either array or object. To decode any JSON value, use
-the ``JSON_DECODE_ANY`` flag (see below).
-
-See :ref:`rfc-conformance` for a discussion on Jansson's conformance
-to the JSON specification. It explains many design decisions that
-affect especially the behavior of the decoder.
-
-Each function takes a *flags* parameter that can be used to control
-the behavior of the decoder. Its default value is 0. The following
-macros can be ORed together to obtain *flags*.
-
-``JSON_REJECT_DUPLICATES``
-   Issue a decoding error if any JSON object in the input text
-   contains duplicate keys. Without this flag, the value of the last
-   occurence of each key ends up in the result. Key equivalence is
-   checked byte-by-byte, without special Unicode comparison
-   algorithms.
-
-   .. versionadded:: 2.1
-
-``JSON_DECODE_ANY``
-   By default, the decoder expects an array or object as the input.
-   With this flag enabled, the decoder accepts any valid JSON value.
-
-   **Note:** Decoding any value may be useful in some scenarios, but
-   it's generally discouraged as it violates strict compatiblity with
-   :rfc:`4627`. If you use this flag, don't expect interoperatibility
-   with other JSON systems.
-
-   .. versionadded:: 2.3
-
-``JSON_DISABLE_EOF_CHECK``
-   By default, the decoder expects that its whole input constitutes a
-   valid JSON text, and issues an error if there's extra data after
-   the otherwise valid JSON input. With this flag enabled, the decoder
-   stops after decoding a valid JSON array or object, and thus allows
-   extra data after the JSON text.
-
-   Normally, reading will stop when the last ``]`` or ``}`` in the
-   JSON input is encountered. If both ``JSON_DISABLE_EOF_CHECK`` and
-   ``JSON_DECODE_ANY`` flags are used, the decoder may read one extra
-   UTF-8 code unit (up to 4 bytes of input). For example, decoding
-   ``4true`` correctly decodes the integer 4, but also reads the
-   ``t``. For this reason, if reading multiple consecutive values that
-   are not arrays or objects, they should be separated by at least one
-   whitespace character.
-
-   .. versionadded:: 2.1
-
-``JSON_DECODE_INT_AS_REAL``
-   JSON defines only one number type. Jansson distinguishes between
-   ints and reals. For more information see :ref:`real-vs-integer`.
-   With this flag enabled the decoder interprets all numbers as real
-   values. Integers that do not have an exact double representation
-   will silently result in a loss of precision. Integers that cause
-   a double overflow will cause an error.
-
-   .. versionadded:: 2.5
-
-Each function also takes an optional :type:`json_error_t` parameter
-that is filled with error information if decoding fails. It's also
-updated on success; the number of bytes of input read is written to
-its ``position`` field. This is especially useful when using
-``JSON_DISABLE_EOF_CHECK`` to read multiple consecutive JSON texts.
-
-.. versionadded:: 2.3
-   Number of bytes of input read is written to the ``position`` field
-   of the :type:`json_error_t` structure.
-
-If no error or position information is needed, you can pass *NULL*.
-
-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
-
-   Decodes the JSON string *input* and returns the array or object it
-   contains, or *NULL* on error, in which case *error* is filled with
-   information about the error. *flags* is described above.
-
-.. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)
-
-   .. refcounting:: new
-
-   Decodes the JSON string *buffer*, whose length is *buflen*, and
-   returns the array or object it contains, or *NULL* on error, in
-   which case *error* is filled with information about the error. This
-   is similar to :func:`json_loads()` except that the string doesn't
-   need to be null-terminated. *flags* is described above.
-
-   .. versionadded:: 2.1
-
-.. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
-
-   .. refcounting:: new
-
-   Decodes the JSON text in stream *input* and returns the array or
-   object it contains, or *NULL* on error, in which case *error* is
-   filled with information about the error. *flags* is described
-   above.
-
-   This function will start reading the input from whatever position
-   the input file was, without attempting to seek first. If an error
-   occurs, the file position will be left indeterminate. On success,
-   the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK``
-   flag was used. In this case, the file position will be at the first
-   character after the last ``]`` or ``}`` in the JSON input. This
-   allows calling :func:`json_loadf()` on the same ``FILE`` object
-   multiple times, if the input consists of consecutive JSON texts,
-   possibly separated by whitespace.
-
-.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
-
-   .. refcounting:: new
-
-   Decodes the JSON text in file *path* and returns the array or
-   object it contains, or *NULL* on error, in which case *error* is
-   filled with information about the error. *flags* is described
-   above.
-
-.. type:: json_load_callback_t
-
-   A typedef for a function that's called by
-   :func:`json_load_callback()` to read a chunk of input data::
-
-       typedef size_t (*json_load_callback_t)(void *buffer, size_t buflen, void *data);
-
-   *buffer* points to a buffer of *buflen* bytes, and *data* is the
-   corresponding :func:`json_load_callback()` argument passed through.
-
-   On success, the function should return the number of bytes read; a
-   returned value of 0 indicates that no data was read and that the
-   end of file has been reached. On error, the function should return
-   ``(size_t)-1`` to abort the decoding process.
-
-   .. versionadded:: 2.4
-
-.. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error)
-
-   .. refcounting:: new
-
-   Decodes the JSON text produced by repeated calls to *callback*, and
-   returns the array or object it contains, or *NULL* on error, in
-   which case *error* is filled with information about the error.
-   *data* is passed through to *callback* on each call. *flags* is
-   described above.
-
-   .. versionadded:: 2.4
-
-
-.. _apiref-pack:
-
-Building Values
-===============
-
-This section 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 strings 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 specifiers. 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 or
-arguments.
-
-``s`` (string) [const char \*]
-    Convert a NULL terminated UTF-8 string to a JSON string.
-
-``s#`` (string) [const char \*, int]
-    Convert a UTF-8 buffer of a given length to a JSON string.
-
-``+`` [const char \*]
-    Like ``s``, but concatenate to the previous string. Only valid
-    after ``s``, ``s#``, ``+`` or ``+#``.
-
-``+#`` [const char \*, int]
-    Like ``s#``, but concatenate to the previous string. Only valid
-    after ``s``, ``s#``, ``+`` or ``+#``.
-
-``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
-    stolen by the container.
-
-``O`` (any value) [json_t \*]
-    Like ``o``, but the argument's reference count is incremented.
-    This is useful if you pack into 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 specifier represent a key,
-    and must be a string (see ``s``, ``s#``, ``+`` and ``+#`` above),
-    as object keys are always strings. The second, fourth, etc. format
-    specifier 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, ...)
-
-   .. refcounting:: new
-
-   Build a new JSON value according to the format string *fmt*. For
-   each format specifier (except for ``{}[]n``), one or more arguments
-   are 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("{sisi}", "foo", 42, "bar", 7);
-
-  /* Like above, ':', ',' and whitespace are ignored */
-  json_pack("{s:i, s:i}", "foo", 42, "bar", 7);
-
-  /* Build the JSON array [[1, 2], {"cool": true}] */
-  json_pack("[[i,i],{s:b}]", 1, 2, "cool", 1);
-
-  /* Build a string from a non-NUL terminated buffer */
-  char buffer[4] = {'t', 'e', 's', 't'};
-  json_pack("s#", buffer, 4);
-
-  /* Concatentate strings together to build the JSON string "foobarbaz" */
-  json_pack("s++", "foo", "bar", "baz");
-
-
-.. _apiref-unpack:
-
-Parsing and Validating Values
-=============================
-
-This section 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 specifier ``!`` or by
-using the flag ``JSON_STRICT``. See below for details.
-
-Here's the full list of format specifiers. 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. The resulting string is extracted by using
-    :func:`json_string_value()` internally, so it exists as long as
-    there are still references to the corresponding JSON 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 specifier represent
-    a key, and must be ``s``. The corresponding argument to unpack
-    functions is read as the object key. The second fourth, etc.
-    format specifier 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.
-
-    .. 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 specifier 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 specifier
-    before the closing bracket or brace. To enable the check globally,
-    use the ``JSON_STRICT`` unpacking flag.
-
-``*``
-    This special format specifier 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 specifier 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, ...)
-
-   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.
-
-.. note::
-
-   The first argument of all unpack functions is ``json_t *root``
-   instead of ``const json_t *root``, because the use of ``O`` format
-   specifier causes the reference count of ``root``, or some value
-   reachable from ``root``, to be increased. Furthermore, the ``o``
-   format specifier 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 specifiers 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``
-    Enable the extra validation step checking that all object and
-    array items are unpacked. This is equivalent to appending the
-    format specifier ``!`` 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 */
-
-    /* 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
-========
-
-Testing for equality of two JSON values cannot, in general, be
-achieved using the ``==`` operator. Equality in the terms of the
-``==`` operator states that the two :type:`json_t` pointers point to
-exactly the same JSON value. However, two JSON values can be equal not
-only if they are exactly the same value, but also if they have equal
-"contents":
-
-* Two integer or real values are equal if their contained numeric
-  values are equal. An integer value is never equal to a real value,
-  though.
-
-* Two strings are equal if their contained UTF-8 strings are equal,
-  byte by byte. Unicode comparison algorithms are not implemented.
-
-* Two arrays are equal if they have the same number of elements and
-  each element in the first array is equal to the corresponding
-  element in the second array.
-
-* Two objects are equal if they have exactly the same keys and the
-  value for each key in the first object is equal to the value of the
-  corresponding key in the second object.
-
-* Two true, false or null values have no "contents", so they are equal
-  if their types are equal. (Because these values are singletons,
-  their equality can actually be tested with ``==``.)
-
-The following function can be used to test whether two JSON values are
-equal.
-
-.. function:: int json_equal(json_t *value1, json_t *value2)
-
-   Returns 1 if *value1* and *value2* are equal, as defined above.
-   Returns 0 if they are inequal or one or both of the pointers are
-   *NULL*.
-
-
-Copying
-=======
-
-Because of reference counting, passing JSON values around doesn't
-require copying them. But sometimes a fresh copy of a JSON value is
-needed. For example, if you need to modify an array, but still want to
-use the original afterwards, you should take a copy of it first.
-
-Jansson supports two kinds of copying: shallow and deep. There is a
-difference between these methods only for arrays and objects. Shallow
-copying only copies the first level value (array or object) and uses
-the same child values in the copied value. Deep copying makes a fresh
-copy of the child values, too. Moreover, all the child values are deep
-copied in a recursive fashion.
-
-.. function:: json_t *json_copy(json_t *value)
-
-   .. refcounting:: new
-
-   Returns a shallow copy of *value*, or *NULL* on error.
-
-.. function:: json_t *json_deep_copy(const json_t *value)
-
-   .. refcounting:: new
-
-   Returns a deep copy of *value*, or *NULL* on error.
-
-
-.. _apiref-custom-memory-allocation:
-
-Custom Memory Allocation
-========================
-
-By default, Jansson uses :func:`malloc()` and :func:`free()` for
-memory allocation. These functions can be overridden if custom
-behavior is needed.
-
-.. type:: json_malloc_t
-
-   A typedef for a function pointer with :func:`malloc()`'s
-   signature::
-
-       typedef void *(*json_malloc_t)(size_t);
-
-.. type:: json_free_t
-
-   A typedef for a function pointer with :func:`free()`'s
-   signature::
-
-       typedef void (*json_free_t)(void *);
-
-.. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn)
-
-   Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead
-   of :func:`free()`. This function has to be called before any other
-   Jansson's API functions to ensure that all memory operations use
-   the same functions.
-
-**Examples:**
-
-Circumvent problems with different CRT heaps on Windows by using
-application's :func:`malloc()` and :func:`free()`::
-
-    json_set_alloc_funcs(malloc, free);
-
-Use the `Boehm's conservative garbage collector`_ for memory
-operations::
-
-    json_set_alloc_funcs(GC_malloc, GC_free);
-
-.. _Boehm's conservative garbage collector: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
-
-Allow storing sensitive data (e.g. passwords or encryption keys) in
-JSON structures by zeroing all memory when freed::
-
-    static void *secure_malloc(size_t size)
-    {
-        /* Store the memory area size in the beginning of the block */
-        void *ptr = malloc(size + 8);
-        *((size_t *)ptr) = size;
-        return ptr + 8;
-    }
-
-    static void secure_free(void *ptr)
-    {
-        size_t size;
-
-        ptr -= 8;
-        size = *((size_t *)ptr);
-
-        guaranteed_memset(ptr, 0, size);
-        free(ptr);
-    }
-
-    int main()
-    {
-        json_set_alloc_funcs(secure_malloc, secure_free);
-        /* ... */
-    }
-
-For more information about the issues of storing sensitive data in
-memory, see
-http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html.
-The page also explains the :func:`guaranteed_memset()` function used
-in the example and gives a sample implementation for it.