jansson: http://www.digip.org/jansson/doc/2.2/apiref.html
＃include "jansson.h"
json_t 这个数据结构用于描述库中所有的JSON类型的值。它通常包含它列举的JSON值(JSON value)的类型(type)和引用计数（reference count）,依赖关系取决于值（value）的类型。
json_t对象通常是以指针的方式来使用。
除非有其它特殊声明，API函数在错误的时候都是返回一个错误值。参照函数的符号特征，出错的返回值通常是NULL或 -1。无效的参数或无效的输入通常是导致出错的原因。申请内存(memory allocation)和I／O操作也可能导致出错。
类型(type)
json_type枚举类型用于JSON值类型的断定：
typedef enum {
JSON_OBJECT,
JSON_ARRAY,
JSON_STRING,
JSON_INTEGER,
JSON_REAL, /*实型*/
JSON_TRUE,
JSON_FALSE,
JSON_NULL
} json_type;
这些与JSON对象、数组、字符串、数字、布尔值和NULL值相符。一个数字(number)可以被描述成是一个JSON_INTEGER类型或者是JSON_REAL类型。值为真的布尔型可以被描述为JSON_TRUE，值为假的布尔型就是JSON_FALSE。
typedef struct {
json_type type;
size_t refcount;
} json_t;
下面是一些用于断定的API：
int json_typeof(const json_t *json)
/*返回一个被转换成 int 的 JSON值的类型，json必需不为NULL，这个函数实际上是作为一个迅速转换的宏来使用*/
json_is_null(const json_t *json)
/*这些函数(实际上是宏) 返回一个trun(非0值,已在json_type中给定，转换得来）或false(zero) for values of other types and for NULL*/
json_is_number (const json_t *json ) ¶/*Returns true for types JSON_TRUE and JSON_FALSE, and false for values of other types and for NULL.*/
在源码中的定义是：
#define json_typeof(json) ((json)->type)
#define json_is_object(json) (json && json_typeof(json) == JSON_OBJECT)
#define json_is_array(json) (json && json_typeof(json) == JSON_ARRAY)
#define json_is_string(json) (json && json_typeof(json) == JSON_STRING)
#define json_is_integer(json) (json && json_typeof(json) == JSON_INTEGER)
#define json_is_real(json) (json && json_typeof(json) == JSON_REAL)
#define json_is_number(json) (json_is_integer(json) || json_is_real(json))
#define json_is_true(json) (json && json_typeof(json) == JSON_TRUE)
#define json_is_false(json) (json && json_typeof(json) == JSON_FALSE)
#define json_is_boolean(json) (json_is_true(json) || json_is_false(json))
#define json_is_null(json) (json && json_typeof(json) == JSON_NULL)
引用计数（reference count）
引用计数是用于追踪一个值是否正在使用。当一个值被创建后，它的引用计数值就被设为1。如果引用了一个值（例如在最后使用时在某处保存了一个值），它的引用计数值就会增加，而当这个值不再需要的时候，引用计数值就会递减。当引用计数值减小到0的时候，它就不能再被引用了，它的值也会被销毁。
下面的函数用于操作引用计数值(reference count)：
json_t *json_incref(json_t *json) / *为json增加一个引用计数值(non-NULL)，然后返回json*/
static JSON_INLINE json_t *json_incref(json_t *json)
{ if(json && json->refcount != (size_t)-1)
++json->refcount;
return json;
}void json_decref(json_t *json) /* 为json递减一个引用计数值，调用json_decref()时引用计数值一但减少到0，值(value)就会被销毁不能再使用*/
static JSON_INLINE
void json_decref(json_t *json)
{
if(json && json->refcount != (size_t)-1 && --json->refcount == 0)
json_delete(json);
}函数在创建新的JSON value时会把引用计数值设为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.
正常来说，所有函数在接收一个作为参数的JSON value时，都会对引用计数值进行管理。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.
下面代码是创建一个新的JSON数组和它添加一个整数：
json_t *array, *integer;
array = json_array();
integer = json_integer(42);
json_array_append(array, integer);
json_decref(integer);注意上面使用了 json_decref() 去释放了一个引用计数，但如果用一个引用偷取函数(a reference stealing function) json_array_append_new() 来代替 json_array_append(),那就变得简单多了，如下：
json_t *array = json_array();
json_array_append_new(array, json_integer(42));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
在一个对象(object)或数组(array)被创建后会直接地或间接地创建一个循环引用circular references，嵌入它自身当中，直接的例子：
json_t *obj = json_object();
json_object_set(obj, "foo", obj);
Jansson会拒绝这样做，json_object_set()会返回一个错误状态(所有其它对object & arrays操作的函数也是如此)。
间接的也是很危险的，如下：json_t *arr1 = json_array(), *arr2 = json_array(); json_array_append(arr1, arr2); json_array_append(arr2, arr1);在上面的例子中，arr2数组中包含了arr1数组，反过来也是一样，在当前性能的限制下，jansson不能检查像这种间接循环引用(Jansson cannot check for this kind of indirect circular references without a performance hit)，所以这是由使用者去避免发生这种情况。如果发生了一个循环引用，内存将会被这些值耗光而且不能被json_decref()释放。而引用计数(reference count)从不会掉到0的，因为计数值一直被每个引用占有着。此外，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)这些值是单独使用，所以函数每次都返回相同的值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_null (void ) Return value: New reference. Returns the JSON null value. 源代码为：<jansson-2.2.1/src/value.c>
/*** simple values ***/ json_t *json_true(void) { static json_t the_true = {JSON_TRUE, (size_t)-1}; return &the_true; } json_t *json_false(void) { static json_t the_false = {JSON_FALSE, (size_t)-1}; return &the_false; } json_t *json_null(void) { static json_t the_null = {JSON_NULL, (size_t)-1}; return &the_null; }
字符串String Jansson使用UTF-8来作为字符编码，All JSON strings must be valid UTF-8 (or ASCII, as it’s a subset of UTF-8).正常的空字符C字符串也可以使用, 所以JSON字符串不包含嵌入的空字符. All other Unicode codepoints U+0001 through U+10FFFF are allowed.
源代码：<jansson-2.2.1/src/value.c>json_t * json_string (const char *value )
- Return value: New reference.
- 用value构造一个json_string；
- 返回一个新的JSON字符串，在出错时返回空，jaon value必需是一个有效的UTF-8编码的Unicode字符串。
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. 你已经用各种方法检查过了).
const char * json_string_value (const json_t *string )
返回jaon_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.返回一个UTF-8编码空字符结尾的字符串相关值，如果字符串不是一个JSON字符串则返回空。
返回值是只读的，不能被用户修改和释放。它(json)在字符串存在期间一直有效(也是在它的引用计数值被减到0之前一直有效)。
int json_string_set (const json_t *string, const char *value )
设置一个相关的字符串值到value(json)里，值必需是一个有效的UTF-8编码的Unicoded字符串。成功时返回0，出错时返回-1。
int json_string_set_nocheck (const json_t *string, const char *value ) < style="margin-top: 3px; margin-bottom: 10px; margin-left: 30px; line-height: 20px; text-align: justify; ">
Like json_string_set(), 但不检查值是否是一个有效的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).
/*** string ***/ json_t *json_string_nocheck(const char *value) { json_string_t *string; if(!value) return NULL; string = jsonp_malloc(sizeof(json_string_t)); if(!string) return NULL; json_init(&string->json, JSON_STRING); string->value = jsonp_strdup(value); if(!string->value) { jsonp_free(string); return NULL; } return &string->json; } json_t *json_string(const char *value) { if(!value || !utf8_check_string(value, -1)) return NULL; return json_string_nocheck(value); } const char *json_string_value(const json_t *json) { if(!json_is_string(json)) return NULL; return json_to_string(json)->value; } int json_string_set_nocheck(json_t *json, const char *value) { char *dup; json_string_t *string; if(!json_is_string(json) || !value) return -1; dup = jsonp_strdup(value); if(!dup) return -1; string = json_to_string(json); jsonp_free(string->value); string->value = dup; return 0; } int json_string_set(json_t *json, const char *value) { if(!value || !utf8_check_string(value, -1)) return -1; return json_string_set_nocheck(json, value); } static void json_delete_string(json_string_t *string) { jsonp_free(string->value); jsonp_free(string); } static int json_string_equal(json_t *string1, json_t *string2) { return strcmp(json_string_value(string1), json_string_value(string2)) == 0; } static json_t *json_string_copy(json_t *string) { return json_string_nocheck(json_string_value(string)); }
数值Number
JSON规格只能容纳一种数字类型："number"。C语言区别整型(integer)与浮点型(floating-point)为不同类型，所以因为这个现在条件，jansson也为它们区分不同类型，它们被分别叫"integer"和"real"。
json_int_t
这是一个常用于存储整数值的C类型， It represents the widest integer type available on your system.实际上它只是一个long long 型的typedef 定义，当然，需要你的编译器支持long long型，否则它是long型。
#typedef long long json_int_t; /* 源代码 jansson-2.2.1/src/jansson.h */
通常可以在使用json_int_t的地方使用纯粹的 int,and the implicit C integer conversion handles the rest.只有当你知道需要去使用全64位范围的值时，你可以明确地使用json_int_t。
JSON_INTEGER_IS_LONG_LONG：这是一个预处理器变量，当json_int_t是long long型时，它是1；当json_int_t是long型时，它是0；（ jansson-2.2.1/src/jansson_config.h ）
使用方法：
#if JSON_INTEGER_IS_LONG_LONG
/* Code specific for long long */
#else
/* Code specific for long */
#endif
JSON_INTEGER_FORMAT：
这是一个用于printf()扩展的宏，它可以使printf()在打印json_int_t类型的数据时可以适应不同的数据长度。
json_int_t x = 123123123;
printf("x is %" JSON_INTEGER_FORMAT "\n", x);
它在jansson.h中定义：
#if JSON_INTEGER_IS_LONG_LONG
#define JSON_INTEGER_FORMAT "lld"
typedef long long json_int_t;
#else
#define JSON_INTEGER_FORMAT "ld"
typedef long json_int_t;
#endif /* JSON_INTEGER_IS_LONG_LONG */
下是操作API： 源代码：<jansson-2.2.1/src/value.c>
json_t * json_integer ( json_int_t value )
- Return value: New reference.
返回一个新的JSON整数，在出错时返回NULL.
json_int_t json_integer_value (const json_t *integer )
返回一个整型的关系值，在不是一个整型值的时候返回0。
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， 把value设置到integer的value中，成功时返回0，如果不是JSON integer型时返回 -1(用上面的宏进行判断).
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.
数组ArrayJSON数组是JSON values的有序集合； 源码在：<value.c>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.
1757
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
