# HG changeset patch # User Tomas Heran # Date 1429259452 25200 # Node ID c6a303a2f8c5ae96d55d304b0c522bf0c2e35178 # Parent 240dc166feabbed8ea70e9ae94e407612aa5c6b5 PSARC/2014/362 Jansson 19903653 Jansson - C library for working with JSON should be added to Userland diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/Makefile --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/Makefile Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,62 @@ +# +# CDDL HEADER START +# +# The contents of this file are subject to the terms of the +# Common Development and Distribution License (the "License"). +# You may not use this file except in compliance with the License. +# +# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +# or http://www.opensolaris.org/os/licensing. +# See the License for the specific language governing permissions +# and limitations under the License. +# +# When distributing Covered Code, include this CDDL HEADER in each +# file and include the License file at usr/src/OPENSOLARIS.LICENSE. +# If applicable, add the following below this CDDL HEADER, with the +# fields enclosed by brackets "[]" replaced with your own identifying +# information: Portions Copyright [yyyy] [name of copyright owner] +# +# CDDL HEADER END +# +# Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved. +# +include ../../make-rules/shared-macros.mk + +COMPONENT_NAME= jansson +COMPONENT_VERSION= 2.7 +COMPONENT_PROJECT_URL= http://www.digip.org/jansson +COMPONENT_SRC= $(COMPONENT_NAME)-$(COMPONENT_VERSION) +COMPONENT_ARCHIVE= $(COMPONENT_SRC).tar.gz +COMPONENT_ARCHIVE_HASH= \ + sha256:7905e6590fb316c0ff943df3dc6a21cd81a59cff7a6d12514054c359d04d78d7 +COMPONENT_ARCHIVE_URL= $(COMPONENT_PROJECT_URL)/releases/$(COMPONENT_ARCHIVE) +COMPONENT_BUGDB= library/jansson + +TPNO= 19403 + +include $(WS_MAKE_RULES)/prep.mk +include $(WS_MAKE_RULES)/configure.mk +include $(WS_MAKE_RULES)/ips.mk +include $(WS_MAKE_RULES)/lint-libraries.mk + +LINT_FLAGS += -I$(PROTOUSRINCDIR) + +CONFIGURE_OPTIONS += CFLAGS="$(CFLAGS)" +CONFIGURE_OPTIONS += --includedir=$(USRINCDIR)/jansson + +# The test/suites/api/check-exports uses nm and expects it to be the GNU kind. +COMPONENT_TEST_ENV += PATH=/usr/gnu/bin:$(PATH) + +ASLR_MODE = $(ASLR_ENABLE) + +# common targets +configure: $(CONFIGURE_32_and_64) + +build: $(BUILD_32_and_64) + +install: $(INSTALL_32_and_64) + +test: $(TEST_32_and_64) + + +REQUIRED_PACKAGES += system/library diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/README --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/README Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,39 @@ +# +# CDDL HEADER START +# +# The contents of this file are subject to the terms of the +# Common Development and Distribution License (the "License"). +# You may not use this file except in compliance with the License. +# +# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +# or http://www.opensolaris.org/os/licensing. +# See the License for the specific language governing permissions +# and limitations under the License. +# +# When distributing Covered Code, include this CDDL HEADER in each +# file and include the License file at usr/src/OPENSOLARIS.LICENSE. +# If applicable, add the following below this CDDL HEADER, with the +# fields enclosed by brackets "[]" replaced with your own identifying +# information: Portions Copyright [yyyy] [name of copyright owner] +# +# CDDL HEADER END +# +# Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved. +# + +The manpage and the HTML documentation is generated using Sphinx - +sphinx-doc.org. The last Oracle approved (TPNO 18268) version is 1.2.2. +The tool is not delivered as part of Solaris, so there's no way to generate +this automatically on build server(s), therefore whenever one is updating the +library, the documentation should be manually re-generated and the resulting +files added here. + +The 'html' subdirectory is added as generated. + +The jansson.3lib in 'man3lib' subdirectory needed to be manually modified after +generation so that Solaris nroff(1) is able to read it (GNU nroff is needed +otherwise). + +Because we deliver the header files to /usr/include/jansson, it's necessary to +make sure the examples in the manpage and HTML documentation are correct when +updating the library. diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_downloads/github_commits.c --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_downloads/github_commits.c Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,201 @@ +/* + * Copyright (c) 2009-2014 Petri Lehtinen + * + * Jansson is free software; you can redistribute it and/or modify + * it under the terms of the MIT license. See LICENSE for details. + */ + +#include +#include + +#include +#include + +#define BUFFER_SIZE (256 * 1024) /* 256 KB */ + +#define URL_FORMAT "https://api.github.com/repos/%s/%s/commits" +#define URL_SIZE 256 + +/* Return the offset of the first newline in text or the length of + text if there's no newline */ +static int newline_offset(const char *text) +{ + const char *newline = strchr(text, '\n'); + if(!newline) + return strlen(text); + else + return (int)(newline - text); +} + +struct write_result +{ + char *data; + int pos; +}; + +static size_t write_response(void *ptr, size_t size, size_t nmemb, void *stream) +{ + struct write_result *result = (struct write_result *)stream; + + if(result->pos + size * nmemb >= BUFFER_SIZE - 1) + { + fprintf(stderr, "error: too small buffer\n"); + return 0; + } + + memcpy(result->data + result->pos, ptr, size * nmemb); + result->pos += size * nmemb; + + return size * nmemb; +} + +static char *request(const char *url) +{ + CURL *curl = NULL; + CURLcode status; + struct curl_slist *headers = NULL; + char *data = NULL; + long code; + + curl_global_init(CURL_GLOBAL_ALL); + curl = curl_easy_init(); + if(!curl) + goto error; + + data = malloc(BUFFER_SIZE); + if(!data) + goto error; + + struct write_result write_result = { + .data = data, + .pos = 0 + }; + + curl_easy_setopt(curl, CURLOPT_URL, url); + + /* GitHub commits API v3 requires a User-Agent header */ + headers = curl_slist_append(headers, "User-Agent: Jansson-Tutorial"); + curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); + + curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_response); + curl_easy_setopt(curl, CURLOPT_WRITEDATA, &write_result); + + status = curl_easy_perform(curl); + if(status != 0) + { + fprintf(stderr, "error: unable to request data from %s:\n", url); + fprintf(stderr, "%s\n", curl_easy_strerror(status)); + goto error; + } + + curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &code); + if(code != 200) + { + fprintf(stderr, "error: server responded with code %ld\n", code); + goto error; + } + + curl_easy_cleanup(curl); + curl_slist_free_all(headers); + curl_global_cleanup(); + + /* zero-terminate the result */ + data[write_result.pos] = '\0'; + + return data; + +error: + if(data) + free(data); + if(curl) + curl_easy_cleanup(curl); + if(headers) + curl_slist_free_all(headers); + curl_global_cleanup(); + return NULL; +} + +int main(int argc, char *argv[]) +{ + size_t i; + char *text; + char url[URL_SIZE]; + + json_t *root; + json_error_t error; + + if(argc != 3) + { + fprintf(stderr, "usage: %s USER REPOSITORY\n\n", argv[0]); + fprintf(stderr, "List commits at USER's REPOSITORY.\n\n"); + return 2; + } + + snprintf(url, URL_SIZE, URL_FORMAT, argv[1], argv[2]); + + text = request(url); + if(!text) + return 1; + + root = json_loads(text, 0, &error); + free(text); + + if(!root) + { + fprintf(stderr, "error: on line %d: %s\n", error.line, error.text); + return 1; + } + + if(!json_is_array(root)) + { + fprintf(stderr, "error: root is not an array\n"); + json_decref(root); + return 1; + } + + for(i = 0; i < json_array_size(root); i++) + { + json_t *data, *sha, *commit, *message; + const char *message_text; + + data = json_array_get(root, i); + if(!json_is_object(data)) + { + fprintf(stderr, "error: commit data %d is not an object\n", (int)(i + 1)); + json_decref(root); + return 1; + } + + sha = json_object_get(data, "sha"); + if(!json_is_string(sha)) + { + fprintf(stderr, "error: commit %d: sha is not a string\n", (int)(i + 1)); + return 1; + } + + commit = json_object_get(data, "commit"); + if(!json_is_object(commit)) + { + fprintf(stderr, "error: commit %d: commit is not an object\n", (int)(i + 1)); + json_decref(root); + return 1; + } + + message = json_object_get(commit, "message"); + if(!json_is_string(message)) + { + fprintf(stderr, "error: commit %d: message is not a string\n", (int)(i + 1)); + json_decref(root); + return 1; + } + + message_text = json_string_value(message); + printf("%.8s %.*s\n", + json_string_value(sha), + newline_offset(message_text), + message_text); + } + + json_decref(root); + return 0; +} diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/apiref.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/apiref.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,1602 @@ +.. _apiref: + +************* +API Reference +************* + +.. highlight:: c + +Preliminaries +============= + +All declarations are in :file:`jansson.h`, so it's enough to + +:: + + #include + +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*. + +.. function:: json_boolean_value(const json_t *json) + + Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE`` + and 0 otherwise. + + .. versionadded:: 2.7 + + +.. _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). All Unicode +codepoints U+0000 through U+10FFFF are allowed, but you must use +length-aware functions if you wish to embed NUL bytes in strings. + +.. function:: json_t *json_string(const char *value) + + .. refcounting:: new + + Returns a new JSON string, or *NULL* on error. *value* must be a + valid null terminated UTF-8 encoded Unicode string. + +.. function:: json_t *json_stringn(const char *value, size_t len) + + .. refcounting:: new + + Like :func:`json_string`, but with explicit length, so *value* may + contain null characters or not be null terminated. + +.. 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:: json_t *json_stringn_nocheck(const char *value, size_t len) + + .. refcounting:: new + + Like :func:`json_string_nocheck`, but with explicit length, so + *value* may contain null characters or not be null terminated. + +.. 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:: size_t json_string_length(const json_t *string) + + Returns the length of *string* in its UTF-8 presentation, or zero + if *string* is not a JSON string. + +.. 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_setn(json_t *string, const char *value, size_t len) + + Like :func:`json_string_set`, but with explicit length, so *value* + may contain null characters or not be null terminated. + +.. 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). + +.. function:: int json_string_setn_nocheck(json_t *string, const char *value, size_t len) + + Like :func:`json_string_set_nocheck`, but with explicit length, + so *value* may contain null characters or not be null terminated. + + +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. + +Even though NUL bytes are allowed in string values, they are not +allowed in object keys. + +.. 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); + } + +.. function:: void json_object_seed(size_t seed) + + Seed the hash function used in Jansson's hashtable implementation. + The seed is used to randomize the hash function so that an + attacker cannot control its output. + + If *seed* is 0, Jansson generates the seed itselfy by reading + random data from the operating system's entropy sources. If no + entropy sources are available, falls back to using a combination + of the current timestamp (with microsecond precision if possible) + and the process ID. + + If called at all, this function must be called before any calls to + :func:`json_object()`, either explicit or implicit. If this + function is not called by the user, the first call to + :func:`json_object()` (either explicit or implicit) seeds the hash + function. See :ref:`portability-thread-safety` for notes on thread + safety. + + If repeatable results are required, for e.g. unit tests, the hash + function can be "unrandomized" by calling :func:`json_object_seed` + with a constant value on program startup, e.g. + ``json_object_seed(1)``. + + .. versionadded:: 2.6 + + +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. ````). + + .. 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. + + The ``JSON_MAX_INDENT`` constant defines the maximum indentation + that can be used, and its value is 31. + + .. versionchanged:: 2.7 + Added ``JSON_MAX_INDENT``. + +``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 + +``JSON_REAL_PRECISION(n)`` + Output all real numbers with at most *n* digits of precision. The + valid range for *n* is between 0 and 31 (inclusive), and other + values result in an undefined behavior. + + By default, the precision is 17, to correctly and losslessly encode + all IEEE 754 double precision floating point numbers. + + .. versionadded:: 2.7 + +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 + +``JSON_ALLOW_NUL`` + Allow ``\u0000`` escape inside string values. This is a safety + measure; If you know your input can contain NUL bytes, use this + flag. If you don't use this flag, you don't have to worry about NUL + bytes inside strings unless you explicitly create themselves by + using e.g. :func:`json_stringn()` or ``s#`` format specifier for + :func:`json_pack()`. + + Object keys cannot have embedded NUL bytes even if this flag is + used. + + .. versionadded:: 2.6 + +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. + + .. versionadded:: 2.5 + +``s%`` (string) [const char \*, size_t] + Like ``s#`` but the length argument is of type :type:`size_t`. + + .. versionadded:: 2.6 + +``+`` [const char \*] + Like ``s``, but concatenate to the previous string. Only valid + after ``s``, ``s#``, ``+`` or ``+#``. + + .. versionadded:: 2.5 + +``+#`` [const char \*, int] + Like ``s#``, but concatenate to the previous string. Only valid + after ``s``, ``s#``, ``+`` or ``+#``. + + .. versionadded:: 2.5 + +``+%`` (string) [const char \*, size_t] + Like ``+#`` but the length argument is of type :type:`size_t`. + + .. versionadded:: 2.6 + +``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 +`, 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. + +``s%`` (string) [const char \*, size_t \*] + Convert a JSON string to a pointer to a NULL terminated UTF-8 + string and its length. + + .. versionadded:: 2.6 + +``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 + 8); + 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. diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/changes.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/changes.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,5 @@ +****************** +Changes in Jansson +****************** + +.. include:: ../CHANGES diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/conformance.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/conformance.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,110 @@ +.. _rfc-conformance: + +*************** +RFC Conformance +*************** + +JSON is specified in :rfc:`4627`, *"The application/json Media Type +for JavaScript Object Notation (JSON)"*. + +Character Encoding +================== + +Jansson only supports UTF-8 encoded JSON texts. It does not support or +auto-detect any of the other encodings mentioned in the RFC, namely +UTF-16LE, UTF-16BE, UTF-32LE or UTF-32BE. Pure ASCII is supported, as +it's a subset of UTF-8. + +Strings +======= + +JSON strings are mapped to C-style null-terminated character arrays, +and UTF-8 encoding is used internally. + +All Unicode codepoints U+0000 through U+10FFFF are allowed in string +values. However, U+0000 is not allowed in object keys because of API +restrictions. + +Unicode normalization or any other transformation is never performed +on any strings (string values or object keys). When checking for +equivalence of strings or object keys, the comparison is performed +byte by byte between the original UTF-8 representations of the +strings. + +Numbers +======= + +.. _real-vs-integer: + +Real vs. Integer +---------------- + +JSON makes no distinction between real and integer numbers; Jansson +does. Real numbers are mapped to the ``double`` type and integers to +the ``json_int_t`` type, which is a typedef of ``long long`` or +``long``, depending on whether ``long long`` is supported by your +compiler or not. + +A JSON number is considered to be a real number if its lexical +representation includes one of ``e``, ``E``, or ``.``; regardless if +its actual numeric value is a true integer (e.g., all of ``1E6``, +``3.0``, ``400E-2``, and ``3.14E3`` are mathematical integers, but +will be treated as real values). With the ``JSON_DECODE_INT_AS_REAL`` +decoder flag set all numbers are interpreted as real. + +All other JSON numbers are considered integers. + +When encoding to JSON, real values are always represented +with a fractional part; e.g., the ``double`` value 3.0 will be +represented in JSON as ``3.0``, not ``3``. + +Overflow, Underflow & Precision +------------------------------- + +Real numbers whose absolute values are too small to be represented in +a C ``double`` will be silently estimated with 0.0. Thus, depending on +platform, JSON numbers very close to zero such as 1E-999 may result in +0.0. + +Real numbers whose absolute values are too large to be represented in +a C ``double`` will result in an overflow error (a JSON decoding +error). Thus, depending on platform, JSON numbers like 1E+999 or +-1E+999 may result in a parsing error. + +Likewise, integer numbers whose absolute values are too large to be +represented in the ``json_int_t`` type (see above) will result in an +overflow error (a JSON decoding error). Thus, depending on platform, +JSON numbers like 1000000000000000 may result in parsing error. + +Parsing JSON real numbers may result in a loss of precision. As long +as overflow does not occur (i.e. a total loss of precision), the +rounded approximate value is silently used. Thus the JSON number +1.000000000000000005 may, depending on platform, result in the +``double`` value 1.0. + +Signed zeros +------------ + +JSON makes no statement about what a number means; however Javascript +(ECMAscript) does state that +0.0 and -0.0 must be treated as being +distinct values, i.e. -0.0 |not-equal| 0.0. Jansson relies on the +underlying floating point library in the C environment in which it is +compiled. Therefore it is platform-dependent whether 0.0 and -0.0 will +be distinct values. Most platforms that use the IEEE 754 +floating-point standard will support signed zeros. + +Note that this only applies to floating-point; neither JSON, C, or +IEEE support the concept of signed integer zeros. + +.. |not-equal| unicode:: U+2260 + +Types +----- + +No support is provided in Jansson for any C numeric types other than +``json_int_t`` and ``double``. This excludes things such as unsigned +types, ``long double``, etc. Obviously, shorter types like ``short``, +``int``, ``long`` (if ``json_int_t`` is ``long long``) and ``float`` +are implicitly handled via the ordinary C type coercion rules (subject +to overflow semantics). Also, no support or hooks are provided for any +supplemental "bignum" type add-on packages. diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/gettingstarted.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/gettingstarted.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,227 @@ +*************** +Getting Started +*************** + +.. highlight:: c + +Compiling and Installing Jansson +================================ + +The Jansson source is available at +http://www.digip.org/jansson/releases/. + +Unix-like systems (including MinGW) +----------------------------------- + +Unpack the source tarball and change to the source directory: + +.. parsed-literal:: + + bunzip2 -c jansson-|release|.tar.bz2 | tar xf - + cd jansson-|release| + +The source uses GNU Autotools (autoconf_, automake_, libtool_), so +compiling and installing is extremely simple:: + + ./configure + make + make check + make install + +To change the destination directory (``/usr/local`` by default), use +the ``--prefix=DIR`` argument to ``./configure``. See ``./configure +--help`` for the list of all possible installation options. (There are +no options to customize the resulting Jansson binary.) + +The command ``make check`` runs the test suite distributed with +Jansson. This step is not strictly necessary, but it may find possible +problems that Jansson has on your platform. If any problems are found, +please report them. + +If you obtained the source from a Git repository (or any other source +control system), there's no ``./configure`` script as it's not kept in +version control. To create the script, the build system needs to be +bootstrapped. There are many ways to do this, but the easiest one is +to use ``autoreconf``:: + + autoreconf -vi + +This command creates the ``./configure`` script, which can then be +used as described above. + +.. _autoconf: http://www.gnu.org/software/autoconf/ +.. _automake: http://www.gnu.org/software/automake/ +.. _libtool: http://www.gnu.org/software/libtool/ + + +.. _build-cmake: + +CMake (various platforms, including Windows) +-------------------------------------------- + +Jansson can be built using CMake_. Create a build directory for an +out-of-tree build, change to that directory, and run ``cmake`` (or ``ccmake``, +``cmake-gui``, or similar) to configure the project. + +See the examples below for more detailed information. + +.. note:: In the below examples ``..`` is used as an argument for ``cmake``. + This is simply the path to the jansson project root directory. + In the example it is assumed you've created a sub-directory ``build`` + and are using that. You could use any path you want. + +.. _build-cmake-unix: + +Unix (Make files) +^^^^^^^^^^^^^^^^^ +Generating make files on unix: + +.. parsed-literal:: + + bunzip2 -c jansson-|release|.tar.bz2 | tar xf - + cd jansson-|release| + + mkdir build + cd build + cmake .. # or `ccmake ..` for a GUI. + +Then to build:: + + make + make check + make install + +Windows (Visual Studio) +^^^^^^^^^^^^^^^^^^^^^^^ +Creating Visual Studio project files from the command line: + +.. parsed-literal:: + + + cd jansson-|release| + + md build + cd build + cmake -G "Visual Studio 10" .. + +You will now have a *Visual Studio Solution* in your build directory. +To run the unit tests build the ``RUN_TESTS`` project. + +If you prefer a GUI the ``cmake`` line in the above example can +be replaced with:: + + cmake-gui .. + +For command line help (including a list of available generators) +for CMake_ simply run:: + + cmake + +To list available CMake_ settings (and what they are currently set to) +for the project, run:: + + cmake -LH .. + +Mac OSX (Xcode) +^^^^^^^^^^^^^^^ +If you prefer using Xcode instead of make files on OSX, +do the following. (Use the same steps as +for :ref:`Unix `):: + + ... + cmake -G "Xcode" .. + +Additional CMake settings +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Shared library +"""""""""""""" +By default the CMake_ project will generate build files for building the +static library. To build the shared version use:: + + ... + cmake -DJANSSON_BUILD_SHARED_LIBS=1 .. + +Changing install directory (same as autoconf --prefix) +"""""""""""""""""""""""""""""""""""""""""""""""""""""" +Just as with the autoconf_ project you can change the destination directory +for ``make install``. The equivalent for autoconfs ``./configure --prefix`` +in CMake_ is:: + + ... + cmake -DCMAKE_INSTALL_PREFIX:PATH=/some/other/path .. + make install + +.. _CMake: http://www.cmake.org + + +Android +------- + +Jansson can be built for Android platforms. Android.mk is in the +source root directory. The configuration header file is located in the +``android`` directory in the source distribution. + + +Other Systems +------------- + +On non Unix-like systems, you may be unable to run the ``./configure`` +script. In this case, follow these steps. All the files mentioned can +be found in the ``src/`` directory. + +1. Create ``jansson_config.h`` (which has some platform-specific + parameters that are normally filled in by the ``./configure`` + script). Edit ``jansson_config.h.in``, replacing all ``@variable@`` + placeholders, and rename the file to ``jansson_config.h``. + +2. Make ``jansson.h`` and ``jansson_config.h`` available to the + compiler, so that they can be found when compiling programs that + use Jansson. + +3. Compile all the ``.c`` files (in the ``src/`` directory) into a + library file. Make the library available to the compiler, as in + step 2. + + +Building the Documentation +-------------------------- + +(This subsection describes how to build the HTML documentation you are +currently reading, so it can be safely skipped.) + +Documentation is in the ``doc/`` subdirectory. It's written in +reStructuredText_ with Sphinx_ annotations. To generate the HTML +documentation, invoke:: + + make html + +and point your browser to ``doc/_build/html/index.html``. Sphinx_ 1.0 +or newer is required to generate the documentation. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _Sphinx: http://sphinx.pocoo.org/ + + +Compiling Programs that Use Jansson +=================================== + +Jansson involves one C header file, :file:`jansson.h`, so it's enough +to put the line + +:: + + #include + +in the beginning of every source file that uses Jansson. + +There's also just one library to link with, ``libjansson``. Compile and +link the program as follows:: + + cc -I /usr/include/jansson -o prog prog.c -ljansson + +Starting from version 1.2, there's also support for pkg-config_:: + + cc -o prog prog.c `pkg-config --cflags --libs jansson` + +.. _pkg-config: http://pkg-config.freedesktop.org/ diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/index.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/index.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,53 @@ +Jansson Documentation +===================== + +This is the documentation for Jansson_ |release|, last updated |today|. + +Introduction +------------ + +Jansson_ is a C library for encoding, decoding and manipulating JSON +data. Its main features and design principles are: + +- Simple and intuitive API and data model + +- Comprehensive documentation + +- No dependencies on other libraries + +- Full Unicode support (UTF-8) + +- Extensive test suite + +Jansson is licensed under the `MIT license`_; see LICENSE in the +source distribution for details. + +Jansson is used in production and its API is stable. It works on +numerous platforms, including numerous Unix like systems and Windows. +It's suitable for use on any system, including desktop, server, and +small embedded systems. + + +.. _`MIT license`: http://www.opensource.org/licenses/mit-license.php +.. _Jansson: http://www.digip.org/jansson/ + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + gettingstarted + upgrading + tutorial + conformance + portability + apiref + changes + + +Indices and Tables +================== + +* :ref:`genindex` +* :ref:`search` diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/portability.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/portability.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,83 @@ +*********** +Portability +*********** + +.. _portability-thread-safety: + +Thread safety +------------- + +Jansson is thread safe and has no mutable global state. The only +exceptions are the hash function seed and memory allocation functions, +see below. + +There's no locking performed inside Jansson's code, so a multithreaded +program must perform its own locking if JSON values are shared by +multiple threads. Jansson's reference counting semantics may make this +a bit harder than it seems, as it's possible to have a reference to a +value that's also stored inside a list or object. Modifying the +container (adding or removing values) may trigger concurrent access to +such values, as containers manage the reference count of their +contained values. Bugs involving concurrent incrementing or +decrementing of deference counts may be hard to track. + +The encoding functions (:func:`json_dumps()` and friends) track +reference loops by modifying the internal state of objects and arrays. +For this reason, encoding functions must not be run on the same JSON +values in two separate threads at the same time. As already noted +above, be especially careful if two arrays or objects share their +contained values with another array or object. + +If you want to make sure that two JSON value hierarchies do not +contain shared values, use :func:`json_deep_copy()` to make copies. + + +Hash function seed +================== + +To prevent an attacker from intentionally causing large JSON objects +with specially crafted keys to perform very slow, the hash function +used by Jansson is randomized using a seed value. The seed is +automatically generated on the first explicit or implicit call to +:func:`json_object()`, if :func:`json_object_seed()` has not been +called beforehand. + +The seed is generated by using operating system's entropy sources if +they are available (``/dev/urandom``, ``CryptGenRandom()``). The +initialization is done in as thread safe manner as possible, by using +architecture specific lockless operations if provided by the platform +or the compiler. + +If you're using threads, it's recommended to autoseed the hashtable +explicitly before spawning any threads by calling +``json_object_seed(0)`` , especially if you're unsure whether the +initialization is thread safe on your platform. + + +Memory allocation functions +=========================== + +Memory allocation functions should be set at most once, and only on +program startup. See :ref:`apiref-custom-memory-allocation`. + + +Locale +------ + +Jansson works fine under any locale. + +However, if the host program is multithreaded and uses ``setlocale()`` +to switch the locale in one thread while Jansson is currently encoding +or decoding JSON data in another thread, the result may be wrong or +the program may even crash. + +Jansson uses locale specific functions for certain string conversions +in the encoder and decoder, and then converts the locale specific +values to/from the JSON representation. This fails if the locale +changes between the string conversion and the locale-to-JSON +conversion. This can only happen in multithreaded programs that use +``setlocale()``, because ``setlocale()`` switches the locale for all +running threads, not only the thread that calls ``setlocale()``. + +If your program uses ``setlocale()`` as described above, consider +using the thread-safe ``uselocale()`` instead. diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/tutorial.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/tutorial.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,286 @@ +.. _tutorial: + +******** +Tutorial +******** + +.. highlight:: c + +In this tutorial, we create a program that fetches the latest commits +of a repository in GitHub_ over the web. `GitHub API`_ uses JSON, so +the result can be parsed using Jansson. + +To stick to the the scope of this tutorial, we will only cover the the +parts of the program related to handling JSON data. For the best user +experience, the full source code is available: +:download:`github_commits.c`. To compile it (on Unix-like systems with +gcc), use the following command:: + + gcc -o github_commits github_commits.c -ljansson -lcurl + +libcurl_ is used to communicate over the web, so it is required to +compile the program. + +The command line syntax is:: + + github_commits USER REPOSITORY + +``USER`` is a GitHub user ID and ``REPOSITORY`` is the repository +name. Please note that the GitHub API is rate limited, so if you run +the program too many times within a short period of time, the sever +starts to respond with an error. + +.. _GitHub: https://github.com/ +.. _GitHub API: http://developer.github.com/ +.. _libcurl: http://curl.haxx.se/ + + +.. _tutorial-github-commits-api: + +The GitHub Repo Commits API +=========================== + +The `GitHub Repo Commits API`_ is used by sending HTTP requests to +URLs like ``https://api.github.com/repos/USER/REPOSITORY/commits``, +where ``USER`` and ``REPOSITORY`` are the GitHub user ID and the name +of the repository whose commits are to be listed, respectively. + +GitHub responds with a JSON array of the following form: + +.. code-block:: none + + [ + { + "sha": "", + "commit": { + "message": "", + + }, + + }, + { + "sha": "", + "commit": { + "message": "", + + }, + + }, + + ] + +In our program, the HTTP request is sent using the following +function:: + + static char *request(const char *url); + +It takes the URL as a parameter, preforms a HTTP GET request, and +returns a newly allocated string that contains the response body. If +the request fails, an error message is printed to stderr and the +return value is *NULL*. For full details, refer to :download:`the code +`, as the actual implementation is not important +here. + +.. _GitHub Repo Commits API: http://developer.github.com/v3/repos/commits/ + +.. _tutorial-the-program: + +The Program +=========== + +First the includes:: + + #include + #include + +Like all the programs using Jansson, we need to include +:file:`jansson.h`. + +The following definitions are used to build the GitHub API request +URL:: + + #define URL_FORMAT "https://api.github.com/repos/%s/%s/commits" + #define URL_SIZE 256 + +The following function is used when formatting the result to find the +first newline in the commit message:: + + /* Return the offset of the first newline in text or the length of + text if there's no newline */ + static int newline_offset(const char *text) + { + const char *newline = strchr(text, '\n'); + if(!newline) + return strlen(text); + else + return (int)(newline - text); + } + +The main function follows. In the beginning, we first declare a bunch +of variables and check the command line parameters:: + + int main(int argc, char *argv[]) + { + size_t i; + char *text; + char url[URL_SIZE]; + + json_t *root; + json_error_t error; + + if(argc != 3) + { + fprintf(stderr, "usage: %s USER REPOSITORY\n\n", argv[0]); + fprintf(stderr, "List commits at USER's REPOSITORY.\n\n"); + return 2; + } + +Then we build the request URL using the user and repository names +given as command line parameters:: + + snprintf(url, URL_SIZE, URL_FORMAT, argv[1], argv[2]); + +This uses the ``URL_SIZE`` and ``URL_FORMAT`` constants defined above. +Now we're ready to actually request the JSON data over the web:: + + text = request(url); + if(!text) + return 1; + +If an error occurs, our function ``request`` prints the error and +returns *NULL*, so it's enough to just return 1 from the main +function. + +Next we'll call :func:`json_loads()` to decode the JSON text we got +as a response:: + + root = json_loads(text, 0, &error); + free(text); + + if(!root) + { + fprintf(stderr, "error: on line %d: %s\n", error.line, error.text); + return 1; + } + +We don't need the JSON text anymore, so we can free the ``text`` +variable right after decoding it. If :func:`json_loads()` fails, it +returns *NULL* and sets error information to the :type:`json_error_t` +structure given as the second parameter. In this case, our program +prints the error information out and returns 1 from the main function. + +Now we're ready to extract the data out of the decoded JSON response. +The structure of the response JSON was explained in section +:ref:`tutorial-github-commits-api`. + +We check that the returned value really is an array:: + + if(!json_is_array(root)) + { + fprintf(stderr, "error: root is not an array\n"); + json_decref(root); + return 1; + } + +Then we proceed to loop over all the commits in the array:: + + for(i = 0; i < json_array_size(root); i++) + { + json_t *data, *sha, *commit, *message; + const char *message_text; + + data = json_array_get(root, i); + if(!json_is_object(data)) + { + fprintf(stderr, "error: commit data %d is not an object\n", i + 1); + json_decref(root); + return 1; + } + ... + +The function :func:`json_array_size()` returns the size of a JSON +array. First, we again declare some variables and then extract the +i'th element of the ``root`` array using :func:`json_array_get()`. +We also check that the resulting value is a JSON object. + +Next we'll extract the commit ID (a hexadecimal SHA-1 sum), +intermediate commit info object, and the commit message from that +object. We also do proper type checks:: + + sha = json_object_get(data, "sha"); + if(!json_is_string(sha)) + { + fprintf(stderr, "error: commit %d: sha is not a string\n", i + 1); + json_decref(root); + return 1; + } + + commit = json_object_get(data, "commit"); + if(!json_is_object(commit)) + { + fprintf(stderr, "error: commit %d: commit is not an object\n", i + 1); + json_decref(root); + return 1; + } + + message = json_object_get(commit, "message"); + if(!json_is_string(message)) + { + fprintf(stderr, "error: commit %d: message is not a string\n", i + 1); + json_decref(root); + return 1; + } + ... + +And finally, we'll print the first 8 characters of the commit ID and +the first line of the commit message. A C-style string is extracted +from a JSON string using :func:`json_string_value()`:: + + message_text = json_string_value(message); + printf("%.8s %.*s\n", + json_string_value(id), + newline_offset(message_text), + message_text); + } + +After sending the HTTP request, we decoded the JSON text using +:func:`json_loads()`, remember? It returns a *new reference* to the +JSON value it decodes. When we're finished with the value, we'll need +to decrease the reference count using :func:`json_decref()`. This way +Jansson can release the resources:: + + json_decref(root); + return 0; + +For a detailed explanation of reference counting in Jansson, see +:ref:`apiref-reference-count` in :ref:`apiref`. + +The program's ready, let's test it and view the latest commits in +Jansson's repository:: + + $ ./github_commits akheron jansson + 1581f26a Merge branch '2.3' + aabfd493 load: Change buffer_pos to be a size_t + bd72efbd load: Avoid unexpected behaviour in macro expansion + e8fd3e30 Document and tweak json_load_callback() + 873eddaf Merge pull request #60 from rogerz/contrib + bd2c0c73 Ignore the binary test_load_callback + 17a51a4b Merge branch '2.3' + 09c39adc Add json_load_callback to the list of exported symbols + cbb80baf Merge pull request #57 from rogerz/contrib + 040bd7b0 Add json_load_callback() + 2637faa4 Make test stripping locale independent + <...> + + +Conclusion +========== + +In this tutorial, we implemented a program that fetches the latest +commits of a GitHub repository using the GitHub Repo Commits API. +Jansson was used to decode the JSON response and to extract the commit +data. + +This tutorial only covered a small part of Jansson. For example, we +did not create or manipulate JSON values at all. Proceed to +:ref:`apiref` to explore all features of Jansson. diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_sources/upgrading.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_sources/upgrading.txt Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,76 @@ +.. highlight:: c + +****************** +Upgrading from 1.x +****************** + +This chapter lists the backwards incompatible changes introduced in +Jansson 2.0, and the steps that are needed for upgrading your code. + +**The incompatibilities are not dramatic.** The biggest change is that +all decoding functions now require and extra parameter. Most programs +can be modified to work with 2.0 by adding a ``0`` as the second +parameter to all calls of :func:`json_loads()`, :func:`json_loadf()` +and :func:`json_load_file()`. + + +Compatibility +============= + +Jansson 2.0 is backwards incompatible with the Jansson 1.x releases. +It is ABI incompatible, i.e. all programs dynamically linking to the +Jansson library need to be recompiled. It's also API incompatible, +i.e. the source code of programs using Jansson 1.x may need +modifications to make them compile against Jansson 2.0. + +All the 2.x releases are guaranteed to be backwards compatible for +both ABI and API, so no recompilation or source changes are needed +when upgrading from 2.x to 2.y. + + +List of Incompatible Changes +============================ + +**Decoding flags** + For future needs, a ``flags`` parameter was added as the second + parameter to all decoding functions, i.e. :func:`json_loads()`, + :func:`json_loadf()` and :func:`json_load_file()`. All calls to + these functions need to be changed by adding a ``0`` as the second + argument. For example:: + + /* old code */ + json_loads(input, &error); + + /* new code */ + json_loads(input, 0, &error); + + +**Underlying type of JSON integers** + The underlying C type of JSON integers has been changed from + :type:`int` to the widest available signed integer type, i.e. + :type:`long long` or :type:`long`, depending on whether + :type:`long long` is supported on your system or not. This makes + the whole 64-bit integer range available on most modern systems. + + ``jansson.h`` has a typedef :type:`json_int_t` to the underlying + integer type. :type:`int` should still be used in most cases when + dealing with smallish JSON integers, as the compiler handles + implicit type coercion. Only when the full 64-bit range is needed, + :type:`json_int_t` should be explicitly used. + + +**Maximum encoder indentation depth** + The maximum argument of the ``JSON_INDENT()`` macro has been + changed from 255 to 31, to free up bits from the ``flags`` + parameter of :func:`json_dumps()`, :func:`json_dumpf()` and + :func:`json_dump_file()`. If your code uses a bigger indentation + than 31, it needs to be changed. + + +**Unsigned integers in API functions** + Version 2.0 unifies unsigned integer usage in the API. All uses of + :type:`unsigned int` and :type:`unsigned long` have been replaced + with :type:`size_t`. This includes flags, container sizes, etc. + This should not require source code changes, as both + :type:`unsigned int` and :type:`unsigned long` are usually + compatible with :type:`size_t`. diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/ajax-loader.gif Binary file components/jansson/doc/html/_static/ajax-loader.gif has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/basic.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_static/basic.css Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,537 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox input[type="text"] { + width: 170px; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + width: 30px; +} + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlighted { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/comment-bright.png Binary file components/jansson/doc/html/_static/comment-bright.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/comment-close.png Binary file components/jansson/doc/html/_static/comment-close.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/comment.png Binary file components/jansson/doc/html/_static/comment.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/default.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_static/default.css Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,256 @@ +/* + * default.css_t + * ~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- default theme. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: #ffffff; + color: #000000; + padding: 0 20px 30px 20px; +} + +div.footer { + color: #ffffff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ffffff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + line-height: 30px; + color: #ffffff; +} + +div.related a { + color: #ffffff; +} + +div.sphinxsidebar { +} + +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #ffffff; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: #ffffff; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: #ffffff; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + + + +/* -- hyperlink styles ------------------------------------------------------ */ + +a { + color: #355f7c; + text-decoration: none; +} + +a:visited { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + + + +/* -- body styles ----------------------------------------------------------- */ + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: #eeffcc; + color: #333333; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +th { + background-color: #ede; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +} + +.viewcode-back { + font-family: sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/doctools.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_static/doctools.js Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,238 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for all documentation. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this); + }); + } + } + return this.each(function() { + highlight(this); + }); +}; + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + if (!body.length) { + body = $('body'); + } + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('

' + _('Hide Search Matches') + '

') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/down-pressed.png Binary file components/jansson/doc/html/_static/down-pressed.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/down.png Binary file components/jansson/doc/html/_static/down.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/file.png Binary file components/jansson/doc/html/_static/file.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/jquery.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_static/jquery.js Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,2 @@ +/*! jQuery v1.8.3 jquery.com | jquery.org/license */ +(function(e,t){function _(e){var t=M[e]={};return v.each(e.split(y),function(e,n){t[n]=!0}),t}function H(e,n,r){if(r===t&&e.nodeType===1){var i="data-"+n.replace(P,"-$1").toLowerCase();r=e.getAttribute(i);if(typeof r=="string"){try{r=r==="true"?!0:r==="false"?!1:r==="null"?null:+r+""===r?+r:D.test(r)?v.parseJSON(r):r}catch(s){}v.data(e,n,r)}else r=t}return r}function B(e){var t;for(t in e){if(t==="data"&&v.isEmptyObject(e[t]))continue;if(t!=="toJSON")return!1}return!0}function et(){return!1}function tt(){return!0}function ut(e){return!e||!e.parentNode||e.parentNode.nodeType===11}function at(e,t){do e=e[t];while(e&&e.nodeType!==1);return e}function ft(e,t,n){t=t||0;if(v.isFunction(t))return v.grep(e,function(e,r){var i=!!t.call(e,r,e);return i===n});if(t.nodeType)return v.grep(e,function(e,r){return e===t===n});if(typeof t=="string"){var r=v.grep(e,function(e){return e.nodeType===1});if(it.test(t))return v.filter(t,r,!n);t=v.filter(t,r)}return v.grep(e,function(e,r){return v.inArray(e,t)>=0===n})}function lt(e){var t=ct.split("|"),n=e.createDocumentFragment();if(n.createElement)while(t.length)n.createElement(t.pop());return n}function Lt(e,t){return e.getElementsByTagName(t)[0]||e.appendChild(e.ownerDocument.createElement(t))}function At(e,t){if(t.nodeType!==1||!v.hasData(e))return;var n,r,i,s=v._data(e),o=v._data(t,s),u=s.events;if(u){delete o.handle,o.events={};for(n in u)for(r=0,i=u[n].length;r").appendTo(i.body),n=t.css("display");t.remove();if(n==="none"||n===""){Pt=i.body.appendChild(Pt||v.extend(i.createElement("iframe"),{frameBorder:0,width:0,height:0}));if(!Ht||!Pt.createElement)Ht=(Pt.contentWindow||Pt.contentDocument).document,Ht.write(""),Ht.close();t=Ht.body.appendChild(Ht.createElement(e)),n=Dt(t,"display"),i.body.removeChild(Pt)}return Wt[e]=n,n}function fn(e,t,n,r){var i;if(v.isArray(t))v.each(t,function(t,i){n||sn.test(e)?r(e,i):fn(e+"["+(typeof i=="object"?t:"")+"]",i,n,r)});else if(!n&&v.type(t)==="object")for(i in t)fn(e+"["+i+"]",t[i],n,r);else r(e,t)}function Cn(e){return function(t,n){typeof t!="string"&&(n=t,t="*");var r,i,s,o=t.toLowerCase().split(y),u=0,a=o.length;if(v.isFunction(n))for(;u)[^>]*$|#([\w\-]*)$)/,E=/^<(\w+)\s*\/?>(?:<\/\1>|)$/,S=/^[\],:{}\s]*$/,x=/(?:^|:|,)(?:\s*\[)+/g,T=/\\(?:["\\\/bfnrt]|u[\da-fA-F]{4})/g,N=/"[^"\\\r\n]*"|true|false|null|-?(?:\d\d*\.|)\d+(?:[eE][\-+]?\d+|)/g,C=/^-ms-/,k=/-([\da-z])/gi,L=function(e,t){return(t+"").toUpperCase()},A=function(){i.addEventListener?(i.removeEventListener("DOMContentLoaded",A,!1),v.ready()):i.readyState==="complete"&&(i.detachEvent("onreadystatechange",A),v.ready())},O={};v.fn=v.prototype={constructor:v,init:function(e,n,r){var s,o,u,a;if(!e)return this;if(e.nodeType)return this.context=this[0]=e,this.length=1,this;if(typeof e=="string"){e.charAt(0)==="<"&&e.charAt(e.length-1)===">"&&e.length>=3?s=[null,e,null]:s=w.exec(e);if(s&&(s[1]||!n)){if(s[1])return n=n instanceof v?n[0]:n,a=n&&n.nodeType?n.ownerDocument||n:i,e=v.parseHTML(s[1],a,!0),E.test(s[1])&&v.isPlainObject(n)&&this.attr.call(e,n,!0),v.merge(this,e);o=i.getElementById(s[2]);if(o&&o.parentNode){if(o.id!==s[2])return r.find(e);this.length=1,this[0]=o}return this.context=i,this.selector=e,this}return!n||n.jquery?(n||r).find(e):this.constructor(n).find(e)}return v.isFunction(e)?r.ready(e):(e.selector!==t&&(this.selector=e.selector,this.context=e.context),v.makeArray(e,this))},selector:"",jquery:"1.8.3",length:0,size:function(){return this.length},toArray:function(){return l.call(this)},get:function(e){return e==null?this.toArray():e<0?this[this.length+e]:this[e]},pushStack:function(e,t,n){var r=v.merge(this.constructor(),e);return r.prevObject=this,r.context=this.context,t==="find"?r.selector=this.selector+(this.selector?" ":"")+n:t&&(r.selector=this.selector+"."+t+"("+n+")"),r},each:function(e,t){return v.each(this,e,t)},ready:function(e){return v.ready.promise().done(e),this},eq:function(e){return e=+e,e===-1?this.slice(e):this.slice(e,e+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(l.apply(this,arguments),"slice",l.call(arguments).join(","))},map:function(e){return this.pushStack(v.map(this,function(t,n){return e.call(t,n,t)}))},end:function(){return this.prevObject||this.constructor(null)},push:f,sort:[].sort,splice:[].splice},v.fn.init.prototype=v.fn,v.extend=v.fn.extend=function(){var e,n,r,i,s,o,u=arguments[0]||{},a=1,f=arguments.length,l=!1;typeof u=="boolean"&&(l=u,u=arguments[1]||{},a=2),typeof u!="object"&&!v.isFunction(u)&&(u={}),f===a&&(u=this,--a);for(;a0)return;r.resolveWith(i,[v]),v.fn.trigger&&v(i).trigger("ready").off("ready")},isFunction:function(e){return v.type(e)==="function"},isArray:Array.isArray||function(e){return v.type(e)==="array"},isWindow:function(e){return e!=null&&e==e.window},isNumeric:function(e){return!isNaN(parseFloat(e))&&isFinite(e)},type:function(e){return e==null?String(e):O[h.call(e)]||"object"},isPlainObject:function(e){if(!e||v.type(e)!=="object"||e.nodeType||v.isWindow(e))return!1;try{if(e.constructor&&!p.call(e,"constructor")&&!p.call(e.constructor.prototype,"isPrototypeOf"))return!1}catch(n){return!1}var r;for(r in e);return r===t||p.call(e,r)},isEmptyObject:function(e){var t;for(t in e)return!1;return!0},error:function(e){throw new Error(e)},parseHTML:function(e,t,n){var r;return!e||typeof e!="string"?null:(typeof t=="boolean"&&(n=t,t=0),t=t||i,(r=E.exec(e))?[t.createElement(r[1])]:(r=v.buildFragment([e],t,n?null:[]),v.merge([],(r.cacheable?v.clone(r.fragment):r.fragment).childNodes)))},parseJSON:function(t){if(!t||typeof t!="string")return null;t=v.trim(t);if(e.JSON&&e.JSON.parse)return e.JSON.parse(t);if(S.test(t.replace(T,"@").replace(N,"]").replace(x,"")))return(new Function("return "+t))();v.error("Invalid JSON: "+t)},parseXML:function(n){var r,i;if(!n||typeof n!="string")return null;try{e.DOMParser?(i=new DOMParser,r=i.parseFromString(n,"text/xml")):(r=new ActiveXObject("Microsoft.XMLDOM"),r.async="false",r.loadXML(n))}catch(s){r=t}return(!r||!r.documentElement||r.getElementsByTagName("parsererror").length)&&v.error("Invalid XML: "+n),r},noop:function(){},globalEval:function(t){t&&g.test(t)&&(e.execScript||function(t){e.eval.call(e,t)})(t)},camelCase:function(e){return e.replace(C,"ms-").replace(k,L)},nodeName:function(e,t){return e.nodeName&&e.nodeName.toLowerCase()===t.toLowerCase()},each:function(e,n,r){var i,s=0,o=e.length,u=o===t||v.isFunction(e);if(r){if(u){for(i in e)if(n.apply(e[i],r)===!1)break}else for(;s0&&e[0]&&e[a-1]||a===0||v.isArray(e));if(f)for(;u-1)a.splice(n,1),i&&(n<=o&&o--,n<=u&&u--)}),this},has:function(e){return v.inArray(e,a)>-1},empty:function(){return a=[],this},disable:function(){return a=f=n=t,this},disabled:function(){return!a},lock:function(){return f=t,n||c.disable(),this},locked:function(){return!f},fireWith:function(e,t){return t=t||[],t=[e,t.slice?t.slice():t],a&&(!r||f)&&(i?f.push(t):l(t)),this},fire:function(){return c.fireWith(this,arguments),this},fired:function(){return!!r}};return c},v.extend({Deferred:function(e){var t=[["resolve","done",v.Callbacks("once memory"),"resolved"],["reject","fail",v.Callbacks("once memory"),"rejected"],["notify","progress",v.Callbacks("memory")]],n="pending",r={state:function(){return n},always:function(){return i.done(arguments).fail(arguments),this},then:function(){var e=arguments;return v.Deferred(function(n){v.each(t,function(t,r){var s=r[0],o=e[t];i[r[1]](v.isFunction(o)?function(){var e=o.apply(this,arguments);e&&v.isFunction(e.promise)?e.promise().done(n.resolve).fail(n.reject).progress(n.notify):n[s+"With"](this===i?n:this,[e])}:n[s])}),e=null}).promise()},promise:function(e){return e!=null?v.extend(e,r):r}},i={};return r.pipe=r.then,v.each(t,function(e,s){var o=s[2],u=s[3];r[s[1]]=o.add,u&&o.add(function(){n=u},t[e^1][2].disable,t[2][2].lock),i[s[0]]=o.fire,i[s[0]+"With"]=o.fireWith}),r.promise(i),e&&e.call(i,i),i},when:function(e){var t=0,n=l.call(arguments),r=n.length,i=r!==1||e&&v.isFunction(e.promise)?r:0,s=i===1?e:v.Deferred(),o=function(e,t,n){return function(r){t[e]=this,n[e]=arguments.length>1?l.call(arguments):r,n===u?s.notifyWith(t,n):--i||s.resolveWith(t,n)}},u,a,f;if(r>1){u=new Array(r),a=new Array(r),f=new Array(r);for(;t
a",n=p.getElementsByTagName("*"),r=p.getElementsByTagName("a")[0];if(!n||!r||!n.length)return{};s=i.createElement("select"),o=s.appendChild(i.createElement("option")),u=p.getElementsByTagName("input")[0],r.style.cssText="top:1px;float:left;opacity:.5",t={leadingWhitespace:p.firstChild.nodeType===3,tbody:!p.getElementsByTagName("tbody").length,htmlSerialize:!!p.getElementsByTagName("link").length,style:/top/.test(r.getAttribute("style")),hrefNormalized:r.getAttribute("href")==="/a",opacity:/^0.5/.test(r.style.opacity),cssFloat:!!r.style.cssFloat,checkOn:u.value==="on",optSelected:o.selected,getSetAttribute:p.className!=="t",enctype:!!i.createElement("form").enctype,html5Clone:i.createElement("nav").cloneNode(!0).outerHTML!=="<:nav>",boxModel:i.compatMode==="CSS1Compat",submitBubbles:!0,changeBubbles:!0,focusinBubbles:!1,deleteExpando:!0,noCloneEvent:!0,inlineBlockNeedsLayout:!1,shrinkWrapBlocks:!1,reliableMarginRight:!0,boxSizingReliable:!0,pixelPosition:!1},u.checked=!0,t.noCloneChecked=u.cloneNode(!0).checked,s.disabled=!0,t.optDisabled=!o.disabled;try{delete p.test}catch(d){t.deleteExpando=!1}!p.addEventListener&&p.attachEvent&&p.fireEvent&&(p.attachEvent("onclick",h=function(){t.noCloneEvent=!1}),p.cloneNode(!0).fireEvent("onclick"),p.detachEvent("onclick",h)),u=i.createElement("input"),u.value="t",u.setAttribute("type","radio"),t.radioValue=u.value==="t",u.setAttribute("checked","checked"),u.setAttribute("name","t"),p.appendChild(u),a=i.createDocumentFragment(),a.appendChild(p.lastChild),t.checkClone=a.cloneNode(!0).cloneNode(!0).lastChild.checked,t.appendChecked=u.checked,a.removeChild(u),a.appendChild(p);if(p.attachEvent)for(l in{submit:!0,change:!0,focusin:!0})f="on"+l,c=f in p,c||(p.setAttribute(f,"return;"),c=typeof p[f]=="function"),t[l+"Bubbles"]=c;return v(function(){var n,r,s,o,u="padding:0;margin:0;border:0;display:block;overflow:hidden;",a=i.getElementsByTagName("body")[0];if(!a)return;n=i.createElement("div"),n.style.cssText="visibility:hidden;border:0;width:0;height:0;position:static;top:0;margin-top:1px",a.insertBefore(n,a.firstChild),r=i.createElement("div"),n.appendChild(r),r.innerHTML="
t
",s=r.getElementsByTagName("td"),s[0].style.cssText="padding:0;margin:0;border:0;display:none",c=s[0].offsetHeight===0,s[0].style.display="",s[1].style.display="none",t.reliableHiddenOffsets=c&&s[0].offsetHeight===0,r.innerHTML="",r.style.cssText="box-sizing:border-box;-moz-box-sizing:border-box;-webkit-box-sizing:border-box;padding:1px;border:1px;display:block;width:4px;margin-top:1%;position:absolute;top:1%;",t.boxSizing=r.offsetWidth===4,t.doesNotIncludeMarginInBodyOffset=a.offsetTop!==1,e.getComputedStyle&&(t.pixelPosition=(e.getComputedStyle(r,null)||{}).top!=="1%",t.boxSizingReliable=(e.getComputedStyle(r,null)||{width:"4px"}).width==="4px",o=i.createElement("div"),o.style.cssText=r.style.cssText=u,o.style.marginRight=o.style.width="0",r.style.width="1px",r.appendChild(o),t.reliableMarginRight=!parseFloat((e.getComputedStyle(o,null)||{}).marginRight)),typeof r.style.zoom!="undefined"&&(r.innerHTML="",r.style.cssText=u+"width:1px;padding:1px;display:inline;zoom:1",t.inlineBlockNeedsLayout=r.offsetWidth===3,r.style.display="block",r.style.overflow="visible",r.innerHTML="
",r.firstChild.style.width="5px",t.shrinkWrapBlocks=r.offsetWidth!==3,n.style.zoom=1),a.removeChild(n),n=r=s=o=null}),a.removeChild(p),n=r=s=o=u=a=p=null,t}();var D=/(?:\{[\s\S]*\}|\[[\s\S]*\])$/,P=/([A-Z])/g;v.extend({cache:{},deletedIds:[],uuid:0,expando:"jQuery"+(v.fn.jquery+Math.random()).replace(/\D/g,""),noData:{embed:!0,object:"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",applet:!0},hasData:function(e){return e=e.nodeType?v.cache[e[v.expando]]:e[v.expando],!!e&&!B(e)},data:function(e,n,r,i){if(!v.acceptData(e))return;var s,o,u=v.expando,a=typeof n=="string",f=e.nodeType,l=f?v.cache:e,c=f?e[u]:e[u]&&u;if((!c||!l[c]||!i&&!l[c].data)&&a&&r===t)return;c||(f?e[u]=c=v.deletedIds.pop()||v.guid++:c=u),l[c]||(l[c]={},f||(l[c].toJSON=v.noop));if(typeof n=="object"||typeof n=="function")i?l[c]=v.extend(l[c],n):l[c].data=v.extend(l[c].data,n);return s=l[c],i||(s.data||(s.data={}),s=s.data),r!==t&&(s[v.camelCase(n)]=r),a?(o=s[n],o==null&&(o=s[v.camelCase(n)])):o=s,o},removeData:function(e,t,n){if(!v.acceptData(e))return;var r,i,s,o=e.nodeType,u=o?v.cache:e,a=o?e[v.expando]:v.expando;if(!u[a])return;if(t){r=n?u[a]:u[a].data;if(r){v.isArray(t)||(t in r?t=[t]:(t=v.camelCase(t),t in r?t=[t]:t=t.split(" ")));for(i=0,s=t.length;i1,null,!1))},removeData:function(e){return this.each(function(){v.removeData(this,e)})}}),v.extend({queue:function(e,t,n){var r;if(e)return t=(t||"fx")+"queue",r=v._data(e,t),n&&(!r||v.isArray(n)?r=v._data(e,t,v.makeArray(n)):r.push(n)),r||[]},dequeue:function(e,t){t=t||"fx";var n=v.queue(e,t),r=n.length,i=n.shift(),s=v._queueHooks(e,t),o=function(){v.dequeue(e,t)};i==="inprogress"&&(i=n.shift(),r--),i&&(t==="fx"&&n.unshift("inprogress"),delete s.stop,i.call(e,o,s)),!r&&s&&s.empty.fire()},_queueHooks:function(e,t){var n=t+"queueHooks";return v._data(e,n)||v._data(e,n,{empty:v.Callbacks("once memory").add(function(){v.removeData(e,t+"queue",!0),v.removeData(e,n,!0)})})}}),v.fn.extend({queue:function(e,n){var r=2;return typeof e!="string"&&(n=e,e="fx",r--),arguments.length1)},removeAttr:function(e){return this.each(function(){v.removeAttr(this,e)})},prop:function(e,t){return v.access(this,v.prop,e,t,arguments.length>1)},removeProp:function(e){return e=v.propFix[e]||e,this.each(function(){try{this[e]=t,delete this[e]}catch(n){}})},addClass:function(e){var t,n,r,i,s,o,u;if(v.isFunction(e))return this.each(function(t){v(this).addClass(e.call(this,t,this.className))});if(e&&typeof e=="string"){t=e.split(y);for(n=0,r=this.length;n=0)r=r.replace(" "+n[s]+" "," ");i.className=e?v.trim(r):""}}}return this},toggleClass:function(e,t){var n=typeof e,r=typeof t=="boolean";return v.isFunction(e)?this.each(function(n){v(this).toggleClass(e.call(this,n,this.className,t),t)}):this.each(function(){if(n==="string"){var i,s=0,o=v(this),u=t,a=e.split(y);while(i=a[s++])u=r?u:!o.hasClass(i),o[u?"addClass":"removeClass"](i)}else if(n==="undefined"||n==="boolean")this.className&&v._data(this,"__className__",this.className),this.className=this.className||e===!1?"":v._data(this,"__className__")||""})},hasClass:function(e){var t=" "+e+" ",n=0,r=this.length;for(;n=0)return!0;return!1},val:function(e){var n,r,i,s=this[0];if(!arguments.length){if(s)return n=v.valHooks[s.type]||v.valHooks[s.nodeName.toLowerCase()],n&&"get"in n&&(r=n.get(s,"value"))!==t?r:(r=s.value,typeof r=="string"?r.replace(R,""):r==null?"":r);return}return i=v.isFunction(e),this.each(function(r){var s,o=v(this);if(this.nodeType!==1)return;i?s=e.call(this,r,o.val()):s=e,s==null?s="":typeof s=="number"?s+="":v.isArray(s)&&(s=v.map(s,function(e){return e==null?"":e+""})),n=v.valHooks[this.type]||v.valHooks[this.nodeName.toLowerCase()];if(!n||!("set"in n)||n.set(this,s,"value")===t)this.value=s})}}),v.extend({valHooks:{option:{get:function(e){var t=e.attributes.value;return!t||t.specified?e.value:e.text}},select:{get:function(e){var t,n,r=e.options,i=e.selectedIndex,s=e.type==="select-one"||i<0,o=s?null:[],u=s?i+1:r.length,a=i<0?u:s?i:0;for(;a=0}),n.length||(e.selectedIndex=-1),n}}},attrFn:{},attr:function(e,n,r,i){var s,o,u,a=e.nodeType;if(!e||a===3||a===8||a===2)return;if(i&&v.isFunction(v.fn[n]))return v(e)[n](r);if(typeof e.getAttribute=="undefined")return v.prop(e,n,r);u=a!==1||!v.isXMLDoc(e),u&&(n=n.toLowerCase(),o=v.attrHooks[n]||(X.test(n)?F:j));if(r!==t){if(r===null){v.removeAttr(e,n);return}return o&&"set"in o&&u&&(s=o.set(e,r,n))!==t?s:(e.setAttribute(n,r+""),r)}return o&&"get"in o&&u&&(s=o.get(e,n))!==null?s:(s=e.getAttribute(n),s===null?t:s)},removeAttr:function(e,t){var n,r,i,s,o=0;if(t&&e.nodeType===1){r=t.split(y);for(;o=0}})});var $=/^(?:textarea|input|select)$/i,J=/^([^\.]*|)(?:\.(.+)|)$/,K=/(?:^|\s)hover(\.\S+|)\b/,Q=/^key/,G=/^(?:mouse|contextmenu)|click/,Y=/^(?:focusinfocus|focusoutblur)$/,Z=function(e){return v.event.special.hover?e:e.replace(K,"mouseenter$1 mouseleave$1")};v.event={add:function(e,n,r,i,s){var o,u,a,f,l,c,h,p,d,m,g;if(e.nodeType===3||e.nodeType===8||!n||!r||!(o=v._data(e)))return;r.handler&&(d=r,r=d.handler,s=d.selector),r.guid||(r.guid=v.guid++),a=o.events,a||(o.events=a={}),u=o.handle,u||(o.handle=u=function(e){return typeof v=="undefined"||!!e&&v.event.triggered===e.type?t:v.event.dispatch.apply(u.elem,arguments)},u.elem=e),n=v.trim(Z(n)).split(" ");for(f=0;f=0&&(y=y.slice(0,-1),a=!0),y.indexOf(".")>=0&&(b=y.split("."),y=b.shift(),b.sort());if((!s||v.event.customEvent[y])&&!v.event.global[y])return;n=typeof n=="object"?n[v.expando]?n:new v.Event(y,n):new v.Event(y),n.type=y,n.isTrigger=!0,n.exclusive=a,n.namespace=b.join("."),n.namespace_re=n.namespace?new RegExp("(^|\\.)"+b.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,h=y.indexOf(":")<0?"on"+y:"";if(!s){u=v.cache;for(f in u)u[f].events&&u[f].events[y]&&v.event.trigger(n,r,u[f].handle.elem,!0);return}n.result=t,n.target||(n.target=s),r=r!=null?v.makeArray(r):[],r.unshift(n),p=v.event.special[y]||{};if(p.trigger&&p.trigger.apply(s,r)===!1)return;m=[[s,p.bindType||y]];if(!o&&!p.noBubble&&!v.isWindow(s)){g=p.delegateType||y,l=Y.test(g+y)?s:s.parentNode;for(c=s;l;l=l.parentNode)m.push([l,g]),c=l;c===(s.ownerDocument||i)&&m.push([c.defaultView||c.parentWindow||e,g])}for(f=0;f=0:v.find(h,this,null,[s]).length),u[h]&&f.push(c);f.length&&w.push({elem:s,matches:f})}d.length>m&&w.push({elem:this,matches:d.slice(m)});for(r=0;r0?this.on(t,null,e,n):this.trigger(t)},Q.test(t)&&(v.event.fixHooks[t]=v.event.keyHooks),G.test(t)&&(v.event.fixHooks[t]=v.event.mouseHooks)}),function(e,t){function nt(e,t,n,r){n=n||[],t=t||g;var i,s,a,f,l=t.nodeType;if(!e||typeof e!="string")return n;if(l!==1&&l!==9)return[];a=o(t);if(!a&&!r)if(i=R.exec(e))if(f=i[1]){if(l===9){s=t.getElementById(f);if(!s||!s.parentNode)return n;if(s.id===f)return n.push(s),n}else if(t.ownerDocument&&(s=t.ownerDocument.getElementById(f))&&u(t,s)&&s.id===f)return n.push(s),n}else{if(i[2])return S.apply(n,x.call(t.getElementsByTagName(e),0)),n;if((f=i[3])&&Z&&t.getElementsByClassName)return S.apply(n,x.call(t.getElementsByClassName(f),0)),n}return vt(e.replace(j,"$1"),t,n,r,a)}function rt(e){return function(t){var n=t.nodeName.toLowerCase();return n==="input"&&t.type===e}}function it(e){return function(t){var n=t.nodeName.toLowerCase();return(n==="input"||n==="button")&&t.type===e}}function st(e){return N(function(t){return t=+t,N(function(n,r){var i,s=e([],n.length,t),o=s.length;while(o--)n[i=s[o]]&&(n[i]=!(r[i]=n[i]))})})}function ot(e,t,n){if(e===t)return n;var r=e.nextSibling;while(r){if(r===t)return-1;r=r.nextSibling}return 1}function ut(e,t){var n,r,s,o,u,a,f,l=L[d][e+" "];if(l)return t?0:l.slice(0);u=e,a=[],f=i.preFilter;while(u){if(!n||(r=F.exec(u)))r&&(u=u.slice(r[0].length)||u),a.push(s=[]);n=!1;if(r=I.exec(u))s.push(n=new m(r.shift())),u=u.slice(n.length),n.type=r[0].replace(j," ");for(o in i.filter)(r=J[o].exec(u))&&(!f[o]||(r=f[o](r)))&&(s.push(n=new m(r.shift())),u=u.slice(n.length),n.type=o,n.matches=r);if(!n)break}return t?u.length:u?nt.error(e):L(e,a).slice(0)}function at(e,t,r){var i=t.dir,s=r&&t.dir==="parentNode",o=w++;return t.first?function(t,n,r){while(t=t[i])if(s||t.nodeType===1)return e(t,n,r)}:function(t,r,u){if(!u){var a,f=b+" "+o+" ",l=f+n;while(t=t[i])if(s||t.nodeType===1){if((a=t[d])===l)return t.sizset;if(typeof a=="string"&&a.indexOf(f)===0){if(t.sizset)return t}else{t[d]=l;if(e(t,r,u))return t.sizset=!0,t;t.sizset=!1}}}else while(t=t[i])if(s||t.nodeType===1)if(e(t,r,u))return t}}function ft(e){return e.length>1?function(t,n,r){var i=e.length;while(i--)if(!e[i](t,n,r))return!1;return!0}:e[0]}function lt(e,t,n,r,i){var s,o=[],u=0,a=e.length,f=t!=null;for(;u-1&&(s[f]=!(o[f]=c))}}else g=lt(g===o?g.splice(d,g.length):g),i?i(null,o,g,a):S.apply(o,g)})}function ht(e){var t,n,r,s=e.length,o=i.relative[e[0].type],u=o||i.relative[" "],a=o?1:0,f=at(function(e){return e===t},u,!0),l=at(function(e){return T.call(t,e)>-1},u,!0),h=[function(e,n,r){return!o&&(r||n!==c)||((t=n).nodeType?f(e,n,r):l(e,n,r))}];for(;a1&&ft(h),a>1&&e.slice(0,a-1).join("").replace(j,"$1"),n,a0,s=e.length>0,o=function(u,a,f,l,h){var p,d,v,m=[],y=0,w="0",x=u&&[],T=h!=null,N=c,C=u||s&&i.find.TAG("*",h&&a.parentNode||a),k=b+=N==null?1:Math.E;T&&(c=a!==g&&a,n=o.el);for(;(p=C[w])!=null;w++){if(s&&p){for(d=0;v=e[d];d++)if(v(p,a,f)){l.push(p);break}T&&(b=k,n=++o.el)}r&&((p=!v&&p)&&y--,u&&x.push(p))}y+=w;if(r&&w!==y){for(d=0;v=t[d];d++)v(x,m,a,f);if(u){if(y>0)while(w--)!x[w]&&!m[w]&&(m[w]=E.call(l));m=lt(m)}S.apply(l,m),T&&!u&&m.length>0&&y+t.length>1&&nt.uniqueSort(l)}return T&&(b=k,c=N),x};return o.el=0,r?N(o):o}function dt(e,t,n){var r=0,i=t.length;for(;r2&&(f=u[0]).type==="ID"&&t.nodeType===9&&!s&&i.relative[u[1].type]){t=i.find.ID(f.matches[0].replace($,""),t,s)[0];if(!t)return n;e=e.slice(u.shift().length)}for(o=J.POS.test(e)?-1:u.length-1;o>=0;o--){f=u[o];if(i.relative[l=f.type])break;if(c=i.find[l])if(r=c(f.matches[0].replace($,""),z.test(u[0].type)&&t.parentNode||t,s)){u.splice(o,1),e=r.length&&u.join("");if(!e)return S.apply(n,x.call(r,0)),n;break}}}return a(e,h)(r,t,s,n,z.test(e)),n}function mt(){}var n,r,i,s,o,u,a,f,l,c,h=!0,p="undefined",d=("sizcache"+Math.random()).replace(".",""),m=String,g=e.document,y=g.documentElement,b=0,w=0,E=[].pop,S=[].push,x=[].slice,T=[].indexOf||function(e){var t=0,n=this.length;for(;ti.cacheLength&&delete e[t.shift()],e[n+" "]=r},e)},k=C(),L=C(),A=C(),O="[\\x20\\t\\r\\n\\f]",M="(?:\\\\.|[-\\w]|[^\\x00-\\xa0])+",_=M.replace("w","w#"),D="([*^$|!~]?=)",P="\\["+O+"*("+M+")"+O+"*(?:"+D+O+"*(?:(['\"])((?:\\\\.|[^\\\\])*?)\\3|("+_+")|)|)"+O+"*\\]",H=":("+M+")(?:\\((?:(['\"])((?:\\\\.|[^\\\\])*?)\\2|([^()[\\]]*|(?:(?:"+P+")|[^:]|\\\\.)*|.*))\\)|)",B=":(even|odd|eq|gt|lt|nth|first|last)(?:\\("+O+"*((?:-\\d)?\\d*)"+O+"*\\)|)(?=[^-]|$)",j=new RegExp("^"+O+"+|((?:^|[^\\\\])(?:\\\\.)*)"+O+"+$","g"),F=new RegExp("^"+O+"*,"+O+"*"),I=new RegExp("^"+O+"*([\\x20\\t\\r\\n\\f>+~])"+O+"*"),q=new RegExp(H),R=/^(?:#([\w\-]+)|(\w+)|\.([\w\-]+))$/,U=/^:not/,z=/[\x20\t\r\n\f]*[+~]/,W=/:not\($/,X=/h\d/i,V=/input|select|textarea|button/i,$=/\\(?!\\)/g,J={ID:new RegExp("^#("+M+")"),CLASS:new RegExp("^\\.("+M+")"),NAME:new RegExp("^\\[name=['\"]?("+M+")['\"]?\\]"),TAG:new RegExp("^("+M.replace("w","w*")+")"),ATTR:new RegExp("^"+P),PSEUDO:new RegExp("^"+H),POS:new RegExp(B,"i"),CHILD:new RegExp("^:(only|nth|first|last)-child(?:\\("+O+"*(even|odd|(([+-]|)(\\d*)n|)"+O+"*(?:([+-]|)"+O+"*(\\d+)|))"+O+"*\\)|)","i"),needsContext:new RegExp("^"+O+"*[>+~]|"+B,"i")},K=function(e){var t=g.createElement("div");try{return e(t)}catch(n){return!1}finally{t=null}},Q=K(function(e){return e.appendChild(g.createComment("")),!e.getElementsByTagName("*").length}),G=K(function(e){return e.innerHTML="",e.firstChild&&typeof e.firstChild.getAttribute!==p&&e.firstChild.getAttribute("href")==="#"}),Y=K(function(e){e.innerHTML="";var t=typeof e.lastChild.getAttribute("multiple");return t!=="boolean"&&t!=="string"}),Z=K(function(e){return e.innerHTML="",!e.getElementsByClassName||!e.getElementsByClassName("e").length?!1:(e.lastChild.className="e",e.getElementsByClassName("e").length===2)}),et=K(function(e){e.id=d+0,e.innerHTML="
",y.insertBefore(e,y.firstChild);var t=g.getElementsByName&&g.getElementsByName(d).length===2+g.getElementsByName(d+0).length;return r=!g.getElementById(d),y.removeChild(e),t});try{x.call(y.childNodes,0)[0].nodeType}catch(tt){x=function(e){var t,n=[];for(;t=this[e];e++)n.push(t);return n}}nt.matches=function(e,t){return nt(e,null,null,t)},nt.matchesSelector=function(e,t){return nt(t,null,null,[e]).length>0},s=nt.getText=function(e){var t,n="",r=0,i=e.nodeType;if(i){if(i===1||i===9||i===11){if(typeof e.textContent=="string")return e.textContent;for(e=e.firstChild;e;e=e.nextSibling)n+=s(e)}else if(i===3||i===4)return e.nodeValue}else for(;t=e[r];r++)n+=s(t);return n},o=nt.isXML=function(e){var t=e&&(e.ownerDocument||e).documentElement;return t?t.nodeName!=="HTML":!1},u=nt.contains=y.contains?function(e,t){var n=e.nodeType===9?e.documentElement:e,r=t&&t.parentNode;return e===r||!!(r&&r.nodeType===1&&n.contains&&n.contains(r))}:y.compareDocumentPosition?function(e,t){return t&&!!(e.compareDocumentPosition(t)&16)}:function(e,t){while(t=t.parentNode)if(t===e)return!0;return!1},nt.attr=function(e,t){var n,r=o(e);return r||(t=t.toLowerCase()),(n=i.attrHandle[t])?n(e):r||Y?e.getAttribute(t):(n=e.getAttributeNode(t),n?typeof e[t]=="boolean"?e[t]?t:null:n.specified?n.value:null:null)},i=nt.selectors={cacheLength:50,createPseudo:N,match:J,attrHandle:G?{}:{href:function(e){return e.getAttribute("href",2)},type:function(e){return e.getAttribute("type")}},find:{ID:r?function(e,t,n){if(typeof t.getElementById!==p&&!n){var r=t.getElementById(e);return r&&r.parentNode?[r]:[]}}:function(e,n,r){if(typeof n.getElementById!==p&&!r){var i=n.getElementById(e);return i?i.id===e||typeof i.getAttributeNode!==p&&i.getAttributeNode("id").value===e?[i]:t:[]}},TAG:Q?function(e,t){if(typeof t.getElementsByTagName!==p)return t.getElementsByTagName(e)}:function(e,t){var n=t.getElementsByTagName(e);if(e==="*"){var r,i=[],s=0;for(;r=n[s];s++)r.nodeType===1&&i.push(r);return i}return n},NAME:et&&function(e,t){if(typeof t.getElementsByName!==p)return t.getElementsByName(name)},CLASS:Z&&function(e,t,n){if(typeof t.getElementsByClassName!==p&&!n)return t.getElementsByClassName(e)}},relative:{">":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace($,""),e[3]=(e[4]||e[5]||"").replace($,""),e[2]==="~="&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),e[1]==="nth"?(e[2]||nt.error(e[0]),e[3]=+(e[3]?e[4]+(e[5]||1):2*(e[2]==="even"||e[2]==="odd")),e[4]=+(e[6]+e[7]||e[2]==="odd")):e[2]&&nt.error(e[0]),e},PSEUDO:function(e){var t,n;if(J.CHILD.test(e[0]))return null;if(e[3])e[2]=e[3];else if(t=e[4])q.test(t)&&(n=ut(t,!0))&&(n=t.indexOf(")",t.length-n)-t.length)&&(t=t.slice(0,n),e[0]=e[0].slice(0,n)),e[2]=t;return e.slice(0,3)}},filter:{ID:r?function(e){return e=e.replace($,""),function(t){return t.getAttribute("id")===e}}:function(e){return e=e.replace($,""),function(t){var n=typeof t.getAttributeNode!==p&&t.getAttributeNode("id");return n&&n.value===e}},TAG:function(e){return e==="*"?function(){return!0}:(e=e.replace($,"").toLowerCase(),function(t){return t.nodeName&&t.nodeName.toLowerCase()===e})},CLASS:function(e){var t=k[d][e+" "];return t||(t=new RegExp("(^|"+O+")"+e+"("+O+"|$)"))&&k(e,function(e){return t.test(e.className||typeof e.getAttribute!==p&&e.getAttribute("class")||"")})},ATTR:function(e,t,n){return function(r,i){var s=nt.attr(r,e);return s==null?t==="!=":t?(s+="",t==="="?s===n:t==="!="?s!==n:t==="^="?n&&s.indexOf(n)===0:t==="*="?n&&s.indexOf(n)>-1:t==="$="?n&&s.substr(s.length-n.length)===n:t==="~="?(" "+s+" ").indexOf(n)>-1:t==="|="?s===n||s.substr(0,n.length+1)===n+"-":!1):!0}},CHILD:function(e,t,n,r){return e==="nth"?function(e){var t,i,s=e.parentNode;if(n===1&&r===0)return!0;if(s){i=0;for(t=s.firstChild;t;t=t.nextSibling)if(t.nodeType===1){i++;if(e===t)break}}return i-=r,i===n||i%n===0&&i/n>=0}:function(t){var n=t;switch(e){case"only":case"first":while(n=n.previousSibling)if(n.nodeType===1)return!1;if(e==="first")return!0;n=t;case"last":while(n=n.nextSibling)if(n.nodeType===1)return!1;return!0}}},PSEUDO:function(e,t){var n,r=i.pseudos[e]||i.setFilters[e.toLowerCase()]||nt.error("unsupported pseudo: "+e);return r[d]?r(t):r.length>1?(n=[e,e,"",t],i.setFilters.hasOwnProperty(e.toLowerCase())?N(function(e,n){var i,s=r(e,t),o=s.length;while(o--)i=T.call(e,s[o]),e[i]=!(n[i]=s[o])}):function(e){return r(e,0,n)}):r}},pseudos:{not:N(function(e){var t=[],n=[],r=a(e.replace(j,"$1"));return r[d]?N(function(e,t,n,i){var s,o=r(e,null,i,[]),u=e.length;while(u--)if(s=o[u])e[u]=!(t[u]=s)}):function(e,i,s){return t[0]=e,r(t,null,s,n),!n.pop()}}),has:N(function(e){return function(t){return nt(e,t).length>0}}),contains:N(function(e){return function(t){return(t.textContent||t.innerText||s(t)).indexOf(e)>-1}}),enabled:function(e){return e.disabled===!1},disabled:function(e){return e.disabled===!0},checked:function(e){var t=e.nodeName.toLowerCase();return t==="input"&&!!e.checked||t==="option"&&!!e.selected},selected:function(e){return e.parentNode&&e.parentNode.selectedIndex,e.selected===!0},parent:function(e){return!i.pseudos.empty(e)},empty:function(e){var t;e=e.firstChild;while(e){if(e.nodeName>"@"||(t=e.nodeType)===3||t===4)return!1;e=e.nextSibling}return!0},header:function(e){return X.test(e.nodeName)},text:function(e){var t,n;return e.nodeName.toLowerCase()==="input"&&(t=e.type)==="text"&&((n=e.getAttribute("type"))==null||n.toLowerCase()===t)},radio:rt("radio"),checkbox:rt("checkbox"),file:rt("file"),password:rt("password"),image:rt("image"),submit:it("submit"),reset:it("reset"),button:function(e){var t=e.nodeName.toLowerCase();return t==="input"&&e.type==="button"||t==="button"},input:function(e){return V.test(e.nodeName)},focus:function(e){var t=e.ownerDocument;return e===t.activeElement&&(!t.hasFocus||t.hasFocus())&&!!(e.type||e.href||~e.tabIndex)},active:function(e){return e===e.ownerDocument.activeElement},first:st(function(){return[0]}),last:st(function(e,t){return[t-1]}),eq:st(function(e,t,n){return[n<0?n+t:n]}),even:st(function(e,t){for(var n=0;n=0;)e.push(r);return e}),gt:st(function(e,t,n){for(var r=n<0?n+t:n;++r",e.querySelectorAll("[selected]").length||i.push("\\["+O+"*(?:checked|disabled|ismap|multiple|readonly|selected|value)"),e.querySelectorAll(":checked").length||i.push(":checked")}),K(function(e){e.innerHTML="

",e.querySelectorAll("[test^='']").length&&i.push("[*^$]="+O+"*(?:\"\"|'')"),e.innerHTML="",e.querySelectorAll(":enabled").length||i.push(":enabled",":disabled")}),i=new RegExp(i.join("|")),vt=function(e,r,s,o,u){if(!o&&!u&&!i.test(e)){var a,f,l=!0,c=d,h=r,p=r.nodeType===9&&e;if(r.nodeType===1&&r.nodeName.toLowerCase()!=="object"){a=ut(e),(l=r.getAttribute("id"))?c=l.replace(n,"\\$&"):r.setAttribute("id",c),c="[id='"+c+"'] ",f=a.length;while(f--)a[f]=c+a[f].join("");h=z.test(e)&&r.parentNode||r,p=a.join(",")}if(p)try{return S.apply(s,x.call(h.querySelectorAll(p),0)),s}catch(v){}finally{l||r.removeAttribute("id")}}return t(e,r,s,o,u)},u&&(K(function(t){e=u.call(t,"div");try{u.call(t,"[test!='']:sizzle"),s.push("!=",H)}catch(n){}}),s=new RegExp(s.join("|")),nt.matchesSelector=function(t,n){n=n.replace(r,"='$1']");if(!o(t)&&!s.test(n)&&!i.test(n))try{var a=u.call(t,n);if(a||e||t.document&&t.document.nodeType!==11)return a}catch(f){}return nt(n,null,null,[t]).length>0})}(),i.pseudos.nth=i.pseudos.eq,i.filters=mt.prototype=i.pseudos,i.setFilters=new mt,nt.attr=v.attr,v.find=nt,v.expr=nt.selectors,v.expr[":"]=v.expr.pseudos,v.unique=nt.uniqueSort,v.text=nt.getText,v.isXMLDoc=nt.isXML,v.contains=nt.contains}(e);var nt=/Until$/,rt=/^(?:parents|prev(?:Until|All))/,it=/^.[^:#\[\.,]*$/,st=v.expr.match.needsContext,ot={children:!0,contents:!0,next:!0,prev:!0};v.fn.extend({find:function(e){var t,n,r,i,s,o,u=this;if(typeof e!="string")return v(e).filter(function(){for(t=0,n=u.length;t0)for(i=r;i=0:v.filter(e,this).length>0:this.filter(e).length>0)},closest:function(e,t){var n,r=0,i=this.length,s=[],o=st.test(e)||typeof e!="string"?v(e,t||this.context):0;for(;r-1:v.find.matchesSelector(n,e)){s.push(n);break}n=n.parentNode}}return s=s.length>1?v.unique(s):s,this.pushStack(s,"closest",e)},index:function(e){return e?typeof e=="string"?v.inArray(this[0],v(e)):v.inArray(e.jquery?e[0]:e,this):this[0]&&this[0].parentNode?this.prevAll().length:-1},add:function(e,t){var n=typeof e=="string"?v(e,t):v.makeArray(e&&e.nodeType?[e]:e),r=v.merge(this.get(),n);return this.pushStack(ut(n[0])||ut(r[0])?r:v.unique(r))},addBack:function(e){return this.add(e==null?this.prevObject:this.prevObject.filter(e))}}),v.fn.andSelf=v.fn.addBack,v.each({parent:function(e){var t=e.parentNode;return t&&t.nodeType!==11?t:null},parents:function(e){return v.dir(e,"parentNode")},parentsUntil:function(e,t,n){return v.dir(e,"parentNode",n)},next:function(e){return at(e,"nextSibling")},prev:function(e){return at(e,"previousSibling")},nextAll:function(e){return v.dir(e,"nextSibling")},prevAll:function(e){return v.dir(e,"previousSibling")},nextUntil:function(e,t,n){return v.dir(e,"nextSibling",n)},prevUntil:function(e,t,n){return v.dir(e,"previousSibling",n)},siblings:function(e){return v.sibling((e.parentNode||{}).firstChild,e)},children:function(e){return v.sibling(e.firstChild)},contents:function(e){return v.nodeName(e,"iframe")?e.contentDocument||e.contentWindow.document:v.merge([],e.childNodes)}},function(e,t){v.fn[e]=function(n,r){var i=v.map(this,t,n);return nt.test(e)||(r=n),r&&typeof r=="string"&&(i=v.filter(r,i)),i=this.length>1&&!ot[e]?v.unique(i):i,this.length>1&&rt.test(e)&&(i=i.reverse()),this.pushStack(i,e,l.call(arguments).join(","))}}),v.extend({filter:function(e,t,n){return n&&(e=":not("+e+")"),t.length===1?v.find.matchesSelector(t[0],e)?[t[0]]:[]:v.find.matches(e,t)},dir:function(e,n,r){var i=[],s=e[n];while(s&&s.nodeType!==9&&(r===t||s.nodeType!==1||!v(s).is(r)))s.nodeType===1&&i.push(s),s=s[n];return i},sibling:function(e,t){var n=[];for(;e;e=e.nextSibling)e.nodeType===1&&e!==t&&n.push(e);return n}});var ct="abbr|article|aside|audio|bdi|canvas|data|datalist|details|figcaption|figure|footer|header|hgroup|mark|meter|nav|output|progress|section|summary|time|video",ht=/ jQuery\d+="(?:null|\d+)"/g,pt=/^\s+/,dt=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/gi,vt=/<([\w:]+)/,mt=/]","i"),Et=/^(?:checkbox|radio)$/,St=/checked\s*(?:[^=]|=\s*.checked.)/i,xt=/\/(java|ecma)script/i,Tt=/^\s*\s*$/g,Nt={option:[1,""],legend:[1,"
","
"],thead:[1,"","
"],tr:[2,"","
"],td:[3,"","
"],col:[2,"","
"],area:[1,"",""],_default:[0,"",""]},Ct=lt(i),kt=Ct.appendChild(i.createElement("div"));Nt.optgroup=Nt.option,Nt.tbody=Nt.tfoot=Nt.colgroup=Nt.caption=Nt.thead,Nt.th=Nt.td,v.support.htmlSerialize||(Nt._default=[1,"X
","
"]),v.fn.extend({text:function(e){return v.access(this,function(e){return e===t?v.text(this):this.empty().append((this[0]&&this[0].ownerDocument||i).createTextNode(e))},null,e,arguments.length)},wrapAll:function(e){if(v.isFunction(e))return this.each(function(t){v(this).wrapAll(e.call(this,t))});if(this[0]){var t=v(e,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&t.insertBefore(this[0]),t.map(function(){var e=this;while(e.firstChild&&e.firstChild.nodeType===1)e=e.firstChild;return e}).append(this)}return this},wrapInner:function(e){return v.isFunction(e)?this.each(function(t){v(this).wrapInner(e.call(this,t))}):this.each(function(){var t=v(this),n=t.contents();n.length?n.wrapAll(e):t.append(e)})},wrap:function(e){var t=v.isFunction(e);return this.each(function(n){v(this).wrapAll(t?e.call(this,n):e)})},unwrap:function(){return this.parent().each(function(){v.nodeName(this,"body")||v(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(e){(this.nodeType===1||this.nodeType===11)&&this.appendChild(e)})},prepend:function(){return this.domManip(arguments,!0,function(e){(this.nodeType===1||this.nodeType===11)&&this.insertBefore(e,this.firstChild)})},before:function(){if(!ut(this[0]))return this.domManip(arguments,!1,function(e){this.parentNode.insertBefore(e,this)});if(arguments.length){var e=v.clean(arguments);return this.pushStack(v.merge(e,this),"before",this.selector)}},after:function(){if(!ut(this[0]))return this.domManip(arguments,!1,function(e){this.parentNode.insertBefore(e,this.nextSibling)});if(arguments.length){var e=v.clean(arguments);return this.pushStack(v.merge(this,e),"after",this.selector)}},remove:function(e,t){var n,r=0;for(;(n=this[r])!=null;r++)if(!e||v.filter(e,[n]).length)!t&&n.nodeType===1&&(v.cleanData(n.getElementsByTagName("*")),v.cleanData([n])),n.parentNode&&n.parentNode.removeChild(n);return this},empty:function(){var e,t=0;for(;(e=this[t])!=null;t++){e.nodeType===1&&v.cleanData(e.getElementsByTagName("*"));while(e.firstChild)e.removeChild(e.firstChild)}return this},clone:function(e,t){return e=e==null?!1:e,t=t==null?e:t,this.map(function(){return v.clone(this,e,t)})},html:function(e){return v.access(this,function(e){var n=this[0]||{},r=0,i=this.length;if(e===t)return n.nodeType===1?n.innerHTML.replace(ht,""):t;if(typeof e=="string"&&!yt.test(e)&&(v.support.htmlSerialize||!wt.test(e))&&(v.support.leadingWhitespace||!pt.test(e))&&!Nt[(vt.exec(e)||["",""])[1].toLowerCase()]){e=e.replace(dt,"<$1>");try{for(;r1&&typeof f=="string"&&St.test(f))return this.each(function(){v(this).domManip(e,n,r)});if(v.isFunction(f))return this.each(function(i){var s=v(this);e[0]=f.call(this,i,n?s.html():t),s.domManip(e,n,r)});if(this[0]){i=v.buildFragment(e,this,l),o=i.fragment,s=o.firstChild,o.childNodes.length===1&&(o=s);if(s){n=n&&v.nodeName(s,"tr");for(u=i.cacheable||c-1;a0?this.clone(!0):this).get(),v(o[i])[t](r),s=s.concat(r);return this.pushStack(s,e,o.selector)}}),v.extend({clone:function(e,t,n){var r,i,s,o;v.support.html5Clone||v.isXMLDoc(e)||!wt.test("<"+e.nodeName+">")?o=e.cloneNode(!0):(kt.innerHTML=e.outerHTML,kt.removeChild(o=kt.firstChild));if((!v.support.noCloneEvent||!v.support.noCloneChecked)&&(e.nodeType===1||e.nodeType===11)&&!v.isXMLDoc(e)){Ot(e,o),r=Mt(e),i=Mt(o);for(s=0;r[s];++s)i[s]&&Ot(r[s],i[s])}if(t){At(e,o);if(n){r=Mt(e),i=Mt(o);for(s=0;r[s];++s)At(r[s],i[s])}}return r=i=null,o},clean:function(e,t,n,r){var s,o,u,a,f,l,c,h,p,d,m,g,y=t===i&&Ct,b=[];if(!t||typeof t.createDocumentFragment=="undefined")t=i;for(s=0;(u=e[s])!=null;s++){typeof u=="number"&&(u+="");if(!u)continue;if(typeof u=="string")if(!gt.test(u))u=t.createTextNode(u);else{y=y||lt(t),c=t.createElement("div"),y.appendChild(c),u=u.replace(dt,"<$1>"),a=(vt.exec(u)||["",""])[1].toLowerCase(),f=Nt[a]||Nt._default,l=f[0],c.innerHTML=f[1]+u+f[2];while(l--)c=c.lastChild;if(!v.support.tbody){h=mt.test(u),p=a==="table"&&!h?c.firstChild&&c.firstChild.childNodes:f[1]===""&&!h?c.childNodes:[];for(o=p.length-1;o>=0;--o)v.nodeName(p[o],"tbody")&&!p[o].childNodes.length&&p[o].parentNode.removeChild(p[o])}!v.support.leadingWhitespace&&pt.test(u)&&c.insertBefore(t.createTextNode(pt.exec(u)[0]),c.firstChild),u=c.childNodes,c.parentNode.removeChild(c)}u.nodeType?b.push(u):v.merge(b,u)}c&&(u=c=y=null);if(!v.support.appendChecked)for(s=0;(u=b[s])!=null;s++)v.nodeName(u,"input")?_t(u):typeof u.getElementsByTagName!="undefined"&&v.grep(u.getElementsByTagName("input"),_t);if(n){m=function(e){if(!e.type||xt.test(e.type))return r?r.push(e.parentNode?e.parentNode.removeChild(e):e):n.appendChild(e)};for(s=0;(u=b[s])!=null;s++)if(!v.nodeName(u,"script")||!m(u))n.appendChild(u),typeof u.getElementsByTagName!="undefined"&&(g=v.grep(v.merge([],u.getElementsByTagName("script")),m),b.splice.apply(b,[s+1,0].concat(g)),s+=g.length)}return b},cleanData:function(e,t){var n,r,i,s,o=0,u=v.expando,a=v.cache,f=v.support.deleteExpando,l=v.event.special;for(;(i=e[o])!=null;o++)if(t||v.acceptData(i)){r=i[u],n=r&&a[r];if(n){if(n.events)for(s in n.events)l[s]?v.event.remove(i,s):v.removeEvent(i,s,n.handle);a[r]&&(delete a[r],f?delete i[u]:i.removeAttribute?i.removeAttribute(u):i[u]=null,v.deletedIds.push(r))}}}}),function(){var e,t;v.uaMatch=function(e){e=e.toLowerCase();var t=/(chrome)[ \/]([\w.]+)/.exec(e)||/(webkit)[ \/]([\w.]+)/.exec(e)||/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(e)||/(msie) ([\w.]+)/.exec(e)||e.indexOf("compatible")<0&&/(mozilla)(?:.*? rv:([\w.]+)|)/.exec(e)||[];return{browser:t[1]||"",version:t[2]||"0"}},e=v.uaMatch(o.userAgent),t={},e.browser&&(t[e.browser]=!0,t.version=e.version),t.chrome?t.webkit=!0:t.webkit&&(t.safari=!0),v.browser=t,v.sub=function(){function e(t,n){return new e.fn.init(t,n)}v.extend(!0,e,this),e.superclass=this,e.fn=e.prototype=this(),e.fn.constructor=e,e.sub=this.sub,e.fn.init=function(r,i){return i&&i instanceof v&&!(i instanceof e)&&(i=e(i)),v.fn.init.call(this,r,i,t)},e.fn.init.prototype=e.fn;var t=e(i);return e}}();var Dt,Pt,Ht,Bt=/alpha\([^)]*\)/i,jt=/opacity=([^)]*)/,Ft=/^(top|right|bottom|left)$/,It=/^(none|table(?!-c[ea]).+)/,qt=/^margin/,Rt=new RegExp("^("+m+")(.*)$","i"),Ut=new RegExp("^("+m+")(?!px)[a-z%]+$","i"),zt=new RegExp("^([-+])=("+m+")","i"),Wt={BODY:"block"},Xt={position:"absolute",visibility:"hidden",display:"block"},Vt={letterSpacing:0,fontWeight:400},$t=["Top","Right","Bottom","Left"],Jt=["Webkit","O","Moz","ms"],Kt=v.fn.toggle;v.fn.extend({css:function(e,n){return v.access(this,function(e,n,r){return r!==t?v.style(e,n,r):v.css(e,n)},e,n,arguments.length>1)},show:function(){return Yt(this,!0)},hide:function(){return Yt(this)},toggle:function(e,t){var n=typeof e=="boolean";return v.isFunction(e)&&v.isFunction(t)?Kt.apply(this,arguments):this.each(function(){(n?e:Gt(this))?v(this).show():v(this).hide()})}}),v.extend({cssHooks:{opacity:{get:function(e,t){if(t){var n=Dt(e,"opacity");return n===""?"1":n}}}},cssNumber:{fillOpacity:!0,fontWeight:!0,lineHeight:!0,opacity:!0,orphans:!0,widows:!0,zIndex:!0,zoom:!0},cssProps:{"float":v.support.cssFloat?"cssFloat":"styleFloat"},style:function(e,n,r,i){if(!e||e.nodeType===3||e.nodeType===8||!e.style)return;var s,o,u,a=v.camelCase(n),f=e.style;n=v.cssProps[a]||(v.cssProps[a]=Qt(f,a)),u=v.cssHooks[n]||v.cssHooks[a];if(r===t)return u&&"get"in u&&(s=u.get(e,!1,i))!==t?s:f[n];o=typeof r,o==="string"&&(s=zt.exec(r))&&(r=(s[1]+1)*s[2]+parseFloat(v.css(e,n)),o="number");if(r==null||o==="number"&&isNaN(r))return;o==="number"&&!v.cssNumber[a]&&(r+="px");if(!u||!("set"in u)||(r=u.set(e,r,i))!==t)try{f[n]=r}catch(l){}},css:function(e,n,r,i){var s,o,u,a=v.camelCase(n);return n=v.cssProps[a]||(v.cssProps[a]=Qt(e.style,a)),u=v.cssHooks[n]||v.cssHooks[a],u&&"get"in u&&(s=u.get(e,!0,i)),s===t&&(s=Dt(e,n)),s==="normal"&&n in Vt&&(s=Vt[n]),r||i!==t?(o=parseFloat(s),r||v.isNumeric(o)?o||0:s):s},swap:function(e,t,n){var r,i,s={};for(i in t)s[i]=e.style[i],e.style[i]=t[i];r=n.call(e);for(i in t)e.style[i]=s[i];return r}}),e.getComputedStyle?Dt=function(t,n){var r,i,s,o,u=e.getComputedStyle(t,null),a=t.style;return u&&(r=u.getPropertyValue(n)||u[n],r===""&&!v.contains(t.ownerDocument,t)&&(r=v.style(t,n)),Ut.test(r)&&qt.test(n)&&(i=a.width,s=a.minWidth,o=a.maxWidth,a.minWidth=a.maxWidth=a.width=r,r=u.width,a.width=i,a.minWidth=s,a.maxWidth=o)),r}:i.documentElement.currentStyle&&(Dt=function(e,t){var n,r,i=e.currentStyle&&e.currentStyle[t],s=e.style;return i==null&&s&&s[t]&&(i=s[t]),Ut.test(i)&&!Ft.test(t)&&(n=s.left,r=e.runtimeStyle&&e.runtimeStyle.left,r&&(e.runtimeStyle.left=e.currentStyle.left),s.left=t==="fontSize"?"1em":i,i=s.pixelLeft+"px",s.left=n,r&&(e.runtimeStyle.left=r)),i===""?"auto":i}),v.each(["height","width"],function(e,t){v.cssHooks[t]={get:function(e,n,r){if(n)return e.offsetWidth===0&&It.test(Dt(e,"display"))?v.swap(e,Xt,function(){return tn(e,t,r)}):tn(e,t,r)},set:function(e,n,r){return Zt(e,n,r?en(e,t,r,v.support.boxSizing&&v.css(e,"boxSizing")==="border-box"):0)}}}),v.support.opacity||(v.cssHooks.opacity={get:function(e,t){return jt.test((t&&e.currentStyle?e.currentStyle.filter:e.style.filter)||"")?.01*parseFloat(RegExp.$1)+"":t?"1":""},set:function(e,t){var n=e.style,r=e.currentStyle,i=v.isNumeric(t)?"alpha(opacity="+t*100+")":"",s=r&&r.filter||n.filter||"";n.zoom=1;if(t>=1&&v.trim(s.replace(Bt,""))===""&&n.removeAttribute){n.removeAttribute("filter");if(r&&!r.filter)return}n.filter=Bt.test(s)?s.replace(Bt,i):s+" "+i}}),v(function(){v.support.reliableMarginRight||(v.cssHooks.marginRight={get:function(e,t){return v.swap(e,{display:"inline-block"},function(){if(t)return Dt(e,"marginRight")})}}),!v.support.pixelPosition&&v.fn.position&&v.each(["top","left"],function(e,t){v.cssHooks[t]={get:function(e,n){if(n){var r=Dt(e,t);return Ut.test(r)?v(e).position()[t]+"px":r}}}})}),v.expr&&v.expr.filters&&(v.expr.filters.hidden=function(e){return e.offsetWidth===0&&e.offsetHeight===0||!v.support.reliableHiddenOffsets&&(e.style&&e.style.display||Dt(e,"display"))==="none"},v.expr.filters.visible=function(e){return!v.expr.filters.hidden(e)}),v.each({margin:"",padding:"",border:"Width"},function(e,t){v.cssHooks[e+t]={expand:function(n){var r,i=typeof n=="string"?n.split(" "):[n],s={};for(r=0;r<4;r++)s[e+$t[r]+t]=i[r]||i[r-2]||i[0];return s}},qt.test(e)||(v.cssHooks[e+t].set=Zt)});var rn=/%20/g,sn=/\[\]$/,on=/\r?\n/g,un=/^(?:color|date|datetime|datetime-local|email|hidden|month|number|password|range|search|tel|text|time|url|week)$/i,an=/^(?:select|textarea)/i;v.fn.extend({serialize:function(){return v.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?v.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||an.test(this.nodeName)||un.test(this.type))}).map(function(e,t){var n=v(this).val();return n==null?null:v.isArray(n)?v.map(n,function(e,n){return{name:t.name,value:e.replace(on,"\r\n")}}):{name:t.name,value:n.replace(on,"\r\n")}}).get()}}),v.param=function(e,n){var r,i=[],s=function(e,t){t=v.isFunction(t)?t():t==null?"":t,i[i.length]=encodeURIComponent(e)+"="+encodeURIComponent(t)};n===t&&(n=v.ajaxSettings&&v.ajaxSettings.traditional);if(v.isArray(e)||e.jquery&&!v.isPlainObject(e))v.each(e,function(){s(this.name,this.value)});else for(r in e)fn(r,e[r],n,s);return i.join("&").replace(rn,"+")};var ln,cn,hn=/#.*$/,pn=/^(.*?):[ \t]*([^\r\n]*)\r?$/mg,dn=/^(?:about|app|app\-storage|.+\-extension|file|res|widget):$/,vn=/^(?:GET|HEAD)$/,mn=/^\/\//,gn=/\?/,yn=/)<[^<]*)*<\/script>/gi,bn=/([?&])_=[^&]*/,wn=/^([\w\+\.\-]+:)(?:\/\/([^\/?#:]*)(?::(\d+)|)|)/,En=v.fn.load,Sn={},xn={},Tn=["*/"]+["*"];try{cn=s.href}catch(Nn){cn=i.createElement("a"),cn.href="",cn=cn.href}ln=wn.exec(cn.toLowerCase())||[],v.fn.load=function(e,n,r){if(typeof e!="string"&&En)return En.apply(this,arguments);if(!this.length)return this;var i,s,o,u=this,a=e.indexOf(" ");return a>=0&&(i=e.slice(a,e.length),e=e.slice(0,a)),v.isFunction(n)?(r=n,n=t):n&&typeof n=="object"&&(s="POST"),v.ajax({url:e,type:s,dataType:"html",data:n,complete:function(e,t){r&&u.each(r,o||[e.responseText,t,e])}}).done(function(e){o=arguments,u.html(i?v("
").append(e.replace(yn,"")).find(i):e)}),this},v.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(e,t){v.fn[t]=function(e){return this.on(t,e)}}),v.each(["get","post"],function(e,n){v[n]=function(e,r,i,s){return v.isFunction(r)&&(s=s||i,i=r,r=t),v.ajax({type:n,url:e,data:r,success:i,dataType:s})}}),v.extend({getScript:function(e,n){return v.get(e,t,n,"script")},getJSON:function(e,t,n){return v.get(e,t,n,"json")},ajaxSetup:function(e,t){return t?Ln(e,v.ajaxSettings):(t=e,e=v.ajaxSettings),Ln(e,t),e},ajaxSettings:{url:cn,isLocal:dn.test(ln[1]),global:!0,type:"GET",contentType:"application/x-www-form-urlencoded; charset=UTF-8",processData:!0,async:!0,accepts:{xml:"application/xml, text/xml",html:"text/html",text:"text/plain",json:"application/json, text/javascript","*":Tn},contents:{xml:/xml/,html:/html/,json:/json/},responseFields:{xml:"responseXML",text:"responseText"},converters:{"* text":e.String,"text html":!0,"text json":v.parseJSON,"text xml":v.parseXML},flatOptions:{context:!0,url:!0}},ajaxPrefilter:Cn(Sn),ajaxTransport:Cn(xn),ajax:function(e,n){function T(e,n,s,a){var l,y,b,w,S,T=n;if(E===2)return;E=2,u&&clearTimeout(u),o=t,i=a||"",x.readyState=e>0?4:0,s&&(w=An(c,x,s));if(e>=200&&e<300||e===304)c.ifModified&&(S=x.getResponseHeader("Last-Modified"),S&&(v.lastModified[r]=S),S=x.getResponseHeader("Etag"),S&&(v.etag[r]=S)),e===304?(T="notmodified",l=!0):(l=On(c,w),T=l.state,y=l.data,b=l.error,l=!b);else{b=T;if(!T||e)T="error",e<0&&(e=0)}x.status=e,x.statusText=(n||T)+"",l?d.resolveWith(h,[y,T,x]):d.rejectWith(h,[x,T,b]),x.statusCode(g),g=t,f&&p.trigger("ajax"+(l?"Success":"Error"),[x,c,l?y:b]),m.fireWith(h,[x,T]),f&&(p.trigger("ajaxComplete",[x,c]),--v.active||v.event.trigger("ajaxStop"))}typeof e=="object"&&(n=e,e=t),n=n||{};var r,i,s,o,u,a,f,l,c=v.ajaxSetup({},n),h=c.context||c,p=h!==c&&(h.nodeType||h instanceof v)?v(h):v.event,d=v.Deferred(),m=v.Callbacks("once memory"),g=c.statusCode||{},b={},w={},E=0,S="canceled",x={readyState:0,setRequestHeader:function(e,t){if(!E){var n=e.toLowerCase();e=w[n]=w[n]||e,b[e]=t}return this},getAllResponseHeaders:function(){return E===2?i:null},getResponseHeader:function(e){var n;if(E===2){if(!s){s={};while(n=pn.exec(i))s[n[1].toLowerCase()]=n[2]}n=s[e.toLowerCase()]}return n===t?null:n},overrideMimeType:function(e){return E||(c.mimeType=e),this},abort:function(e){return e=e||S,o&&o.abort(e),T(0,e),this}};d.promise(x),x.success=x.done,x.error=x.fail,x.complete=m.add,x.statusCode=function(e){if(e){var t;if(E<2)for(t in e)g[t]=[g[t],e[t]];else t=e[x.status],x.always(t)}return this},c.url=((e||c.url)+"").replace(hn,"").replace(mn,ln[1]+"//"),c.dataTypes=v.trim(c.dataType||"*").toLowerCase().split(y),c.crossDomain==null&&(a=wn.exec(c.url.toLowerCase()),c.crossDomain=!(!a||a[1]===ln[1]&&a[2]===ln[2]&&(a[3]||(a[1]==="http:"?80:443))==(ln[3]||(ln[1]==="http:"?80:443)))),c.data&&c.processData&&typeof c.data!="string"&&(c.data=v.param(c.data,c.traditional)),kn(Sn,c,n,x);if(E===2)return x;f=c.global,c.type=c.type.toUpperCase(),c.hasContent=!vn.test(c.type),f&&v.active++===0&&v.event.trigger("ajaxStart");if(!c.hasContent){c.data&&(c.url+=(gn.test(c.url)?"&":"?")+c.data,delete c.data),r=c.url;if(c.cache===!1){var N=v.now(),C=c.url.replace(bn,"$1_="+N);c.url=C+(C===c.url?(gn.test(c.url)?"&":"?")+"_="+N:"")}}(c.data&&c.hasContent&&c.contentType!==!1||n.contentType)&&x.setRequestHeader("Content-Type",c.contentType),c.ifModified&&(r=r||c.url,v.lastModified[r]&&x.setRequestHeader("If-Modified-Since",v.lastModified[r]),v.etag[r]&&x.setRequestHeader("If-None-Match",v.etag[r])),x.setRequestHeader("Accept",c.dataTypes[0]&&c.accepts[c.dataTypes[0]]?c.accepts[c.dataTypes[0]]+(c.dataTypes[0]!=="*"?", "+Tn+"; q=0.01":""):c.accepts["*"]);for(l in c.headers)x.setRequestHeader(l,c.headers[l]);if(!c.beforeSend||c.beforeSend.call(h,x,c)!==!1&&E!==2){S="abort";for(l in{success:1,error:1,complete:1})x[l](c[l]);o=kn(xn,c,n,x);if(!o)T(-1,"No Transport");else{x.readyState=1,f&&p.trigger("ajaxSend",[x,c]),c.async&&c.timeout>0&&(u=setTimeout(function(){x.abort("timeout")},c.timeout));try{E=1,o.send(b,T)}catch(k){if(!(E<2))throw k;T(-1,k)}}return x}return x.abort()},active:0,lastModified:{},etag:{}});var Mn=[],_n=/\?/,Dn=/(=)\?(?=&|$)|\?\?/,Pn=v.now();v.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Mn.pop()||v.expando+"_"+Pn++;return this[e]=!0,e}}),v.ajaxPrefilter("json jsonp",function(n,r,i){var s,o,u,a=n.data,f=n.url,l=n.jsonp!==!1,c=l&&Dn.test(f),h=l&&!c&&typeof a=="string"&&!(n.contentType||"").indexOf("application/x-www-form-urlencoded")&&Dn.test(a);if(n.dataTypes[0]==="jsonp"||c||h)return s=n.jsonpCallback=v.isFunction(n.jsonpCallback)?n.jsonpCallback():n.jsonpCallback,o=e[s],c?n.url=f.replace(Dn,"$1"+s):h?n.data=a.replace(Dn,"$1"+s):l&&(n.url+=(_n.test(f)?"&":"?")+n.jsonp+"="+s),n.converters["script json"]=function(){return u||v.error(s+" was not called"),u[0]},n.dataTypes[0]="json",e[s]=function(){u=arguments},i.always(function(){e[s]=o,n[s]&&(n.jsonpCallback=r.jsonpCallback,Mn.push(s)),u&&v.isFunction(o)&&o(u[0]),u=o=t}),"script"}),v.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/javascript|ecmascript/},converters:{"text script":function(e){return v.globalEval(e),e}}}),v.ajaxPrefilter("script",function(e){e.cache===t&&(e.cache=!1),e.crossDomain&&(e.type="GET",e.global=!1)}),v.ajaxTransport("script",function(e){if(e.crossDomain){var n,r=i.head||i.getElementsByTagName("head")[0]||i.documentElement;return{send:function(s,o){n=i.createElement("script"),n.async="async",e.scriptCharset&&(n.charset=e.scriptCharset),n.src=e.url,n.onload=n.onreadystatechange=function(e,i){if(i||!n.readyState||/loaded|complete/.test(n.readyState))n.onload=n.onreadystatechange=null,r&&n.parentNode&&r.removeChild(n),n=t,i||o(200,"success")},r.insertBefore(n,r.firstChild)},abort:function(){n&&n.onload(0,1)}}}});var Hn,Bn=e.ActiveXObject?function(){for(var e in Hn)Hn[e](0,1)}:!1,jn=0;v.ajaxSettings.xhr=e.ActiveXObject?function(){return!this.isLocal&&Fn()||In()}:Fn,function(e){v.extend(v.support,{ajax:!!e,cors:!!e&&"withCredentials"in e})}(v.ajaxSettings.xhr()),v.support.ajax&&v.ajaxTransport(function(n){if(!n.crossDomain||v.support.cors){var r;return{send:function(i,s){var o,u,a=n.xhr();n.username?a.open(n.type,n.url,n.async,n.username,n.password):a.open(n.type,n.url,n.async);if(n.xhrFields)for(u in n.xhrFields)a[u]=n.xhrFields[u];n.mimeType&&a.overrideMimeType&&a.overrideMimeType(n.mimeType),!n.crossDomain&&!i["X-Requested-With"]&&(i["X-Requested-With"]="XMLHttpRequest");try{for(u in i)a.setRequestHeader(u,i[u])}catch(f){}a.send(n.hasContent&&n.data||null),r=function(e,i){var u,f,l,c,h;try{if(r&&(i||a.readyState===4)){r=t,o&&(a.onreadystatechange=v.noop,Bn&&delete Hn[o]);if(i)a.readyState!==4&&a.abort();else{u=a.status,l=a.getAllResponseHeaders(),c={},h=a.responseXML,h&&h.documentElement&&(c.xml=h);try{c.text=a.responseText}catch(p){}try{f=a.statusText}catch(p){f=""}!u&&n.isLocal&&!n.crossDomain?u=c.text?200:404:u===1223&&(u=204)}}}catch(d){i||s(-1,d)}c&&s(u,f,c,l)},n.async?a.readyState===4?setTimeout(r,0):(o=++jn,Bn&&(Hn||(Hn={},v(e).unload(Bn)),Hn[o]=r),a.onreadystatechange=r):r()},abort:function(){r&&r(0,1)}}}});var qn,Rn,Un=/^(?:toggle|show|hide)$/,zn=new RegExp("^(?:([-+])=|)("+m+")([a-z%]*)$","i"),Wn=/queueHooks$/,Xn=[Gn],Vn={"*":[function(e,t){var n,r,i=this.createTween(e,t),s=zn.exec(t),o=i.cur(),u=+o||0,a=1,f=20;if(s){n=+s[2],r=s[3]||(v.cssNumber[e]?"":"px");if(r!=="px"&&u){u=v.css(i.elem,e,!0)||n||1;do a=a||".5",u/=a,v.style(i.elem,e,u+r);while(a!==(a=i.cur()/o)&&a!==1&&--f)}i.unit=r,i.start=u,i.end=s[1]?u+(s[1]+1)*n:n}return i}]};v.Animation=v.extend(Kn,{tweener:function(e,t){v.isFunction(e)?(t=e,e=["*"]):e=e.split(" ");var n,r=0,i=e.length;for(;r-1,f={},l={},c,h;a?(l=i.position(),c=l.top,h=l.left):(c=parseFloat(o)||0,h=parseFloat(u)||0),v.isFunction(t)&&(t=t.call(e,n,s)),t.top!=null&&(f.top=t.top-s.top+c),t.left!=null&&(f.left=t.left-s.left+h),"using"in t?t.using.call(e,f):i.css(f)}},v.fn.extend({position:function(){if(!this[0])return;var e=this[0],t=this.offsetParent(),n=this.offset(),r=er.test(t[0].nodeName)?{top:0,left:0}:t.offset();return n.top-=parseFloat(v.css(e,"marginTop"))||0,n.left-=parseFloat(v.css(e,"marginLeft"))||0,r.top+=parseFloat(v.css(t[0],"borderTopWidth"))||0,r.left+=parseFloat(v.css(t[0],"borderLeftWidth"))||0,{top:n.top-r.top,left:n.left-r.left}},offsetParent:function(){return this.map(function(){var e=this.offsetParent||i.body;while(e&&!er.test(e.nodeName)&&v.css(e,"position")==="static")e=e.offsetParent;return e||i.body})}}),v.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(e,n){var r=/Y/.test(n);v.fn[e]=function(i){return v.access(this,function(e,i,s){var o=tr(e);if(s===t)return o?n in o?o[n]:o.document.documentElement[i]:e[i];o?o.scrollTo(r?v(o).scrollLeft():s,r?s:v(o).scrollTop()):e[i]=s},e,i,arguments.length,null)}}),v.each({Height:"height",Width:"width"},function(e,n){v.each({padding:"inner"+e,content:n,"":"outer"+e},function(r,i){v.fn[i]=function(i,s){var o=arguments.length&&(r||typeof i!="boolean"),u=r||(i===!0||s===!0?"margin":"border");return v.access(this,function(n,r,i){var s;return v.isWindow(n)?n.document.documentElement["client"+e]:n.nodeType===9?(s=n.documentElement,Math.max(n.body["scroll"+e],s["scroll"+e],n.body["offset"+e],s["offset"+e],s["client"+e])):i===t?v.css(n,r,i,u):v.style(n,r,i,u)},n,o?i:t,o,null)}})}),e.jQuery=e.$=v,typeof define=="function"&&define.amd&&define.amd.jQuery&&define("jquery",[],function(){return v})})(window); \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/minus.png Binary file components/jansson/doc/html/_static/minus.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/plus.png Binary file components/jansson/doc/html/_static/plus.png has changed diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/pygments.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_static/pygments.css Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,62 @@ +.highlight .hll { background-color: #ffffcc } +.highlight { background: #eeffcc; } +.highlight .c { color: #408090; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #333333 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #208050 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mf { color: #208050 } /* Literal.Number.Float */ +.highlight .mh { color: #208050 } /* Literal.Number.Hex */ +.highlight .mi { color: #208050 } /* Literal.Number.Integer */ +.highlight .mo { color: #208050 } /* Literal.Number.Oct */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/_static/searchtools.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/_static/searchtools.js Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,622 @@ +/* + * searchtools.js_t + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilties for the full-text search. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + + +/** + * Simple result scoring code. + */ +var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [filename, title, anchor, descr, score] + // and returns the new score. + /* + score: function(result) { + return result[4]; + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: {0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5}, // used to be unimportantResults + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + // query found in terms + term: 5 +}; + + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + loadIndex : function(url) { + $.ajax({type: "GET", url: url, data: null, + dataType: "script", cache: true, + complete: function(jqxhr, textstatus) { + if (textstatus != "success") { + document.getElementById("searchindexloader").src = url; + } + }}); + }, + + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + var i; + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + } + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('

' + _('Searching') + '

').appendTo(this.out); + this.dots = $('').appendTo(this.title); + this.status = $('

').appendTo(this.out); + this.output = $('
'); + } + // Prettify the comment rating. + comment.pretty_rating = comment.rating + ' point' + + (comment.rating == 1 ? '' : 's'); + // Make a class (for displaying not yet moderated comments differently) + comment.css_class = comment.displayed ? '' : ' moderate'; + // Create a div for this comment. + var context = $.extend({}, opts, comment); + var div = $(renderTemplate(commentTemplate, context)); + + // If the user has voted on this comment, highlight the correct arrow. + if (comment.vote) { + var direction = (comment.vote == 1) ? 'u' : 'd'; + div.find('#' + direction + 'v' + comment.id).hide(); + div.find('#' + direction + 'u' + comment.id).show(); + } + + if (opts.moderator || comment.text != '[deleted]') { + div.find('a.reply').show(); + if (comment.proposal_diff) + div.find('#sp' + comment.id).show(); + if (opts.moderator && !comment.displayed) + div.find('#cm' + comment.id).show(); + if (opts.moderator || (opts.username == comment.username)) + div.find('#dc' + comment.id).show(); + } + return div; + } + + /** + * A simple template renderer. Placeholders such as <%id%> are replaced + * by context['id'] with items being escaped. Placeholders such as <#id#> + * are not escaped. + */ + function renderTemplate(template, context) { + var esc = $(document.createElement('div')); + + function handle(ph, escape) { + var cur = context; + $.each(ph.split('.'), function() { + cur = cur[this]; + }); + return escape ? esc.text(cur || "").html() : cur; + } + + return template.replace(/<([%#])([\w\.]*)\1>/g, function() { + return handle(arguments[2], arguments[1] == '%' ? true : false); + }); + } + + /** Flash an error message briefly. */ + function showError(message) { + $(document.createElement('div')).attr({'class': 'popup-error'}) + .append($(document.createElement('div')) + .attr({'class': 'error-message'}).text(message)) + .appendTo('body') + .fadeIn("slow") + .delay(2000) + .fadeOut("slow"); + } + + /** Add a link the user uses to open the comments popup. */ + $.fn.comment = function() { + return this.each(function() { + var id = $(this).attr('id').substring(1); + var count = COMMENT_METADATA[id]; + var title = count + ' comment' + (count == 1 ? '' : 's'); + var image = count > 0 ? opts.commentBrightImage : opts.commentImage; + var addcls = count == 0 ? ' nocomment' : ''; + $(this) + .append( + $(document.createElement('a')).attr({ + href: '#', + 'class': 'sphinx-comment-open' + addcls, + id: 'ao' + id + }) + .append($(document.createElement('img')).attr({ + src: image, + alt: 'comment', + title: title + })) + .click(function(event) { + event.preventDefault(); + show($(this).attr('id').substring(2)); + }) + ) + .append( + $(document.createElement('a')).attr({ + href: '#', + 'class': 'sphinx-comment-close hidden', + id: 'ah' + id + }) + .append($(document.createElement('img')).attr({ + src: opts.closeCommentImage, + alt: 'close', + title: 'close' + })) + .click(function(event) { + event.preventDefault(); + hide($(this).attr('id').substring(2)); + }) + ); + }); + }; + + var opts = { + processVoteURL: '/_process_vote', + addCommentURL: '/_add_comment', + getCommentsURL: '/_get_comments', + acceptCommentURL: '/_accept_comment', + deleteCommentURL: '/_delete_comment', + commentImage: '/static/_static/comment.png', + closeCommentImage: '/static/_static/comment-close.png', + loadingImage: '/static/_static/ajax-loader.gif', + commentBrightImage: '/static/_static/comment-bright.png', + upArrow: '/static/_static/up.png', + downArrow: '/static/_static/down.png', + upArrowPressed: '/static/_static/up-pressed.png', + downArrowPressed: '/static/_static/down-pressed.png', + voting: false, + moderator: false + }; + + if (typeof COMMENT_OPTIONS != "undefined") { + opts = jQuery.extend(opts, COMMENT_OPTIONS); + } + + var popupTemplate = '\ +
\ +

\ + Sort by:\ + best rated\ + newest\ + oldest\ +

\ +
Comments
\ +
\ + loading comments...
\ +
    \ +
    \ +

    Add a comment\ + (markup):

    \ +
    \ + reStructured text markup: *emph*, **strong**, \ + ``code``, \ + code blocks: :: and an indented block after blank line
    \ +
    \ + \ +

    \ + \ + Propose a change ▹\ + \ + \ + Propose a change ▿\ + \ +

    \ + \ + \ + \ + \ + \ +
    \ +
    '; + + var commentTemplate = '\ +
    \ +
    \ +
    \ + \ + \ + \ + \ + \ + \ +
    \ +
    \ + \ + \ + \ + \ + \ + \ +
    \ +
    \ +
    \ +

    \ + <%username%>\ + <%pretty_rating%>\ + <%time.delta%>\ +

    \ +
    <#text#>
    \ +

    \ + \ + reply ▿\ + proposal ▹\ + proposal ▿\ + \ + \ +

    \ + 
    \
+<#proposal_diff#>\
+
    \ +
      \ +
      \ +
      \ +
      \ + '; + + var replyTemplate = '\ +
    • \ +
      \ +
      \ + \ + \ + \ + \ + \ + \ +
      \ +
      • '; + + $(document).ready(function() { + init(); + }); +})(jQuery); + +$(document).ready(function() { + // add comment anchors for all paragraphs that are commentable + $('.sphinx-has-comment').comment(); + + // highlight search words in search results + $("div.context").each(function() { + var params = $.getQueryParameters(); + var terms = (params.q) ? params.q[0].split(/\s+/) : []; + var result = $(this); + $.each(terms, function() { + result.highlightText(this.toLowerCase(), 'highlighted'); + }); + }); + + // directly open comment window if requested + var anchor = document.location.hash; + if (anchor.substring(0, 9) == '#comment-') { + $('#ao' + anchor.substring(9)).click(); + document.location.hash = '#s' + anchor.substring(9); + } +}); diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/apiref.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/apiref.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,1785 @@ + + + + + + + + API Reference — Jansson 2.7 documentation + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      API Reference¶

      +
      +

      Preliminaries¶

      +

      All declarations are in 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.

      +
      +
      +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 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:

      +
      +
      +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.

      + + +
      +
      +int json_typeof(const json_t *json)¶
      +

      Return the type of the JSON value (a json_type cast to +int). json MUST NOT be NULL. This function is actually +implemented as a macro for speed.

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +json_boolean_value(const json_t *json)¶
      +

      Alias of json_is_true(), i.e. returns 1 for JSON_TRUE +and 0 otherwise.

      +
      +

      New in version 2.7.

      +
      +
      + + +
      +

      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.

      +
      +
      +json_t *json_incref(json_t *json)¶
      +

      Increment the reference count of json if it’s not NULL. +Returns json.

      +
      + +
      +
      +void json_decref(json_t *json)¶
      +

      Decrement the reference count of json. As soon as a call to +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 json_incref(). As soon as +the value is no longer needed, 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 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 json_decref(). By using a reference stealing +function json_array_append_new() instead of +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 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 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 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.

      +
      +
      +json_t *json_true(void)¶
      +
      Return value: New reference.

      Returns the JSON true value.

      +
      + +
      +
      +json_t *json_false(void)¶
      +
      Return value: New reference.

      Returns the JSON false value.

      +
      + +
      +
      +json_t *json_boolean(val)¶
      +
      Return value: New reference.

      Returns JSON false if val is zero, and JSON true otherwise. +This is a macro, and equivalent to val ? json_true() : +json_false().

      +
      +

      New in version 2.4.

      +
      +
      + +
      +
      +json_t *json_null(void)¶
      +
      Return value: New reference.

      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). All Unicode +codepoints U+0000 through U+10FFFF are allowed, but you must use +length-aware functions if you wish to embed NUL bytes in strings.

      +
      +
      +json_t *json_string(const char *value)¶
      +
      Return value: New reference.

      Returns a new JSON string, or NULL on error. value must be a +valid null terminated UTF-8 encoded Unicode string.

      +
      + +
      +
      +json_t *json_stringn(const char *value, size_t len)¶
      +
      Return value: New reference.

      Like json_string(), but with explicit length, so value may +contain null characters or not be null terminated.

      +
      + +
      +
      +json_t *json_string_nocheck(const char *value)¶
      +
      Return value: New reference.

      Like 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).

      +
      + +
      +
      +json_t *json_stringn_nocheck(const char *value, size_t len)¶
      +
      Return value: New reference.

      Like json_string_nocheck(), but with explicit length, so +value may contain null characters or not be null terminated.

      +
      + +
      +
      +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.

      +
      + +
      +
      +size_t json_string_length(const json_t *string)¶
      +

      Returns the length of string in its UTF-8 presentation, or zero +if string is not a JSON string.

      +
      + +
      +
      +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.

      +
      + +
      +
      +int json_string_setn(json_t *string, const char *value, size_t len)¶
      +

      Like json_string_set(), but with explicit length, so value +may contain null characters or not be null terminated.

      +
      + +
      +
      +int json_string_set_nocheck(const json_t *string, const char *value)¶
      +

      Like 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).

      +
      + +
      +
      +int json_string_setn_nocheck(json_t *string, const char *value, size_t len)¶
      +

      Like json_string_set_nocheck(), but with explicit length, +so value may contain null characters or not be null terminated.

      +
      + +
      +
      +

      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 RFC Conformance.

      +
      +
      +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 +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 printf() conversion +specifier that corresponds to json_int_t, without the +leading % sign, i.e. either "lld" or "ld". This macro +is required because the actual type of json_int_t can be +either long or long long, and printf() reuiqres +different length modifiers for the two.

      +

      Example:

      +
      json_int_t x = 123123123;
+printf("x is %" JSON_INTEGER_FORMAT "\n", x);
+
      +
      +
      +
      +
      +
      +json_t *json_integer(json_int_t value)¶
      +
      Return value: New reference.

      Returns a new JSON integer, or NULL on error.

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +json_t *json_real(double value)¶
      +
      Return value: New reference.

      Returns a new JSON real, or NULL on error.

      +
      + +
      +
      +double json_real_value(const json_t *real)¶
      +

      Returns the associated value of real, or 0.0 if real is not a +JSON real.

      +
      + +
      +
      +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:

      +
      +
      +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.

      +
      +
      +json_t *json_array(void)¶
      +
      Return value: New reference.

      Returns a new JSON array, or NULL on error. Initially, the array +is empty.

      +
      + +
      +
      +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.

      +
      + +
      +
      +json_t *json_array_get(const json_t *array, size_t index)¶
      +
      Return value: Borrowed reference.

      Returns the element in array at position index. The valid range +for index is from 0 to the return value of +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.

      +
      + +
      +
      +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 +json_array_size() minus 1. Returns 0 on success and -1 on +error.

      +
      + +
      +
      +int json_array_set_new(json_t *array, size_t index, json_t *value)¶
      +

      Like json_array_set() but steals the reference to value. +This is useful when value is newly created and not used after +the call.

      +
      + +
      +
      +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.

      +
      + +
      +
      +int json_array_append_new(json_t *array, json_t *value)¶
      +

      Like json_array_append() but steals the reference to +value. This is useful when value is newly created and not used +after the call.

      +
      + +
      +
      +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.

      +
      + +
      +
      +int json_array_insert_new(json_t *array, size_t index, json_t *value)¶
      +

      Like json_array_insert() but steals the reference to +value. This is useful when value is newly created and not used +after the call.

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      +
      +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 size_t and +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.

      +
      +

      New in version 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.

      +

      Even though NUL bytes are allowed in string values, they are not +allowed in object keys.

      +
      +
      +json_t *json_object(void)¶
      +
      Return value: New reference.

      Returns a new JSON object, or NULL on error. Initially, the +object is empty.

      +
      + +
      +
      +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.

      +
      + +
      +
      +json_t *json_object_get(const json_t *object, const char *key)¶
      +
      Return value: Borrowed reference.

      Get a value corresponding to key from object. Returns NULL if +key is not found and on error.

      +
      + +
      +
      +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.

      +
      + +
      +
      +int json_object_set_nocheck(json_t *object, const char *key, json_t *value)¶
      +

      Like 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).

      +
      + +
      +
      +int json_object_set_new(json_t *object, const char *key, json_t *value)¶
      +

      Like json_object_set() but steals the reference to +value. This is useful when value is newly created and not used +after the call.

      +
      + +
      +
      +int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)¶
      +

      Like 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).

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +int json_object_update_existing(json_t *object, json_t *other)¶
      +

      Like 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.

      +
      +

      New in version 2.3.

      +
      +
      + +
      +
      +int json_object_update_missing(json_t *object, json_t *other)¶
      +

      Like 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.

      +
      +

      New in version 2.3.

      +
      +
      + +

      The following macro can be used to iterate through all key-value pairs +in an object.

      +
      +
      +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 const char * and +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.

      +
      +

      New in version 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.

      +
      +
      +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.

      +
      + +
      +
      +void *json_object_iter_at(json_t *object, const char *key)¶
      +

      Like 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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +const char *json_object_iter_key(void *iter)¶
      +

      Extract the associated key from iter.

      +
      + +
      +
      +json_t *json_object_iter_value(void *iter)¶
      +
      Return value: Borrowed reference.

      Extract the associated value from iter.

      +
      + +
      +
      +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.

      +
      + +
      +
      +int json_object_iter_set_new(json_t *object, void *iter, json_t *value)¶
      +

      Like json_object_iter_set(), but steals the reference to +value. This is useful when value is newly created and not used +after the call.

      +
      + +
      +
      +void *json_object_key_to_iter(const char *key)¶
      +

      Like json_object_iter_at(), but much faster. Only works for +values returned by json_object_iter_key(). Using other keys +will lead to segfaults. This function is used internally to +implement json_object_foreach().

      +
      +

      New in version 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);
+}
+
      +
      +
      +
      +void json_object_seed(size_t seed)¶
      +

      Seed the hash function used in Jansson’s hashtable implementation. +The seed is used to randomize the hash function so that an +attacker cannot control its output.

      +

      If seed is 0, Jansson generates the seed itselfy by reading +random data from the operating system’s entropy sources. If no +entropy sources are available, falls back to using a combination +of the current timestamp (with microsecond precision if possible) +and the process ID.

      +

      If called at all, this function must be called before any calls to +json_object(), either explicit or implicit. If this +function is not called by the user, the first call to +json_object() (either explicit or implicit) seeds the hash +function. See Thread safety for notes on thread +safety.

      +

      If repeatable results are required, for e.g. unit tests, the hash +function can be “unrandomized” by calling json_object_seed() +with a constant value on program startup, e.g. +json_object_seed(1).

      +
      +

      New in version 2.6.

      +
      +
      + +
      +
      +

      Error reporting¶

      +

      Jansson uses a single struct type to pass error information to the +user. See sections Decoding, Building Values and +Parsing and Validating Values for functions that pass error information using +this struct.

      +
      +
      +json_error_t¶
      +
      +
      +char text[]
      +

      The error message (in UTF-8), or an empty string if a message is +not available.

      +
      + +
      +
      +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>).

      +
      + +
      +
      +int line¶
      +

      The line number on which the error occurred.

      +
      + +
      +
      +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.

      +
      + +
      +
      +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 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 Decoding for more info.

      +

      All functions also accept NULL as the 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.

      +

      The JSON_MAX_INDENT constant defines the maximum indentation +that can be used, and its value is 31.

      +
      +

      Changed in version 2.7: Added JSON_MAX_INDENT.

      +
      +
      +
      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.

      +
      +

      New in version 2.1.

      +
      +
      +
      JSON_ESCAPE_SLASH
      +

      Escape the / characters in strings with \/.

      +
      +

      New in version 2.4.

      +
      +
      +
      JSON_REAL_PRECISION(n)
      +

      Output all real numbers with at most n digits of precision. The +valid range for n is between 0 and 31 (inclusive), and other +values result in an undefined behavior.

      +

      By default, the precision is 17, to correctly and losslessly encode +all IEEE 754 double precision floating point numbers.

      +
      +

      New in version 2.7.

      +
      +
      +
      +

      The following functions perform the actual JSON encoding. The result +is in UTF-8.

      +
      +
      +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 free().

      +
      + +
      +
      +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.

      +
      + +
      +
      +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.

      +
      + +
      +
      +json_dump_callback_t¶
      +

      A typedef for a function that’s called by +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 +json_dump_callback() argument passed through.

      +

      On error, the function should return -1 to stop the encoding +process. On success, it should return 0.

      +
      +

      New in version 2.2.

      +
      +
      + +
      +
      +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.

      +
      +

      New in version 2.2.

      +
      +
      + +
      +
      +

      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 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.

      +
      +

      New in version 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.

      +
      +

      New in version 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.

      +
      +

      New in version 2.1.

      +
      +
      +
      JSON_DECODE_INT_AS_REAL
      +

      JSON defines only one number type. Jansson distinguishes between +ints and reals. For more information see 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.

      +
      +

      New in version 2.5.

      +
      +
      +
      JSON_ALLOW_NUL
      +

      Allow \u0000 escape inside string values. This is a safety +measure; If you know your input can contain NUL bytes, use this +flag. If you don’t use this flag, you don’t have to worry about NUL +bytes inside strings unless you explicitly create themselves by +using e.g. json_stringn() or s# format specifier for +json_pack().

      +

      Object keys cannot have embedded NUL bytes even if this flag is +used.

      +
      +

      New in version 2.6.

      +
      +
      +
      +

      Each function also takes an optional 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.

      +
      +

      New in version 2.3: Number of bytes of input read is written to the position field +of the json_error_t structure.

      +
      +

      If no error or position information is needed, you can pass NULL.

      +

      The following functions perform the actual JSON decoding.

      +
      +
      +json_t *json_loads(const char *input, size_t flags, json_error_t *error)¶
      +
      Return value: New reference.

      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.

      +
      + +
      +
      +json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)¶
      +
      Return value: New reference.

      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 json_loads() except that the string doesn’t +need to be null-terminated. flags is described above.

      +
      +

      New in version 2.1.

      +
      +
      + +
      +
      +json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)¶
      +
      Return value: New reference.

      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 json_loadf() on the same FILE object +multiple times, if the input consists of consecutive JSON texts, +possibly separated by whitespace.

      +
      + +
      +
      +json_t *json_load_file(const char *path, size_t flags, json_error_t *error)¶
      +
      Return value: New reference.

      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.

      +
      + +
      +
      +json_load_callback_t¶
      +

      A typedef for a function that’s called by +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 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.

      +
      +

      New in version 2.4.

      +
      +
      + +
      +
      +json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error)¶
      +
      Return value: New reference.

      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.

      +
      +

      New in version 2.4.

      +
      +
      + +
      +
      +

      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.

      +
      +

      New in version 2.5.

      +
      +
      +
      s% (string) [const char *, size_t]
      +

      Like s# but the length argument is of type size_t.

      +
      +

      New in version 2.6.

      +
      +
      +
      + [const char *]
      +

      Like s, but concatenate to the previous string. Only valid +after s, s#, + or +#.

      +
      +

      New in version 2.5.

      +
      +
      +
      +# [const char *, int]
      +

      Like s#, but concatenate to the previous string. Only valid +after s, s#, + or +#.

      +
      +

      New in version 2.5.

      +
      +
      +
      +% (string) [const char *, size_t]
      +

      Like +# but the length argument is of type size_t.

      +
      +

      New in version 2.6.

      +
      +
      +
      n (null)
      +
      Output a JSON null value. No argument is consumed.
      +
      b (boolean) [int]
      +
      Convert a C int to JSON boolean value. Zero is converted +to false and non-zero to true.
      +
      i (integer) [int]
      +
      Convert a C int to JSON integer.
      +
      I (integer) [json_int_t]
      +
      Convert a C json_int_t to JSON integer.
      +
      f (real) [double]
      +
      Convert a C 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:

      +
      +
      +json_t *json_pack(const char *fmt, ...)¶
      +
      Return value: New reference.

      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.

      +
      + +
      +
      +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)¶
      +
      Return value: New reference.

      Like 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");
+
      +
      +
      +
      +

      Parsing and Validating Values¶

      +

      This section describes functions that help to validate complex values +and extract, or unpack, data from them. Like 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. 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 +json_string_value() internally, so it exists as long as +there are still references to the corresponding JSON string.
      +
      s% (string) [const char *, size_t *]
      +

      Convert a JSON string to a pointer to a NULL terminated UTF-8 +string and its length.

      +
      +

      New in version 2.6.

      +
      +
      +
      n (null)
      +
      Expect a JSON null value. Nothing is extracted.
      +
      b (boolean) [int]
      +
      Convert a JSON boolean value to a C int, so that true +is converted to 1 and false to 0.
      +
      i (integer) [int]
      +
      Convert a JSON integer to C int.
      +
      I (integer) [json_int_t]
      +
      Convert a JSON integer to C json_int_t.
      +
      f (real) [double]
      +
      Convert a JSON real to C double.
      +
      F (integer or real) [double]
      +
      Convert a JSON number (integer or real) to C double.
      +
      o (any value) [json_t *]
      +
      Store a JSON value with no conversion to a 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.

      +
      +

      New in version 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:

      +
      +
      +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.

      +
      + +
      +
      +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 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.

      +
      +
      +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.

      +
      +
      +json_t *json_copy(json_t *value)¶
      +
      Return value: New reference.

      Returns a shallow copy of value, or NULL on error.

      +
      + +
      +
      +json_t *json_deep_copy(const json_t *value)¶
      +
      Return value: New reference.

      Returns a deep copy of value, or NULL on error.

      +
      + +
      +
      +

      Custom Memory Allocation¶

      +

      By default, Jansson uses malloc() and free() for +memory allocation. These functions can be overridden if custom +behavior is needed.

      +
      +
      +json_malloc_t¶
      +

      A typedef for a function pointer with malloc()‘s +signature:

      +
      typedef void *(*json_malloc_t)(size_t);
+
      +
      +
      + +
      +
      +json_free_t¶
      +

      A typedef for a function pointer with free()‘s +signature:

      +
      typedef void (*json_free_t)(void *);
+
      +
      +
      + +
      +
      +void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn)¶
      +

      Use malloc_fn instead of malloc() and free_fn instead +of 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 malloc() and 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);
+
      +
      +

      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 + 8);
+    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 guaranteed_memset() function used +in the example and gives a sample implementation for it.

      +
      + + + + + + +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      Portability

      +

      Next topic

      +

      Changes in Jansson

      +

      This Page

      + + + +
      +
      +
      + +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/changes.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/changes.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,720 @@ + + + + + + + + Changes in Jansson — Jansson 2.7 documentation + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      Changes in Jansson¶

      +
      +

      Version 2.7¶

      +

      Released 2014-10-02

      +
        +
      • New features:
          +
        • json_pack() and friends: Add format specifiers s% and +% +for a size_t string length (#141).
          • +
        • json_unpack() and friends: Add format specifier s% for +unpacking the string length along with the string itself (#141).
          • +
        • Add length-aware string constructors json_stringn() and +json_stringn_nocheck(), length-aware string mutators +json_string_setn() and json_string_setn_nocheck(), and a +function for getting string’s length json_string_length() (#141, +#143).
          • +
        • Support \u0000 escapes in the decoder. The support can be +enabled by using the JSON_ALLOW_NUL decoding flag (#141).
          • +
        • Add json_boolean_value() as an alias for json_is_true() +(#146).
          • +
        • Add JSON_REAL_PRECISION encoding flag/macro for controlling real +number precision (#178).
          • +
        • Define the maximum indentation as JSON_MAX_INDENT (#191).
          • +
        +
        • +
      • Bug fixes:
          +
        • Some malformed \uNNNN escapes could crash the decoder with an +assertion failure.
          • +
        • Avoid integer overflows with very long strings in UTF-8 decoder and +hashtable.
          • +
        • Check for NULL key in json_object_get() and +json_object_del() (#151).
          • +
        • Enhance hashtable seeding on Windows (#162).
          • +
        • json_unpack(): Allow mixing JSON_STRICT with optional keys +(#162, #163).
          • +
        • Fix int/int32 mismatch (#142).
          • +
        • Parse subnormal numbers correctly (#202).
          • +
        +
        • +
      • Build:
          +
        • Remove VS2010 build files. CMake should be used on Windows instead +(#165).
          • +
        • Fix CMake build flags for MinGW (#193).
          • +
        • Add CMake config files for find_package. Rename config.h to +jansson_private_config.h (#157, #159).
          • +
        • Make Valgrind checks work with CMake (#160).
          • +
        • Fix feature checks to use correct __ATOMIC flags.
          • +
        • Fix CMake checks for uint16_t and uint8_t support (#177).
          • +
        • Make Jansson build on SmartOS/Solaris (#171).
          • +
        • Work around a GCC bug on Solaris (#175).
          • +
        • Fix autoreconf on Debian (#182).
          • +
        • Don’t use GNU make specific export for global AM_CFLAGS (#203, +#204).
          • +
        • Fix building on Android using the supplied Android.mk (#166, +#174).
          • +
        • Android.mk: Add -DHAVE_STDINT_H to LOCAL_CFLAGS (#200).
          • +
        +
        • +
      • Documentation:
          +
        • Document JANSSON_BUILD_SHARED_LIBS CMake option (#187).
          • +
        +
        • +
      • Tests:
          +
        • Close file handles correctly (#198).
          • +
        +
        • +
      • Other changes:
          +
        • \uNNNN escapes are now encoded in upper case for better +readability.
          • +
        • Enable usage of AddressSanitizer (#180).
          • +
        +
        • +
      +
      +
      +

      Version 2.6¶

      +

      Released 2014-02-11

      +
        +
      • Security:
          +
        • CVE-2013-6401: The hash function used by the hashtable +implementation has been changed, and is automatically seeded with +random data when the first JSON object is created. This prevents +an attacker from causing large JSON objects with specially crafted +keys perform poorly.
          • +
        +
        • +
      • New features: +
        • +
      • Bug fixes:
          +
        • Include CMake specific files in the release tarball.
          • +
        +
        • +
      • Documentation:
          +
        • Fix tutorial source to send a User-Agent header, which is now +required by the GitHub API.
          • +
        • Set all memory to zero in secure_free() example.
          • +
        +
        • +
      +
      +
      +

      Version 2.5¶

      +

      Released 2013-09-19

      +
        +
      • New features: +
        • +
      • Bug fixes:
          +
        • json_dumps() and friends: Don’t crash if json is NULL and +JSON_ENCODE_ANY is set.
          • +
        • Fix a theoretical integer overflow in jsonp_strdup().
          • +
        • Fix l_isxdigit() macro (#97).
          • +
        • Fix an off-by-one error in json_array_remove().
          • +
        +
        • +
      • Build:
          +
        • Support CMake in addition to GNU Autotools (#106, #107, #112, +#115, #120, #127).
          • +
        • Support building for Android (#109).
          • +
        • Don’t use -Werror by default.
          • +
        • Support building and testing with VPATH (#93).
          • +
        • Fix compilation when NDEBUG is defined (#128)
          • +
        +
        • +
      • Tests:
          +
        • Fix a refleak in test/bin/json_process.c.
          • +
        +
        • +
      • Documentation:
          +
        • Clarify the return value of json_load_callback_t().
          • +
        • Document how to circumvent problems with separate heaps on Windows.
          • +
        • Fix memory leaks and warnings in github_commits.c.
          • +
        • Use json_decref() properly in tutorial.
          • +
        +
        • +
      • Other:
          +
        • Make it possible to forward declare struct json_t.
          • +
        +
        • +
      +
      +
      +

      Version 2.4¶

      +

      Released 2012-09-23

      +
        +
      • New features:
          +
        • Add json_boolean() macro that returns the JSON true or false +value based on its argument (#86).
          • +
        • Add json_load_callback() that calls a callback function +repeatedly to read the JSON input (#57).
          • +
        • Add JSON_ESCAPE_SLASH encoding flag to escape all occurences of +/ with \/.
          • +
        +
        • +
      • Bug fixes:
          +
        • Check for and reject NaN and Inf values for reals. Encoding these +values resulted in invalid JSON.
          • +
        • Fix json_real_set() to return -1 on error.
          • +
        +
        • +
      • Build:
          +
        • Jansson now builds on Windows with Visual Studio 2010, and +includes solution and project files in win32/vs2010/ +directory.
          • +
        • Fix build warnings (#77, #78).
          • +
        • Add -no-undefined to LDFLAGS (#90).
          • +
        +
        • +
      • Tests:
          +
        • Fix the symbol exports test on Linux/PPC64 (#88).
          • +
        +
        • +
      • Documentation:
          +
        • Fix typos (#73, #84).
          • +
        +
        • +
      +
      +
      +

      Version 2.3.1¶

      +

      Released 2012-04-20

      +
        +
      • Build issues:
          +
        • Only use long long if strtoll() is also available.
          • +
        +
        • +
      • Documentation:
          +
        • Fix the names of library version constants in documentation. (#52)
          • +
        • Change the tutorial to use GitHub API v3. (#65)
          • +
        +
        • +
      • Tests:
          +
        • Make some tests locale independent. (#51)
          • +
        • Distribute the library exports test in the tarball.
          • +
        • Make test run on shells that don’t support the export FOO=bar +syntax.
          • +
        +
        • +
      +
      +
      +

      Version 2.3¶

      +

      Released 2012-01-27

      +
        +
      • New features:
          +
        • json_unpack() and friends: Add support for optional object keys +with the {s?o} syntax.
          • +
        • Add json_object_update_existing() and +json_object_update_missing(), for updating only existing keys or +only adding missing keys to an object. (#37)
          • +
        • Add json_object_foreach() for more convenient iteration over +objects. (#45, #46)
          • +
        • When decoding JSON, write the number of bytes that were read from +input to error.position also on success. This is handy with +JSON_DISABLE_EOF_CHECK.
          • +
        • Add support for decoding any JSON value, not just arrays or +objects. The support is enabled with the new JSON_DECODE_ANY +flag. Patch by Andrea Marchesini. (#4)
          • +
        +
        • +
      • Bug fixes
          +
        • Avoid problems with object’s serial number growing too big. (#40, +#41)
          • +
        • Decoding functions now return NULL if the first argument is NULL. +Patch by Andrea Marchesini.
          • +
        • Include jansson_config.h.win32 in the distribution tarball.
          • +
        • Remove + and leading zeros from exponents in the encoder. +(#39)
          • +
        • Make Jansson build and work on MinGW. (#39, #38)
          • +
        +
        • +
      • Documentation
          +
        • Note that the same JSON values must not be encoded in parallel by +separate threads. (#42)
          • +
        • Document MinGW support.
          • +
        +
        • +
      +
      +
      +

      Version 2.2.1¶

      +

      Released 2011-10-06

      +
        +
      • Bug fixes:
          +
        • Fix real number encoding and decoding under non-C locales. (#32)
          • +
        • Fix identifier decoding under non-UTF-8 locales. (#35)
          • +
        • json_load_file(): Open the input file in binary mode for maximum +compatiblity.
          • +
        +
        • +
      • Documentation:
          +
        • Clarify the lifecycle of the result of the s fromat of +json_unpack(). (#31)
          • +
        • Add some portability info. (#36)
          • +
        • Little clarifications here and there.
          • +
        +
        • +
      • Other:
          +
        • Some style fixes, issues detected by static analyzers.
          • +
        +
        • +
      +
      +
      +

      Version 2.2¶

      +

      Released 2011-09-03

      +
        +
      • New features: +
        • +
      • Bug fixes: +
        • +
      • Other:
          +
        • Documentation typo fixes and clarifications.
          • +
        +
        • +
      +
      +
      +

      Version 2.1¶

      +

      Released 2011-06-10

      +
        +
      • New features:
          +
        • json_loadb(): Decode a string with a given size, useful if the +string is not null terminated.
          • +
        • Add JSON_ENCODE_ANY encoding flag to allow encoding any JSON +value. By default, only arrays and objects can be encoded. (#19)
          • +
        • Add JSON_REJECT_DUPLICATES decoding flag to issue a decoding +error if any JSON object in the input contins duplicate keys. (#3)
          • +
        • Add JSON_DISABLE_EOF_CHECK decoding flag to stop decoding after a +valid JSON input. This allows other data after the JSON data.
          • +
        +
        • +
      • Bug fixes:
          +
        • Fix an additional memory leak when memory allocation fails in +json_object_set() and friends.
          • +
        • Clear errno before calling strtod() for better portability. (#27)
          • +
        +
        • +
      • Building:
          +
        • Avoid set-but-not-used warning/error in a test. (#20)
          • +
        +
        • +
      • Other:
          +
        • Minor clarifications to documentation.
          • +
        +
        • +
      +
      +
      +

      Version 2.0.1¶

      +

      Released 2011-03-31

      +
        +
      • Bug fixes:
          +
        • Replace a few malloc() and free() calls with their +counterparts that support custom memory management.
          • +
        • Fix object key hashing in json_unpack() strict checking mode.
          • +
        • Fix the parentheses in JANSSON_VERSION_HEX macro.
          • +
        • Fix json_object_size() return value.
          • +
        • Fix a few compilation issues.
          • +
        +
        • +
      • Portability:
          +
        • Enhance portability of va_copy().
          • +
        • Test framework portability enhancements.
          • +
        +
        • +
      • Documentation:
          +
        • Distribute doc/upgrading.rst with the source tarball.
          • +
        • Build documentation in strict mode in make distcheck.
          • +
        +
        • +
      +
      +
      +

      Version 2.0¶

      +

      Released 2011-02-28

      +

      This release is backwards incompatible with the 1.x release series. +See the chapter “Upgrading from older versions” in documentation for +details.

      +
        +
      • Backwards incompatible changes:
          +
        • Unify unsigned integer usage in the API: All occurences of +unsigned int and unsigned long have been replaced with size_t.
          • +
        • Change JSON integer’s underlying type to the widest signed integer +type available, i.e. long long if it’s supported, otherwise long. +Add a typedef json_int_t that defines the type.
          • +
        • Change the maximum indentation depth to 31 spaces in encoder. This +frees up bits from the flags parameter of encoding functions +json_dumpf(), json_dumps() and json_dump_file().
          • +
        • For future needs, add a flags parameter to all decoding functions +json_loadf(), json_loads() and json_load_file().
          • +
        +
        • +
      • New features +
        • +
      • Fix many portability issues, especially on Windows.
        • +
      • Configuration
          +
        • Add file jansson_config.h that contains site specific +configuration. It’s created automatically by the configure script, +or can be created by hand if the configure script cannot be used. +The file jansson_config.h.win32 can be used without +modifications on Windows systems.
          • +
        • Add a section to documentation describing how to build Jansson on +Windows.
          • +
        • Documentation now requires Sphinx 1.0 or newer.
          • +
        +
        • +
      +
      +
      +

      Version 1.3¶

      +

      Released 2010-06-13

      +
        +
      • New functions: +
        • +
      • New encoding flags:
          +
        • JSON_PRESERVE_ORDER: Preserve the insertion order of object +keys.
          • +
        +
        • +
      • Bug fixes:
          +
        • Fix an error that occured when an array or object was first +encoded as empty, then populated with some data, and then +re-encoded
          • +
        • Fix the situation like above, but when the first encoding resulted +in an error
          • +
        +
        • +
      • Documentation:
          +
        • Clarify the documentation on reference stealing, providing an +example usage pattern
          • +
        +
        • +
      +
      +
      +

      Version 1.2.1¶

      +

      Released 2010-04-03

      +
        +
      • Bug fixes:
          +
        • Fix reference counting on true, false and null
          • +
        • Estimate real number underflows in decoder with 0.0 instead of +issuing an error
          • +
        +
        • +
      • Portability:
          +
        • Make int32_t available on all systems
          • +
        • Support compilers that don’t have the inline keyword
          • +
        • Require Autoconf 2.60 (for int32_t)
          • +
        +
        • +
      • Tests:
          +
        • Print test names correctly when VERBOSE=1
          • +
        • test/suites/api: Fail when a test fails
          • +
        • Enhance tests for iterators
          • +
        • Enhance tests for decoding texts that contain null bytes
          • +
        +
        • +
      • Documentation:
          +
        • Don’t remove changes.rst in make clean
          • +
        • Add a chapter on RFC conformance
          • +
        +
        • +
      +
      +
      +

      Version 1.2¶

      +

      Released 2010-01-21

      +
        +
      • New functions: +
        • +
      • New encoding flags:
          +
        • JSON_SORT_KEYS: Sort objects by key
          • +
        • JSON_ENSURE_ASCII: Escape all non-ASCII Unicode characters
          • +
        • JSON_COMPACT: Use a compact representation with all unneeded +whitespace stripped
          • +
        +
        • +
      • Bug fixes:
          +
        • Revise and unify whitespace usage in encoder: Add spaces between +array and object items, never append newline to output.
          • +
        • Remove const qualifier from the json_t parameter in +json_string_set(), json_integer_set() and json_real_set().
          • +
        • Use int32_t internally for representing Unicode code points +(int is not enough on all platforms)
          • +
        +
        • +
      • Other changes:
          +
        • Convert CHANGES (this file) to reStructured text and add it to +HTML documentation
          • +
        • The test system has been refactored. Python is no longer required +to run the tests.
          • +
        • Documentation can now be built by invoking make html
          • +
        • Support for pkg-config
          • +
        +
        • +
      +
      +
      +

      Version 1.1.3¶

      +

      Released 2009-12-18

      +
        +
      • Encode reals correctly, so that first encoding and then decoding a +real always produces the same value
        • +
      • Don’t export private symbols in libjansson.so
        • +
      +
      +
      +

      Version 1.1.2¶

      +

      Released 2009-11-08

      +
        +
      • Fix a bug where an error message was not produced if the input file +could not be opened in json_load_file()
        • +
      • Fix an assertion failure in decoder caused by a minus sign without a +digit after it
        • +
      • Remove an unneeded include of stdint.h in jansson.h
        • +
      +
      +
      +

      Version 1.1.1¶

      +

      Released 2009-10-26

      +
        +
      • All documentation files were not distributed with v1.1; build +documentation in make distcheck to prevent this in the future
        • +
      • Fix v1.1 release date in CHANGES
        • +
      +
      +
      +

      Version 1.1¶

      +

      Released 2009-10-20

      +
        +
      • API additions and improvements:
          +
        • Extend array and object APIs
          • +
        • Add functions to modify integer, real and string values
          • +
        • Improve argument validation
          • +
        • Use unsigned int instead of uint32_t for encoding flags
          • +
        +
        • +
      • Enhance documentation
          +
        • Add getting started guide and tutorial
          • +
        • Fix some typos
          • +
        • General clarifications and cleanup
          • +
        +
        • +
      • Check for integer and real overflows and underflows in decoder
        • +
      • Make singleton values thread-safe (true, false and null)
        • +
      • Enhance circular reference handling
        • +
      • Don’t define -std=c99 in AM_CFLAGS
        • +
      • Add C++ guards to jansson.h
        • +
      • Minor performance and portability improvements
        • +
      • Expand test coverage
        • +
      +
      +
      +

      Version 1.0.4¶

      +

      Released 2009-10-11

      +
        +
      • Relax Autoconf version requirement to 2.59
        • +
      • Make Jansson compile on platforms where plain char is unsigned
        • +
      • Fix API tests for object
        • +
      +
      +
      +

      Version 1.0.3¶

      +

      Released 2009-09-14

      +
        +
      • Check for integer and real overflows and underflows in decoder
        • +
      • Use the Python json module for tests, or simplejson if the json +module is not found
        • +
      • Distribute changelog (this file)
        • +
      +
      +
      +

      Version 1.0.2¶

      +

      Released 2009-09-08

      +
        +
      • Handle EOF correctly in decoder
        • +
      +
      +
      +

      Version 1.0.1¶

      +

      Released 2009-09-04

      + +
      +
      +

      Version 1.0¶

      +

      Released 2009-08-25

      +
        +
      • Initial release
        • +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      API Reference

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/conformance.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/conformance.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,211 @@ + + + + + + + + RFC Conformance — Jansson 2.7 documentation + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      RFC Conformance¶

      +

      JSON is specified in RFC 4627, “The application/json Media Type +for JavaScript Object Notation (JSON)”.

      +
      +

      Character Encoding¶

      +

      Jansson only supports UTF-8 encoded JSON texts. It does not support or +auto-detect any of the other encodings mentioned in the RFC, namely +UTF-16LE, UTF-16BE, UTF-32LE or UTF-32BE. Pure ASCII is supported, as +it’s a subset of UTF-8.

      +
      +
      +

      Strings¶

      +

      JSON strings are mapped to C-style null-terminated character arrays, +and UTF-8 encoding is used internally.

      +

      All Unicode codepoints U+0000 through U+10FFFF are allowed in string +values. However, U+0000 is not allowed in object keys because of API +restrictions.

      +

      Unicode normalization or any other transformation is never performed +on any strings (string values or object keys). When checking for +equivalence of strings or object keys, the comparison is performed +byte by byte between the original UTF-8 representations of the +strings.

      +
      +
      +

      Numbers¶

      +
      +

      Real vs. Integer¶

      +

      JSON makes no distinction between real and integer numbers; Jansson +does. Real numbers are mapped to the double type and integers to +the json_int_t type, which is a typedef of long long or +long, depending on whether long long is supported by your +compiler or not.

      +

      A JSON number is considered to be a real number if its lexical +representation includes one of e, E, or .; regardless if +its actual numeric value is a true integer (e.g., all of 1E6, +3.0, 400E-2, and 3.14E3 are mathematical integers, but +will be treated as real values). With the JSON_DECODE_INT_AS_REAL +decoder flag set all numbers are interpreted as real.

      +

      All other JSON numbers are considered integers.

      +

      When encoding to JSON, real values are always represented +with a fractional part; e.g., the double value 3.0 will be +represented in JSON as 3.0, not 3.

      +
      +
      +

      Overflow, Underflow & Precision¶

      +

      Real numbers whose absolute values are too small to be represented in +a C double will be silently estimated with 0.0. Thus, depending on +platform, JSON numbers very close to zero such as 1E-999 may result in +0.0.

      +

      Real numbers whose absolute values are too large to be represented in +a C double will result in an overflow error (a JSON decoding +error). Thus, depending on platform, JSON numbers like 1E+999 or +-1E+999 may result in a parsing error.

      +

      Likewise, integer numbers whose absolute values are too large to be +represented in the json_int_t type (see above) will result in an +overflow error (a JSON decoding error). Thus, depending on platform, +JSON numbers like 1000000000000000 may result in parsing error.

      +

      Parsing JSON real numbers may result in a loss of precision. As long +as overflow does not occur (i.e. a total loss of precision), the +rounded approximate value is silently used. Thus the JSON number +1.000000000000000005 may, depending on platform, result in the +double value 1.0.

      +
      +
      +

      Signed zeros¶

      +

      JSON makes no statement about what a number means; however Javascript +(ECMAscript) does state that +0.0 and -0.0 must be treated as being +distinct values, i.e. -0.0 ≠ 0.0. Jansson relies on the +underlying floating point library in the C environment in which it is +compiled. Therefore it is platform-dependent whether 0.0 and -0.0 will +be distinct values. Most platforms that use the IEEE 754 +floating-point standard will support signed zeros.

      +

      Note that this only applies to floating-point; neither JSON, C, or +IEEE support the concept of signed integer zeros.

      +
      +
      +

      Types¶

      +

      No support is provided in Jansson for any C numeric types other than +json_int_t and double. This excludes things such as unsigned +types, long double, etc. Obviously, shorter types like short, +int, long (if json_int_t is long long) and float +are implicitly handled via the ordinary C type coercion rules (subject +to overflow semantics). Also, no support or hooks are provided for any +supplemental “bignum” type add-on packages.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      Tutorial

      +

      Next topic

      +

      Portability

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/genindex.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/genindex.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,519 @@ + + + + + + + + + Index — Jansson 2.7 documentation + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + + +

      Index

      + +
      + J + | R + +
      +

      J

      + + + +
      + +
      json_array (C function) +
      + + +
      json_array_append (C function) +
      + + +
      json_array_append_new (C function) +
      + + +
      json_array_clear (C function) +
      + + +
      json_array_extend (C function) +
      + + +
      json_array_foreach (C function) +
      + + +
      json_array_get (C function) +
      + + +
      json_array_insert (C function) +
      + + +
      json_array_insert_new (C function) +
      + + +
      json_array_remove (C function) +
      + + +
      json_array_set (C function) +
      + + +
      json_array_set_new (C function) +
      + + +
      json_array_size (C function) +
      + + +
      json_boolean (C function) +
      + + +
      json_boolean_value (C function) +
      + + +
      json_copy (C function) +
      + + +
      json_decref (C function) +
      + + +
      json_deep_copy (C function) +
      + + +
      json_dump_callback (C function) +
      + + +
      json_dump_callback_t (C type) +
      + + +
      json_dump_file (C function) +
      + + +
      json_dumpf (C function) +
      + + +
      json_dumps (C function) +
      + + +
      json_equal (C function) +
      + + +
      json_error_t (C type) +
      + + +
      json_error_t.column (C member) +
      + + +
      json_error_t.line (C member) +
      + + +
      json_error_t.position (C member) +
      + + +
      json_false (C function) +
      + + +
      json_free_t (C type) +
      + + +
      json_incref (C function) +
      + + +
      json_int_t (C type) +
      + + +
      json_integer (C function) +
      + + +
      json_integer_set (C function) +
      + + +
      json_integer_value (C function) +
      + + +
      json_is_array (C function) +
      + + +
      json_is_boolean (C function) +
      + + +
      json_is_false (C function) +
      + + +
      json_is_integer (C function) +
      + + +
      json_is_null (C function) +
      + + +
      json_is_number (C function) +
      + + +
      json_is_object (C function) +
      + + +
      json_is_real (C function) +
      + + +
      json_is_string (C function) +
      + + +
      json_is_true (C function) +
      + + +
      json_load_callback (C function) +
      + + +
      json_load_callback_t (C type) +
      + + +
      json_load_file (C function) +
      + + +
      json_loadb (C function) +
      + + +
      json_loadf (C function) +
      + +
      + +
      json_loads (C function) +
      + + +
      json_malloc_t (C type) +
      + + +
      json_null (C function) +
      + + +
      json_number_value (C function) +
      + + +
      json_object (C function) +
      + + +
      json_object_clear (C function) +
      + + +
      json_object_del (C function) +
      + + +
      json_object_foreach (C function) +
      + + +
      json_object_get (C function) +
      + + +
      json_object_iter (C function) +
      + + +
      json_object_iter_at (C function) +
      + + +
      json_object_iter_key (C function) +
      + + +
      json_object_iter_next (C function) +
      + + +
      json_object_iter_set (C function) +
      + + +
      json_object_iter_set_new (C function) +
      + + +
      json_object_iter_value (C function) +
      + + +
      json_object_key_to_iter (C function) +
      + + +
      json_object_seed (C function) +
      + + +
      json_object_set (C function) +
      + + +
      json_object_set_new (C function) +
      + + +
      json_object_set_new_nocheck (C function) +
      + + +
      json_object_set_nocheck (C function) +
      + + +
      json_object_size (C function) +
      + + +
      json_object_update (C function) +
      + + +
      json_object_update_existing (C function) +
      + + +
      json_object_update_missing (C function) +
      + + +
      json_pack (C function) +
      + + +
      json_pack_ex (C function) +
      + + +
      json_real (C function) +
      + + +
      json_real_set (C function) +
      + + +
      json_real_value (C function) +
      + + +
      json_set_alloc_funcs (C function) +
      + + +
      json_string (C function) +
      + + +
      json_string_length (C function) +
      + + +
      json_string_nocheck (C function) +
      + + +
      json_string_set (C function) +
      + + +
      json_string_set_nocheck (C function) +
      + + +
      json_string_setn (C function) +
      + + +
      json_string_setn_nocheck (C function) +
      + + +
      json_string_value (C function) +
      + + +
      json_stringn (C function) +
      + + +
      json_stringn_nocheck (C function) +
      + + +
      json_t (C type) +
      + + +
      json_true (C function) +
      + + +
      json_type (C type) +
      + + +
      json_typeof (C function) +
      + + +
      json_unpack (C function) +
      + + +
      json_unpack_ex (C function) +
      + + +
      json_vpack_ex (C function) +
      + + +
      json_vunpack_ex (C function) +
      + +
      + +

      R

      + + +
      + +
      + RFC +
      + +
      + +
      RFC 4627, [1], [2], [3] +
      + +
      +
      + + + +
      +
      +
      +
      +
      + + + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/gettingstarted.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/gettingstarted.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,324 @@ + + + + + + + + Getting Started — Jansson 2.7 documentation + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      Getting Started¶

      +
      +

      Compiling and Installing Jansson¶

      +

      The Jansson source is available at +http://www.digip.org/jansson/releases/.

      +
      +

      Unix-like systems (including MinGW)¶

      +

      Unpack the source tarball and change to the source directory:

      +
      +bunzip2 -c jansson-2.7.tar.bz2 | tar xf -
+cd jansson-2.7
+
      +

      The source uses GNU Autotools (autoconf, automake, libtool), so +compiling and installing is extremely simple:

      +
      ./configure
+make
+make check
+make install
+
      +
      +

      To change the destination directory (/usr/local by default), use +the --prefix=DIR argument to ./configure. See ./configure +--help for the list of all possible installation options. (There are +no options to customize the resulting Jansson binary.)

      +

      The command make check runs the test suite distributed with +Jansson. This step is not strictly necessary, but it may find possible +problems that Jansson has on your platform. If any problems are found, +please report them.

      +

      If you obtained the source from a Git repository (or any other source +control system), there’s no ./configure script as it’s not kept in +version control. To create the script, the build system needs to be +bootstrapped. There are many ways to do this, but the easiest one is +to use autoreconf:

      +
      autoreconf -vi
+
      +
      +

      This command creates the ./configure script, which can then be +used as described above.

      +
      +
      +

      CMake (various platforms, including Windows)¶

      +

      Jansson can be built using CMake. Create a build directory for an +out-of-tree build, change to that directory, and run cmake (or ccmake, +cmake-gui, or similar) to configure the project.

      +

      See the examples below for more detailed information.

      +
      +

      Note

      +

      In the below examples .. is used as an argument for cmake. +This is simply the path to the jansson project root directory. +In the example it is assumed you’ve created a sub-directory build +and are using that. You could use any path you want.

      +
      +
      +

      Unix (Make files)¶

      +

      Generating make files on unix:

      +
      +bunzip2 -c jansson-2.7.tar.bz2 | tar xf -
+cd jansson-2.7
+
+mkdir build
+cd build
+cmake .. # or ccmake ..() for a GUI.
+
      +

      Then to build:

      +
      make
+make check
+make install
+
      +
      +
      +
      +

      Windows (Visual Studio)¶

      +

      Creating Visual Studio project files from the command line:

      +
      +<unpack>
+cd jansson-2.7
+
+md build
+cd build
+cmake -G "Visual Studio 10" ..
+
      +

      You will now have a Visual Studio Solution in your build directory. +To run the unit tests build the RUN_TESTS project.

      +

      If you prefer a GUI the cmake line in the above example can +be replaced with:

      +
      cmake-gui ..
+
      +
      +

      For command line help (including a list of available generators) +for CMake simply run:

      +
      cmake
+
      +
      +

      To list available CMake settings (and what they are currently set to) +for the project, run:

      +
      cmake -LH ..
+
      +
      +
      +
      +

      Mac OSX (Xcode)¶

      +

      If you prefer using Xcode instead of make files on OSX, +do the following. (Use the same steps as +for Unix):

      +
      ...
+cmake -G "Xcode" ..
+
      +
      +
      +
      +

      Additional CMake settings¶

      +
      +
      Shared library¶
      +

      By default the CMake project will generate build files for building the +static library. To build the shared version use:

      +
      ...
+cmake -DJANSSON_BUILD_SHARED_LIBS=1 ..
+
      +
      +
      +
      +
      Changing install directory (same as autoconf –prefix)¶
      +

      Just as with the autoconf project you can change the destination directory +for make install. The equivalent for autoconfs ./configure --prefix +in CMake is:

      +
      ...
+cmake -DCMAKE_INSTALL_PREFIX:PATH=/some/other/path ..
+make install
+
      +
      +
      +
      +
      +
      +

      Android¶

      +

      Jansson can be built for Android platforms. Android.mk is in the +source root directory. The configuration header file is located in the +android directory in the source distribution.

      +
      +
      +

      Other Systems¶

      +

      On non Unix-like systems, you may be unable to run the ./configure +script. In this case, follow these steps. All the files mentioned can +be found in the src/ directory.

      +
        +
      1. Create jansson_config.h (which has some platform-specific +parameters that are normally filled in by the ./configure +script). Edit jansson_config.h.in, replacing all @variable@ +placeholders, and rename the file to jansson_config.h.
        2. +
      2. Make jansson.h and jansson_config.h available to the +compiler, so that they can be found when compiling programs that +use Jansson.
        3. +
      3. Compile all the .c files (in the src/ directory) into a +library file. Make the library available to the compiler, as in +step 2.
        4. +
      +
      +
      +

      Building the Documentation¶

      +

      (This subsection describes how to build the HTML documentation you are +currently reading, so it can be safely skipped.)

      +

      Documentation is in the doc/ subdirectory. It’s written in +reStructuredText with Sphinx annotations. To generate the HTML +documentation, invoke:

      +
      make html
+
      +
      +

      and point your browser to doc/_build/html/index.html. Sphinx 1.0 +or newer is required to generate the documentation.

      +
      +
      +
      +

      Compiling Programs that Use Jansson¶

      +

      Jansson involves one C header file, jansson.h, so it’s enough +to put the line

      +
      #include <jansson.h>
+
      +
      +

      in the beginning of every source file that uses Jansson.

      +

      There’s also just one library to link with, libjansson. Compile and +link the program as follows:

      +
      cc -I /usr/include/jansson -o prog prog.c -ljansson
+
      +
      +

      Starting from version 1.2, there’s also support for pkg-config:

      +
      cc -o prog prog.c `pkg-config --cflags --libs jansson`
+
      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      Jansson Documentation

      +

      Next topic

      +

      Upgrading from 1.x

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/index.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/index.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,215 @@ + + + + + + + + Jansson Documentation — Jansson 2.7 documentation + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      Jansson Documentation¶

      +

      This is the documentation for Jansson 2.7, last updated October 28, 2014.

      +
      +

      Introduction¶

      +

      Jansson is a C library for encoding, decoding and manipulating JSON +data. Its main features and design principles are:

      +
        +
      • Simple and intuitive API and data model
        • +
      • Comprehensive documentation
        • +
      • No dependencies on other libraries
        • +
      • Full Unicode support (UTF-8)
        • +
      • Extensive test suite
        • +
      +

      Jansson is licensed under the MIT license; see LICENSE in the +source distribution for details.

      +

      Jansson is used in production and its API is stable. It works on +numerous platforms, including numerous Unix like systems and Windows. +It’s suitable for use on any system, including desktop, server, and +small embedded systems.

      +
      + +
      +
      +

      Indices and Tables¶

      + +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Next topic

      +

      Getting Started

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/portability.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/portability.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,186 @@ + + + + + + + + Portability — Jansson 2.7 documentation + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      Portability¶

      +
      +

      Thread safety¶

      +

      Jansson is thread safe and has no mutable global state. The only +exceptions are the hash function seed and memory allocation functions, +see below.

      +

      There’s no locking performed inside Jansson’s code, so a multithreaded +program must perform its own locking if JSON values are shared by +multiple threads. Jansson’s reference counting semantics may make this +a bit harder than it seems, as it’s possible to have a reference to a +value that’s also stored inside a list or object. Modifying the +container (adding or removing values) may trigger concurrent access to +such values, as containers manage the reference count of their +contained values. Bugs involving concurrent incrementing or +decrementing of deference counts may be hard to track.

      +

      The encoding functions (json_dumps() and friends) track +reference loops by modifying the internal state of objects and arrays. +For this reason, encoding functions must not be run on the same JSON +values in two separate threads at the same time. As already noted +above, be especially careful if two arrays or objects share their +contained values with another array or object.

      +

      If you want to make sure that two JSON value hierarchies do not +contain shared values, use json_deep_copy() to make copies.

      +
      +

      Hash function seed¶

      +

      To prevent an attacker from intentionally causing large JSON objects +with specially crafted keys to perform very slow, the hash function +used by Jansson is randomized using a seed value. The seed is +automatically generated on the first explicit or implicit call to +json_object(), if json_object_seed() has not been +called beforehand.

      +

      The seed is generated by using operating system’s entropy sources if +they are available (/dev/urandom, CryptGenRandom()). The +initialization is done in as thread safe manner as possible, by using +architecture specific lockless operations if provided by the platform +or the compiler.

      +

      If you’re using threads, it’s recommended to autoseed the hashtable +explicitly before spawning any threads by calling +json_object_seed(0) , especially if you’re unsure whether the +initialization is thread safe on your platform.

      +
      +
      +

      Memory allocation functions¶

      +

      Memory allocation functions should be set at most once, and only on +program startup. See Custom Memory Allocation.

      +
      +
      +
      +

      Locale¶

      +

      Jansson works fine under any locale.

      +

      However, if the host program is multithreaded and uses setlocale() +to switch the locale in one thread while Jansson is currently encoding +or decoding JSON data in another thread, the result may be wrong or +the program may even crash.

      +

      Jansson uses locale specific functions for certain string conversions +in the encoder and decoder, and then converts the locale specific +values to/from the JSON representation. This fails if the locale +changes between the string conversion and the locale-to-JSON +conversion. This can only happen in multithreaded programs that use +setlocale(), because setlocale() switches the locale for all +running threads, not only the thread that calls setlocale().

      +

      If your program uses setlocale() as described above, consider +using the thread-safe uselocale() instead.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      RFC Conformance

      +

      Next topic

      +

      API Reference

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/search.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/search.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,99 @@ + + + + + + + + Search — Jansson 2.7 documentation + + + + + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +

      Search

      +
      + +

      + Please activate JavaScript to enable the search + functionality. +

      +
      +

      + From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list. +

      +
      + + + +
      + +
      + +
      + +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/searchindex.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/searchindex.js Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,1 @@ +Search.setIndex({envversion:42,terms:{all:[0,1,3,4,5,6,7],code:[6,3,4,5,1],entropi:[3,1],maximum:[3,4,5],queri:3,consum:3,json_typeof:3,poorli:5,prefix:3,concept:7,urandom:1,skip:0,follow:[0,6,3],ptr:3,lld:3,compact:[3,5],whose:[3,7,6],privat:5,depend:[2,7,4,3],system:[3,5],uint8_t:5,json_boolean_valu:[3,5],sensit:3,readabl:[3,5],specif:[0,5,1,3],send:[5,6],program:3,json_object_foreach:[3,5],decis:3,under:[2,5,1],preprocess:3,sent:6,codepoint:[3,7],sourc:[0,1,2,3,4,5,6],everi:[0,3],digip:0,json_object:[3,1],"void":3,json_object_get:[3,5,6],dhave_stdint_h:5,whether:[3,4,5,1,7],fall:3,veri:[7,5,1],appar:3,implicitli:7,json_decode_ani:[3,5],exact:3,implement:[3,5,6],cool:3,failur:[3,5],"0x010201":3,foo:[3,5],doesn:[3,5],level:3,did:6,quux:3,dif:3,list:[0,3,6,1,2],iter:[3,5],"try":3,item:[3,5],supplement:7,form:[3,6],stderr:6,small:[2,7,6],retun:3,dir:0,json_string_set:[3,5],upper:5,repres:[3,5,7],snprintf:6,"14e3":7,natur:3,direct:3,uselocal:1,sign:[3,5],zero:[3,5],design:[2,3],pass:[3,5],"873eddaf":6,improv:5,append:[3,5],compat:[2,3],index:[0,3,2],what:[0,7],jansson_minor_vers:3,appear:3,compar:3,cast:3,preserv:[3,5],abi:4,section:[3,5,6],json_dumpf:[3,4,5],current:[0,1,3],delet:3,"2637faa4":6,consecut:3,"new":[3,4,5,6],arr2:3,json_load_callback_t:[3,5],va_list:3,whatev:3,full:[2,4,6,3],themselv:3,abov:[0,1,5,3,7,6],gener:[0,5,1,3],never:[3,5,7],len:3,json_object_iter_set_new:[3,5],behaviour:[3,6],explicitli:[3,4,1],studio:5,free:[3,4,5,6],solari:5,address:3,path:[0,3],along:5,becom:3,modifi:[3,4,5,1],implicit:[3,4,1],json_nul:3,convert:[3,5,1],produc:[3,5],convers:[3,1],broken:5,shift:3,anymor:6,step:[0,4,3],autoreconf:[0,5],fetch:6,precis:[3,5],jansson:3,extrem:0,chang:3,werror:5,call:[6,3,4,5,1],portabl:[2,5],json_stringn:[3,5],subsect:0,semant:[7,1],via:7,regardless:[3,7],danger:3,circumv:[3,5],appli:7,modul:5,json_max_ind:[3,5],prefer:0,inequ:3,releas:[0,4,5,6,3],"boolean":3,reuiqr:3,printf:[3,6],decrement:[3,1],total:7,coercion:[7,4],unit:[0,3],json_pack:[3,5],unnnn:5,hexadecim:[3,6],from:[0,1,2,3,5,6],describ:[0,5,1,3],would:3,commun:6,distinct:[3,7],doubl:[3,7],two:[3,5,1],coverag:5,next:[3,6],few:5,json_fals:3,value2:3,value1:3,recommend:1,scope:6,basi:3,tell:3,minor:[3,5],"const":[3,5,6],sort:[3,5],relax:5,relat:6,mismatch:5,problem:[0,5,3],enhanc:5,warn:5,bunzip2:0,flag:[3,4,5,7],marchesini:5,indic:3,particular:3,actual:[3,7,6],hold:3,unpack:[0,5,3],easiest:0,must:[3,5,1,7],word:3,"32le":7,alia:[3,5],work:[2,4,5,1,3],annot:0,dev:1,json_number_valu:3,other:[3,5,7],obvious:7,can:[0,1,3,4,5,6],json_:3,json_array_remov:[3,5],rememb:6,root:[0,6,3],"0x010300":3,control:[0,5,3],defer:1,malform:5,want:[0,1,3],stream:3,give:3,process:3,lock:1,ppc64:5,digit:[3,5],accept:3,abort:3,fprintf:6,explor:6,tarbal:[0,5],strtoll:5,serial:[3,5],keep:3,unsign:[5,4,7],occur:[3,5,6,7],autose:1,alwai:[3,5,7],gcc:[5,6],subnorm:5,end:3,newlin:[3,5,6],secur:[3,5],anoth:1,ordinari:[3,7],json_boolean:[3,5],write:[3,5],how:[0,5,3],json_is_numb:3,consist:3,pure:7,other_arrai:3,instead:[0,5,1,3],json_copi:[3,5],simpl:[0,5,3,2],updat:[2,5,3],map:7,product:2,resourc:6,overridden:3,jansson_private_config:5,after:[3,5,6],"long":[3,4,5,7],befor:[3,5,1],wrong:1,callback:[3,5],repeatedli:[3,5],mai:[0,7,4,1,3],multipl:[3,1],associ:3,grow:[3,5],advantag:3,repo:2,"short":[7,6],attempt:3,practic:3,third:3,read:[0,5,3],opaqu:3,bootstrap:0,explicit:[3,1],correspond:3,"__atom":5,caus:[3,5,1],inform:[0,6,3],"switch":1,increment:[3,1],combin:3,json_is_nul:3,allow:[3,5,7],json_object_se:[3,5,1],json_object_update_miss:[3,5],order:[3,5],json_real_valu:3,oper:[3,1],json_object_set_nocheck:[3,5],djansson_build_shared_lib:0,json_array_insert:3,concatent:3,"32be":7,jsonp_strdup:5,json_is_integ:3,top:3,becaus:[3,7,1],increas:3,through:[3,7],affect:3,size_t:[3,4,5,6],still:[3,4],pointer:3,run_test:0,dynam:[3,4],paramet:[0,4,5,6,3],member:3,style:[7,5,6],"1581f26a":6,concaten:3,concis:3,jansson_config:[0,5],fix:[3,5],better:5,segfault:3,window:[3,5],complex:3,comprehens:2,main:[2,6,3],alter:3,non:[0,5,3],"float":[3,7],"return":[3,5,6],fourth:3,jansson_micro_vers:3,json_vpack_ex:[3,5],python:5,timestamp:3,safe:[0,5,1,3],handi:5,initi:[3,5,1],borrow:3,json_is_tru:[3,5],framework:5,json_unpack_ex:[3,5],placehold:0,discuss:3,nor:3,term:3,somewher:3,name:[3,5,6,7],json_decode_int_as_r:[3,5,7],edit:0,sucess:3,drop:3,dcmake_install_prefix:0,separ:[3,5,1],micro:3,achiev:3,alreadi:[3,1],mode:5,each:3,debug:3,found:[0,5,3],unicod:[2,7,5,3],compatibl:[3,5],gui:0,mean:[3,7],subset:[3,7],bignum:7,due:3,replac:[0,4,5,3],chunk:[3,5],hard:1,gc_malloc:3,ensur:3,realli:[3,6],line:[0,6,3],contrib:6,"17a51a4b":6,json_integer_valu:3,"static":[0,5,6,3],expect:3,json_set_alloc_func:[3,5],happen:[3,1],extract:[3,5,6],special:[3,5,1],out:[0,6,3],variabl:[0,6,3],rfc:[3,5],json_dump:[3,4,5,1],safeti:[2,3],space:[3,5],miss:5,newli:[3,6],content:[3,5],method:3,suitabl:2,print:[3,5,6],got:6,correct:5,interoperat:3,achiv:3,clarifi:5,qualifi:5,json_object_iter_valu:3,insid:[3,1],"_new":3,json_is_fals:3,manipul:[2,6,3],situat:5,given:[3,5,6],argv:6,standard:7,reason:[3,1],base:[3,5],json_object_update_exist:[3,5],json_array_foreach:[3,5],dictionari:3,usual:[3,4],put:0,org:0,"byte":[3,5,7],argc:6,afterward:3,boehm:3,care:1,json_object_set_new_nocheck:[3,5],indent:[3,4,5],val:3,thread:[2,5,3],angl:3,where:[3,5,6],could:[0,5],omit:3,refus:3,round:7,counterpart:5,thing:7,length:[3,5,6],enforc:3,place:3,unabl:0,outsid:3,principl:2,fmt:3,first:[3,5,6,1],origin:[3,7],pleas:[0,6],major:3,suffix:3,directli:3,prevent:[5,1],onc:1,independ:[5,6],yourself:3,restrict:7,distcheck:5,json_string_setn:[3,5],done:1,least:3,"1e6":7,stabl:2,json_array_append:3,open:5,size:[3,4,5,6],avail:[0,1,3,4,5,6],differ:3,json_validate_onli:3,silent:[3,7],script:[0,5],data:[2,5,6,1,3],caught:3,perfectli:3,mkdir:0,sometim:3,messag:[3,5,6],parallel:5,json_load_fil:[3,4,5],json_free_t:3,attack:[3,5,1],definit:6,too:[3,5,6,7],json_arrai:3,subdirectori:0,termin:[3,5,7],conveni:5,"final":6,store:[3,1],includ:[3,5,7],shell:5,statement:[3,7],especi:[3,5,1],json_string_set_nocheck:[3,5],json_int_t:[3,4,5,7],specifi:[3,5,7],forward:[3,5],part:[3,7,6],unrandom:3,conserv:3,rst:5,kept:[0,3],exactli:3,than:[7,4,1],std:5,denot:3,kind:3,target:5,keyword:[3,5],provid:[7,5,1],remov:[3,5,1],older:5,tree:0,rate:6,structur:[3,6],charact:[3,5],project:[0,5],json_object_iter_kei:3,str:3,were:[3,5],posit:[3,5],src:0,toward:3,thu:[3,7],seri:5,fashion:3,newline_offset:6,modern:4,beforehand:1,argument:[0,4,5,3],cryptgenrandom:1,packag:7,seed:[3,5],manner:1,json_dump_callback_t:3,tabl:3,need:[0,4,5,6,3],seem:1,element:[3,6],seek:3,minu:[3,5],option:[0,5,3],"4true":3,date:5,built:[0,5],equival:[0,7,3],recompil:4,destroi:3,moreov:3,violat:3,cbb80baf:6,note:[3,5,6,1,7],mix:5,without:[3,5],take:[3,5,6],which:[0,7,5,3],environ:7,brace:3,noth:3,singl:3,recurs:3,even:[3,1],begin:[0,6,3],json_object_clear:3,unless:3,distribut:[0,5,2],normal:[0,7,3],unsur:1,c99:5,previou:3,reach:3,jansson_build_shared_lib:5,json_error_t:[3,5,6],json_object_iter_at:[3,5],detect:[3,5,7],json_ensure_ascii:[3,5],thi:[0,1,2,3,4,5,6,7],pair:3,indirectli:3,url_siz:6,sub:0,don:[3,5,6],correctli:[3,5],url:6,doc:[0,5],clear:5,later:3,cover:6,doe:7,bracket:3,json_incref:3,clean:5,left:3,"400e":7,json_is_str:[3,6],json_array_s:[3,6],heap:[3,5],"16be":7,opposit:3,comparis:3,json_array_extend:3,syntax:[5,6],concurr:1,pkg:[0,5],worri:3,jansson_version_hex:[3,5],identifi:[3,5],longer:[3,5],fine:1,find:[0,6],help:[0,3],involv:[0,1],absolut:7,onli:[1,3,4,5,6,7],slow:1,locat:0,thei:[0,1,3],pretti:3,strtod:5,losslessli:3,explain:[3,6],configur:[0,5],solut:[0,5],behind:3,json_string_nocheck:[3,5],won:3,"10ffff":[3,7],jansson_major_vers:3,constant:[3,5,6],local:[0,5,2],over:[3,5,6],sure:1,overwritten:3,info:[3,5,6],hit:3,unus:3,free_fn:3,get:[3,5],likewis:7,stop:[3,5],soon:3,e8fd3e30:6,cannot:[3,5],foobarbaz:3,json_sort_kei:[3,5],json_malloc_t:3,neither:[3,7],requir:[0,4,5,6,3],ssb:3,bar:[3,5],enabl:[3,5],crt:3,emb:3,baz:3,dramat:4,yield:3,patch:5,gc_free:3,sha:6,suit:[0,5,2],common:3,though:3,contain:[6,3,4,5,1],steal:[3,5],view:6,respond:6,conform:[3,5],set:[3,5,7],json_is_boolean:[3,5],packer:3,startup:[3,1],json_strict:[3,5],mutabl:1,hierarchi:1,nul:3,result:[0,1,5,3,7,6],respons:6,fail:[3,5,6,1],close:[3,5,7],best:6,subject:7,strchr:6,awar:[3,5],statu:3,said:3,myint1:3,kei:[3,5,1,7],myint3:3,myint2:3,pattern:5,someth:3,json_object_it:3,restructur:5,secure_fre:[3,5],json_reject_dupl:[3,5],between:[3,5,1,7],json_unpack:[3,5],"import":6,awai:3,experi:6,libtool:0,signatur:3,accord:3,libjansson:[0,5],extend:5,numer:[2,7,3],javascript:7,typedef:[3,4,5,7],json_object_iter_set:[3,5],extens:2,json_str:3,succeed:3,here:[3,5,6],json_vunpack_ex:[3,5],distinguish:3,decreas:[3,6],embed:[2,3],addit:[3,5],both:[3,4],protect:3,last:[2,3],similar:[0,3],howev:[3,7,1],json_encode_ani:[3,5],valgrind:5,against:[3,4],etc:[3,4,7],tutori:[2,5],present:3,guaranteed_memset:3,agent:5,let:6,json_integ:3,json_deep_copi:[3,5,1],com:[3,6],preprocessor:[3,5],json_process:5,simpli:0,reject:5,point:[0,7,5,3],int32_t:5,period:6,except:[3,1],header:[0,5],written:[0,3],theoret:5,linux:5,respect:[3,6],throughout:3,assum:0,simpler:3,duplic:[3,5],github_commit:[5,6],clarif:5,creat:[0,5,6,3],second:[3,4,6],platform:[7,5],json_typ:3,underflow:5,json_real_precis:[3,5],secret:3,compos:3,empti:[3,5],sinc:3,json_ind:[3,4],"int":[3,4,5,6,7],json:[2,1,3,4,5,6,7],much:3,unexpect:6,interpret:[3,7],modif:[5,4],stdint:5,addresssanit:5,popul:5,vpath:5,field:[3,5,6],bd2c0c73:6,octob:2,buflen:3,am_cflag:5,ani:[0,1,2,3,5,7],assert:[3,5],craft:[5,1],file:[3,5],togeth:3,child:3,json_string_setn_nocheck:[3,5],rang:[3,4],andrea:5,those:3,"case":[0,4,5,6,3],stolen:3,gnu:[0,5],plain:[3,5],bz2:0,harder:1,search:2,defin:[3,5,6],invok:[0,5],unifi:[5,4],behavior:3,indetermin:3,json_preserve_ord:[3,5],invoc:3,cve:5,loop:[6,1],pack:3,spawn:1,real:[3,5],malloc:[3,5],have:[0,4,5,1,3],tar:0,applic:[3,7],readi:6,therefor:7,them:[0,4,3],json_object_del:[3,5],destin:0,akheron:6,itself:[3,5],json_real_set:[3,5],revis:5,unneed:5,ascii:[3,5,7],sever:6,around:[3,5],incompat:[2,5,3],mutat:5,clearli:3,strcmp:3,"16le":7,media:7,make:[3,5,7],same:[3,5],"while":[3,5,1],shorter:[3,7],binari:[0,5,6],html:[0,5,3],json_dump_fil:[3,4,5],auto:7,json_real:3,algorithm:3,android:5,document:[3,5],start:[3,5],finish:6,http:[0,6,3],json_t:[3,5,6],see:[0,1,2,3,5,6,7],json_integer_is_long_long:3,dwheeler:3,expans:6,nest:3,smallish:4,upon:3,hand:[3,5],va_copi:5,user:[3,5,6],mani:[0,5,6,3],json_integer_set:[3,5],encrypt:3,stack:3,expand:[3,5],pull:6,test_load_callback:6,off:5,lib:0,discourag:3,mention:[0,7],find_packag:5,whole:[3,4],random:[3,5,1],parenthes:[3,5],autotool:[0,5],more:[0,5,6,3],exampl:[0,4,5,6,3],command:[0,6],ecmascript:7,uint32_t:5,endif:3,undefin:[3,5],json_object_key_to_it:3,model:2,lcurl:6,json_dump_callback:[3,5],latest:6,explan:6,load:6,construct:3,protocol:3,just:[0,5,6,3],when:[0,5,4,3,7,6],json_integer_format:3,exclud:7,obtain:[0,3],rest:3,refactor:5,aspect:3,json_is_object:[3,6],touch:3,config:[0,5],speed:3,languag:3,web:6,now:[0,4,5,6],struct:[3,5],widest:[3,4,5],also:[0,1,3,4,5,6,7],scenario:3,restructuredtext:0,supporetd:3,littl:5,desktop:2,add:[3,5,6,7],cleanup:5,simplejson:5,bigger:4,versa:3,json_loadb:[3,5],els:[3,6],expon:5,approxim:7,match:3,bin:5,int32:5,json_array_insert_new:3,refleak:5,format:[3,5,6],handl:[3,4,5,6,7],big:5,caller:3,howto:3,intuit:2,json_array_set_new:3,know:3,insert:[3,5],guid:5,bit:[3,4,5,1],password:3,l_isxdigit:5,licens:2,u0000:[3,5],loss:[3,7],ignor:[3,6],like:[3,5,7],success:[3,5],whitespac:[3,5],should:[3,4,5,1],changelog:5,integ:[3,5],mit:2,ldflag:5,collect:3,necessari:0,either:3,ieee:[3,7],furthermor:3,bunch:6,output:[3,5],hook:7,page:[2,3],underli:[3,4,5,7],encount:3,www:[0,3],json_load_callback:[3,5,6],old:4,deal:4,json_is_r:3,some:[0,5,6,3],json_decref:[3,5,6],vs2010:5,global:[3,5,1],shallow:[3,5],intern:[3,5,1,7],contin:5,sampl:3,proper:[3,6],guarante:[3,4],indirect:3,server:2,constitut:3,fromat:5,json_object_upd:3,win32:5,json_pack_ex:[3,5],friend:[5,1],lead:[3,5],json_object_set_new:3,leak:5,avoid:[3,5,6],extra:[3,4],json_string_length:[3,5],per:3,buffer:3,mathemat:7,larg:[7,5,1],prog:0,malloc_fn:3,three:3,freed:3,myint:3,run:[0,5,6,1,3],garbag:3,"enum":3,usag:[5,4,6],json_equ:[3,5],host:1,lexic:7,repositori:[0,6],offset:6,strlen:6,jansson_:3,microsecond:3,json_tru:3,chapter:[5,4],comparison:[3,7],about:[3,7],obj:3,json_loadf:[3,4,5],most:[3,4,1,7],column:[3,5],proce:6,json_object_iter_next:3,json_array_append_new:3,manag:[3,5,1],lifecycl:5,issu:[3,5],constructor:5,commit:2,disabl:3,block:3,compil:[3,5,7],own:[3,1],cflag:0,consid:[7,1],url_format:6,json_stringn_nocheck:[3,5],within:6,automat:[5,1],upgrad:[2,5],automak:0,guard:5,right:[3,6],been:[3,4,5,1],strip:[5,6],smarto:5,browser:0,json_escape_slash:[3,5],your:[0,7,4,1,3],merg:6,ccmake:0,inclus:3,git:0,wai:[0,6,3],area:3,errno:5,support:[0,2,5,4,3,7],buffer_po:6,bodi:6,transform:7,overwrit:3,verbos:5,strict:[3,5],reli:7,trigger:1,inner:3,message_text:6,ndebug:5,biggest:4,perform:[3,5,1,7],strictli:0,"_build":0,treat:[7,5],"function":[3,5],properli:5,typo:5,lockless:1,enough:[0,5,6,3],back:3,github:[2,5],"_new_":3,link:[0,4],measur:3,newer:[0,5],renam:[0,5],overflow:[3,5],inlin:5,bug:[3,5,1],conclus:2,faster:3,suppli:5,notat:7,json_array_clear:3,libcurl:6,utf:[2,7,5,3],input:[3,4,5],"09c39adc":6,possibl:[0,5,1,3],"default":[0,5,3],wish:3,access:[3,1],analyz:5,intermedi:6,below:[0,1,3],unspecifi:3,limit:6,sum:6,site:5,otherwis:[3,5],ljansson:[0,6],autoconf:5,secure_malloc:3,jansson_vers:[3,5],reachabl:3,featur:[2,5,6,3],hash:[3,5],json_allow_nul:[3,5],multibyt:3,certain:[3,1],"abstract":3,deep:[3,5],json_object_s:[3,5],"char":[3,5,6],itselfi:3,exist:[3,5],bd72efbd:6,our:6,request:6,mingw:5,inf:5,rogerz:6,check:[0,7,5,6,3],aabfd493:6,fill:[0,3],again:6,macro:[3,4,5,6],cmake:5,collector:3,estim:[7,5],json_disable_eof_check:[3,5],nan:5,detail:[0,5,6,3,2],local_cflag:5,setlocal:1,declar:[3,5,6],uint16_t:5,futur:[5,4],branch:6,test:[0,5,6,3,2],json_array_set:3,you:[0,6,1,3],json_load:[3,4,5,6],intention:1,architectur:1,repeat:3,json_is_arrai:[3,6],tweak:6,symbol:[5,6],introduc:4,invalid:[3,5],"040bd7b0":6,track:[3,1],preform:6,escap:[3,5],usr:0,singleton:[3,5],bracker:3,sisi:3,debian:5,fraction:7,multithread:1,state:[3,7,1],json_string_valu:[3,6],sphinx:[0,5],eof:[3,5],json_object_set:[3,5],vice:3,directori:5,hashtabl:[3,5,1],crash:[5,1],visual:[3,5],rule:7,depth:[5,4],text:[3,5,6,7],json_array_get:[3,6],arr1:3,time:[3,6,1],fresh:3,"export":[5,6],backward:[3,4,5],json_compact:[3,5],stick:6},objtypes:{"0":"c:function","1":"c:type","2":"c:member"},objnames:{"0":["c","function","C function"],"1":["c","type","C type"],"2":["c","member","C member"]},filenames:["gettingstarted","portability","index","apiref","upgrading","changes","tutorial","conformance"],titles:["Getting Started","Portability","Jansson Documentation","API Reference","Upgrading from 1.x","Changes in Jansson","Tutorial","RFC Conformance"],objects:{"":{json_is_string:[3,0,1,"c.json_is_string"],json_copy:[3,0,1,"c.json_copy"],json_array_insert:[3,0,1,"c.json_array_insert"],json_array_append:[3,0,1,"c.json_array_append"],json_typeof:[3,0,1,"c.json_typeof"],json_array_extend:[3,0,1,"c.json_array_extend"],json_is_object:[3,0,1,"c.json_is_object"],json_is_number:[3,0,1,"c.json_is_number"],json_object_key_to_iter:[3,0,1,"c.json_object_key_to_iter"],json_loads:[3,0,1,"c.json_loads"],json_object_update_existing:[3,0,1,"c.json_object_update_existing"],json_vpack_ex:[3,0,1,"c.json_vpack_ex"],json_string_nocheck:[3,0,1,"c.json_string_nocheck"],json_loadf:[3,0,1,"c.json_loadf"],json_object_foreach:[3,0,1,"c.json_object_foreach"],json_loadb:[3,0,1,"c.json_loadb"],json_object:[3,0,1,"c.json_object"],json_number_value:[3,0,1,"c.json_number_value"],json_array_clear:[3,0,1,"c.json_array_clear"],json_object_get:[3,0,1,"c.json_object_get"],json_array_set_new:[3,0,1,"c.json_array_set_new"],json_unpack:[3,0,1,"c.json_unpack"],json_unpack_ex:[3,0,1,"c.json_unpack_ex"],json_null:[3,0,1,"c.json_null"],json_load_callback:[3,0,1,"c.json_load_callback"],json_array_size:[3,0,1,"c.json_array_size"],json_integer_value:[3,0,1,"c.json_integer_value"],json_set_alloc_funcs:[3,0,1,"c.json_set_alloc_funcs"],json_is_null:[3,0,1,"c.json_is_null"],json_string_set:[3,0,1,"c.json_string_set"],json_is_boolean:[3,0,1,"c.json_is_boolean"],json_decref:[3,0,1,"c.json_decref"],json_string_length:[3,0,1,"c.json_string_length"],json_object_set:[3,0,1,"c.json_object_set"],json_false:[3,0,1,"c.json_false"],json_load_file:[3,0,1,"c.json_load_file"],json_pack_ex:[3,0,1,"c.json_pack_ex"],json_object_set_new:[3,0,1,"c.json_object_set_new"],json_dumpf:[3,0,1,"c.json_dumpf"],json_dumps:[3,0,1,"c.json_dumps"],json_load_callback_t:[3,1,1,"c.json_load_callback_t"],json_array_remove:[3,0,1,"c.json_array_remove"],json_object_iter_set_new:[3,0,1,"c.json_object_iter_set_new"],json_object_iter_set:[3,0,1,"c.json_object_iter_set"],json_array_foreach:[3,0,1,"c.json_array_foreach"],json_vunpack_ex:[3,0,1,"c.json_vunpack_ex"],json_dump_callback:[3,0,1,"c.json_dump_callback"],json_equal:[3,0,1,"c.json_equal"],json_object_seed:[3,0,1,"c.json_object_seed"],json_object_set_new_nocheck:[3,0,1,"c.json_object_set_new_nocheck"],json_object_iter_next:[3,0,1,"c.json_object_iter_next"],json_deep_copy:[3,0,1,"c.json_deep_copy"],json_array_append_new:[3,0,1,"c.json_array_append_new"],json_string_value:[3,0,1,"c.json_string_value"],json_object_update_missing:[3,0,1,"c.json_object_update_missing"],json_stringn:[3,0,1,"c.json_stringn"],json_type:[3,1,1,"c.json_type"],json_string_setn:[3,0,1,"c.json_string_setn"],json_pack:[3,0,1,"c.json_pack"],json_integer:[3,0,1,"c.json_integer"],json_array:[3,0,1,"c.json_array"],json_is_false:[3,0,1,"c.json_is_false"],json_object_del:[3,0,1,"c.json_object_del"],json_free_t:[3,1,1,"c.json_free_t"],json_array_set:[3,0,1,"c.json_array_set"],json_string_set_nocheck:[3,0,1,"c.json_string_set_nocheck"],json_int_t:[3,1,1,"c.json_int_t"],json_object_size:[3,0,1,"c.json_object_size"],json_string_setn_nocheck:[3,0,1,"c.json_string_setn_nocheck"],json_object_update:[3,0,1,"c.json_object_update"],json_object_iter_key:[3,0,1,"c.json_object_iter_key"],json_object_iter_value:[3,0,1,"c.json_object_iter_value"],json_is_integer:[3,0,1,"c.json_is_integer"],json_dump_callback_t:[3,1,1,"c.json_dump_callback_t"],json_boolean_value:[3,0,1,"c.json_boolean_value"],json_real_set:[3,0,1,"c.json_real_set"],json_dump_file:[3,0,1,"c.json_dump_file"],json_true:[3,0,1,"c.json_true"],json_boolean:[3,0,1,"c.json_boolean"],json_is_real:[3,0,1,"c.json_is_real"],json_real:[3,0,1,"c.json_real"],json_real_value:[3,0,1,"c.json_real_value"],json_object_clear:[3,0,1,"c.json_object_clear"],json_t:[3,1,1,"c.json_t"],json_error_t:[3,1,1,"c.json_error_t"],json_object_set_nocheck:[3,0,1,"c.json_object_set_nocheck"],json_stringn_nocheck:[3,0,1,"c.json_stringn_nocheck"],json_integer_set:[3,0,1,"c.json_integer_set"],json_is_array:[3,0,1,"c.json_is_array"],json_object_iter:[3,0,1,"c.json_object_iter"],json_malloc_t:[3,1,1,"c.json_malloc_t"],json_array_get:[3,0,1,"c.json_array_get"],json_array_insert_new:[3,0,1,"c.json_array_insert_new"],json_is_true:[3,0,1,"c.json_is_true"],json_incref:[3,0,1,"c.json_incref"],json_object_iter_at:[3,0,1,"c.json_object_iter_at"],json_string:[3,0,1,"c.json_string"]},json_error_t:{column:[3,2,1,"c.json_error_t.column"],position:[3,2,1,"c.json_error_t.position"],line:[3,2,1,"c.json_error_t.line"]}},titleterms:{represent:3,osx:0,xcode:0,prefix:0,underflow:7,platform:0,window:0,program:[0,6],local:1,real:7,string:[3,7],variou:0,get:0,fals:3,repo:6,report:3,introduct:2,like:0,list:4,integ:7,rfc:7,mingw:0,valid:3,compil:0,conform:7,set:0,sign:7,zero:7,librari:[0,3],compat:4,safeti:1,content:2,version:[3,5],refer:3,hash:1,studio:0,valu:3,addit:0,thread:1,equal:3,precis:7,jansson:[0,5,2],tutori:6,commit:6,chang:[0,4,5],portabl:1,arrai:3,encod:[3,7],number:[3,7],upgrad:4,unix:0,api:[3,6],instal:0,from:4,memori:[3,1],system:0,custom:3,start:0,includ:0,type:[3,7],"function":1,copi:3,visual:0,pars:3,overflow:7,"true":3,conclus:6,count:3,charact:7,error:3,autoconf:0,share:0,indic:2,seed:1,file:0,tabl:2,"null":3,incompat:4,cmake:0,make:0,same:0,other:0,decod:3,build:[0,3],android:0,document:[0,2],circular:3,preliminari:3,object:3,mac:0,alloc:[3,1],github:6,directori:0}}) \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/tutorial.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/tutorial.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,371 @@ + + + + + + + + Tutorial — Jansson 2.7 documentation + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      Tutorial¶

      +

      In this tutorial, we create a program that fetches the latest commits +of a repository in GitHub over the web. GitHub API uses JSON, so +the result can be parsed using Jansson.

      +

      To stick to the the scope of this tutorial, we will only cover the the +parts of the program related to handling JSON data. For the best user +experience, the full source code is available: +github_commits.c. To compile it (on Unix-like systems with +gcc), use the following command:

      +
      gcc -o github_commits github_commits.c -ljansson -lcurl
+
      +
      +

      libcurl is used to communicate over the web, so it is required to +compile the program.

      +

      The command line syntax is:

      +
      github_commits USER REPOSITORY
+
      +
      +

      USER is a GitHub user ID and REPOSITORY is the repository +name. Please note that the GitHub API is rate limited, so if you run +the program too many times within a short period of time, the sever +starts to respond with an error.

      +
      +

      The GitHub Repo Commits API¶

      +

      The GitHub Repo Commits API is used by sending HTTP requests to +URLs like https://api.github.com/repos/USER/REPOSITORY/commits, +where USER and REPOSITORY are the GitHub user ID and the name +of the repository whose commits are to be listed, respectively.

      +

      GitHub responds with a JSON array of the following form:

      +
      [
+    {
+        "sha": "<the commit ID>",
+        "commit": {
+            "message": "<the commit message>",
+            <more fields, not important to this tutorial...>
+        },
+        <more fields...>
+    },
+    {
+        "sha": "<the commit ID>",
+        "commit": {
+            "message": "<the commit message>",
+            <more fields...>
+        },
+        <more fields...>
+    },
+    <more commits...>
+]
+
      +
      +

      In our program, the HTTP request is sent using the following +function:

      +
      static char *request(const char *url);
+
      +
      +

      It takes the URL as a parameter, preforms a HTTP GET request, and +returns a newly allocated string that contains the response body. If +the request fails, an error message is printed to stderr and the +return value is NULL. For full details, refer to the code, as the actual implementation is not important +here.

      +
      +
      +

      The Program¶

      +

      First the includes:

      +
      #include <string.h>
+#include <jansson.h>
+
      +
      +

      Like all the programs using Jansson, we need to include +jansson.h.

      +

      The following definitions are used to build the GitHub API request +URL:

      +
      #define URL_FORMAT   "https://api.github.com/repos/%s/%s/commits"
+#define URL_SIZE     256
+
      +
      +

      The following function is used when formatting the result to find the +first newline in the commit message:

      +
      /* Return the offset of the first newline in text or the length of
+   text if there's no newline */
+static int newline_offset(const char *text)
+{
+    const char *newline = strchr(text, '\n');
+    if(!newline)
+        return strlen(text);
+    else
+        return (int)(newline - text);
+}
+
      +
      +

      The main function follows. In the beginning, we first declare a bunch +of variables and check the command line parameters:

      +
      int main(int argc, char *argv[])
+{
+    size_t i;
+    char *text;
+    char url[URL_SIZE];
+
+    json_t *root;
+    json_error_t error;
+
+    if(argc != 3)
+    {
+        fprintf(stderr, "usage: %s USER REPOSITORY\n\n", argv[0]);
+        fprintf(stderr, "List commits at USER's REPOSITORY.\n\n");
+        return 2;
+    }
+
      +
      +

      Then we build the request URL using the user and repository names +given as command line parameters:

      +
      snprintf(url, URL_SIZE, URL_FORMAT, argv[1], argv[2]);
+
      +
      +

      This uses the URL_SIZE and URL_FORMAT constants defined above. +Now we’re ready to actually request the JSON data over the web:

      +
      text = request(url);
+if(!text)
+    return 1;
+
      +
      +

      If an error occurs, our function request prints the error and +returns NULL, so it’s enough to just return 1 from the main +function.

      +

      Next we’ll call json_loads() to decode the JSON text we got +as a response:

      +
      root = json_loads(text, 0, &error);
+free(text);
+
+if(!root)
+{
+    fprintf(stderr, "error: on line %d: %s\n", error.line, error.text);
+    return 1;
+}
+
      +
      +

      We don’t need the JSON text anymore, so we can free the text +variable right after decoding it. If json_loads() fails, it +returns NULL and sets error information to the json_error_t +structure given as the second parameter. In this case, our program +prints the error information out and returns 1 from the main function.

      +

      Now we’re ready to extract the data out of the decoded JSON response. +The structure of the response JSON was explained in section +The GitHub Repo Commits API.

      +

      We check that the returned value really is an array:

      +
      if(!json_is_array(root))
+{
+    fprintf(stderr, "error: root is not an array\n");
+    json_decref(root);
+    return 1;
+}
+
      +
      +

      Then we proceed to loop over all the commits in the array:

      +
      for(i = 0; i < json_array_size(root); i++)
+{
+    json_t *data, *sha, *commit, *message;
+    const char *message_text;
+
+    data = json_array_get(root, i);
+    if(!json_is_object(data))
+    {
+        fprintf(stderr, "error: commit data %d is not an object\n", i + 1);
+        json_decref(root);
+        return 1;
+    }
+...
+
      +
      +

      The function json_array_size() returns the size of a JSON +array. First, we again declare some variables and then extract the +i’th element of the root array using json_array_get(). +We also check that the resulting value is a JSON object.

      +

      Next we’ll extract the commit ID (a hexadecimal SHA-1 sum), +intermediate commit info object, and the commit message from that +object. We also do proper type checks:

      +
          sha = json_object_get(data, "sha");
+    if(!json_is_string(sha))
+    {
+        fprintf(stderr, "error: commit %d: sha is not a string\n", i + 1);
+        json_decref(root);
+        return 1;
+    }
+
+    commit = json_object_get(data, "commit");
+    if(!json_is_object(commit))
+    {
+        fprintf(stderr, "error: commit %d: commit is not an object\n", i + 1);
+        json_decref(root);
+        return 1;
+    }
+
+    message = json_object_get(commit, "message");
+    if(!json_is_string(message))
+    {
+        fprintf(stderr, "error: commit %d: message is not a string\n", i + 1);
+        json_decref(root);
+        return 1;
+    }
+...
+
      +
      +

      And finally, we’ll print the first 8 characters of the commit ID and +the first line of the commit message. A C-style string is extracted +from a JSON string using json_string_value():

      +
          message_text = json_string_value(message);
+    printf("%.8s %.*s\n",
+           json_string_value(id),
+           newline_offset(message_text),
+           message_text);
+}
+
      +
      +

      After sending the HTTP request, we decoded the JSON text using +json_loads(), remember? It returns a new reference to the +JSON value it decodes. When we’re finished with the value, we’ll need +to decrease the reference count using json_decref(). This way +Jansson can release the resources:

      +
      json_decref(root);
+return 0;
+
      +
      +

      For a detailed explanation of reference counting in Jansson, see +Reference Count in API Reference.

      +

      The program’s ready, let’s test it and view the latest commits in +Jansson’s repository:

      +
      $ ./github_commits akheron jansson
+1581f26a Merge branch '2.3'
+aabfd493 load: Change buffer_pos to be a size_t
+bd72efbd load: Avoid unexpected behaviour in macro expansion
+e8fd3e30 Document and tweak json_load_callback()
+873eddaf Merge pull request #60 from rogerz/contrib
+bd2c0c73 Ignore the binary test_load_callback
+17a51a4b Merge branch '2.3'
+09c39adc Add json_load_callback to the list of exported symbols
+cbb80baf Merge pull request #57 from rogerz/contrib
+040bd7b0 Add json_load_callback()
+2637faa4 Make test stripping locale independent
+<...>
+
      +
      +
      +
      +

      Conclusion¶

      +

      In this tutorial, we implemented a program that fetches the latest +commits of a GitHub repository using the GitHub Repo Commits API. +Jansson was used to decode the JSON response and to extract the commit +data.

      +

      This tutorial only covered a small part of Jansson. For example, we +did not create or manipulate JSON values at all. Proceed to +API Reference to explore all features of Jansson.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      Upgrading from 1.x

      +

      Next topic

      +

      RFC Conformance

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/html/upgrading.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/html/upgrading.html Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,181 @@ + + + + + + + + Upgrading from 1.x — Jansson 2.7 documentation + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      Upgrading from 1.x¶

      +

      This chapter lists the backwards incompatible changes introduced in +Jansson 2.0, and the steps that are needed for upgrading your code.

      +

      The incompatibilities are not dramatic. The biggest change is that +all decoding functions now require and extra parameter. Most programs +can be modified to work with 2.0 by adding a 0 as the second +parameter to all calls of json_loads(), json_loadf() +and json_load_file().

      +
      +

      Compatibility¶

      +

      Jansson 2.0 is backwards incompatible with the Jansson 1.x releases. +It is ABI incompatible, i.e. all programs dynamically linking to the +Jansson library need to be recompiled. It’s also API incompatible, +i.e. the source code of programs using Jansson 1.x may need +modifications to make them compile against Jansson 2.0.

      +

      All the 2.x releases are guaranteed to be backwards compatible for +both ABI and API, so no recompilation or source changes are needed +when upgrading from 2.x to 2.y.

      +
      +
      +

      List of Incompatible Changes¶

      +
      +
      Decoding flags
      +

      For future needs, a flags parameter was added as the second +parameter to all decoding functions, i.e. json_loads(), +json_loadf() and json_load_file(). All calls to +these functions need to be changed by adding a 0 as the second +argument. For example:

      +
      /* old code */
+json_loads(input, &error);
+
+/* new code */
+json_loads(input, 0, &error);
+
      +
      +
      +
      Underlying type of JSON integers
      +

      The underlying C type of JSON integers has been changed from +int to the widest available signed integer type, i.e. +long long or long, depending on whether +long long is supported on your system or not. This makes +the whole 64-bit integer range available on most modern systems.

      +

      jansson.h has a typedef json_int_t to the underlying +integer type. int should still be used in most cases when +dealing with smallish JSON integers, as the compiler handles +implicit type coercion. Only when the full 64-bit range is needed, +json_int_t should be explicitly used.

      +
      +
      Maximum encoder indentation depth
      +
      The maximum argument of the JSON_INDENT() macro has been +changed from 255 to 31, to free up bits from the flags +parameter of json_dumps(), json_dumpf() and +json_dump_file(). If your code uses a bigger indentation +than 31, it needs to be changed.
      +
      Unsigned integers in API functions
      +
      Version 2.0 unifies unsigned integer usage in the API. All uses of +unsigned int and unsigned long have been replaced +with size_t. This includes flags, container sizes, etc. +This should not require source code changes, as both +unsigned int and unsigned long are usually +compatible with size_t.
      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      Getting Started

      +

      Next topic

      +

      Tutorial

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2009-2014, Petri Lehtinen. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/doc/man3lib/libjansson.3lib --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/doc/man3lib/libjansson.3lib Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,3652 @@ +.\" Man page generated from reStructuredText. +. +.TH "LIBJANSSON" "3LIB" "October 28, 2014" "2.7" "Jansson" +.SH NAME +jansson \- Jansson Documentation +.sp +This is the documentation for \fI\%Jansson\fP 2.7, last updated October 28, 2014\&. +.SH INTRODUCTION +.sp +\fI\%Jansson\fP is a C library for encoding, decoding and manipulating JSON +data. Its main features and design principles are: +.INDENT 0.0 +.IP \(bu 2 +Simple and intuitive API and data model +.IP \(bu 2 +Comprehensive documentation +.IP \(bu 2 +No dependencies on other libraries +.IP \(bu 2 +Full Unicode support (UTF\-8) +.IP \(bu 2 +Extensive test suite +.UNINDENT +.sp +Jansson is licensed under the \fI\%MIT license\fP; see LICENSE in the +source distribution for details. +.sp +Jansson is used in production and its API is stable. It works on +numerous platforms, including numerous Unix like systems and Windows. +It\(aqs suitable for use on any system, including desktop, server, and +small embedded systems. +.SH CONTENTS +.SS Getting Started +.SS Compiling and Installing Jansson +.sp +The Jansson source is available at +\fI\%http://www.digip.org/jansson/releases/\fP\&. +.SS Unix\-like systems (including MinGW) +.sp +Unpack the source tarball and change to the source directory: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +bunzip2 \-c jansson\-2.7\&.tar.bz2 | tar xf \- +cd jansson\-2.7 +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +The source uses GNU Autotools (\fI\%autoconf\fP, \fI\%automake\fP, \fI\%libtool\fP), so +compiling and installing is extremely simple: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +\&./configure +make +make check +make install +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +To change the destination directory (\fB/usr/local\fP by default), use +the \fB\-\-prefix=DIR\fP argument to \fB\&./configure\fP\&. See \fB\&./configure +\-\-help\fP for the list of all possible installation options. (There are +no options to customize the resulting Jansson binary.) +.sp +The command \fBmake check\fP runs the test suite distributed with +Jansson. This step is not strictly necessary, but it may find possible +problems that Jansson has on your platform. If any problems are found, +please report them. +.sp +If you obtained the source from a Git repository (or any other source +control system), there\(aqs no \fB\&./configure\fP script as it\(aqs not kept in +version control. To create the script, the build system needs to be +bootstrapped. There are many ways to do this, but the easiest one is +to use \fBautoreconf\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +autoreconf \-vi +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +This command creates the \fB\&./configure\fP script, which can then be +used as described above. +.SS CMake (various platforms, including Windows) +.sp +Jansson can be built using \fI\%CMake\fP\&. Create a build directory for an +out\-of\-tree build, change to that directory, and run \fBcmake\fP (or \fBccmake\fP, +\fBcmake\-gui\fP, or similar) to configure the project. +.sp +See the examples below for more detailed information. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +In the below examples \fB\&..\fP is used as an argument for \fBcmake\fP\&. +This is simply the path to the jansson project root directory. +In the example it is assumed you\(aqve created a sub\-directory \fBbuild\fP +and are using that. You could use any path you want. +.UNINDENT +.UNINDENT +.SS Unix (Make files) +.sp +Generating make files on unix: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +bunzip2 \-c jansson\-2.7\&.tar.bz2 | tar xf \- +cd jansson\-2.7 + +mkdir build +cd build +cmake .. # or \fBccmake ..()\fP for a GUI. +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Then to build: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +make +make check +make install +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Windows (Visual Studio) +.sp +Creating Visual Studio project files from the command line: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW + +cd jansson\-2.7 + +md build +cd build +cmake \-G "Visual Studio 10" .. +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +You will now have a \fIVisual Studio Solution\fP in your build directory. +To run the unit tests build the \fBRUN_TESTS\fP project. +.sp +If you prefer a GUI the \fBcmake\fP line in the above example can +be replaced with: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +cmake\-gui .. +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +For command line help (including a list of available generators) +for \fI\%CMake\fP simply run: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +cmake +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +To list available \fI\%CMake\fP settings (and what they are currently set to) +for the project, run: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +cmake \-LH .. +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Mac OSX (Xcode) +.sp +If you prefer using Xcode instead of make files on OSX, +do the following. (Use the same steps as +for \fIUnix\fP): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +\&... +cmake \-G "Xcode" .. +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Additional CMake settings +.SS Shared library +.sp +By default the \fI\%CMake\fP project will generate build files for building the +static library. To build the shared version use: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +\&... +cmake \-DJANSSON_BUILD_SHARED_LIBS=1 .. +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Changing install directory (same as autoconf \-\-prefix) +.sp +Just as with the \fI\%autoconf\fP project you can change the destination directory +for \fBmake install\fP\&. The equivalent for autoconfs \fB\&./configure \-\-prefix\fP +in \fI\%CMake\fP is: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +\&... +cmake \-DCMAKE_INSTALL_PREFIX:PATH=/some/other/path .. +make install +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Android +.sp +Jansson can be built for Android platforms. Android.mk is in the +source root directory. The configuration header file is located in the +\fBandroid\fP directory in the source distribution. +.SS Other Systems +.sp +On non Unix\-like systems, you may be unable to run the \fB\&./configure\fP +script. In this case, follow these steps. All the files mentioned can +be found in the \fBsrc/\fP directory. +.INDENT 0.0 +.IP 1. 3 +Create \fBjansson_config.h\fP (which has some platform\-specific +parameters that are normally filled in by the \fB\&./configure\fP +script). Edit \fBjansson_config.h.in\fP, replacing all \fB@variable@\fP +placeholders, and rename the file to \fBjansson_config.h\fP\&. +.IP 2. 3 +Make \fBjansson.h\fP and \fBjansson_config.h\fP available to the +compiler, so that they can be found when compiling programs that +use Jansson. +.IP 3. 3 +Compile all the \fB\&.c\fP files (in the \fBsrc/\fP directory) into a +library file. Make the library available to the compiler, as in +step 2. +.UNINDENT +.SS Building the Documentation +.sp +(This subsection describes how to build the HTML documentation you are +currently reading, so it can be safely skipped.) +.sp +Documentation is in the \fBdoc/\fP subdirectory. It\(aqs written in +\fI\%reStructuredText\fP with \fI\%Sphinx\fP annotations. To generate the HTML +documentation, invoke: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +make html +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +and point your browser to \fBdoc/_build/html/index.html\fP\&. \fI\%Sphinx\fP 1.0 +or newer is required to generate the documentation. +.SS Compiling Programs that Use Jansson +.sp +Jansson involves one C header file, \fBjansson.h\fP, so it\(aqs enough +to put the line +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +#include +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +in the beginning of every source file that uses Jansson. +.sp +There\(aqs also just one library to link with, \fBlibjansson\fP\&. Compile and +link the program as follows: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +cc \-I/usr/include/jansson \-o prog prog.c \-ljansson +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Starting from version 1.2, there\(aqs also support for \fI\%pkg\-config\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +cc \-o prog prog.c \(gapkg\-config \-\-cflags \-\-libs jansson\(ga +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Upgrading from 1.x +.sp +This chapter lists the backwards incompatible changes introduced in +Jansson 2.0, and the steps that are needed for upgrading your code. +.sp +\fBThe incompatibilities are not dramatic.\fP The biggest change is that +all decoding functions now require and extra parameter. Most programs +can be modified to work with 2.0 by adding a \fB0\fP as the second +parameter to all calls of \fBjson_loads()\fP, \fBjson_loadf()\fP +and \fBjson_load_file()\fP\&. +.SS Compatibility +.sp +Jansson 2.0 is backwards incompatible with the Jansson 1.x releases. +It is ABI incompatible, i.e. all programs dynamically linking to the +Jansson library need to be recompiled. It\(aqs also API incompatible, +i.e. the source code of programs using Jansson 1.x may need +modifications to make them compile against Jansson 2.0. +.sp +All the 2.x releases are guaranteed to be backwards compatible for +both ABI and API, so no recompilation or source changes are needed +when upgrading from 2.x to 2.y. +.SS List of Incompatible Changes +.INDENT 0.0 +.TP +.B \fBDecoding flags\fP +For future needs, a \fBflags\fP parameter was added as the second +parameter to all decoding functions, i.e. \fBjson_loads()\fP, +\fBjson_loadf()\fP and \fBjson_load_file()\fP\&. All calls to +these functions need to be changed by adding a \fB0\fP as the second +argument. For example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* old code */ +json_loads(input, &error); + +/* new code */ +json_loads(input, 0, &error); +.ft R +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBUnderlying type of JSON integers\fP +The underlying C type of JSON integers has been changed from +\fBint\fP to the widest available signed integer type, i.e. +\fBlong long\fP or \fBlong\fP, depending on whether +\fBlong long\fP is supported on your system or not. This makes +the whole 64\-bit integer range available on most modern systems. +.sp +\fBjansson.h\fP has a typedef \fBjson_int_t\fP to the underlying +integer type. \fBint\fP should still be used in most cases when +dealing with smallish JSON integers, as the compiler handles +implicit type coercion. Only when the full 64\-bit range is needed, +\fBjson_int_t\fP should be explicitly used. +.TP +.B \fBMaximum encoder indentation depth\fP +The maximum argument of the \fBJSON_INDENT()\fP macro has been +changed from 255 to 31, to free up bits from the \fBflags\fP +parameter of \fBjson_dumps()\fP, \fBjson_dumpf()\fP and +\fBjson_dump_file()\fP\&. If your code uses a bigger indentation +than 31, it needs to be changed. +.TP +.B \fBUnsigned integers in API functions\fP +Version 2.0 unifies unsigned integer usage in the API. All uses of +\fBunsigned int\fP and \fBunsigned long\fP have been replaced +with \fBsize_t\fP\&. This includes flags, container sizes, etc. +This should not require source code changes, as both +\fBunsigned int\fP and \fBunsigned long\fP are usually +compatible with \fBsize_t\fP\&. +.UNINDENT +.SS Tutorial +.sp +In this tutorial, we create a program that fetches the latest commits +of a repository in \fI\%GitHub\fP over the web. \fI\%GitHub API\fP uses JSON, so +the result can be parsed using Jansson. +.sp +To stick to the the scope of this tutorial, we will only cover the the +parts of the program related to handling JSON data. For the best user +experience, the full source code is available: +\fBgithub_commits.c\fP\&. To compile it (on Unix\-like systems with +gcc), use the following command: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +gcc \-o github_commits github_commits.c \-ljansson \-lcurl +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +\fI\%libcurl\fP is used to communicate over the web, so it is required to +compile the program. +.sp +The command line syntax is: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +github_commits USER REPOSITORY +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +\fBUSER\fP is a GitHub user ID and \fBREPOSITORY\fP is the repository +name. Please note that the GitHub API is rate limited, so if you run +the program too many times within a short period of time, the sever +starts to respond with an error. +.SS The GitHub Repo Commits API +.sp +The \fI\%GitHub Repo Commits API\fP is used by sending HTTP requests to +URLs like \fBhttps://api.github.com/repos/USER/REPOSITORY/commits\fP, +where \fBUSER\fP and \fBREPOSITORY\fP are the GitHub user ID and the name +of the repository whose commits are to be listed, respectively. +.sp +GitHub responds with a JSON array of the following form: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +[ + { + "sha": "", + "commit": { + "message": "", + + }, + + }, + { + "sha": "", + "commit": { + "message": "", + + }, + + }, + +] +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +In our program, the HTTP request is sent using the following +function: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +static char *request(const char *url); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +It takes the URL as a parameter, preforms a HTTP GET request, and +returns a newly allocated string that contains the response body. If +the request fails, an error message is printed to stderr and the +return value is \fINULL\fP\&. For full details, refer to \fBthe code\fP, as the actual implementation is not important +here. +.SS The Program +.sp +First the includes: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +#include +#include +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Like all the programs using Jansson, we need to include +\fBjansson.h\fP\&. +.sp +The following definitions are used to build the GitHub API request +URL: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +#define URL_FORMAT "https://api.github.com/repos/%s/%s/commits" +#define URL_SIZE 256 +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +The following function is used when formatting the result to find the +first newline in the commit message: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* Return the offset of the first newline in text or the length of + text if there\(aqs no newline */ +static int newline_offset(const char *text) +{ + const char *newline = strchr(text, \(aq\en\(aq); + if(!newline) + return strlen(text); + else + return (int)(newline \- text); +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +The main function follows. In the beginning, we first declare a bunch +of variables and check the command line parameters: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +int main(int argc, char *argv[]) +{ + size_t i; + char *text; + char url[URL_SIZE]; + + json_t *root; + json_error_t error; + + if(argc != 3) + { + fprintf(stderr, "usage: %s USER REPOSITORY\en\en", argv[0]); + fprintf(stderr, "List commits at USER\(aqs REPOSITORY.\en\en"); + return 2; + } +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Then we build the request URL using the user and repository names +given as command line parameters: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +snprintf(url, URL_SIZE, URL_FORMAT, argv[1], argv[2]); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +This uses the \fBURL_SIZE\fP and \fBURL_FORMAT\fP constants defined above. +Now we\(aqre ready to actually request the JSON data over the web: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +text = request(url); +if(!text) + return 1; +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +If an error occurs, our function \fBrequest\fP prints the error and +returns \fINULL\fP, so it\(aqs enough to just return 1 from the main +function. +.sp +Next we\(aqll call \fBjson_loads()\fP to decode the JSON text we got +as a response: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +root = json_loads(text, 0, &error); +free(text); + +if(!root) +{ + fprintf(stderr, "error: on line %d: %s\en", error.line, error.text); + return 1; +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +We don\(aqt need the JSON text anymore, so we can free the \fBtext\fP +variable right after decoding it. If \fBjson_loads()\fP fails, it +returns \fINULL\fP and sets error information to the \fBjson_error_t\fP +structure given as the second parameter. In this case, our program +prints the error information out and returns 1 from the main function. +.sp +Now we\(aqre ready to extract the data out of the decoded JSON response. +The structure of the response JSON was explained in section +\fI\%The GitHub Repo Commits API\fP\&. +.sp +We check that the returned value really is an array: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +if(!json_is_array(root)) +{ + fprintf(stderr, "error: root is not an array\en"); + json_decref(root); + return 1; +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Then we proceed to loop over all the commits in the array: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +for(i = 0; i < json_array_size(root); i++) +{ + json_t *data, *sha, *commit, *message; + const char *message_text; + + data = json_array_get(root, i); + if(!json_is_object(data)) + { + fprintf(stderr, "error: commit data %d is not an object\en", i + 1); + json_decref(root); + return 1; + } +\&... +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +The function \fBjson_array_size()\fP returns the size of a JSON +array. First, we again declare some variables and then extract the +i\(aqth element of the \fBroot\fP array using \fBjson_array_get()\fP\&. +We also check that the resulting value is a JSON object. +.sp +Next we\(aqll extract the commit ID (a hexadecimal SHA\-1 sum), +intermediate commit info object, and the commit message from that +object. We also do proper type checks: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW + sha = json_object_get(data, "sha"); + if(!json_is_string(sha)) + { + fprintf(stderr, "error: commit %d: sha is not a string\en", i + 1); + json_decref(root); + return 1; + } + + commit = json_object_get(data, "commit"); + if(!json_is_object(commit)) + { + fprintf(stderr, "error: commit %d: commit is not an object\en", i + 1); + json_decref(root); + return 1; + } + + message = json_object_get(commit, "message"); + if(!json_is_string(message)) + { + fprintf(stderr, "error: commit %d: message is not a string\en", i + 1); + json_decref(root); + return 1; + } +\&... +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +And finally, we\(aqll print the first 8 characters of the commit ID and +the first line of the commit message. A C\-style string is extracted +from a JSON string using \fBjson_string_value()\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW + message_text = json_string_value(message); + printf("%.8s %.*s\en", + json_string_value(id), + newline_offset(message_text), + message_text); +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +After sending the HTTP request, we decoded the JSON text using +\fBjson_loads()\fP, remember? It returns a \fInew reference\fP to the +JSON value it decodes. When we\(aqre finished with the value, we\(aqll need +to decrease the reference count using \fBjson_decref()\fP\&. This way +Jansson can release the resources: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_decref(root); +return 0; +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +For a detailed explanation of reference counting in Jansson, see +\fIapiref\-reference\-count\fP in \fIapiref\fP\&. +.sp +The program\(aqs ready, let\(aqs test it and view the latest commits in +Jansson\(aqs repository: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +$ ./github_commits akheron jansson +1581f26a Merge branch \(aq2.3\(aq +aabfd493 load: Change buffer_pos to be a size_t +bd72efbd load: Avoid unexpected behaviour in macro expansion +e8fd3e30 Document and tweak json_load_callback() +873eddaf Merge pull request #60 from rogerz/contrib +bd2c0c73 Ignore the binary test_load_callback +17a51a4b Merge branch \(aq2.3\(aq +09c39adc Add json_load_callback to the list of exported symbols +cbb80baf Merge pull request #57 from rogerz/contrib +040bd7b0 Add json_load_callback() +2637faa4 Make test stripping locale independent +<...> +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Conclusion +.sp +In this tutorial, we implemented a program that fetches the latest +commits of a GitHub repository using the GitHub Repo Commits API. +Jansson was used to decode the JSON response and to extract the commit +data. +.sp +This tutorial only covered a small part of Jansson. For example, we +did not create or manipulate JSON values at all. Proceed to +\fIapiref\fP to explore all features of Jansson. +.SS RFC Conformance +.sp +JSON is specified in \fI\%RFC 4627\fP, \fI"The application/json Media Type +for JavaScript Object Notation (JSON)"\fP\&. +.SS Character Encoding +.sp +Jansson only supports UTF\-8 encoded JSON texts. It does not support or +auto\-detect any of the other encodings mentioned in the RFC, namely +UTF\-16LE, UTF\-16BE, UTF\-32LE or UTF\-32BE. Pure ASCII is supported, as +it\(aqs a subset of UTF\-8. +.SS Strings +.sp +JSON strings are mapped to C\-style null\-terminated character arrays, +and UTF\-8 encoding is used internally. +.sp +All Unicode codepoints U+0000 through U+10FFFF are allowed in string +values. However, U+0000 is not allowed in object keys because of API +restrictions. +.sp +Unicode normalization or any other transformation is never performed +on any strings (string values or object keys). When checking for +equivalence of strings or object keys, the comparison is performed +byte by byte between the original UTF\-8 representations of the +strings. +.SS Numbers +.SS Real vs. Integer +.sp +JSON makes no distinction between real and integer numbers; Jansson +does. Real numbers are mapped to the \fBdouble\fP type and integers to +the \fBjson_int_t\fP type, which is a typedef of \fBlong long\fP or +\fBlong\fP, depending on whether \fBlong long\fP is supported by your +compiler or not. +.sp +A JSON number is considered to be a real number if its lexical +representation includes one of \fBe\fP, \fBE\fP, or \fB\&.\fP; regardless if +its actual numeric value is a true integer (e.g., all of \fB1E6\fP, +\fB3.0\fP, \fB400E\-2\fP, and \fB3.14E3\fP are mathematical integers, but +will be treated as real values). With the \fBJSON_DECODE_INT_AS_REAL\fP +decoder flag set all numbers are interpreted as real. +.sp +All other JSON numbers are considered integers. +.sp +When encoding to JSON, real values are always represented +with a fractional part; e.g., the \fBdouble\fP value 3.0 will be +represented in JSON as \fB3.0\fP, not \fB3\fP\&. +.SS Overflow, Underflow & Precision +.sp +Real numbers whose absolute values are too small to be represented in +a C \fBdouble\fP will be silently estimated with 0.0. Thus, depending on +platform, JSON numbers very close to zero such as 1E\-999 may result in +0.0. +.sp +Real numbers whose absolute values are too large to be represented in +a C \fBdouble\fP will result in an overflow error (a JSON decoding +error). Thus, depending on platform, JSON numbers like 1E+999 or +\-1E+999 may result in a parsing error. +.sp +Likewise, integer numbers whose absolute values are too large to be +represented in the \fBjson_int_t\fP type (see above) will result in an +overflow error (a JSON decoding error). Thus, depending on platform, +JSON numbers like 1000000000000000 may result in parsing error. +.sp +Parsing JSON real numbers may result in a loss of precision. As long +as overflow does not occur (i.e. a total loss of precision), the +rounded approximate value is silently used. Thus the JSON number +1.000000000000000005 may, depending on platform, result in the +\fBdouble\fP value 1.0. +.SS Signed zeros +.sp +JSON makes no statement about what a number means; however Javascript +(ECMAscript) does state that +0.0 and \-0.0 must be treated as being +distinct values, i.e. \-0.0 ≠ 0.0. Jansson relies on the +underlying floating point library in the C environment in which it is +compiled. Therefore it is platform\-dependent whether 0.0 and \-0.0 will +be distinct values. Most platforms that use the IEEE 754 +floating\-point standard will support signed zeros. +.sp +Note that this only applies to floating\-point; neither JSON, C, or +IEEE support the concept of signed integer zeros. +.SS Types +.sp +No support is provided in Jansson for any C numeric types other than +\fBjson_int_t\fP and \fBdouble\fP\&. This excludes things such as unsigned +types, \fBlong double\fP, etc. Obviously, shorter types like \fBshort\fP, +\fBint\fP, \fBlong\fP (if \fBjson_int_t\fP is \fBlong long\fP) and \fBfloat\fP +are implicitly handled via the ordinary C type coercion rules (subject +to overflow semantics). Also, no support or hooks are provided for any +supplemental "bignum" type add\-on packages. +.SS Portability +.SS Thread safety +.sp +Jansson is thread safe and has no mutable global state. The only +exceptions are the hash function seed and memory allocation functions, +see below. +.sp +There\(aqs no locking performed inside Jansson\(aqs code, so a multithreaded +program must perform its own locking if JSON values are shared by +multiple threads. Jansson\(aqs reference counting semantics may make this +a bit harder than it seems, as it\(aqs possible to have a reference to a +value that\(aqs also stored inside a list or object. Modifying the +container (adding or removing values) may trigger concurrent access to +such values, as containers manage the reference count of their +contained values. Bugs involving concurrent incrementing or +decrementing of deference counts may be hard to track. +.sp +The encoding functions (\fBjson_dumps()\fP and friends) track +reference loops by modifying the internal state of objects and arrays. +For this reason, encoding functions must not be run on the same JSON +values in two separate threads at the same time. As already noted +above, be especially careful if two arrays or objects share their +contained values with another array or object. +.sp +If you want to make sure that two JSON value hierarchies do not +contain shared values, use \fBjson_deep_copy()\fP to make copies. +.SS Hash function seed +.sp +To prevent an attacker from intentionally causing large JSON objects +with specially crafted keys to perform very slow, the hash function +used by Jansson is randomized using a seed value. The seed is +automatically generated on the first explicit or implicit call to +\fBjson_object()\fP, if \fBjson_object_seed()\fP has not been +called beforehand. +.sp +The seed is generated by using operating system\(aqs entropy sources if +they are available (\fB/dev/urandom\fP, \fBCryptGenRandom()\fP). The +initialization is done in as thread safe manner as possible, by using +architecture specific lockless operations if provided by the platform +or the compiler. +.sp +If you\(aqre using threads, it\(aqs recommended to autoseed the hashtable +explicitly before spawning any threads by calling +\fBjson_object_seed(0)\fP , especially if you\(aqre unsure whether the +initialization is thread safe on your platform. +.SS Memory allocation functions +.sp +Memory allocation functions should be set at most once, and only on +program startup. See \fIapiref\-custom\-memory\-allocation\fP\&. +.SS Locale +.sp +Jansson works fine under any locale. +.sp +However, if the host program is multithreaded and uses \fBsetlocale()\fP +to switch the locale in one thread while Jansson is currently encoding +or decoding JSON data in another thread, the result may be wrong or +the program may even crash. +.sp +Jansson uses locale specific functions for certain string conversions +in the encoder and decoder, and then converts the locale specific +values to/from the JSON representation. This fails if the locale +changes between the string conversion and the locale\-to\-JSON +conversion. This can only happen in multithreaded programs that use +\fBsetlocale()\fP, because \fBsetlocale()\fP switches the locale for all +running threads, not only the thread that calls \fBsetlocale()\fP\&. +.sp +If your program uses \fBsetlocale()\fP as described above, consider +using the thread\-safe \fBuselocale()\fP instead. +.SS API Reference +.SS Preliminaries +.sp +All declarations are in \fBjansson.h\fP, so it\(aqs enough to +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +#include +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +in each source file. +.sp +All constants are prefixed with \fBJSON_\fP (except for those describing +the library version, prefixed with \fBJANSSON_\fP). Other identifiers +are prefixed with \fBjson_\fP\&. Type names are suffixed with \fB_t\fP and +\fBtypedef\fP\(aqd so that the \fBstruct\fP keyword need not be used. +.SS Library Version +.sp +The Jansson version is of the form \fIA.B.C\fP, where \fIA\fP is the major +version, \fIB\fP is the minor version and \fIC\fP is the micro version. If the +micro version is zero, it\(aqs omitted from the version string, i.e. the +version string is just \fIA.B\fP\&. +.sp +When a new release only fixes bugs and doesn\(aqt 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. +.sp +The following preprocessor constants specify the current version of +the library: +.INDENT 0.0 +.TP +.B \fBJANSSON_MAJOR_VERSION\fP, \fBJANSSON_MINOR_VERSION\fP, \fBJANSSON_MICRO_VERSION\fP +Integers specifying the major, minor and micro versions, +respectively. +.TP +.B \fBJANSSON_VERSION\fP +A string representation of the current version, e.g. \fB"1.2.1"\fP or +\fB"1.3"\fP\&. +.TP +.B \fBJANSSON_VERSION_HEX\fP +A 3\-byte hexadecimal representation of the version, e.g. +\fB0x010201\fP for version 1.2.1 and \fB0x010300\fP for version 1.3. +This is useful in numeric comparisions, e.g.: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +#if JANSSON_VERSION_HEX >= 0x010300 +/* Code specific to version 1.3 and above */ +#endif +.ft R +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS Value Representation +.sp +The JSON specification (\fI\%RFC 4627\fP) defines the following data types: +\fIobject\fP, \fIarray\fP, \fIstring\fP, \fInumber\fP, \fIboolean\fP, and \fInull\fP\&. JSON +types are used dynamically; arrays and objects can hold any other data +type, including themselves. For this reason, Jansson\(aqs type system is +also dynamic in nature. There\(aqs one C type to represent all JSON +values, and this structure knows the type of the JSON value it holds. +.INDENT 0.0 +.TP +.B 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\(aqs reference count. The rest depends on the type of the +value. +.UNINDENT +.sp +Objects of \fBjson_t\fP 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. +.sp +Unless noted otherwise, all API functions return an error value if an +error occurs. Depending on the function\(aqs signature, the error value +is either \fINULL\fP or \-1. Invalid arguments or invalid input are +apparent sources for errors. Memory allocation and I/O operations may +also cause errors. +.SS Type +.sp +The type of a JSON value is queried and tested using the following +functions: +.INDENT 0.0 +.TP +.B enum json_type +The type of a JSON value. The following members are defined: +.TS +center; +|l|. +_ +T{ +\fBJSON_OBJECT\fP +T} +_ +T{ +\fBJSON_ARRAY\fP +T} +_ +T{ +\fBJSON_STRING\fP +T} +_ +T{ +\fBJSON_INTEGER\fP +T} +_ +T{ +\fBJSON_REAL\fP +T} +_ +T{ +\fBJSON_TRUE\fP +T} +_ +T{ +\fBJSON_FALSE\fP +T} +_ +T{ +\fBJSON_NULL\fP +T} +_ +.TE +.sp +These correspond to JSON object, array, string, number, boolean and +null. A number is represented by either a value of the type +\fBJSON_INTEGER\fP or of the type \fBJSON_REAL\fP\&. A true boolean value +is represented by a value of the type \fBJSON_TRUE\fP and false by a +value of the type \fBJSON_FALSE\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_typeof(const json_t\fI\ *json\fP) +Return the type of the JSON value (a \fBjson_type\fP cast to +\fBint\fP). \fIjson\fP MUST NOT be \fINULL\fP\&. This function is actually +implemented as a macro for speed. +.UNINDENT +.INDENT 0.0 +.TP +.B json_is_object(const json_t\fI\ *json\fP) +.TP +.B json_is_array(const json_t\fI\ *json\fP) +.TP +.B json_is_string(const json_t\fI\ *json\fP) +.TP +.B json_is_integer(const json_t\fI\ *json\fP) +.TP +.B json_is_real(const json_t\fI\ *json\fP) +.TP +.B json_is_true(const json_t\fI\ *json\fP) +.TP +.B json_is_false(const json_t\fI\ *json\fP) +.TP +.B json_is_null(const json_t\fI\ *json\fP) +These functions (actually macros) return true (non\-zero) for values +of the given type, and false (zero) for values of other types and +for \fINULL\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B json_is_number(const json_t\fI\ *json\fP) +Returns true for values of types \fBJSON_INTEGER\fP and +\fBJSON_REAL\fP, and false for other types and for \fINULL\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B json_is_boolean(const json_t\fI\ *json\fP) +Returns true for types \fBJSON_TRUE\fP and \fBJSON_FALSE\fP, and false +for values of other types and for \fINULL\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B json_boolean_value(const json_t\fI\ *json\fP) +Alias of \fBjson_is_true()\fP, i.e. returns 1 for \fBJSON_TRUE\fP +and 0 otherwise. +.sp +New in version 2.7. + +.UNINDENT +.SS Reference Count +.sp +The reference count is used to track whether a value is still in use +or not. When a value is created, it\(aqs 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. +.sp +The following functions are used to manipulate the reference count. +.INDENT 0.0 +.TP +.B json_t *json_incref(json_t\fI\ *json\fP) +Increment the reference count of \fIjson\fP if it\(aqs not \fINULL\fP\&. +Returns \fIjson\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B void json_decref(json_t\fI\ *json\fP) +Decrement the reference count of \fIjson\fP\&. As soon as a call to +\fBjson_decref()\fP drops the reference count to zero, the value +is destroyed and it can no longer be used. +.UNINDENT +.sp +Functions creating new JSON values set the reference count to 1. These +functions are said to return a \fBnew reference\fP\&. Other functions +returning (existing) JSON values do not normally increase the +reference count. These functions are said to return a \fBborrowed +reference\fP\&. So, if the user will hold a reference to a value returned +as a borrowed reference, he must call \fBjson_incref()\fP\&. As soon as +the value is no longer needed, \fBjson_decref()\fP should be called +to release the reference. +.sp +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 \fBsteal\fP the reference, i.e. they +have the same result as if the user called \fBjson_decref()\fP on +the argument right after calling the function. These functions are +suffixed with \fB_new\fP or have \fB_new_\fP somewhere in their name. +.sp +For example, the following code creates a new JSON array and appends +an integer to it: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_t *array, *integer; + +array = json_array(); +integer = json_integer(42); + +json_array_append(array, integer); +json_decref(integer); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Note how the caller has to release the reference to the integer value +by calling \fBjson_decref()\fP\&. By using a reference stealing +function \fBjson_array_append_new()\fP instead of +\fBjson_array_append()\fP, the code becomes much simpler: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_t *array = json_array(); +json_array_append_new(array, json_integer(42)); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +In this case, the user doesn\(aqt have to explicitly release the +reference to the integer value, as \fBjson_array_append_new()\fP +steals the reference when appending the value to the array. +.sp +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. +.SS Circular References +.sp +A circular reference is created when an object or an array is, +directly or indirectly, inserted inside itself. The direct case is +simple: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_t *obj = json_object(); +json_object_set(obj, "foo", obj); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Jansson will refuse to do this, and \fBjson_object_set()\fP (and +all the other such functions for objects and arrays) will return with +an error status. The indirect case is the dangerous one: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_t *arr1 = json_array(), *arr2 = json_array(); +json_array_append(arr1, arr2); +json_array_append(arr2, arr1); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +In this example, the array \fBarr2\fP is contained in the array +\fBarr1\fP, and vice versa. Jansson cannot check for this kind of +indirect circular references without a performance hit, so it\(aqs up to +the user to avoid them. +.sp +If a circular reference is created, the memory consumed by the values +cannot be freed by \fBjson_decref()\fP\&. 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. +.SS True, False and Null +.sp +These three values are implemented as singletons, so the returned +pointers won\(aqt change between invocations of these functions. +.INDENT 0.0 +.TP +.B json_t *json_true(void) +Return value: New reference. +.sp +Returns the JSON true value. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_false(void) +Return value: New reference. +.sp +Returns the JSON false value. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_boolean(val) +Return value: New reference. +.sp +Returns JSON false if \fBval\fP is zero, and JSON true otherwise. +This is a macro, and equivalent to \fBval ? json_true() : +json_false()\fP\&. +.sp +New in version 2.4. + +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_null(void) +Return value: New reference. +.sp +Returns the JSON null value. +.UNINDENT +.SS String +.sp +Jansson uses UTF\-8 as the character encoding. All JSON strings must be +valid UTF\-8 (or ASCII, as it\(aqs a subset of UTF\-8). All Unicode +codepoints U+0000 through U+10FFFF are allowed, but you must use +length\-aware functions if you wish to embed NUL bytes in strings. +.INDENT 0.0 +.TP +.B json_t *json_string(const char\fI\ *value\fP) +Return value: New reference. +.sp +Returns a new JSON string, or \fINULL\fP on error. \fIvalue\fP must be a +valid null terminated UTF\-8 encoded Unicode string. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_stringn(const char\fI\ *value\fP, size_t\fI\ len\fP) +Return value: New reference. +.sp +Like \fBjson_string()\fP, but with explicit length, so \fIvalue\fP may +contain null characters or not be null terminated. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_string_nocheck(const char\fI\ *value\fP) +Return value: New reference. +.sp +Like \fBjson_string()\fP, but doesn\(aqt check that \fIvalue\fP 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). +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_stringn_nocheck(const char\fI\ *value\fP, size_t\fI\ len\fP) +Return value: New reference. +.sp +Like \fBjson_string_nocheck()\fP, but with explicit length, so +\fIvalue\fP may contain null characters or not be null terminated. +.UNINDENT +.INDENT 0.0 +.TP +.B const char *json_string_value(const json_t\fI\ *string\fP) +Returns the associated value of \fIstring\fP as a null terminated UTF\-8 +encoded string, or \fINULL\fP if \fIstring\fP is not a JSON string. +.sp +The retuned value is read\-only and must not be modified or freed by +the user. It is valid as long as \fIstring\fP exists, i.e. as long as +its reference count has not dropped to zero. +.UNINDENT +.INDENT 0.0 +.TP +.B size_t json_string_length(const json_t\fI\ *string\fP) +Returns the length of \fIstring\fP in its UTF\-8 presentation, or zero +if \fIstring\fP is not a JSON string. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_string_set(const json_t\fI\ *string\fP, const char\fI\ *value\fP) +Sets the associated value of \fIstring\fP to \fIvalue\fP\&. \fIvalue\fP must be a +valid UTF\-8 encoded Unicode string. Returns 0 on success and \-1 on +error. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_string_setn(json_t\fI\ *string\fP, const char\fI\ *value\fP, size_t\fI\ len\fP) +Like \fBjson_string_set()\fP, but with explicit length, so \fIvalue\fP +may contain null characters or not be null terminated. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_string_set_nocheck(const json_t\fI\ *string\fP, const char\fI\ *value\fP) +Like \fBjson_string_set()\fP, but doesn\(aqt check that \fIvalue\fP 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). +.UNINDENT +.INDENT 0.0 +.TP +.B int json_string_setn_nocheck(json_t\fI\ *string\fP, const char\fI\ *value\fP, size_t\fI\ len\fP) +Like \fBjson_string_set_nocheck()\fP, but with explicit length, +so \fIvalue\fP may contain null characters or not be null terminated. +.UNINDENT +.SS Number +.sp +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 \fIrfc\-conformance\fP\&. +.INDENT 0.0 +.TP +.B 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\(aqs just a typedef of \fBlong long\fP if your compiler +supports it, otherwise \fBlong\fP\&. +.sp +Usually, you can safely use plain \fBint\fP in place of +\fBjson_int_t\fP, and the implicit C integer conversion handles the +rest. Only when you know that you need the full 64\-bit range, you +should use \fBjson_int_t\fP explicitly. +.UNINDENT +.INDENT 0.0 +.TP +.B \fBJSON_INTEGER_IS_LONG_LONG\fP +This is a preprocessor variable that holds the value 1 if +\fBjson_int_t\fP is \fBlong long\fP, and 0 if it\(aqs \fBlong\fP\&. It +can be used as follows: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +#if JSON_INTEGER_IS_LONG_LONG +/* Code specific for long long */ +#else +/* Code specific for long */ +#endif +.ft R +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBJSON_INTEGER_FORMAT\fP +This is a macro that expands to a \fBprintf()\fP conversion +specifier that corresponds to \fBjson_int_t\fP, without the +leading \fB%\fP sign, i.e. either \fB"lld"\fP or \fB"ld"\fP\&. This macro +is required because the actual type of \fBjson_int_t\fP can be +either \fBlong\fP or \fBlong long\fP, and \fBprintf()\fP reuiqres +different length modifiers for the two. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_int_t x = 123123123; +printf("x is %" JSON_INTEGER_FORMAT "\en", x); +.ft R +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_integer(json_int_t\fI\ value\fP) +Return value: New reference. +.sp +Returns a new JSON integer, or \fINULL\fP on error. +.UNINDENT +.INDENT 0.0 +.TP +.B json_int_t json_integer_value(const json_t\fI\ *integer\fP) +Returns the associated value of \fIinteger\fP, or 0 if \fIjson\fP is not a +JSON integer. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_integer_set(const json_t\fI\ *integer\fP, json_int_t\fI\ value\fP) +Sets the associated value of \fIinteger\fP to \fIvalue\fP\&. Returns 0 on +success and \-1 if \fIinteger\fP is not a JSON integer. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_real(double\fI\ value\fP) +Return value: New reference. +.sp +Returns a new JSON real, or \fINULL\fP on error. +.UNINDENT +.INDENT 0.0 +.TP +.B double json_real_value(const json_t\fI\ *real\fP) +Returns the associated value of \fIreal\fP, or 0.0 if \fIreal\fP is not a +JSON real. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_real_set(const json_t\fI\ *real\fP, double\fI\ value\fP) +Sets the associated value of \fIreal\fP to \fIvalue\fP\&. Returns 0 on +success and \-1 if \fIreal\fP is not a JSON real. +.UNINDENT +.sp +In addition to the functions above, there\(aqs a common query function +for integers and reals: +.INDENT 0.0 +.TP +.B double json_number_value(const json_t\fI\ *json\fP) +Returns the associated value of the JSON integer or JSON real +\fIjson\fP, cast to double regardless of the actual type. If \fIjson\fP is +neither JSON real nor JSON integer, 0.0 is returned. +.UNINDENT +.SS Array +.sp +A JSON array is an ordered collection of other JSON values. +.INDENT 0.0 +.TP +.B json_t *json_array(void) +Return value: New reference. +.sp +Returns a new JSON array, or \fINULL\fP on error. Initially, the array +is empty. +.UNINDENT +.INDENT 0.0 +.TP +.B size_t json_array_size(const json_t\fI\ *array\fP) +Returns the number of elements in \fIarray\fP, or 0 if \fIarray\fP is NULL +or not a JSON array. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_array_get(const json_t\fI\ *array\fP, size_t\fI\ index\fP) +Return value: Borrowed reference. +.sp +Returns the element in \fIarray\fP at position \fIindex\fP\&. The valid range +for \fIindex\fP is from 0 to the return value of +\fBjson_array_size()\fP minus 1. If \fIarray\fP is not a JSON array, +if \fIarray\fP is \fINULL\fP, or if \fIindex\fP is out of range, \fINULL\fP is +returned. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_set(json_t\fI\ *array\fP, size_t\fI\ index\fP, json_t\fI\ *value\fP) +Replaces the element in \fIarray\fP at position \fIindex\fP with \fIvalue\fP\&. +The valid range for \fIindex\fP is from 0 to the return value of +\fBjson_array_size()\fP minus 1. Returns 0 on success and \-1 on +error. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_set_new(json_t\fI\ *array\fP, size_t\fI\ index\fP, json_t\fI\ *value\fP) +Like \fBjson_array_set()\fP but steals the reference to \fIvalue\fP\&. +This is useful when \fIvalue\fP is newly created and not used after +the call. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_append(json_t\fI\ *array\fP, json_t\fI\ *value\fP) +Appends \fIvalue\fP to the end of \fIarray\fP, growing the size of \fIarray\fP +by 1. Returns 0 on success and \-1 on error. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_append_new(json_t\fI\ *array\fP, json_t\fI\ *value\fP) +Like \fBjson_array_append()\fP but steals the reference to +\fIvalue\fP\&. This is useful when \fIvalue\fP is newly created and not used +after the call. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_insert(json_t\fI\ *array\fP, size_t\fI\ index\fP, json_t\fI\ *value\fP) +Inserts \fIvalue\fP to \fIarray\fP at position \fIindex\fP, shifting the +elements at \fIindex\fP and after it one position towards the end of +the array. Returns 0 on success and \-1 on error. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_insert_new(json_t\fI\ *array\fP, size_t\fI\ index\fP, json_t\fI\ *value\fP) +Like \fBjson_array_insert()\fP but steals the reference to +\fIvalue\fP\&. This is useful when \fIvalue\fP is newly created and not used +after the call. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_remove(json_t\fI\ *array\fP, size_t\fI\ index\fP) +Removes the element in \fIarray\fP at position \fIindex\fP, shifting the +elements after \fIindex\fP 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. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_clear(json_t\fI\ *array\fP) +Removes all elements from \fIarray\fP\&. Returns 0 on sucess and \-1 on +error. The reference count of all removed values are decremented. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_array_extend(json_t\fI\ *array\fP, json_t\fI\ *other_array\fP) +Appends all elements in \fIother_array\fP to the end of \fIarray\fP\&. +Returns 0 on success and \-1 on error. +.UNINDENT +.sp +The following macro can be used to iterate through all elements +in an array. +.INDENT 0.0 +.TP +.B json_array_foreach(array, index, value) +Iterate over every element of \fBarray\fP, running the block +of code that follows each time with the proper values set to +variables \fBindex\fP and \fBvalue\fP, of types \fBsize_t\fP and +\fBjson_t *\fP respectively. Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* 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 */ +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +The items are returned in increasing index order. +.sp +This macro expands to an ordinary \fBfor\fP 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. +.sp +New in version 2.5. + +.UNINDENT +.SS Object +.sp +A JSON object is a dictionary of key\-value pairs, where the key is a +Unicode string and the value is any JSON value. +.sp +Even though NUL bytes are allowed in string values, they are not +allowed in object keys. +.INDENT 0.0 +.TP +.B json_t *json_object(void) +Return value: New reference. +.sp +Returns a new JSON object, or \fINULL\fP on error. Initially, the +object is empty. +.UNINDENT +.INDENT 0.0 +.TP +.B size_t json_object_size(const json_t\fI\ *object\fP) +Returns the number of elements in \fIobject\fP, or 0 if \fIobject\fP is not +a JSON object. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_object_get(const json_t\fI\ *object\fP, const char\fI\ *key\fP) +Return value: Borrowed reference. +.sp +Get a value corresponding to \fIkey\fP from \fIobject\fP\&. Returns \fINULL\fP if +\fIkey\fP is not found and on error. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_set(json_t\fI\ *object\fP, const char\fI\ *key\fP, json_t\fI\ *value\fP) +Set the value of \fIkey\fP to \fIvalue\fP in \fIobject\fP\&. \fIkey\fP must be a +valid null terminated UTF\-8 encoded Unicode string. If there +already is a value for \fIkey\fP, it is replaced by the new value. +Returns 0 on success and \-1 on error. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_set_nocheck(json_t\fI\ *object\fP, const char\fI\ *key\fP, json_t\fI\ *value\fP) +Like \fBjson_object_set()\fP, but doesn\(aqt check that \fIkey\fP 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). +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_set_new(json_t\fI\ *object\fP, const char\fI\ *key\fP, json_t\fI\ *value\fP) +Like \fBjson_object_set()\fP but steals the reference to +\fIvalue\fP\&. This is useful when \fIvalue\fP is newly created and not used +after the call. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_set_new_nocheck(json_t\fI\ *object\fP, const char\fI\ *key\fP, json_t\fI\ *value\fP) +Like \fBjson_object_set_new()\fP, but doesn\(aqt check that \fIkey\fP 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). +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_del(json_t\fI\ *object\fP, const char\fI\ *key\fP) +Delete \fIkey\fP from \fIobject\fP if it exists. Returns 0 on success, or +\-1 if \fIkey\fP was not found. The reference count of the removed value +is decremented. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_clear(json_t\fI\ *object\fP) +Remove all elements from \fIobject\fP\&. Returns 0 on success and \-1 if +\fIobject\fP is not a JSON object. The reference count of all removed +values are decremented. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_update(json_t\fI\ *object\fP, json_t\fI\ *other\fP) +Update \fIobject\fP with the key\-value pairs from \fIother\fP, overwriting +existing keys. Returns 0 on success or \-1 on error. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_update_existing(json_t\fI\ *object\fP, json_t\fI\ *other\fP) +Like \fBjson_object_update()\fP, but only the values of existing +keys are updated. No new keys are created. Returns 0 on success or +\-1 on error. +.sp +New in version 2.3. + +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_update_missing(json_t\fI\ *object\fP, json_t\fI\ *other\fP) +Like \fBjson_object_update()\fP, but only new keys are created. +The value of any existing key is not changed. Returns 0 on success +or \-1 on error. +.sp +New in version 2.3. + +.UNINDENT +.sp +The following macro can be used to iterate through all key\-value pairs +in an object. +.INDENT 0.0 +.TP +.B json_object_foreach(object, key, value) +Iterate over every key\-value pair of \fBobject\fP, running the block +of code that follows each time with the proper values set to +variables \fBkey\fP and \fBvalue\fP, of types \fBconst char *\fP and +\fBjson_t *\fP respectively. Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* 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 */ +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +The items are not returned in any particular order. +.sp +This macro expands to an ordinary \fBfor\fP 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. +.sp +New in version 2.3. + +.UNINDENT +.sp +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. +.INDENT 0.0 +.TP +.B void *json_object_iter(json_t\fI\ *object\fP) +Returns an opaque iterator which can be used to iterate over all +key\-value pairs in \fIobject\fP, or \fINULL\fP if \fIobject\fP is empty. +.UNINDENT +.INDENT 0.0 +.TP +.B void *json_object_iter_at(json_t\fI\ *object\fP, const char\fI\ *key\fP) +Like \fBjson_object_iter()\fP, but returns an iterator to the +key\-value pair in \fIobject\fP whose key is equal to \fIkey\fP, or NULL if +\fIkey\fP is not found in \fIobject\fP\&. Iterating forward to the end of +\fIobject\fP only yields all key\-value pairs of the object if \fIkey\fP +happens to be the first key in the underlying hash table. +.UNINDENT +.INDENT 0.0 +.TP +.B void *json_object_iter_next(json_t\fI\ *object\fP, void\fI\ *iter\fP) +Returns an iterator pointing to the next key\-value pair in \fIobject\fP +after \fIiter\fP, or \fINULL\fP if the whole object has been iterated +through. +.UNINDENT +.INDENT 0.0 +.TP +.B const char *json_object_iter_key(void\fI\ *iter\fP) +Extract the associated key from \fIiter\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_object_iter_value(void\fI\ *iter\fP) +Return value: Borrowed reference. +.sp +Extract the associated value from \fIiter\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_iter_set(json_t\fI\ *object\fP, void\fI\ *iter\fP, json_t\fI\ *value\fP) +Set the value of the key\-value pair in \fIobject\fP, that is pointed to +by \fIiter\fP, to \fIvalue\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_object_iter_set_new(json_t\fI\ *object\fP, void\fI\ *iter\fP, json_t\fI\ *value\fP) +Like \fBjson_object_iter_set()\fP, but steals the reference to +\fIvalue\fP\&. This is useful when \fIvalue\fP is newly created and not used +after the call. +.UNINDENT +.INDENT 0.0 +.TP +.B void *json_object_key_to_iter(const char\fI\ *key\fP) +Like \fBjson_object_iter_at()\fP, but much faster. Only works for +values returned by \fBjson_object_iter_key()\fP\&. Using other keys +will lead to segfaults. This function is used internally to +implement \fBjson_object_foreach()\fP\&. +.sp +New in version 2.3. + +.UNINDENT +.sp +The iteration protocol can be used for example as follows: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* 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); +} +.ft R +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void json_object_seed(size_t\fI\ seed\fP) +Seed the hash function used in Jansson\(aqs hashtable implementation. +The seed is used to randomize the hash function so that an +attacker cannot control its output. +.sp +If \fIseed\fP is 0, Jansson generates the seed itselfy by reading +random data from the operating system\(aqs entropy sources. If no +entropy sources are available, falls back to using a combination +of the current timestamp (with microsecond precision if possible) +and the process ID. +.sp +If called at all, this function must be called before any calls to +\fBjson_object()\fP, either explicit or implicit. If this +function is not called by the user, the first call to +\fBjson_object()\fP (either explicit or implicit) seeds the hash +function. See \fIportability\-thread\-safety\fP for notes on thread +safety. +.sp +If repeatable results are required, for e.g. unit tests, the hash +function can be "unrandomized" by calling \fBjson_object_seed()\fP +with a constant value on program startup, e.g. +\fBjson_object_seed(1)\fP\&. +.sp +New in version 2.6. + +.UNINDENT +.SS Error reporting +.sp +Jansson uses a single struct type to pass error information to the +user. See sections \fIapiref\-decoding\fP, \fIapiref\-pack\fP and +\fIapiref\-unpack\fP for functions that pass error information using +this struct. +.INDENT 0.0 +.TP +.B json_error_t +.INDENT 7.0 +.TP +.B char text[] +The error message (in UTF\-8), or an empty string if a message is +not available. +.UNINDENT +.INDENT 7.0 +.TP +.B char source[] +Source of the error. This can be (a part of) the file name or a +special identifier in angle brackers (e.g. \fB\fP). +.UNINDENT +.INDENT 7.0 +.TP +.B int line +The line number on which the error occurred. +.UNINDENT +.INDENT 7.0 +.TP +.B int column +The column on which the error occurred. Note that this is the +\fIcharacter column\fP, not the byte column, i.e. a multibyte UTF\-8 +character counts as one column. +.UNINDENT +.INDENT 7.0 +.TP +.B size_t position +The position in bytes from the start of the input. This is +useful for debugging Unicode encoding problems. +.UNINDENT +.UNINDENT +.sp +The normal use of \fBjson_error_t\fP is to allocate it on the stack, +and pass a pointer to a function. Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +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 */ + } + ... +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Also note that if the call succeeded (\fBjson != NULL\fP in the above +example), the contents of \fBerror\fP are generally left unspecified. +The decoding functions write to the \fBposition\fP member also on +success. See \fIapiref\-decoding\fP for more info. +.sp +All functions also accept \fINULL\fP as the \fBjson_error_t\fP pointer, +in which case no error information is returned to the caller. +.SS Encoding +.sp +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 \fIroot\fP values of a JSON text. +To encode any JSON value, use the \fBJSON_ENCODE_ANY\fP flag (see +below). +.sp +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 \fBJSON_INDENT\fP and \fBJSON_COMPACT\fP flags +described below. A newline is never appended to the end of the encoded +JSON data. +.sp +Each function takes a \fIflags\fP 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 \fIflags\fP\&. +.INDENT 0.0 +.TP +.B \fBJSON_INDENT(n)\fP +Pretty\-print the result, using newlines between array and object +items, and indenting with \fIn\fP spaces. The valid range for \fIn\fP is +between 0 and 31 (inclusive), other values result in an undefined +output. If \fBJSON_INDENT\fP is not used or \fIn\fP is 0, no newlines are +inserted between array and object items. +.sp +The \fBJSON_MAX_INDENT\fP constant defines the maximum indentation +that can be used, and its value is 31. +.sp +Changed in version 2.7: Added \fBJSON_MAX_INDENT\fP\&. + +.TP +.B \fBJSON_COMPACT\fP +This flag enables a compact representation, i.e. sets the separator +between array and object items to \fB","\fP and between object keys +and values to \fB":"\fP\&. Without this flag, the corresponding +separators are \fB", "\fP and \fB": "\fP for more readable output. +.TP +.B \fBJSON_ENSURE_ASCII\fP +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. +.TP +.B \fBJSON_SORT_KEYS\fP +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. +.TP +.B \fBJSON_PRESERVE_ORDER\fP +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. +.TP +.B \fBJSON_ENCODE_ANY\fP +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 +\fIroot\fP value to the encoding functions. +.sp +\fBNote:\fP Encoding any value may be useful in some scenarios, but +it\(aqs generally discouraged as it violates strict compatiblity with +\fI\%RFC 4627\fP\&. If you use this flag, don\(aqt expect interoperatibility +with other JSON systems. +.sp +New in version 2.1. + +.TP +.B \fBJSON_ESCAPE_SLASH\fP +Escape the \fB/\fP characters in strings with \fB\e/\fP\&. +.sp +New in version 2.4. + +.TP +.B \fBJSON_REAL_PRECISION(n)\fP +Output all real numbers with at most \fIn\fP digits of precision. The +valid range for \fIn\fP is between 0 and 31 (inclusive), and other +values result in an undefined behavior. +.sp +By default, the precision is 17, to correctly and losslessly encode +all IEEE 754 double precision floating point numbers. +.sp +New in version 2.7. + +.UNINDENT +.sp +The following functions perform the actual JSON encoding. The result +is in UTF\-8. +.INDENT 0.0 +.TP +.B char *json_dumps(const json_t\fI\ *root\fP, size_t\fI\ flags\fP) +Returns the JSON representation of \fIroot\fP as a string, or \fINULL\fP on +error. \fIflags\fP is described above. The return value must be freed +by the caller using \fBfree()\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_dumpf(const json_t\fI\ *root\fP, FILE\fI\ *output\fP, size_t\fI\ flags\fP) +Write the JSON representation of \fIroot\fP to the stream \fIoutput\fP\&. +\fIflags\fP is described above. Returns 0 on success and \-1 on error. +If an error occurs, something may have already been written to +\fIoutput\fP\&. In this case, the output is undefined and most likely not +valid JSON. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_dump_file(const json_t\fI\ *json\fP, const char\fI\ *path\fP, size_t\fI\ flags\fP) +Write the JSON representation of \fIroot\fP to the file \fIpath\fP\&. If +\fIpath\fP already exists, it is overwritten. \fIflags\fP is described +above. Returns 0 on success and \-1 on error. +.UNINDENT +.INDENT 0.0 +.TP +.B json_dump_callback_t +A typedef for a function that\(aqs called by +\fBjson_dump_callback()\fP: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +\fIbuffer\fP points to a buffer containing a chunk of output, \fIsize\fP is +the length of the buffer, and \fIdata\fP is the corresponding +\fBjson_dump_callback()\fP argument passed through. +.sp +On error, the function should return \-1 to stop the encoding +process. On success, it should return 0. +.sp +New in version 2.2. + +.UNINDENT +.INDENT 0.0 +.TP +.B int json_dump_callback(const json_t\fI\ *json\fP, json_dump_callback_t\fI\ callback\fP, void\fI\ *data\fP, size_t\fI\ flags\fP) +Call \fIcallback\fP repeatedly, passing a chunk of the JSON +representation of \fIroot\fP each time. \fIflags\fP is described above. +Returns 0 on success and \-1 on error. +.sp +New in version 2.2. + +.UNINDENT +.SS Decoding +.sp +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 \fBJSON_DECODE_ANY\fP flag (see below). +.sp +See \fIrfc\-conformance\fP for a discussion on Jansson\(aqs conformance +to the JSON specification. It explains many design decisions that +affect especially the behavior of the decoder. +.sp +Each function takes a \fIflags\fP 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 \fIflags\fP\&. +.INDENT 0.0 +.TP +.B \fBJSON_REJECT_DUPLICATES\fP +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. +.sp +New in version 2.1. + +.TP +.B \fBJSON_DECODE_ANY\fP +By default, the decoder expects an array or object as the input. +With this flag enabled, the decoder accepts any valid JSON value. +.sp +\fBNote:\fP Decoding any value may be useful in some scenarios, but +it\(aqs generally discouraged as it violates strict compatiblity with +\fI\%RFC 4627\fP\&. If you use this flag, don\(aqt expect interoperatibility +with other JSON systems. +.sp +New in version 2.3. + +.TP +.B \fBJSON_DISABLE_EOF_CHECK\fP +By default, the decoder expects that its whole input constitutes a +valid JSON text, and issues an error if there\(aqs 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. +.sp +Normally, reading will stop when the last \fB]\fP or \fB}\fP in the +JSON input is encountered. If both \fBJSON_DISABLE_EOF_CHECK\fP and +\fBJSON_DECODE_ANY\fP flags are used, the decoder may read one extra +UTF\-8 code unit (up to 4 bytes of input). For example, decoding +\fB4true\fP correctly decodes the integer 4, but also reads the +\fBt\fP\&. For this reason, if reading multiple consecutive values that +are not arrays or objects, they should be separated by at least one +whitespace character. +.sp +New in version 2.1. + +.TP +.B \fBJSON_DECODE_INT_AS_REAL\fP +JSON defines only one number type. Jansson distinguishes between +ints and reals. For more information see \fIreal\-vs\-integer\fP\&. +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. +.sp +New in version 2.5. + +.TP +.B \fBJSON_ALLOW_NUL\fP +Allow \fB\eu0000\fP escape inside string values. This is a safety +measure; If you know your input can contain NUL bytes, use this +flag. If you don\(aqt use this flag, you don\(aqt have to worry about NUL +bytes inside strings unless you explicitly create themselves by +using e.g. \fBjson_stringn()\fP or \fBs#\fP format specifier for +\fBjson_pack()\fP\&. +.sp +Object keys cannot have embedded NUL bytes even if this flag is +used. +.sp +New in version 2.6. + +.UNINDENT +.sp +Each function also takes an optional \fBjson_error_t\fP parameter +that is filled with error information if decoding fails. It\(aqs also +updated on success; the number of bytes of input read is written to +its \fBposition\fP field. This is especially useful when using +\fBJSON_DISABLE_EOF_CHECK\fP to read multiple consecutive JSON texts. +.sp +New in version 2.3: Number of bytes of input read is written to the \fBposition\fP field +of the \fBjson_error_t\fP structure. + +.sp +If no error or position information is needed, you can pass \fINULL\fP\&. +.sp +The following functions perform the actual JSON decoding. +.INDENT 0.0 +.TP +.B json_t *json_loads(const char\fI\ *input\fP, size_t\fI\ flags\fP, json_error_t\fI\ *error\fP) +Return value: New reference. +.sp +Decodes the JSON string \fIinput\fP and returns the array or object it +contains, or \fINULL\fP on error, in which case \fIerror\fP is filled with +information about the error. \fIflags\fP is described above. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_loadb(const char\fI\ *buffer\fP, size_t\fI\ buflen\fP, size_t\fI\ flags\fP, json_error_t\fI\ *error\fP) +Return value: New reference. +.sp +Decodes the JSON string \fIbuffer\fP, whose length is \fIbuflen\fP, and +returns the array or object it contains, or \fINULL\fP on error, in +which case \fIerror\fP is filled with information about the error. This +is similar to \fBjson_loads()\fP except that the string doesn\(aqt +need to be null\-terminated. \fIflags\fP is described above. +.sp +New in version 2.1. + +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_loadf(FILE\fI\ *input\fP, size_t\fI\ flags\fP, json_error_t\fI\ *error\fP) +Return value: New reference. +.sp +Decodes the JSON text in stream \fIinput\fP and returns the array or +object it contains, or \fINULL\fP on error, in which case \fIerror\fP is +filled with information about the error. \fIflags\fP is described +above. +.sp +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 \fBJSON_DISABLE_EOF_CHECK\fP +flag was used. In this case, the file position will be at the first +character after the last \fB]\fP or \fB}\fP in the JSON input. This +allows calling \fBjson_loadf()\fP on the same \fBFILE\fP object +multiple times, if the input consists of consecutive JSON texts, +possibly separated by whitespace. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_load_file(const char\fI\ *path\fP, size_t\fI\ flags\fP, json_error_t\fI\ *error\fP) +Return value: New reference. +.sp +Decodes the JSON text in file \fIpath\fP and returns the array or +object it contains, or \fINULL\fP on error, in which case \fIerror\fP is +filled with information about the error. \fIflags\fP is described +above. +.UNINDENT +.INDENT 0.0 +.TP +.B json_load_callback_t +A typedef for a function that\(aqs called by +\fBjson_load_callback()\fP to read a chunk of input data: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +typedef size_t (*json_load_callback_t)(void *buffer, size_t buflen, void *data); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +\fIbuffer\fP points to a buffer of \fIbuflen\fP bytes, and \fIdata\fP is the +corresponding \fBjson_load_callback()\fP argument passed through. +.sp +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 +\fB(size_t)\-1\fP to abort the decoding process. +.sp +New in version 2.4. + +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_load_callback(json_load_callback_t\fI\ callback\fP, void\fI\ *data\fP, size_t\fI\ flags\fP, json_error_t\fI\ *error\fP) +Return value: New reference. +.sp +Decodes the JSON text produced by repeated calls to \fIcallback\fP, and +returns the array or object it contains, or \fINULL\fP on error, in +which case \fIerror\fP is filled with information about the error. +\fIdata\fP is passed through to \fIcallback\fP on each call. \fIflags\fP is +described above. +.sp +New in version 2.4. + +.UNINDENT +.SS Building Values +.sp +This section describes functions that help to create, or \fIpack\fP, +complex JSON values, especially nested objects and arrays. Value +building is based on a \fIformat string\fP that is used to tell the +functions about the expected arguments. +.sp +For example, the format string \fB"i"\fP specifies a single integer +value, while the format string \fB"[ssb]"\fP or the equivalent \fB"[s, s, +b]"\fP specifies an array value with two strings and a boolean as its +items: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* Create the JSON integer 42 */ +json_pack("i", 42); + +/* Create the JSON array ["foo", "bar", true] */ +json_pack("[ssb]", "foo", "bar", 1); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Here\(aqs 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. +.INDENT 0.0 +.TP +.B \fBs\fP (string) [const char *] +Convert a NULL terminated UTF\-8 string to a JSON string. +.TP +.B \fBs#\fP (string) [const char *, int] +Convert a UTF\-8 buffer of a given length to a JSON string. +.sp +New in version 2.5. + +.TP +.B \fBs%\fP (string) [const char *, size_t] +Like \fBs#\fP but the length argument is of type \fBsize_t\fP\&. +.sp +New in version 2.6. + +.TP +.B \fB+\fP [const char *] +Like \fBs\fP, but concatenate to the previous string. Only valid +after \fBs\fP, \fBs#\fP, \fB+\fP or \fB+#\fP\&. +.sp +New in version 2.5. + +.TP +.B \fB+#\fP [const char *, int] +Like \fBs#\fP, but concatenate to the previous string. Only valid +after \fBs\fP, \fBs#\fP, \fB+\fP or \fB+#\fP\&. +.sp +New in version 2.5. + +.TP +.B \fB+%\fP (string) [const char *, size_t] +Like \fB+#\fP but the length argument is of type \fBsize_t\fP\&. +.sp +New in version 2.6. + +.TP +.B \fBn\fP (null) +Output a JSON null value. No argument is consumed. +.TP +.B \fBb\fP (boolean) [int] +Convert a C \fBint\fP to JSON boolean value. Zero is converted +to \fBfalse\fP and non\-zero to \fBtrue\fP\&. +.TP +.B \fBi\fP (integer) [int] +Convert a C \fBint\fP to JSON integer. +.TP +.B \fBI\fP (integer) [json_int_t] +Convert a C \fBjson_int_t\fP to JSON integer. +.TP +.B \fBf\fP (real) [double] +Convert a C \fBdouble\fP to JSON real. +.TP +.B \fBo\fP (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 \fBo\fP is +stolen by the container. +.TP +.B \fBO\fP (any value) [json_t *] +Like \fBo\fP, but the argument\(aqs 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 \fBO\fP to +yourself. +.TP +.B \fB[fmt]\fP (array) +Build an array with contents from the inner format string. \fBfmt\fP +may contain objects and arrays, i.e. recursive value building is +supported. +.TP +.B \fB{fmt}\fP (object) +Build an object with contents from the inner format string +\fBfmt\fP\&. The first, third, etc. format specifier represent a key, +and must be a string (see \fBs\fP, \fBs#\fP, \fB+\fP and \fB+#\fP 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. +.UNINDENT +.sp +Whitespace, \fB:\fP and \fB,\fP are ignored. +.sp +The following functions compose the value building API: +.INDENT 0.0 +.TP +.B json_t *json_pack(const char\fI\ *fmt\fP, \&...) +Return value: New reference. +.sp +Build a new JSON value according to the format string \fIfmt\fP\&. For +each format specifier (except for \fB{}[]n\fP), one or more arguments +are consumed and used to build the corresponding value. Returns +\fINULL\fP on error. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_pack_ex(json_error_t\fI\ *error\fP, size_t\fI\ flags\fP, const char\fI\ *fmt\fP, \&...) +.TP +.B json_t *json_vpack_ex(json_error_t\fI\ *error\fP, size_t\fI\ flags\fP, const char\fI\ *fmt\fP, va_list\fI\ ap\fP) +Return value: New reference. +.sp +Like \fBjson_pack()\fP, but an in the case of an error, an error +message is written to \fIerror\fP, if it\(aqs not \fINULL\fP\&. The \fIflags\fP +parameter is currently unused and should be set to 0. +.sp +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. +.UNINDENT +.sp +More examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* Build an empty JSON object */ +json_pack("{}"); + +/* Build the JSON object {"foo": 42, "bar": 7} */ +json_pack("{sisi}", "foo", 42, "bar", 7); + +/* Like above, \(aq:\(aq, \(aq,\(aq 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] = {\(aqt\(aq, \(aqe\(aq, \(aqs\(aq, \(aqt\(aq}; +json_pack("s#", buffer, 4); + +/* Concatentate strings together to build the JSON string "foobarbaz" */ +json_pack("s++", "foo", "bar", "baz"); +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Parsing and Validating Values +.sp +This section describes functions that help to validate complex values +and extract, or \fIunpack\fP, data from them. Like \fIbuilding values\fP, this is also based on format strings. +.sp +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 \fB!\fP or by +using the flag \fBJSON_STRICT\fP\&. See below for details. +.sp +Here\(aqs 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. +.INDENT 0.0 +.TP +.B \fBs\fP (string) [const char *] +Convert a JSON string to a pointer to a NULL terminated UTF\-8 +string. The resulting string is extracted by using +\fBjson_string_value()\fP internally, so it exists as long as +there are still references to the corresponding JSON string. +.TP +.B \fBs%\fP (string) [const char *, size_t *] +Convert a JSON string to a pointer to a NULL terminated UTF\-8 +string and its length. +.sp +New in version 2.6. + +.TP +.B \fBn\fP (null) +Expect a JSON null value. Nothing is extracted. +.TP +.B \fBb\fP (boolean) [int] +Convert a JSON boolean value to a C \fBint\fP, so that \fBtrue\fP +is converted to 1 and \fBfalse\fP to 0. +.TP +.B \fBi\fP (integer) [int] +Convert a JSON integer to C \fBint\fP\&. +.TP +.B \fBI\fP (integer) [json_int_t] +Convert a JSON integer to C \fBjson_int_t\fP\&. +.TP +.B \fBf\fP (real) [double] +Convert a JSON real to C \fBdouble\fP\&. +.TP +.B \fBF\fP (integer or real) [double] +Convert a JSON number (integer or real) to C \fBdouble\fP\&. +.TP +.B \fBo\fP (any value) [json_t *] +Store a JSON value with no conversion to a \fBjson_t\fP pointer. +.TP +.B \fBO\fP (any value) [json_t *] +Like \fBO\fP, but the JSON value\(aqs reference count is incremented. +.TP +.B \fB[fmt]\fP (array) +Convert each item in the JSON array according to the inner format +string. \fBfmt\fP may contain objects and arrays, i.e. recursive +value extraction is supporetd. +.TP +.B \fB{fmt}\fP (object) +Convert each item in the JSON object according to the inner format +string \fBfmt\fP\&. The first, third, etc. format specifier represent +a key, and must be \fBs\fP\&. 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. \fBNote\fP that every other +argument is read from and every other is written to. +.sp +\fBfmt\fP may contain objects and arrays as values, i.e. recursive +value extraction is supporetd. +.sp +New in version 2.3: Any \fBs\fP representing a key may be suffixed with a \fB?\fP to +make the key optional. If the key is not found, nothing is +extracted. See below for an example. + +.TP +.B \fB!\fP +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 \fBJSON_STRICT\fP unpacking flag. +.TP +.B \fB*\fP +This special format specifier is the opposite of \fB!\fP\&. If the +\fBJSON_STRICT\fP flag is used, \fB*\fP 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. +.UNINDENT +.sp +Whitespace, \fB:\fP and \fB,\fP are ignored. +.sp +The following functions compose the parsing and validation API: +.INDENT 0.0 +.TP +.B int json_unpack(json_t\fI\ *root\fP, const char\fI\ *fmt\fP, \&...) +Validate and unpack the JSON value \fIroot\fP according to the format +string \fIfmt\fP\&. Returns 0 on success and \-1 on failure. +.UNINDENT +.INDENT 0.0 +.TP +.B int json_unpack_ex(json_t\fI\ *root\fP, json_error_t\fI\ *error\fP, size_t\fI\ flags\fP, const char\fI\ *fmt\fP, \&...) +.TP +.B int json_vunpack_ex(json_t\fI\ *root\fP, json_error_t\fI\ *error\fP, size_t\fI\ flags\fP, const char\fI\ *fmt\fP, va_list\fI\ ap\fP) +Validate and unpack the JSON value \fIroot\fP according to the format +string \fIfmt\fP\&. If an error occurs and \fIerror\fP is not \fINULL\fP, write +error information to \fIerror\fP\&. \fIflags\fP can be used to control the +behaviour of the unpacker, see below for the flags. Returns 0 on +success and \-1 on failure. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The first argument of all unpack functions is \fBjson_t *root\fP +instead of \fBconst json_t *root\fP, because the use of \fBO\fP format +specifier causes the reference count of \fBroot\fP, or some value +reachable from \fBroot\fP, to be increased. Furthermore, the \fBo\fP +format specifier may be used to extract a value as\-is, which allows +modifying the structure or contents of a value reachable from +\fBroot\fP\&. +.sp +If the \fBO\fP and \fBo\fP format specifiers are not used, it\(aqs +perfectly safe to cast a \fBconst json_t *\fP variable to plain +\fBjson_t *\fP when used with these functions. +.UNINDENT +.UNINDENT +.sp +The following unpacking flags are available: +.INDENT 0.0 +.TP +.B \fBJSON_STRICT\fP +Enable the extra validation step checking that all object and +array items are unpacked. This is equivalent to appending the +format specifier \fB!\fP to the end of every array and object in the +format string. +.TP +.B \fBJSON_VALIDATE_ONLY\fP +Don\(aqt 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. +.UNINDENT +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +/* 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\(aqt exist */ +.ft R +.fi +.UNINDENT +.UNINDENT +.SS Equality +.sp +Testing for equality of two JSON values cannot, in general, be +achieved using the \fB==\fP operator. Equality in the terms of the +\fB==\fP operator states that the two \fBjson_t\fP 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": +.INDENT 0.0 +.IP \(bu 2 +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. +.IP \(bu 2 +Two strings are equal if their contained UTF\-8 strings are equal, +byte by byte. Unicode comparison algorithms are not implemented. +.IP \(bu 2 +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. +.IP \(bu 2 +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. +.IP \(bu 2 +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 \fB==\fP\&.) +.UNINDENT +.sp +The following function can be used to test whether two JSON values are +equal. +.INDENT 0.0 +.TP +.B int json_equal(json_t\fI\ *value1\fP, json_t\fI\ *value2\fP) +Returns 1 if \fIvalue1\fP and \fIvalue2\fP are equal, as defined above. +Returns 0 if they are inequal or one or both of the pointers are +\fINULL\fP\&. +.UNINDENT +.SS Copying +.sp +Because of reference counting, passing JSON values around doesn\(aqt +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. +.sp +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. +.INDENT 0.0 +.TP +.B json_t *json_copy(json_t\fI\ *value\fP) +Return value: New reference. +.sp +Returns a shallow copy of \fIvalue\fP, or \fINULL\fP on error. +.UNINDENT +.INDENT 0.0 +.TP +.B json_t *json_deep_copy(const json_t\fI\ *value\fP) +Return value: New reference. +.sp +Returns a deep copy of \fIvalue\fP, or \fINULL\fP on error. +.UNINDENT +.SS Custom Memory Allocation +.sp +By default, Jansson uses \fBmalloc()\fP and \fBfree()\fP for +memory allocation. These functions can be overridden if custom +behavior is needed. +.INDENT 0.0 +.TP +.B json_malloc_t +A typedef for a function pointer with \fBmalloc()\fP\(aqs +signature: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +typedef void *(*json_malloc_t)(size_t); +.ft R +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B json_free_t +A typedef for a function pointer with \fBfree()\fP\(aqs +signature: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft CW +typedef void (*json_free_t)(void *); +.ft R +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B void json_set_alloc_funcs(json_malloc_t\fI\ malloc_fn\fP, json_free_t\fI\ free_fn\fP) +Use \fImalloc_fn\fP instead of \fBmalloc()\fP and \fIfree_fn\fP instead +of \fBfree()\fP\&. This function has to be called before any other +Jansson\(aqs API functions to ensure that all memory operations use +the same functions. +.UNINDENT +.sp +\fBExamples:\fP +.sp +Circumvent problems with different CRT heaps on Windows by using +application\(aqs \fBmalloc()\fP and \fBfree()\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_set_alloc_funcs(malloc, free); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Use the \fI\%Boehm\(aqs conservative garbage collector\fP for memory +operations: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +json_set_alloc_funcs(GC_malloc, GC_free); +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +Allow storing sensitive data (e.g. passwords or encryption keys) in +JSON structures by zeroing all memory when freed: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft CW +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 + 8); + free(ptr); +} + +int main() +{ + json_set_alloc_funcs(secure_malloc, secure_free); + /* ... */ +} +.ft R +.fi +.UNINDENT +.UNINDENT +.sp +For more information about the issues of storing sensitive data in +memory, see +\fI\%http://www.dwheeler.com/secure\-programs/Secure\-Programs\-HOWTO/protect\-secrets.html\fP\&. +The page also explains the \fBguaranteed_memset()\fP function used +in the example and gives a sample implementation for it. +.SS Changes in Jansson +.SS Version 2.7 +.sp +Released 2014\-10\-02 +.INDENT 0.0 +.IP \(bu 2 +New features: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_pack()\fP and friends: Add format specifiers \fBs%\fP and \fB+%\fP +for a size_t string length (#141). +.IP \(bu 2 +\fBjson_unpack()\fP and friends: Add format specifier \fBs%\fP for +unpacking the string length along with the string itself (#141). +.IP \(bu 2 +Add length\-aware string constructors \fBjson_stringn()\fP and +\fBjson_stringn_nocheck()\fP, length\-aware string mutators +\fBjson_string_setn()\fP and \fBjson_string_setn_nocheck()\fP, and a +function for getting string\(aqs length \fBjson_string_length()\fP (#141, +#143). +.IP \(bu 2 +Support \fB\eu0000\fP escapes in the decoder. The support can be +enabled by using the \fBJSON_ALLOW_NUL\fP decoding flag (#141). +.IP \(bu 2 +Add \fBjson_boolean_value()\fP as an alias for \fBjson_is_true()\fP +(#146). +.IP \(bu 2 +Add JSON_REAL_PRECISION encoding flag/macro for controlling real +number precision (#178). +.IP \(bu 2 +Define the maximum indentation as JSON_MAX_INDENT (#191). +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Some malformed \fB\euNNNN\fP escapes could crash the decoder with an +assertion failure. +.IP \(bu 2 +Avoid integer overflows with very long strings in UTF\-8 decoder and +hashtable. +.IP \(bu 2 +Check for \fINULL\fP key in \fBjson_object_get()\fP and +\fBjson_object_del()\fP (#151). +.IP \(bu 2 +Enhance hashtable seeding on Windows (#162). +.IP \(bu 2 +\fBjson_unpack()\fP: Allow mixing JSON_STRICT with optional keys +(#162, #163). +.IP \(bu 2 +Fix int/int32 mismatch (#142). +.IP \(bu 2 +Parse subnormal numbers correctly (#202). +.UNINDENT +.IP \(bu 2 +Build: +.INDENT 2.0 +.IP \(bu 2 +Remove VS2010 build files. CMake should be used on Windows instead +(#165). +.IP \(bu 2 +Fix CMake build flags for MinGW (#193). +.IP \(bu 2 +Add CMake config files for find_package. Rename config.h to +jansson_private_config.h (#157, #159). +.IP \(bu 2 +Make Valgrind checks work with CMake (#160). +.IP \(bu 2 +Fix feature checks to use correct __ATOMIC flags. +.IP \(bu 2 +Fix CMake checks for uint16_t and uint8_t support (#177). +.IP \(bu 2 +Make Jansson build on SmartOS/Solaris (#171). +.IP \(bu 2 +Work around a GCC bug on Solaris (#175). +.IP \(bu 2 +Fix autoreconf on Debian (#182). +.IP \(bu 2 +Don\(aqt use GNU make specific export for global AM_CFLAGS (#203, +#204). +.IP \(bu 2 +Fix building on Android using the supplied Android.mk (#166, +#174). +.IP \(bu 2 +Android.mk: Add \-DHAVE_STDINT_H to LOCAL_CFLAGS (#200). +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Document JANSSON_BUILD_SHARED_LIBS CMake option (#187). +.UNINDENT +.IP \(bu 2 +Tests: +.INDENT 2.0 +.IP \(bu 2 +Close file handles correctly (#198). +.UNINDENT +.IP \(bu 2 +Other changes: +.INDENT 2.0 +.IP \(bu 2 +\fB\euNNNN\fP escapes are now encoded in upper case for better +readability. +.IP \(bu 2 +Enable usage of AddressSanitizer (#180). +.UNINDENT +.UNINDENT +.SS Version 2.6 +.sp +Released 2014\-02\-11 +.INDENT 0.0 +.IP \(bu 2 +Security: +.INDENT 2.0 +.IP \(bu 2 +CVE\-2013\-6401: The hash function used by the hashtable +implementation has been changed, and is automatically seeded with +random data when the first JSON object is created. This prevents +an attacker from causing large JSON objects with specially crafted +keys perform poorly. +.UNINDENT +.IP \(bu 2 +New features: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_object_seed()\fP: Set the seed value of the hash function. +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Include CMake specific files in the release tarball. +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Fix tutorial source to send a User\-Agent header, which is now +required by the GitHub API. +.IP \(bu 2 +Set all memory to zero in secure_free() example. +.UNINDENT +.UNINDENT +.SS Version 2.5 +.sp +Released 2013\-09\-19 +.INDENT 0.0 +.IP \(bu 2 +New features: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_pack()\fP and friends: Add format specifiers \fBs#\fP, \fB+\fP and +\fB+#\fP\&. +.IP \(bu 2 +Add \fBJSON_DECODE_INT_AS_REAL\fP decoding flag to treat all numbers +as real in the decoder (#123). +.IP \(bu 2 +Add \fBjson_array_foreach()\fP, paralleling \fBjson_object_foreach()\fP +(#118). +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_dumps()\fP and friends: Don\(aqt crash if json is \fINULL\fP and +\fBJSON_ENCODE_ANY\fP is set. +.IP \(bu 2 +Fix a theoretical integer overflow in \fBjsonp_strdup()\fP\&. +.IP \(bu 2 +Fix \fBl_isxdigit()\fP macro (#97). +.IP \(bu 2 +Fix an off\-by\-one error in \fBjson_array_remove()\fP\&. +.UNINDENT +.IP \(bu 2 +Build: +.INDENT 2.0 +.IP \(bu 2 +Support CMake in addition to GNU Autotools (#106, #107, #112, +#115, #120, #127). +.IP \(bu 2 +Support building for Android (#109). +.IP \(bu 2 +Don\(aqt use \fB\-Werror\fP by default. +.IP \(bu 2 +Support building and testing with VPATH (#93). +.IP \(bu 2 +Fix compilation when \fBNDEBUG\fP is defined (#128) +.UNINDENT +.IP \(bu 2 +Tests: +.INDENT 2.0 +.IP \(bu 2 +Fix a refleak in \fBtest/bin/json_process.c\fP\&. +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Clarify the return value of \fBjson_load_callback_t()\fP\&. +.IP \(bu 2 +Document how to circumvent problems with separate heaps on Windows. +.IP \(bu 2 +Fix memory leaks and warnings in \fBgithub_commits.c\fP\&. +.IP \(bu 2 +Use \fBjson_decref()\fP properly in tutorial. +.UNINDENT +.IP \(bu 2 +Other: +.INDENT 2.0 +.IP \(bu 2 +Make it possible to forward declare \fBstruct json_t\fP\&. +.UNINDENT +.UNINDENT +.SS Version 2.4 +.sp +Released 2012\-09\-23 +.INDENT 0.0 +.IP \(bu 2 +New features: +.INDENT 2.0 +.IP \(bu 2 +Add \fBjson_boolean()\fP macro that returns the JSON true or false +value based on its argument (#86). +.IP \(bu 2 +Add \fBjson_load_callback()\fP that calls a callback function +repeatedly to read the JSON input (#57). +.IP \(bu 2 +Add JSON_ESCAPE_SLASH encoding flag to escape all occurences of +\fB/\fP with \fB\e/\fP\&. +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Check for and reject NaN and Inf values for reals. Encoding these +values resulted in invalid JSON. +.IP \(bu 2 +Fix \fBjson_real_set()\fP to return \-1 on error. +.UNINDENT +.IP \(bu 2 +Build: +.INDENT 2.0 +.IP \(bu 2 +Jansson now builds on Windows with Visual Studio 2010, and +includes solution and project files in \fBwin32/vs2010/\fP +directory. +.IP \(bu 2 +Fix build warnings (#77, #78). +.IP \(bu 2 +Add \fB\-no\-undefined\fP to LDFLAGS (#90). +.UNINDENT +.IP \(bu 2 +Tests: +.INDENT 2.0 +.IP \(bu 2 +Fix the symbol exports test on Linux/PPC64 (#88). +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Fix typos (#73, #84). +.UNINDENT +.UNINDENT +.SS Version 2.3.1 +.sp +Released 2012\-04\-20 +.INDENT 0.0 +.IP \(bu 2 +Build issues: +.INDENT 2.0 +.IP \(bu 2 +Only use \fBlong long\fP if \fBstrtoll()\fP is also available. +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Fix the names of library version constants in documentation. (#52) +.IP \(bu 2 +Change the tutorial to use GitHub API v3. (#65) +.UNINDENT +.IP \(bu 2 +Tests: +.INDENT 2.0 +.IP \(bu 2 +Make some tests locale independent. (#51) +.IP \(bu 2 +Distribute the library exports test in the tarball. +.IP \(bu 2 +Make test run on shells that don\(aqt support the \fBexport FOO=bar\fP +syntax. +.UNINDENT +.UNINDENT +.SS Version 2.3 +.sp +Released 2012\-01\-27 +.INDENT 0.0 +.IP \(bu 2 +New features: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_unpack()\fP and friends: Add support for optional object keys +with the \fB{s?o}\fP syntax. +.IP \(bu 2 +Add \fBjson_object_update_existing()\fP and +\fBjson_object_update_missing()\fP, for updating only existing keys or +only adding missing keys to an object. (#37) +.IP \(bu 2 +Add \fBjson_object_foreach()\fP for more convenient iteration over +objects. (#45, #46) +.IP \(bu 2 +When decoding JSON, write the number of bytes that were read from +input to \fBerror.position\fP also on success. This is handy with +\fBJSON_DISABLE_EOF_CHECK\fP\&. +.IP \(bu 2 +Add support for decoding any JSON value, not just arrays or +objects. The support is enabled with the new \fBJSON_DECODE_ANY\fP +flag. Patch by Andrea Marchesini. (#4) +.UNINDENT +.IP \(bu 2 +Bug fixes +.INDENT 2.0 +.IP \(bu 2 +Avoid problems with object\(aqs serial number growing too big. (#40, +#41) +.IP \(bu 2 +Decoding functions now return NULL if the first argument is NULL. +Patch by Andrea Marchesini. +.IP \(bu 2 +Include \fBjansson_config.h.win32\fP in the distribution tarball. +.IP \(bu 2 +Remove \fB+\fP and leading zeros from exponents in the encoder. +(#39) +.IP \(bu 2 +Make Jansson build and work on MinGW. (#39, #38) +.UNINDENT +.IP \(bu 2 +Documentation +.INDENT 2.0 +.IP \(bu 2 +Note that the same JSON values must not be encoded in parallel by +separate threads. (#42) +.IP \(bu 2 +Document MinGW support. +.UNINDENT +.UNINDENT +.SS Version 2.2.1 +.sp +Released 2011\-10\-06 +.INDENT 0.0 +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Fix real number encoding and decoding under non\-C locales. (#32) +.IP \(bu 2 +Fix identifier decoding under non\-UTF\-8 locales. (#35) +.IP \(bu 2 +\fBjson_load_file()\fP: Open the input file in binary mode for maximum +compatiblity. +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Clarify the lifecycle of the result of the \fBs\fP fromat of +\fBjson_unpack()\fP\&. (#31) +.IP \(bu 2 +Add some portability info. (#36) +.IP \(bu 2 +Little clarifications here and there. +.UNINDENT +.IP \(bu 2 +Other: +.INDENT 2.0 +.IP \(bu 2 +Some style fixes, issues detected by static analyzers. +.UNINDENT +.UNINDENT +.SS Version 2.2 +.sp +Released 2011\-09\-03 +.INDENT 0.0 +.IP \(bu 2 +New features: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_dump_callback()\fP: Pass the encoder output to a callback +function in chunks. +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_string_set()\fP: Check that target is a string and value is +not NULL. +.UNINDENT +.IP \(bu 2 +Other: +.INDENT 2.0 +.IP \(bu 2 +Documentation typo fixes and clarifications. +.UNINDENT +.UNINDENT +.SS Version 2.1 +.sp +Released 2011\-06\-10 +.INDENT 0.0 +.IP \(bu 2 +New features: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_loadb()\fP: Decode a string with a given size, useful if the +string is not null terminated. +.IP \(bu 2 +Add \fBJSON_ENCODE_ANY\fP encoding flag to allow encoding any JSON +value. By default, only arrays and objects can be encoded. (#19) +.IP \(bu 2 +Add \fBJSON_REJECT_DUPLICATES\fP decoding flag to issue a decoding +error if any JSON object in the input contins duplicate keys. (#3) +.IP \(bu 2 +Add \fBJSON_DISABLE_EOF_CHECK\fP decoding flag to stop decoding after a +valid JSON input. This allows other data after the JSON data. +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Fix an additional memory leak when memory allocation fails in +\fBjson_object_set()\fP and friends. +.IP \(bu 2 +Clear errno before calling \fBstrtod()\fP for better portability. (#27) +.UNINDENT +.IP \(bu 2 +Building: +.INDENT 2.0 +.IP \(bu 2 +Avoid set\-but\-not\-used warning/error in a test. (#20) +.UNINDENT +.IP \(bu 2 +Other: +.INDENT 2.0 +.IP \(bu 2 +Minor clarifications to documentation. +.UNINDENT +.UNINDENT +.SS Version 2.0.1 +.sp +Released 2011\-03\-31 +.INDENT 0.0 +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Replace a few \fBmalloc()\fP and \fBfree()\fP calls with their +counterparts that support custom memory management. +.IP \(bu 2 +Fix object key hashing in json_unpack() strict checking mode. +.IP \(bu 2 +Fix the parentheses in \fBJANSSON_VERSION_HEX\fP macro. +.IP \(bu 2 +Fix \fBjson_object_size()\fP return value. +.IP \(bu 2 +Fix a few compilation issues. +.UNINDENT +.IP \(bu 2 +Portability: +.INDENT 2.0 +.IP \(bu 2 +Enhance portability of \fBva_copy()\fP\&. +.IP \(bu 2 +Test framework portability enhancements. +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Distribute \fBdoc/upgrading.rst\fP with the source tarball. +.IP \(bu 2 +Build documentation in strict mode in \fBmake distcheck\fP\&. +.UNINDENT +.UNINDENT +.SS Version 2.0 +.sp +Released 2011\-02\-28 +.sp +This release is backwards incompatible with the 1.x release series. +See the chapter "Upgrading from older versions" in documentation for +details. +.INDENT 0.0 +.IP \(bu 2 +Backwards incompatible changes: +.INDENT 2.0 +.IP \(bu 2 +Unify unsigned integer usage in the API: All occurences of +unsigned int and unsigned long have been replaced with size_t. +.IP \(bu 2 +Change JSON integer\(aqs underlying type to the widest signed integer +type available, i.e. long long if it\(aqs supported, otherwise long. +Add a typedef json_int_t that defines the type. +.IP \(bu 2 +Change the maximum indentation depth to 31 spaces in encoder. This +frees up bits from the flags parameter of encoding functions +\fBjson_dumpf()\fP, \fBjson_dumps()\fP and \fBjson_dump_file()\fP\&. +.IP \(bu 2 +For future needs, add a flags parameter to all decoding functions +\fBjson_loadf()\fP, \fBjson_loads()\fP and \fBjson_load_file()\fP\&. +.UNINDENT +.IP \(bu 2 +New features +.INDENT 2.0 +.IP \(bu 2 +\fBjson_pack()\fP, \fBjson_pack_ex()\fP, \fBjson_vpack_ex()\fP: Create JSON +values based on a format string. +.IP \(bu 2 +\fBjson_unpack()\fP, \fBjson_unpack_ex()\fP, \fBjson_vunpack_ex()\fP: Simple +value extraction and validation functionality based on a format +string. +.IP \(bu 2 +Add column, position and source fields to the \fBjson_error_t\fP +struct. +.IP \(bu 2 +Enhance error reporting in the decoder. +.IP \(bu 2 +\fBJANSSON_VERSION\fP et al.: Preprocessor constants that define the +library version. +.IP \(bu 2 +\fBjson_set_alloc_funcs()\fP: Set custom memory allocation functions. +.UNINDENT +.IP \(bu 2 +Fix many portability issues, especially on Windows. +.IP \(bu 2 +Configuration +.INDENT 2.0 +.IP \(bu 2 +Add file \fBjansson_config.h\fP that contains site specific +configuration. It\(aqs created automatically by the configure script, +or can be created by hand if the configure script cannot be used. +The file \fBjansson_config.h.win32\fP can be used without +modifications on Windows systems. +.IP \(bu 2 +Add a section to documentation describing how to build Jansson on +Windows. +.IP \(bu 2 +Documentation now requires Sphinx 1.0 or newer. +.UNINDENT +.UNINDENT +.SS Version 1.3 +.sp +Released 2010\-06\-13 +.INDENT 0.0 +.IP \(bu 2 +New functions: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_object_iter_set()\fP, \fBjson_object_iter_set_new()\fP: Change +object contents while iterating over it. +.IP \(bu 2 +\fBjson_object_iter_at()\fP: Return an iterator that points to a +specific object item. +.UNINDENT +.IP \(bu 2 +New encoding flags: +.INDENT 2.0 +.IP \(bu 2 +\fBJSON_PRESERVE_ORDER\fP: Preserve the insertion order of object +keys. +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Fix an error that occured when an array or object was first +encoded as empty, then populated with some data, and then +re\-encoded +.IP \(bu 2 +Fix the situation like above, but when the first encoding resulted +in an error +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Clarify the documentation on reference stealing, providing an +example usage pattern +.UNINDENT +.UNINDENT +.SS Version 1.2.1 +.sp +Released 2010\-04\-03 +.INDENT 0.0 +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Fix reference counting on \fBtrue\fP, \fBfalse\fP and \fBnull\fP +.IP \(bu 2 +Estimate real number underflows in decoder with 0.0 instead of +issuing an error +.UNINDENT +.IP \(bu 2 +Portability: +.INDENT 2.0 +.IP \(bu 2 +Make \fBint32_t\fP available on all systems +.IP \(bu 2 +Support compilers that don\(aqt have the \fBinline\fP keyword +.IP \(bu 2 +Require Autoconf 2.60 (for \fBint32_t\fP) +.UNINDENT +.IP \(bu 2 +Tests: +.INDENT 2.0 +.IP \(bu 2 +Print test names correctly when \fBVERBOSE=1\fP +.IP \(bu 2 +\fBtest/suites/api\fP: Fail when a test fails +.IP \(bu 2 +Enhance tests for iterators +.IP \(bu 2 +Enhance tests for decoding texts that contain null bytes +.UNINDENT +.IP \(bu 2 +Documentation: +.INDENT 2.0 +.IP \(bu 2 +Don\(aqt remove \fBchanges.rst\fP in \fBmake clean\fP +.IP \(bu 2 +Add a chapter on RFC conformance +.UNINDENT +.UNINDENT +.SS Version 1.2 +.sp +Released 2010\-01\-21 +.INDENT 0.0 +.IP \(bu 2 +New functions: +.INDENT 2.0 +.IP \(bu 2 +\fBjson_equal()\fP: Test whether two JSON values are equal +.IP \(bu 2 +\fBjson_copy()\fP and \fBjson_deep_copy()\fP: Make shallow and deep copies +of JSON values +.IP \(bu 2 +Add a version of all functions taking a string argument that +doesn\(aqt check for valid UTF\-8: \fBjson_string_nocheck()\fP, +\fBjson_string_set_nocheck()\fP, \fBjson_object_set_nocheck()\fP, +\fBjson_object_set_new_nocheck()\fP +.UNINDENT +.IP \(bu 2 +New encoding flags: +.INDENT 2.0 +.IP \(bu 2 +\fBJSON_SORT_KEYS\fP: Sort objects by key +.IP \(bu 2 +\fBJSON_ENSURE_ASCII\fP: Escape all non\-ASCII Unicode characters +.IP \(bu 2 +\fBJSON_COMPACT\fP: Use a compact representation with all unneeded +whitespace stripped +.UNINDENT +.IP \(bu 2 +Bug fixes: +.INDENT 2.0 +.IP \(bu 2 +Revise and unify whitespace usage in encoder: Add spaces between +array and object items, never append newline to output. +.IP \(bu 2 +Remove const qualifier from the \fBjson_t\fP parameter in +\fBjson_string_set()\fP, \fBjson_integer_set()\fP and \fBjson_real_set()\fP\&. +.IP \(bu 2 +Use \fBint32_t\fP internally for representing Unicode code points +(int is not enough on all platforms) +.UNINDENT +.IP \(bu 2 +Other changes: +.INDENT 2.0 +.IP \(bu 2 +Convert \fBCHANGES\fP (this file) to reStructured text and add it to +HTML documentation +.IP \(bu 2 +The test system has been refactored. Python is no longer required +to run the tests. +.IP \(bu 2 +Documentation can now be built by invoking \fBmake html\fP +.IP \(bu 2 +Support for pkg\-config +.UNINDENT +.UNINDENT +.SS Version 1.1.3 +.sp +Released 2009\-12\-18 +.INDENT 0.0 +.IP \(bu 2 +Encode reals correctly, so that first encoding and then decoding a +real always produces the same value +.IP \(bu 2 +Don\(aqt export private symbols in \fBlibjansson.so\fP +.UNINDENT +.SS Version 1.1.2 +.sp +Released 2009\-11\-08 +.INDENT 0.0 +.IP \(bu 2 +Fix a bug where an error message was not produced if the input file +could not be opened in \fBjson_load_file()\fP +.IP \(bu 2 +Fix an assertion failure in decoder caused by a minus sign without a +digit after it +.IP \(bu 2 +Remove an unneeded include of \fBstdint.h\fP in \fBjansson.h\fP +.UNINDENT +.SS Version 1.1.1 +.sp +Released 2009\-10\-26 +.INDENT 0.0 +.IP \(bu 2 +All documentation files were not distributed with v1.1; build +documentation in make distcheck to prevent this in the future +.IP \(bu 2 +Fix v1.1 release date in \fBCHANGES\fP +.UNINDENT +.SS Version 1.1 +.sp +Released 2009\-10\-20 +.INDENT 0.0 +.IP \(bu 2 +API additions and improvements: +.INDENT 2.0 +.IP \(bu 2 +Extend array and object APIs +.IP \(bu 2 +Add functions to modify integer, real and string values +.IP \(bu 2 +Improve argument validation +.IP \(bu 2 +Use unsigned int instead of \fBuint32_t\fP for encoding flags +.UNINDENT +.IP \(bu 2 +Enhance documentation +.INDENT 2.0 +.IP \(bu 2 +Add getting started guide and tutorial +.IP \(bu 2 +Fix some typos +.IP \(bu 2 +General clarifications and cleanup +.UNINDENT +.IP \(bu 2 +Check for integer and real overflows and underflows in decoder +.IP \(bu 2 +Make singleton values thread\-safe (\fBtrue\fP, \fBfalse\fP and \fBnull\fP) +.IP \(bu 2 +Enhance circular reference handling +.IP \(bu 2 +Don\(aqt define \fB\-std=c99\fP in \fBAM_CFLAGS\fP +.IP \(bu 2 +Add C++ guards to \fBjansson.h\fP +.IP \(bu 2 +Minor performance and portability improvements +.IP \(bu 2 +Expand test coverage +.UNINDENT +.SS Version 1.0.4 +.sp +Released 2009\-10\-11 +.INDENT 0.0 +.IP \(bu 2 +Relax Autoconf version requirement to 2.59 +.IP \(bu 2 +Make Jansson compile on platforms where plain \fBchar\fP is unsigned +.IP \(bu 2 +Fix API tests for object +.UNINDENT +.SS Version 1.0.3 +.sp +Released 2009\-09\-14 +.INDENT 0.0 +.IP \(bu 2 +Check for integer and real overflows and underflows in decoder +.IP \(bu 2 +Use the Python json module for tests, or simplejson if the json +module is not found +.IP \(bu 2 +Distribute changelog (this file) +.UNINDENT +.SS Version 1.0.2 +.sp +Released 2009\-09\-08 +.INDENT 0.0 +.IP \(bu 2 +Handle EOF correctly in decoder +.UNINDENT +.SS Version 1.0.1 +.sp +Released 2009\-09\-04 +.INDENT 0.0 +.IP \(bu 2 +Fixed broken \fBjson_is_boolean()\fP +.UNINDENT +.SS Version 1.0 +.sp +Released 2009\-08\-25 +.INDENT 0.0 +.IP \(bu 2 +Initial release +.UNINDENT +.INDENT 0.0 +.IP \(bu 2 +\fIgenindex\fP +.IP \(bu 2 +\fIsearch\fP +.UNINDENT +.sp +.SH AUTHOR +Petri Lehtinen +.SH COPYRIGHT +2009-2014, Petri Lehtinen +.\" Generated by docutils manpage writer. +. diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/jansson.p5m --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/jansson.p5m Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,95 @@ +# +# CDDL HEADER START +# +# The contents of this file are subject to the terms of the +# Common Development and Distribution License (the "License"). +# You may not use this file except in compliance with the License. +# +# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +# or http://www.opensolaris.org/os/licensing. +# See the License for the specific language governing permissions +# and limitations under the License. +# +# When distributing Covered Code, include this CDDL HEADER in each +# file and include the License file at usr/src/OPENSOLARIS.LICENSE. +# If applicable, add the following below this CDDL HEADER, with the +# fields enclosed by brackets "[]" replaced with your own identifying +# information: Portions Copyright [yyyy] [name of copyright owner] +# +# CDDL HEADER END +# +# Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved. +# + + default mangler.man.stability volatile> + set action.hash doc/html/%<\1>> +set name=pkg.fmri \ + value=pkg:/library/jansson@$(IPS_COMPONENT_VERSION),$(BUILD_VERSION) +set name=pkg.summary value="Jansson - C library for working with JSON data" +set name=pkg.description \ + value="Jansson is a C library for encoding, decoding and manipulating JSON data. It features a simple and intuitive API and data model, comprehensive documentation, full Unicode support (UTF-8), an extensive test suite and no dependencies on other libraries." +set name=com.oracle.info.description value="the Jansson C library" +set name=com.oracle.info.tpno value=$(TPNO) +set name=info.classification \ + value=org.opensolaris.category.2008:System/Libraries +set name=info.source-url value=$(COMPONENT_ARCHIVE_URL) +set name=info.upstream-url value=$(COMPONENT_PROJECT_URL) +set name=org.opensolaris.arc-caseid value=PSARC/2014/362 +set name=org.opensolaris.consolidation value=$(CONSOLIDATION) +file path=usr/include/jansson/jansson.h +file path=usr/include/jansson/jansson_config.h +link path=usr/lib/$(MACH64)/libjansson.so target=libjansson.so.4.7.0 +link path=usr/lib/$(MACH64)/libjansson.so.4 target=libjansson.so.4.7.0 +file path=usr/lib/$(MACH64)/libjansson.so.4.7.0 +file path=usr/lib/$(MACH64)/llib-ljansson.ln +file path=usr/lib/$(MACH64)/pkgconfig/jansson.pc +link path=usr/lib/libjansson.so target=libjansson.so.4.7.0 +link path=usr/lib/libjansson.so.4 target=libjansson.so.4.7.0 +file path=usr/lib/libjansson.so.4.7.0 +file path=usr/lib/llib-ljansson +file path=usr/lib/llib-ljansson.ln +file path=usr/lib/pkgconfig/jansson.pc +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_downloads/github_commits.c +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_downloads/github_commits.c +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/apiref.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/changes.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/conformance.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/gettingstarted.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/index.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/portability.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/tutorial.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_sources/upgrading.txt +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/ajax-loader.gif +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/basic.css +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/comment-bright.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/comment-close.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/comment.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/default.css +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/doctools.js +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/down-pressed.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/down.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/file.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/jquery.js +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/minus.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/plus.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/pygments.css +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/searchtools.js +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/sidebar.js +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/underscore.js +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/up-pressed.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/up.png +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/_static/websupport.js +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/apiref.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/changes.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/conformance.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/genindex.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/gettingstarted.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/index.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/portability.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/search.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/searchindex.js +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/tutorial.html +file path=usr/share/doc/jansson-$(COMPONENT_VERSION)/html/upgrading.html +file doc/man3lib/libjansson.3lib path=usr/share/man/man3lib/libjansson.3lib +license LICENSE license=MIT + diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/llib-ljansson --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/llib-ljansson Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,39 @@ +/* + * CDDL HEADER START + * + * The contents of this file are subject to the terms of the + * Common Development and Distribution License (the "License"). + * You may not use this file except in compliance with the License. + * + * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE + * or http://www.opensolaris.org/os/licensing. + * See the License for the specific language governing permissions + * and limitations under the License. + * + * When distributing Covered Code, include this CDDL HEADER in each + * file and include the License file at usr/src/OPENSOLARIS.LICENSE. + * If applicable, add the following below this CDDL HEADER, with the + * fields enclosed by brackets "[]" replaced with your own identifying + * information: Portions Copyright [yyyy] [name of copyright owner] + * + * CDDL HEADER END + */ + +/* + * Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved. + */ + +/* LINTLIBRARY */ +/* PROTOLIB1 */ + +/* + * This little dance is necessary to avoid ftello/fseeko + * complaints vs libc. We don't use them but we do #include + * stdio.h and as we are large file aware they get defined + * differently than libc. + */ +#include +#undef _LARGEFILE_SOURCE + +#include +#include diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/patches/001-usr-include-jansson.patch --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/patches/001-usr-include-jansson.patch Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,16 @@ +Tomas Heran +Need to install header files to /usr/include/jansson +This patch will not be reported upstream. + +diff -r fa5b56b77f9c -r 10395313a7ae jansson.pc.in +--- a/jansson.pc.in Tue Oct 28 16:31:32 2014 +0100 ++++ b/jansson.pc.in Tue Oct 28 17:05:35 2014 +0100 +@@ -1,7 +1,7 @@ + prefix=@prefix@ + exec_prefix=@exec_prefix@ + libdir=@libdir@ +-includedir=${prefix}/include ++includedir=${prefix}/include/jansson + + Name: Jansson + Description: Library for encoding, decoding and manipulating JSON data diff -r 240dc166feab -r c6a303a2f8c5 components/jansson/patches/002-usr-include-jansson.patch --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/components/jansson/patches/002-usr-include-jansson.patch Fri Apr 17 01:30:52 2015 -0700 @@ -0,0 +1,15 @@ +Tomas Heran +Reported upstream as https://github.com/akheron/jansson/issues/209 + +diff -r 10395313a7ae -r 1834d7632071 src/jansson.h +--- a/src/jansson.h Tue Oct 28 17:05:35 2014 +0100 ++++ b/src/jansson.h Thu Nov 27 11:50:46 2014 +0100 +@@ -12,7 +12,7 @@ + #include /* for size_t */ + #include + +-#include ++#include "jansson_config.h" + + #ifdef __cplusplus + extern "C" {