"Fossies" - the Fresh Open Source Software Archive 
Member "jansson-2.14/doc/apiref.rst" (9 Sep 2021, 71940 Bytes) of package /linux/www/jansson-2.14.tar.bz2:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) reStructured Text source code syntax highlighting (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 .. _apiref:
2
3 *************
4 API Reference
5 *************
6
7 .. highlight:: c
8
9 Preliminaries
10 =============
11
12 All declarations are in :file:`jansson.h`, so it's enough to
13
14 ::
15
16 #include <jansson.h>
17
18 in each source file.
19
20 All constants are prefixed with ``JSON_`` (except for those describing
21 the library version, prefixed with ``JANSSON_``). Other identifiers
22 are prefixed with ``json_``. Type names are suffixed with ``_t`` and
23 ``typedef``\ 'd so that the ``struct`` keyword need not be used.
24
25
26 Library Version
27 ===============
28
29 The Jansson version is of the form *A.B.C*, where *A* is the major
30 version, *B* is the minor version and *C* is the micro version. If the
31 micro version is zero, it's omitted from the version string, i.e. the
32 version string is just *A.B*.
33
34 When a new release only fixes bugs and doesn't add new features or
35 functionality, the micro version is incremented. When new features are
36 added in a backwards compatible way, the minor version is incremented
37 and the micro version is set to zero. When there are backwards
38 incompatible changes, the major version is incremented and others are
39 set to zero.
40
41 The following preprocessor constants specify the current version of
42 the library:
43
44 ``JANSSON_MAJOR_VERSION``, ``JANSSON_MINOR_VERSION``, ``JANSSON_MICRO_VERSION``
45 Integers specifying the major, minor and micro versions,
46 respectively.
47
48 ``JANSSON_VERSION``
49 A string representation of the current version, e.g. ``"1.2.1"`` or
50 ``"1.3"``.
51
52 ``JANSSON_VERSION_HEX``
53 A 3-byte hexadecimal representation of the version, e.g.
54 ``0x010201`` for version 1.2.1 and ``0x010300`` for version 1.3.
55 This is useful in numeric comparisons, e.g.::
56
57 #if JANSSON_VERSION_HEX >= 0x010300
58 /* Code specific to version 1.3 and above */
59 #endif
60
61 Additionally, there are functions to determine the version of Jansson at
62 runtime:
63
64 .. function:: const char *jansson_version_str()
65
66 Return the version of the Jansson library, in the same format as
67 the ``JANSSON_VERSION`` preprocessor constant.
68
69 .. versionadded:: 2.13
70
71 .. function:: int jansson_version_cmp(int major, int minor, int micro)
72
73 Returns an integer less than, equal to, or greater than zero if
74 the runtime version of Jansson is found, respectively, to be less
75 than, to match, or be greater than the provided *major*, *minor*, and
76 *micro*.
77
78 .. versionadded:: 2.13
79
80 ``JANSSON_THREAD_SAFE_REFCOUNT``
81 If this value is defined all read-only operations and reference counting in
82 Jansson are thread safe. This value is not defined for versions older than
83 ``2.11`` or when the compiler does not provide built-in atomic functions.
84
85
86 Value Representation
87 ====================
88
89 The JSON specification (:rfc:`4627`) defines the following data types:
90 *object*, *array*, *string*, *number*, *boolean*, and *null*. JSON
91 types are used dynamically; arrays and objects can hold any other data
92 type, including themselves. For this reason, Jansson's type system is
93 also dynamic in nature. There's one C type to represent all JSON
94 values, and this structure knows the type of the JSON value it holds.
95
96 .. type:: json_t
97
98 This data structure is used throughout the library to represent all
99 JSON values. It always contains the type of the JSON value it holds
100 and the value's reference count. The rest depends on the type of the
101 value.
102
103 Objects of :type:`json_t` are always used through a pointer. There
104 are APIs for querying the type, manipulating the reference count, and
105 for constructing and manipulating values of different types.
106
107 Unless noted otherwise, all API functions return an error value if an
108 error occurs. Depending on the function's signature, the error value
109 is either *NULL* or -1. Invalid arguments or invalid input are
110 apparent sources for errors. Memory allocation and I/O operations may
111 also cause errors.
112
113
114 Type
115 ----
116
117 .. c:enum:: json_type
118
119 The type of a JSON value. The following members are defined:
120
121 +--------------------+
122 | ``JSON_OBJECT`` |
123 +--------------------+
124 | ``JSON_ARRAY`` |
125 +--------------------+
126 | ``JSON_STRING`` |
127 +--------------------+
128 | ``JSON_INTEGER`` |
129 +--------------------+
130 | ``JSON_REAL`` |
131 +--------------------+
132 | ``JSON_TRUE`` |
133 +--------------------+
134 | ``JSON_FALSE`` |
135 +--------------------+
136 | ``JSON_NULL`` |
137 +--------------------+
138
139 These correspond to JSON object, array, string, number, boolean and
140 null. A number is represented by either a value of the type
141 ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value
142 is represented by a value of the type ``JSON_TRUE`` and false by a
143 value of the type ``JSON_FALSE``.
144
145 .. function:: int json_typeof(const json_t *json)
146
147 Return the type of the JSON value (a :type:`json_type` cast to
148 ``int``). *json* MUST NOT be *NULL*. This function is actually
149 implemented as a macro for speed.
150
151 .. function:: int json_is_object(const json_t *json)
152 int json_is_array(const json_t *json)
153 int json_is_string(const json_t *json)
154 int json_is_integer(const json_t *json)
155 int json_is_real(const json_t *json)
156 int json_is_true(const json_t *json)
157 int json_is_false(const json_t *json)
158 int json_is_null(const json_t *json)
159
160 These functions (actually macros) return true (non-zero) for values
161 of the given type, and false (zero) for values of other types and
162 for *NULL*.
163
164 .. function:: int json_is_number(const json_t *json)
165
166 Returns true for values of types ``JSON_INTEGER`` and
167 ``JSON_REAL``, and false for other types and for *NULL*.
168
169 .. function:: int json_is_boolean(const json_t *json)
170
171 Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
172 for values of other types and for *NULL*.
173
174 .. function:: int json_boolean_value(const json_t *json)
175
176 Alias of :func:`json_is_true()`, i.e. returns 1 for ``JSON_TRUE``
177 and 0 otherwise.
178
179 .. versionadded:: 2.7
180
181
182 .. _apiref-reference-count:
183
184 Reference Count
185 ---------------
186
187 The reference count is used to track whether a value is still in use
188 or not. When a value is created, it's reference count is set to 1. If
189 a reference to a value is kept (e.g. a value is stored somewhere for
190 later use), its reference count is incremented, and when the value is
191 no longer needed, the reference count is decremented. When the
192 reference count drops to zero, there are no references left, and the
193 value can be destroyed.
194
195 .. function:: json_t *json_incref(json_t *json)
196
197 Increment the reference count of *json* if it's not *NULL*.
198 Returns *json*.
199
200 .. function:: void json_decref(json_t *json)
201
202 Decrement the reference count of *json*. As soon as a call to
203 :func:`json_decref()` drops the reference count to zero, the value
204 is destroyed and it can no longer be used.
205
206 Functions creating new JSON values set the reference count to 1. These
207 functions are said to return a **new reference**. Other functions
208 returning (existing) JSON values do not normally increase the
209 reference count. These functions are said to return a **borrowed
210 reference**. So, if the user will hold a reference to a value returned
211 as a borrowed reference, he must call :func:`json_incref`. As soon as
212 the value is no longer needed, :func:`json_decref` should be called
213 to release the reference.
214
215 Normally, all functions accepting a JSON value as an argument will
216 manage the reference, i.e. increase and decrease the reference count
217 as needed. However, some functions **steal** the reference, i.e. they
218 have the same result as if the user called :func:`json_decref()` on
219 the argument right after calling the function. These functions are
220 suffixed with ``_new`` or have ``_new_`` somewhere in their name.
221
222 For example, the following code creates a new JSON array and appends
223 an integer to it::
224
225 json_t *array, *integer;
226
227 array = json_array();
228 integer = json_integer(42);
229
230 json_array_append(array, integer);
231 json_decref(integer);
232
233 Note how the caller has to release the reference to the integer value
234 by calling :func:`json_decref()`. By using a reference stealing
235 function :func:`json_array_append_new()` instead of
236 :func:`json_array_append()`, the code becomes much simpler::
237
238 json_t *array = json_array();
239 json_array_append_new(array, json_integer(42));
240
241 In this case, the user doesn't have to explicitly release the
242 reference to the integer value, as :func:`json_array_append_new()`
243 steals the reference when appending the value to the array.
244
245 In the following sections it is clearly documented whether a function
246 will return a new or borrowed reference or steal a reference to its
247 argument.
248
249
250 Circular References
251 -------------------
252
253 A circular reference is created when an object or an array is,
254 directly or indirectly, inserted inside itself. The direct case is
255 simple::
256
257 json_t *obj = json_object();
258 json_object_set(obj, "foo", obj);
259
260 Jansson will refuse to do this, and :func:`json_object_set()` (and
261 all the other such functions for objects and arrays) will return with
262 an error status. The indirect case is the dangerous one::
263
264 json_t *arr1 = json_array(), *arr2 = json_array();
265 json_array_append(arr1, arr2);
266 json_array_append(arr2, arr1);
267
268 In this example, the array ``arr2`` is contained in the array
269 ``arr1``, and vice versa. Jansson cannot check for this kind of
270 indirect circular references without a performance hit, so it's up to
271 the user to avoid them.
272
273 If a circular reference is created, the memory consumed by the values
274 cannot be freed by :func:`json_decref()`. The reference counts never
275 drops to zero because the values are keeping the references to each
276 other. Moreover, trying to encode the values with any of the encoding
277 functions will fail. The encoder detects circular references and
278 returns an error status.
279
280 Scope Dereferencing
281 -------------------
282
283 .. versionadded:: 2.9
284
285 It is possible to use the ``json_auto_t`` type to automatically
286 dereference a value at the end of a scope. For example::
287
288 void function(void) {
289 json_auto_t *value = NULL;
290 value = json_string("foo");
291 /* json_decref(value) is automatically called. */
292 }
293
294 This feature is only available on GCC and Clang. So if your project
295 has a portability requirement for other compilers, you should avoid
296 this feature.
297
298 Additionally, as always, care should be taken when passing values to
299 functions that steal references.
300
301 True, False and Null
302 ====================
303
304 These three values are implemented as singletons, so the returned
305 pointers won't change between invocations of these functions.
306
307 .. function:: json_t *json_true(void)
308
309 .. refcounting:: new
310
311 Returns the JSON true value.
312
313 .. function:: json_t *json_false(void)
314
315 .. refcounting:: new
316
317 Returns the JSON false value.
318
319 .. function:: json_t *json_boolean(val)
320
321 .. refcounting:: new
322
323 Returns JSON false if ``val`` is zero, and JSON true otherwise.
324 This is a macro, and equivalent to ``val ? json_true() :
325 json_false()``.
326
327 .. versionadded:: 2.4
328
329
330 .. function:: json_t *json_null(void)
331
332 .. refcounting:: new
333
334 Returns the JSON null value.
335
336
337 String
338 ======
339
340 Jansson uses UTF-8 as the character encoding. All JSON strings must be
341 valid UTF-8 (or ASCII, as it's a subset of UTF-8). All Unicode
342 codepoints U+0000 through U+10FFFF are allowed, but you must use
343 length-aware functions if you wish to embed null bytes in strings.
344
345 .. function:: json_t *json_string(const char *value)
346
347 .. refcounting:: new
348
349 Returns a new JSON string, or *NULL* on error. *value* must be a
350 valid null terminated UTF-8 encoded Unicode string.
351
352 .. function:: json_t *json_stringn(const char *value, size_t len)
353
354 .. refcounting:: new
355
356 Like :func:`json_string`, but with explicit length, so *value* may
357 contain null characters or not be null terminated.
358
359 .. versionadded:: 2.7
360
361 .. function:: json_t *json_string_nocheck(const char *value)
362
363 .. refcounting:: new
364
365 Like :func:`json_string`, but doesn't check that *value* is valid
366 UTF-8. Use this function only if you are certain that this really
367 is the case (e.g. you have already checked it by other means).
368
369 .. function:: json_t *json_stringn_nocheck(const char *value, size_t len)
370
371 .. refcounting:: new
372
373 Like :func:`json_string_nocheck`, but with explicit length, so
374 *value* may contain null characters or not be null terminated.
375
376 .. versionadded:: 2.7
377
378 .. function:: const char *json_string_value(const json_t *string)
379
380 Returns the associated value of *string* as a null terminated UTF-8
381 encoded string, or *NULL* if *string* is not a JSON string.
382
383 The returned value is read-only and must not be modified or freed by
384 the user. It is valid as long as *string* exists, i.e. as long as
385 its reference count has not dropped to zero.
386
387 .. function:: size_t json_string_length(const json_t *string)
388
389 Returns the length of *string* in its UTF-8 presentation, or zero
390 if *string* is not a JSON string.
391
392 .. versionadded:: 2.7
393
394 .. function:: int json_string_set(json_t *string, const char *value)
395
396 Sets the associated value of *string* to *value*. *value* must be a
397 valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
398 error.
399
400 .. function:: int json_string_setn(json_t *string, const char *value, size_t len)
401
402 Like :func:`json_string_set`, but with explicit length, so *value*
403 may contain null characters or not be null terminated.
404
405 .. versionadded:: 2.7
406
407 .. function:: int json_string_set_nocheck(json_t *string, const char *value)
408
409 Like :func:`json_string_set`, but doesn't check that *value* is
410 valid UTF-8. Use this function only if you are certain that this
411 really is the case (e.g. you have already checked it by other
412 means).
413
414 .. function:: int json_string_setn_nocheck(json_t *string, const char *value, size_t len)
415
416 Like :func:`json_string_set_nocheck`, but with explicit length,
417 so *value* may contain null characters or not be null terminated.
418
419 .. versionadded:: 2.7
420
421 .. function:: json_t *json_sprintf(const char *format, ...)
422 json_t *json_vsprintf(const char *format, va_list ap)
423
424 .. refcounting:: new
425
426 Construct a JSON string from a format string and varargs, just like
427 :func:`printf()`.
428
429 .. versionadded:: 2.11
430
431
432 Number
433 ======
434
435 The JSON specification only contains one numeric type, "number". The C
436 programming language has distinct types for integer and floating-point
437 numbers, so for practical reasons Jansson also has distinct types for
438 the two. They are called "integer" and "real", respectively. For more
439 information, see :ref:`rfc-conformance`.
440
441 .. type:: json_int_t
442
443 This is the C type that is used to store JSON integer values. It
444 represents the widest integer type available on your system. In
445 practice it's just a typedef of ``long long`` if your compiler
446 supports it, otherwise ``long``.
447
448 Usually, you can safely use plain ``int`` in place of
449 ``json_int_t``, and the implicit C integer conversion handles the
450 rest. Only when you know that you need the full 64-bit range, you
451 should use ``json_int_t`` explicitly.
452
453 ``JSON_INTEGER_IS_LONG_LONG``
454 This is a preprocessor variable that holds the value 1 if
455 :type:`json_int_t` is ``long long``, and 0 if it's ``long``. It
456 can be used as follows::
457
458 #if JSON_INTEGER_IS_LONG_LONG
459 /* Code specific for long long */
460 #else
461 /* Code specific for long */
462 #endif
463
464 ``JSON_INTEGER_FORMAT``
465 This is a macro that expands to a :func:`printf()` conversion
466 specifier that corresponds to :type:`json_int_t`, without the
467 leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro
468 is required because the actual type of :type:`json_int_t` can be
469 either ``long`` or ``long long``, and :func:`printf()` requires
470 different length modifiers for the two.
471
472 Example::
473
474 json_int_t x = 123123123;
475 printf("x is %" JSON_INTEGER_FORMAT "\n", x);
476
477
478 .. function:: json_t *json_integer(json_int_t value)
479
480 .. refcounting:: new
481
482 Returns a new JSON integer, or *NULL* on error.
483
484 .. function:: json_int_t json_integer_value(const json_t *integer)
485
486 Returns the associated value of *integer*, or 0 if *json* is not a
487 JSON integer.
488
489 .. function:: int json_integer_set(const json_t *integer, json_int_t value)
490
491 Sets the associated value of *integer* to *value*. Returns 0 on
492 success and -1 if *integer* is not a JSON integer.
493
494 .. function:: json_t *json_real(double value)
495
496 .. refcounting:: new
497
498 Returns a new JSON real, or *NULL* on error.
499
500 .. function:: double json_real_value(const json_t *real)
501
502 Returns the associated value of *real*, or 0.0 if *real* is not a
503 JSON real.
504
505 .. function:: int json_real_set(const json_t *real, double value)
506
507 Sets the associated value of *real* to *value*. Returns 0 on
508 success and -1 if *real* is not a JSON real.
509
510 .. function:: double json_number_value(const json_t *json)
511
512 Returns the associated value of the JSON integer or JSON real
513 *json*, cast to double regardless of the actual type. If *json* is
514 neither JSON real nor JSON integer, 0.0 is returned.
515
516
517 Array
518 =====
519
520 A JSON array is an ordered collection of other JSON values.
521
522 .. function:: json_t *json_array(void)
523
524 .. refcounting:: new
525
526 Returns a new JSON array, or *NULL* on error. Initially, the array
527 is empty.
528
529 .. function:: size_t json_array_size(const json_t *array)
530
531 Returns the number of elements in *array*, or 0 if *array* is NULL
532 or not a JSON array.
533
534 .. function:: json_t *json_array_get(const json_t *array, size_t index)
535
536 .. refcounting:: borrow
537
538 Returns the element in *array* at position *index*. The valid range
539 for *index* is from 0 to the return value of
540 :func:`json_array_size()` minus 1. If *array* is not a JSON array,
541 if *array* is *NULL*, or if *index* is out of range, *NULL* is
542 returned.
543
544 .. function:: int json_array_set(json_t *array, size_t index, json_t *value)
545
546 Replaces the element in *array* at position *index* with *value*.
547 The valid range for *index* is from 0 to the return value of
548 :func:`json_array_size()` minus 1. Returns 0 on success and -1 on
549 error.
550
551 .. function:: int json_array_set_new(json_t *array, size_t index, json_t *value)
552
553 Like :func:`json_array_set()` but steals the reference to *value*.
554 This is useful when *value* is newly created and not used after
555 the call.
556
557 .. function:: int json_array_append(json_t *array, json_t *value)
558
559 Appends *value* to the end of *array*, growing the size of *array*
560 by 1. Returns 0 on success and -1 on error.
561
562 .. function:: int json_array_append_new(json_t *array, json_t *value)
563
564 Like :func:`json_array_append()` but steals the reference to
565 *value*. This is useful when *value* is newly created and not used
566 after the call.
567
568 .. function:: int json_array_insert(json_t *array, size_t index, json_t *value)
569
570 Inserts *value* to *array* at position *index*, shifting the
571 elements at *index* and after it one position towards the end of
572 the array. Returns 0 on success and -1 on error.
573
574 .. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value)
575
576 Like :func:`json_array_insert()` but steals the reference to
577 *value*. This is useful when *value* is newly created and not used
578 after the call.
579
580 .. function:: int json_array_remove(json_t *array, size_t index)
581
582 Removes the element in *array* at position *index*, shifting the
583 elements after *index* one position towards the start of the array.
584 Returns 0 on success and -1 on error. The reference count of the
585 removed value is decremented.
586
587 .. function:: int json_array_clear(json_t *array)
588
589 Removes all elements from *array*. Returns 0 on success and -1 on
590 error. The reference count of all removed values are decremented.
591
592 .. function:: int json_array_extend(json_t *array, json_t *other_array)
593
594 Appends all elements in *other_array* to the end of *array*.
595 Returns 0 on success and -1 on error.
596
597 .. function:: void json_array_foreach(array, index, value)
598
599 Iterate over every element of ``array``, running the block
600 of code that follows each time with the proper values set to
601 variables ``index`` and ``value``, of types :type:`size_t` and
602 :type:`json_t` pointer respectively. Example::
603
604 /* array is a JSON array */
605 size_t index;
606 json_t *value;
607
608 json_array_foreach(array, index, value) {
609 /* block of code that uses index and value */
610 }
611
612 The items are returned in increasing index order.
613
614 This macro expands to an ordinary ``for`` statement upon
615 preprocessing, so its performance is equivalent to that of
616 hand-written code using the array access functions.
617 The main advantage of this macro is that it abstracts
618 away the complexity, and makes for more concise and readable code.
619
620 .. versionadded:: 2.5
621
622
623 Object
624 ======
625
626 A JSON object is a dictionary of key-value pairs, where the key is a
627 Unicode string and the value is any JSON value.
628
629 Even though null bytes are allowed in string values, they are not
630 allowed in object keys.
631
632 .. function:: json_t *json_object(void)
633
634 .. refcounting:: new
635
636 Returns a new JSON object, or *NULL* on error. Initially, the
637 object is empty.
638
639 .. function:: size_t json_object_size(const json_t *object)
640
641 Returns the number of elements in *object*, or 0 if *object* is not
642 a JSON object.
643
644 .. function:: json_t *json_object_get(const json_t *object, const char *key)
645
646 .. refcounting:: borrow
647
648 Get a value corresponding to *key* from *object*. Returns *NULL* if
649 *key* is not found and on error.
650
651 .. function:: json_t *json_object_getn(const json_t *object, const char *key, size_t key_len)
652
653 .. refcounting:: borrow
654
655 Like :func:`json_object_get`, but give the fixed-length *key* with length *key_len*.
656 See :ref:`fixed_length_keys` for details.
657
658 .. versionadded:: 2.14
659
660 .. function:: int json_object_set(json_t *object, const char *key, json_t *value)
661
662 Set the value of *key* to *value* in *object*. *key* must be a
663 valid null terminated UTF-8 encoded Unicode string. If there
664 already is a value for *key*, it is replaced by the new value.
665 Returns 0 on success and -1 on error.
666
667 .. function:: int json_object_setn(json_t *object, const char *key, size_t key_len, json_t *value)
668
669 Like :func:`json_object_set`, but give the fixed-length *key* with length *key_len*.
670 See :ref:`fixed_length_keys` for details.
671
672 .. versionadded:: 2.14
673
674 .. function:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value)
675
676 Like :func:`json_object_set`, but doesn't check that *key* is
677 valid UTF-8. Use this function only if you are certain that this
678 really is the case (e.g. you have already checked it by other
679 means).
680
681 .. function:: int json_object_setn_nocheck(json_t *object, const char *key, size_t key_len, json_t *value)
682
683 Like :func:`json_object_set_nocheck`, but give the fixed-length *key* with length *key_len*.
684 See :ref:`fixed_length_keys` for details.
685
686 .. versionadded:: 2.14
687
688 .. function:: int json_object_set_new(json_t *object, const char *key, json_t *value)
689
690 Like :func:`json_object_set()` but steals the reference to
691 *value*. This is useful when *value* is newly created and not used
692 after the call.
693
694 .. function:: int json_object_setn_new(json_t *object, const char *key, size_t key_len, json_t *value)
695
696 Like :func:`json_object_set_new`, but give the fixed-length *key* with length *key_len*.
697 See :ref:`fixed_length_keys` for details.
698
699 .. versionadded:: 2.14
700
701 .. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
702
703 Like :func:`json_object_set_new`, but doesn't check that *key* is
704 valid UTF-8. Use this function only if you are certain that this
705 really is the case (e.g. you have already checked it by other
706 means).
707
708 .. function:: int json_object_setn_new_nocheck(json_t *object, const char *key, size_t key_len, json_t *value)
709
710 Like :func:`json_object_set_new_nocheck`, but give the fixed-length *key* with length *key_len*.
711 See :ref:`fixed_length_keys` for details.
712
713 .. versionadded:: 2.14
714
715 .. function:: int json_object_del(json_t *object, const char *key)
716
717 Delete *key* from *object* if it exists. Returns 0 on success, or
718 -1 if *key* was not found. The reference count of the removed value
719 is decremented.
720
721 .. function:: int json_object_deln(json_t *object, const char *key, size_t key_len)
722
723 Like :func:`json_object_del`, but give the fixed-length *key* with length *key_len*.
724 See :ref:`fixed_length_keys` for details.
725
726 .. versionadded:: 2.14
727
728 .. function:: int json_object_clear(json_t *object)
729
730 Remove all elements from *object*. Returns 0 on success and -1 if
731 *object* is not a JSON object. The reference count of all removed
732 values are decremented.
733
734 .. function:: int json_object_update(json_t *object, json_t *other)
735
736 Update *object* with the key-value pairs from *other*, overwriting
737 existing keys. Returns 0 on success or -1 on error.
738
739 .. function:: int json_object_update_existing(json_t *object, json_t *other)
740
741 Like :func:`json_object_update()`, but only the values of existing
742 keys are updated. No new keys are created. Returns 0 on success or
743 -1 on error.
744
745 .. versionadded:: 2.3
746
747 .. function:: int json_object_update_missing(json_t *object, json_t *other)
748
749 Like :func:`json_object_update()`, but only new keys are created.
750 The value of any existing key is not changed. Returns 0 on success
751 or -1 on error.
752
753 .. versionadded:: 2.3
754
755 .. function:: int json_object_update_new(json_t *object, json_t *other)
756
757 Like :func:`json_object_update()`, but steals the reference to
758 *other*. This is useful when *other* is newly created and not used
759 after the call.
760
761 .. function:: int json_object_update_existing_new(json_t *object, json_t *other)
762
763 Like :func:`json_object_update_new()`, but only the values of existing
764 keys are updated. No new keys are created. Returns 0 on success or
765 -1 on error.
766
767 .. function:: int json_object_update_missing_new(json_t *object, json_t *other)
768
769 Like :func:`json_object_update_new()`, but only new keys are created.
770 The value of any existing key is not changed. Returns 0 on success
771 or -1 on error.
772
773 .. function:: int json_object_update_recursive(json_t *object, json_t *other)
774
775 Like :func:`json_object_update()`, but object values in *other* are
776 recursively merged with the corresponding values in *object* if they are also
777 objects, instead of overwriting them. Returns 0 on success or -1 on error.
778
779 .. function:: void json_object_foreach(object, key, value)
780
781 Iterate over every key-value pair of ``object``, running the block
782 of code that follows each time with the proper values set to
783 variables ``key`` and ``value``, of types ``const char *`` and
784 :type:`json_t` pointer respectively. Example::
785
786 /* obj is a JSON object */
787 const char *key;
788 json_t *value;
789
790 json_object_foreach(obj, key, value) {
791 /* block of code that uses key and value */
792 }
793
794 The items are returned in the order they were inserted to the
795 object.
796
797 **Note:** It's not safe to call ``json_object_del(object, key)`` or ``json_object_deln(object, key, key_len)``
798 during iteration. If you need to, use
799 :func:`json_object_foreach_safe` instead.
800
801 This macro expands to an ordinary ``for`` statement upon
802 preprocessing, so its performance is equivalent to that of
803 hand-written iteration code using the object iteration protocol
804 (see below). The main advantage of this macro is that it abstracts
805 away the complexity behind iteration, and makes for more concise and
806 readable code.
807
808 .. versionadded:: 2.3
809
810
811 .. function:: void json_object_foreach_safe(object, tmp, key, value)
812
813 Like :func:`json_object_foreach()`, but it's safe to call
814 ``json_object_del(object, key)`` or ``json_object_deln(object, key, key_len)`` during iteration.
815 You need to pass an extra ``void *`` parameter ``tmp`` that is used for temporary storage.
816
817 .. versionadded:: 2.8
818
819 .. function:: void json_object_keylen_foreach(object, key, key_len, value)
820
821 Like :c:func:`json_object_foreach`, but in *key_len* stored length of the *key*.
822 Example::
823
824 /* obj is a JSON object */
825 const char *key;
826 json_t *value;
827 size_t len;
828
829 json_object_keylen_foreach(obj, key, len, value) {
830 printf("got key %s with length %zu\n", key, len);
831 }
832
833 **Note:** It's not safe to call ``json_object_deln(object, key, key_len)``
834 during iteration. If you need to, use
835 :func:`json_object_keylen_foreach_safe` instead.
836
837 .. versionadded:: 2.14
838
839
840 .. function:: void json_object_keylen_foreach_safe(object, tmp, key, key_len, value)
841
842 Like :func:`json_object_keylen_foreach()`, but it's safe to call
843 ``json_object_deln(object, key, key_len)`` during iteration.
844 You need to pass an extra ``void *`` parameter ``tmp`` that is used for temporary storage.
845
846 .. versionadded:: 2.14
847
848 The following functions can be used to iterate through all key-value
849 pairs in an object. The items are returned in the order they were
850 inserted to the object.
851
852 .. function:: void *json_object_iter(json_t *object)
853
854 Returns an opaque iterator which can be used to iterate over all
855 key-value pairs in *object*, or *NULL* if *object* is empty.
856
857 .. function:: void *json_object_iter_at(json_t *object, const char *key)
858
859 Like :func:`json_object_iter()`, but returns an iterator to the
860 key-value pair in *object* whose key is equal to *key*, or NULL if
861 *key* is not found in *object*. Iterating forward to the end of
862 *object* only yields all key-value pairs of the object if *key*
863 happens to be the first key in the underlying hash table.
864
865 .. function:: void *json_object_iter_next(json_t *object, void *iter)
866
867 Returns an iterator pointing to the next key-value pair in *object*
868 after *iter*, or *NULL* if the whole object has been iterated
869 through.
870
871 .. function:: const char *json_object_iter_key(void *iter)
872
873 Extract the associated key from *iter*.
874
875 .. function:: size_t json_object_iter_key_len(void *iter)
876
877 Extract the associated key length from *iter*.
878
879 .. versionadded:: 2.14
880
881 .. function:: json_t *json_object_iter_value(void *iter)
882
883 .. refcounting:: borrow
884
885 Extract the associated value from *iter*.
886
887 .. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value)
888
889 Set the value of the key-value pair in *object*, that is pointed to
890 by *iter*, to *value*.
891
892 .. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
893
894 Like :func:`json_object_iter_set()`, but steals the reference to
895 *value*. This is useful when *value* is newly created and not used
896 after the call.
897
898 .. function:: void *json_object_key_to_iter(const char *key)
899
900 Like :func:`json_object_iter_at()`, but much faster. Only works for
901 values returned by :func:`json_object_iter_key()`. Using other keys
902 will lead to segfaults. This function is used internally to
903 implement :func:`json_object_foreach`. Example::
904
905 /* obj is a JSON object */
906 const char *key;
907 json_t *value;
908
909 void *iter = json_object_iter(obj);
910 while(iter)
911 {
912 key = json_object_iter_key(iter);
913 value = json_object_iter_value(iter);
914 /* use key and value ... */
915 iter = json_object_iter_next(obj, iter);
916 }
917
918 .. versionadded:: 2.3
919
920 .. function:: void json_object_seed(size_t seed)
921
922 Seed the hash function used in Jansson's hashtable implementation.
923 The seed is used to randomize the hash function so that an
924 attacker cannot control its output.
925
926 If *seed* is 0, Jansson generates the seed itself by reading
927 random data from the operating system's entropy sources. If no
928 entropy sources are available, falls back to using a combination
929 of the current timestamp (with microsecond precision if possible)
930 and the process ID.
931
932 If called at all, this function must be called before any calls to
933 :func:`json_object()`, either explicit or implicit. If this
934 function is not called by the user, the first call to
935 :func:`json_object()` (either explicit or implicit) seeds the hash
936 function. See :ref:`thread-safety` for notes on thread safety.
937
938 If repeatable results are required, for e.g. unit tests, the hash
939 function can be "unrandomized" by calling :func:`json_object_seed`
940 with a constant value on program startup, e.g.
941 ``json_object_seed(1)``.
942
943 .. versionadded:: 2.6
944
945
946 Error reporting
947 ===============
948
949 Jansson uses a single struct type to pass error information to the
950 user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
951 :ref:`apiref-unpack` for functions that pass error information using
952 this struct.
953
954 .. type:: json_error_t
955
956 .. member:: char text[]
957
958 The error message (in UTF-8), or an empty string if a message is
959 not available.
960
961 The last byte of this array contains a numeric error code. Use
962 :func:`json_error_code()` to extract this code.
963
964 .. member:: char source[]
965
966 Source of the error. This can be (a part of) the file name or a
967 special identifier in angle brackets (e.g. ``<string>``).
968
969 .. member:: int line
970
971 The line number on which the error occurred.
972
973 .. member:: int column
974
975 The column on which the error occurred. Note that this is the
976 *character column*, not the byte column, i.e. a multibyte UTF-8
977 character counts as one column.
978
979 .. member:: int position
980
981 The position in bytes from the start of the input. This is
982 useful for debugging Unicode encoding problems.
983
984 The normal use of :type:`json_error_t` is to allocate it on the stack,
985 and pass a pointer to a function. Example::
986
987 int main() {
988 json_t *json;
989 json_error_t error;
990
991 json = json_load_file("/path/to/file.json", 0, &error);
992 if(!json) {
993 /* the error variable contains error information */
994 }
995 ...
996 }
997
998 Also note that if the call succeeded (``json != NULL`` in the above
999 example), the contents of ``error`` are generally left unspecified.
1000 The decoding functions write to the ``position`` member also on
1001 success. See :ref:`apiref-decoding` for more info.
1002
1003 All functions also accept *NULL* as the :type:`json_error_t` pointer,
1004 in which case no error information is returned to the caller.
1005
1006 .. c:enum:: json_error_code
1007
1008 An enumeration containing numeric error codes. The following errors are
1009 currently defined:
1010
1011 ``json_error_unknown``
1012
1013 Unknown error. This should only be returned for non-errorneous
1014 :type:`json_error_t` structures.
1015
1016 ``json_error_out_of_memory``
1017
1018 The library couldn’t allocate any heap memory.
1019
1020 ``json_error_stack_overflow``
1021
1022 Nesting too deep.
1023
1024 ``json_error_cannot_open_file``
1025
1026 Couldn’t open input file.
1027
1028 ``json_error_invalid_argument``
1029
1030 A function argument was invalid.
1031
1032 ``json_error_invalid_utf8``
1033
1034 The input string isn’t valid UTF-8.
1035
1036 ``json_error_premature_end_of_input``
1037
1038 The input ended in the middle of a JSON value.
1039
1040 ``json_error_end_of_input_expected``
1041
1042 There was some text after the end of a JSON value. See the
1043 ``JSON_DISABLE_EOF_CHECK`` flag.
1044
1045 ``json_error_invalid_syntax``
1046
1047 JSON syntax error.
1048
1049 ``json_error_invalid_format``
1050
1051 Invalid format string for packing or unpacking.
1052
1053 ``json_error_wrong_type``
1054
1055 When packing or unpacking, the actual type of a value differed from the
1056 one specified in the format string.
1057
1058 ``json_error_null_character``
1059
1060 A null character was detected in a JSON string. See the
1061 ``JSON_ALLOW_NUL`` flag.
1062
1063 ``json_error_null_value``
1064
1065 When packing or unpacking, some key or value was ``NULL``.
1066
1067 ``json_error_null_byte_in_key``
1068
1069 An object key would contain a null byte. Jansson can’t represent such
1070 keys; see :ref:`rfc-conformance`.
1071
1072 ``json_error_duplicate_key``
1073
1074 Duplicate key in object. See the ``JSON_REJECT_DUPLICATES`` flag.
1075
1076 ``json_error_numeric_overflow``
1077
1078 When converting a JSON number to a C numeric type, a numeric overflow
1079 was detected.
1080
1081 ``json_error_item_not_found``
1082
1083 Key in object not found.
1084
1085 ``json_error_index_out_of_range``
1086
1087 Array index is out of range.
1088
1089 .. versionadded:: 2.11
1090
1091 .. function:: enum json_error_code json_error_code(const json_error_t *error)
1092
1093 Returns the error code embedded in ``error->text``.
1094
1095 .. versionadded:: 2.11
1096
1097
1098 Encoding
1099 ========
1100
1101 This section describes the functions that can be used to encode
1102 values to JSON. By default, only objects and arrays can be encoded
1103 directly, since they are the only valid *root* values of a JSON text.
1104 To encode any JSON value, use the ``JSON_ENCODE_ANY`` flag (see
1105 below).
1106
1107 By default, the output has no newlines, and spaces are used between
1108 array and object elements for a readable output. This behavior can be
1109 altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags
1110 described below. A newline is never appended to the end of the encoded
1111 JSON data.
1112
1113 Each function takes a *flags* parameter that controls some aspects of
1114 how the data is encoded. Its default value is 0. The following macros
1115 can be ORed together to obtain *flags*.
1116
1117 ``JSON_INDENT(n)``
1118 Pretty-print the result, using newlines between array and object
1119 items, and indenting with *n* spaces. The valid range for *n* is
1120 between 0 and 31 (inclusive), other values result in an undefined
1121 output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are
1122 inserted between array and object items.
1123
1124 The ``JSON_MAX_INDENT`` constant defines the maximum indentation
1125 that can be used, and its value is 31.
1126
1127 .. versionchanged:: 2.7
1128 Added ``JSON_MAX_INDENT``.
1129
1130 ``JSON_COMPACT``
1131 This flag enables a compact representation, i.e. sets the separator
1132 between array and object items to ``","`` and between object keys
1133 and values to ``":"``. Without this flag, the corresponding
1134 separators are ``", "`` and ``": "`` for more readable output.
1135
1136 ``JSON_ENSURE_ASCII``
1137 If this flag is used, the output is guaranteed to consist only of
1138 ASCII characters. This is achieved by escaping all Unicode
1139 characters outside the ASCII range.
1140
1141 ``JSON_SORT_KEYS``
1142 If this flag is used, all the objects in output are sorted by key.
1143 This is useful e.g. if two JSON texts are diffed or visually
1144 compared.
1145
1146 ``JSON_PRESERVE_ORDER``
1147 **Deprecated since version 2.8:** Order of object keys
1148 is always preserved.
1149
1150 Prior to version 2.8: If this flag is used, object keys in the
1151 output are sorted into the same order in which they were first
1152 inserted to the object. For example, decoding a JSON text and then
1153 encoding with this flag preserves the order of object keys.
1154
1155 ``JSON_ENCODE_ANY``
1156 Specifying this flag makes it possible to encode any JSON value on
1157 its own. Without it, only objects and arrays can be passed as the
1158 *json* value to the encoding functions.
1159
1160 **Note:** Encoding any value may be useful in some scenarios, but
1161 it's generally discouraged as it violates strict compatibility with
1162 :rfc:`4627`. If you use this flag, don't expect interoperability
1163 with other JSON systems.
1164
1165 .. versionadded:: 2.1
1166
1167 ``JSON_ESCAPE_SLASH``
1168 Escape the ``/`` characters in strings with ``\/``.
1169
1170 .. versionadded:: 2.4
1171
1172 ``JSON_REAL_PRECISION(n)``
1173 Output all real numbers with at most *n* digits of precision. The
1174 valid range for *n* is between 0 and 31 (inclusive), and other
1175 values result in an undefined behavior.
1176
1177 By default, the precision is 17, to correctly and losslessly encode
1178 all IEEE 754 double precision floating point numbers.
1179
1180 .. versionadded:: 2.7
1181
1182 ``JSON_EMBED``
1183 If this flag is used, the opening and closing characters of the top-level
1184 array ('[', ']') or object ('{', '}') are omitted during encoding. This
1185 flag is useful when concatenating multiple arrays or objects into a stream.
1186
1187 .. versionadded:: 2.10
1188
1189 These functions output UTF-8:
1190
1191 .. function:: char *json_dumps(const json_t *json, size_t flags)
1192
1193 Returns the JSON representation of *json* as a string, or *NULL* on
1194 error. *flags* is described above. The return value must be freed
1195 by the caller using :func:`free()`. Note that if you have called
1196 :func:`json_set_alloc_funcs()` to override :func:`free()`, you should
1197 call your custom free function instead to free the return value.
1198
1199 .. function:: size_t json_dumpb(const json_t *json, char *buffer, size_t size, size_t flags)
1200
1201 Writes the JSON representation of *json* to the *buffer* of
1202 *size* bytes. Returns the number of bytes that would be written
1203 or 0 on error. *flags* is described above. *buffer* is not
1204 null-terminated.
1205
1206 This function never writes more than *size* bytes. If the return
1207 value is greater than *size*, the contents of the *buffer* are
1208 undefined. This behavior enables you to specify a NULL *buffer*
1209 to determine the length of the encoding. For example::
1210
1211 size_t size = json_dumpb(json, NULL, 0, 0);
1212 if (size == 0)
1213 return -1;
1214
1215 char *buf = alloca(size);
1216
1217 size = json_dumpb(json, buf, size, 0);
1218
1219 .. versionadded:: 2.10
1220
1221 .. function:: int json_dumpf(const json_t *json, FILE *output, size_t flags)
1222
1223 Write the JSON representation of *json* to the stream *output*.
1224 *flags* is described above. Returns 0 on success and -1 on error.
1225 If an error occurs, something may have already been written to
1226 *output*. In this case, the output is undefined and most likely not
1227 valid JSON.
1228
1229 .. function:: int json_dumpfd(const json_t *json, int output, size_t flags)
1230
1231 Write the JSON representation of *json* to the stream *output*.
1232 *flags* is described above. Returns 0 on success and -1 on error.
1233 If an error occurs, something may have already been written to
1234 *output*. In this case, the output is undefined and most likely not
1235 valid JSON.
1236
1237 It is important to note that this function can only succeed on stream
1238 file descriptors (such as SOCK_STREAM). Using this function on a
1239 non-stream file descriptor will result in undefined behavior. For
1240 non-stream file descriptors, see instead :func:`json_dumpb()`.
1241
1242 This function requires POSIX and fails on all non-POSIX systems.
1243
1244 .. versionadded:: 2.10
1245
1246 .. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
1247
1248 Write the JSON representation of *json* to the file *path*. If
1249 *path* already exists, it is overwritten. *flags* is described
1250 above. Returns 0 on success and -1 on error.
1251
1252 .. type:: json_dump_callback_t
1253
1254 A typedef for a function that's called by
1255 :func:`json_dump_callback()`::
1256
1257 typedef int (*json_dump_callback_t)(const char *buffer, size_t size, void *data);
1258
1259 *buffer* points to a buffer containing a chunk of output, *size* is
1260 the length of the buffer, and *data* is the corresponding
1261 :func:`json_dump_callback()` argument passed through.
1262
1263 *buffer* is guaranteed to be a valid UTF-8 string (i.e. multi-byte
1264 code unit sequences are preserved). *buffer* never contains
1265 embedded null bytes.
1266
1267 On error, the function should return -1 to stop the encoding
1268 process. On success, it should return 0.
1269
1270 .. versionadded:: 2.2
1271
1272 .. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags)
1273
1274 Call *callback* repeatedly, passing a chunk of the JSON
1275 representation of *json* each time. *flags* is described above.
1276 Returns 0 on success and -1 on error.
1277
1278 .. versionadded:: 2.2
1279
1280
1281 .. _apiref-decoding:
1282
1283 Decoding
1284 ========
1285
1286 This section describes the functions that can be used to decode JSON
1287 text to the Jansson representation of JSON data. The JSON
1288 specification requires that a JSON text is either a serialized array
1289 or object, and this requirement is also enforced with the following
1290 functions. In other words, the top level value in the JSON text being
1291 decoded must be either array or object. To decode any JSON value, use
1292 the ``JSON_DECODE_ANY`` flag (see below).
1293
1294 See :ref:`rfc-conformance` for a discussion on Jansson's conformance
1295 to the JSON specification. It explains many design decisions that
1296 affect especially the behavior of the decoder.
1297
1298 Each function takes a *flags* parameter that can be used to control
1299 the behavior of the decoder. Its default value is 0. The following
1300 macros can be ORed together to obtain *flags*.
1301
1302 ``JSON_REJECT_DUPLICATES``
1303 Issue a decoding error if any JSON object in the input text
1304 contains duplicate keys. Without this flag, the value of the last
1305 occurrence of each key ends up in the result. Key equivalence is
1306 checked byte-by-byte, without special Unicode comparison
1307 algorithms.
1308
1309 .. versionadded:: 2.1
1310
1311 ``JSON_DECODE_ANY``
1312 By default, the decoder expects an array or object as the input.
1313 With this flag enabled, the decoder accepts any valid JSON value.
1314
1315 **Note:** Decoding any value may be useful in some scenarios, but
1316 it's generally discouraged as it violates strict compatibility with
1317 :rfc:`4627`. If you use this flag, don't expect interoperability
1318 with other JSON systems.
1319
1320 .. versionadded:: 2.3
1321
1322 ``JSON_DISABLE_EOF_CHECK``
1323 By default, the decoder expects that its whole input constitutes a
1324 valid JSON text, and issues an error if there's extra data after
1325 the otherwise valid JSON input. With this flag enabled, the decoder
1326 stops after decoding a valid JSON array or object, and thus allows
1327 extra data after the JSON text.
1328
1329 Normally, reading will stop when the last ``]`` or ``}`` in the
1330 JSON input is encountered. If both ``JSON_DISABLE_EOF_CHECK`` and
1331 ``JSON_DECODE_ANY`` flags are used, the decoder may read one extra
1332 UTF-8 code unit (up to 4 bytes of input). For example, decoding
1333 ``4true`` correctly decodes the integer 4, but also reads the
1334 ``t``. For this reason, if reading multiple consecutive values that
1335 are not arrays or objects, they should be separated by at least one
1336 whitespace character.
1337
1338 .. versionadded:: 2.1
1339
1340 ``JSON_DECODE_INT_AS_REAL``
1341 JSON defines only one number type. Jansson distinguishes between
1342 ints and reals. For more information see :ref:`real-vs-integer`.
1343 With this flag enabled the decoder interprets all numbers as real
1344 values. Integers that do not have an exact double representation
1345 will silently result in a loss of precision. Integers that cause
1346 a double overflow will cause an error.
1347
1348 .. versionadded:: 2.5
1349
1350 ``JSON_ALLOW_NUL``
1351 Allow ``\u0000`` escape inside string values. This is a safety
1352 measure; If you know your input can contain null bytes, use this
1353 flag. If you don't use this flag, you don't have to worry about null
1354 bytes inside strings unless you explicitly create themselves by
1355 using e.g. :func:`json_stringn()` or ``s#`` format specifier for
1356 :func:`json_pack()`.
1357
1358 Object keys cannot have embedded null bytes even if this flag is
1359 used.
1360
1361 .. versionadded:: 2.6
1362
1363 Each function also takes an optional :type:`json_error_t` parameter
1364 that is filled with error information if decoding fails. It's also
1365 updated on success; the number of bytes of input read is written to
1366 its ``position`` field. This is especially useful when using
1367 ``JSON_DISABLE_EOF_CHECK`` to read multiple consecutive JSON texts.
1368
1369 .. versionadded:: 2.3
1370 Number of bytes of input read is written to the ``position`` field
1371 of the :type:`json_error_t` structure.
1372
1373 If no error or position information is needed, you can pass *NULL*.
1374
1375 .. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
1376
1377 .. refcounting:: new
1378
1379 Decodes the JSON string *input* and returns the array or object it
1380 contains, or *NULL* on error, in which case *error* is filled with
1381 information about the error. *flags* is described above.
1382
1383 .. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)
1384
1385 .. refcounting:: new
1386
1387 Decodes the JSON string *buffer*, whose length is *buflen*, and
1388 returns the array or object it contains, or *NULL* on error, in
1389 which case *error* is filled with information about the error. This
1390 is similar to :func:`json_loads()` except that the string doesn't
1391 need to be null-terminated. *flags* is described above.
1392
1393 .. versionadded:: 2.1
1394
1395 .. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
1396
1397 .. refcounting:: new
1398
1399 Decodes the JSON text in stream *input* and returns the array or
1400 object it contains, or *NULL* on error, in which case *error* is
1401 filled with information about the error. *flags* is described
1402 above.
1403
1404 This function will start reading the input from whatever position
1405 the input file was in, without attempting to seek first. If an error
1406 occurs, the file position will be left indeterminate. On success,
1407 the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK``
1408 flag was used. In this case, the file position will be at the first
1409 character after the last ``]`` or ``}`` in the JSON input. This
1410 allows calling :func:`json_loadf()` on the same ``FILE`` object
1411 multiple times, if the input consists of consecutive JSON texts,
1412 possibly separated by whitespace.
1413
1414 .. function:: json_t *json_loadfd(int input, size_t flags, json_error_t *error)
1415
1416 .. refcounting:: new
1417
1418 Decodes the JSON text in stream *input* and returns the array or
1419 object it contains, or *NULL* on error, in which case *error* is
1420 filled with information about the error. *flags* is described
1421 above.
1422
1423 This function will start reading the input from whatever position
1424 the input file descriptor was in, without attempting to seek first.
1425 If an error occurs, the file position will be left indeterminate.
1426 On success, the file position will be at EOF, unless
1427 ``JSON_DISABLE_EOF_CHECK`` flag was used. In this case, the file
1428 descriptor's position will be at the first character after the last
1429 ``]`` or ``}`` in the JSON input. This allows calling
1430 :func:`json_loadfd()` on the same file descriptor multiple times,
1431 if the input consists of consecutive JSON texts, possibly separated
1432 by whitespace.
1433
1434 It is important to note that this function can only succeed on stream
1435 file descriptors (such as SOCK_STREAM). Using this function on a
1436 non-stream file descriptor will result in undefined behavior. For
1437 non-stream file descriptors, see instead :func:`json_loadb()`. In
1438 addition, please note that this function cannot be used on non-blocking
1439 file descriptors (such as a non-blocking socket). Using this function
1440 on non-blocking file descriptors has a high risk of data loss because
1441 it does not support resuming.
1442
1443 This function requires POSIX and fails on all non-POSIX systems.
1444
1445 .. versionadded:: 2.10
1446
1447 .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
1448
1449 .. refcounting:: new
1450
1451 Decodes the JSON text in file *path* and returns the array or
1452 object it contains, or *NULL* on error, in which case *error* is
1453 filled with information about the error. *flags* is described
1454 above.
1455
1456 .. type:: json_load_callback_t
1457
1458 A typedef for a function that's called by
1459 :func:`json_load_callback()` to read a chunk of input data::
1460
1461 typedef size_t (*json_load_callback_t)(void *buffer, size_t buflen, void *data);
1462
1463 *buffer* points to a buffer of *buflen* bytes, and *data* is the
1464 corresponding :func:`json_load_callback()` argument passed through.
1465
1466 On success, the function should write at most *buflen* bytes to
1467 *buffer*, and return the number of bytes written; a returned value
1468 of 0 indicates that no data was produced and that the end of file
1469 has been reached. On error, the function should return
1470 ``(size_t)-1`` to abort the decoding process.
1471
1472 In UTF-8, some code points are encoded as multi-byte sequences. The
1473 callback function doesn't need to worry about this, as Jansson
1474 handles it at a higher level. For example, you can safely read a
1475 fixed number of bytes from a network connection without having to
1476 care about code unit sequences broken apart by the chunk
1477 boundaries.
1478
1479 .. versionadded:: 2.4
1480
1481 .. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error)
1482
1483 .. refcounting:: new
1484
1485 Decodes the JSON text produced by repeated calls to *callback*, and
1486 returns the array or object it contains, or *NULL* on error, in
1487 which case *error* is filled with information about the error.
1488 *data* is passed through to *callback* on each call. *flags* is
1489 described above.
1490
1491 .. versionadded:: 2.4
1492
1493
1494 .. _apiref-pack:
1495
1496 Building Values
1497 ===============
1498
1499 This section describes functions that help to create, or *pack*,
1500 complex JSON values, especially nested objects and arrays. Value
1501 building is based on a *format string* that is used to tell the
1502 functions about the expected arguments.
1503
1504 For example, the format string ``"i"`` specifies a single integer
1505 value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s,
1506 b]"`` specifies an array value with two strings and a boolean as its
1507 items::
1508
1509 /* Create the JSON integer 42 */
1510 json_pack("i", 42);
1511
1512 /* Create the JSON array ["foo", "bar", true] */
1513 json_pack("[ssb]", "foo", "bar", 1);
1514
1515 Here's the full list of format specifiers. The type in parentheses
1516 denotes the resulting JSON type, and the type in brackets (if any)
1517 denotes the C type that is expected as the corresponding argument or
1518 arguments.
1519
1520 ``s`` (string) [const char \*]
1521 Convert a null terminated UTF-8 string to a JSON string.
1522
1523 ``s?`` (string) [const char \*]
1524 Like ``s``, but if the argument is *NULL*, output a JSON null
1525 value.
1526
1527 .. versionadded:: 2.8
1528
1529 ``s*`` (string) [const char \*]
1530 Like ``s``, but if the argument is *NULL*, do not output any value.
1531 This format can only be used inside an object or an array. If used
1532 inside an object, the corresponding key is additionally suppressed
1533 when the value is omitted. See below for an example.
1534
1535 .. versionadded:: 2.11
1536
1537 ``s#`` (string) [const char \*, int]
1538 Convert a UTF-8 buffer of a given length to a JSON string.
1539
1540 .. versionadded:: 2.5
1541
1542 ``s%`` (string) [const char \*, size_t]
1543 Like ``s#`` but the length argument is of type :type:`size_t`.
1544
1545 .. versionadded:: 2.6
1546
1547 ``+`` [const char \*]
1548 Like ``s``, but concatenate to the previous string. Only valid
1549 after ``s``, ``s#``, ``+`` or ``+#``.
1550
1551 .. versionadded:: 2.5
1552
1553 ``+#`` [const char \*, int]
1554 Like ``s#``, but concatenate to the previous string. Only valid
1555 after ``s``, ``s#``, ``+`` or ``+#``.
1556
1557 .. versionadded:: 2.5
1558
1559 ``+%`` (string) [const char \*, size_t]
1560 Like ``+#`` but the length argument is of type :type:`size_t`.
1561
1562 .. versionadded:: 2.6
1563
1564 ``n`` (null)
1565 Output a JSON null value. No argument is consumed.
1566
1567 ``b`` (boolean) [int]
1568 Convert a C ``int`` to JSON boolean value. Zero is converted
1569 to ``false`` and non-zero to ``true``.
1570
1571 ``i`` (integer) [int]
1572 Convert a C ``int`` to JSON integer.
1573
1574 ``I`` (integer) [json_int_t]
1575 Convert a C :type:`json_int_t` to JSON integer.
1576
1577 ``f`` (real) [double]
1578 Convert a C ``double`` to JSON real.
1579
1580 ``o`` (any value) [json_t \*]
1581 Output any given JSON value as-is. If the value is added to an
1582 array or object, the reference to the value passed to ``o`` is
1583 stolen by the container.
1584
1585 ``O`` (any value) [json_t \*]
1586 Like ``o``, but the argument's reference count is incremented.
1587 This is useful if you pack into an array or object and want to
1588 keep the reference for the JSON value consumed by ``O`` to
1589 yourself.
1590
1591 ``o?``, ``O?`` (any value) [json_t \*]
1592 Like ``o`` and ``O``, respectively, but if the argument is
1593 *NULL*, output a JSON null value.
1594
1595 .. versionadded:: 2.8
1596
1597 ``o*``, ``O*`` (any value) [json_t \*]
1598 Like ``o`` and ``O``, respectively, but if the argument is
1599 *NULL*, do not output any value. This format can only be used
1600 inside an object or an array. If used inside an object, the
1601 corresponding key is additionally suppressed. See below for an
1602 example.
1603
1604 .. versionadded:: 2.11
1605
1606 ``[fmt]`` (array)
1607 Build an array with contents from the inner format string. ``fmt``
1608 may contain objects and arrays, i.e. recursive value building is
1609 supported.
1610
1611 ``{fmt}`` (object)
1612 Build an object with contents from the inner format string
1613 ``fmt``. The first, third, etc. format specifier represent a key,
1614 and must be a string (see ``s``, ``s#``, ``+`` and ``+#`` above),
1615 as object keys are always strings. The second, fourth, etc. format
1616 specifier represent a value. Any value may be an object or array,
1617 i.e. recursive value building is supported.
1618
1619 Whitespace, ``:`` and ``,`` are ignored.
1620
1621 .. function:: json_t *json_pack(const char *fmt, ...)
1622
1623 .. refcounting:: new
1624
1625 Build a new JSON value according to the format string *fmt*. For
1626 each format specifier (except for ``{}[]n``), one or more arguments
1627 are consumed and used to build the corresponding value. Returns
1628 *NULL* on error.
1629
1630 .. function:: json_t *json_pack_ex(json_error_t *error, size_t flags, const char *fmt, ...)
1631 json_t *json_vpack_ex(json_error_t *error, size_t flags, const char *fmt, va_list ap)
1632
1633 .. refcounting:: new
1634
1635 Like :func:`json_pack()`, but an in the case of an error, an error
1636 message is written to *error*, if it's not *NULL*. The *flags*
1637 parameter is currently unused and should be set to 0.
1638
1639 As only the errors in format string (and out-of-memory errors) can
1640 be caught by the packer, these two functions are most likely only
1641 useful for debugging format strings.
1642
1643 More examples::
1644
1645 /* Build an empty JSON object */
1646 json_pack("{}");
1647
1648 /* Build the JSON object {"foo": 42, "bar": 7} */
1649 json_pack("{sisi}", "foo", 42, "bar", 7);
1650
1651 /* Like above, ':', ',' and whitespace are ignored */
1652 json_pack("{s:i, s:i}", "foo", 42, "bar", 7);
1653
1654 /* Build the JSON array [[1, 2], {"cool": true}] */
1655 json_pack("[[i,i],{s:b}]", 1, 2, "cool", 1);
1656
1657 /* Build a string from a non-null terminated buffer */
1658 char buffer[4] = {'t', 'e', 's', 't'};
1659 json_pack("s#", buffer, 4);
1660
1661 /* Concatenate strings together to build the JSON string "foobarbaz" */
1662 json_pack("s++", "foo", "bar", "baz");
1663
1664 /* Create an empty object or array when optional members are missing */
1665 json_pack("{s:s*,s:o*,s:O*}", "foo", NULL, "bar", NULL, "baz", NULL);
1666 json_pack("[s*,o*,O*]", NULL, NULL, NULL);
1667
1668
1669 .. _apiref-unpack:
1670
1671 Parsing and Validating Values
1672 =============================
1673
1674 This section describes functions that help to validate complex values
1675 and extract, or *unpack*, data from them. Like :ref:`building values
1676 <apiref-pack>`, this is also based on format strings.
1677
1678 While a JSON value is unpacked, the type specified in the format
1679 string is checked to match that of the JSON value. This is the
1680 validation part of the process. In addition to this, the unpacking
1681 functions can also check that all items of arrays and objects are
1682 unpacked. This check be enabled with the format specifier ``!`` or by
1683 using the flag ``JSON_STRICT``. See below for details.
1684
1685 Here's the full list of format specifiers. The type in parentheses
1686 denotes the JSON type, and the type in brackets (if any) denotes the C
1687 type whose address should be passed.
1688
1689 ``s`` (string) [const char \*]
1690 Convert a JSON string to a pointer to a null terminated UTF-8
1691 string. The resulting string is extracted by using
1692 :func:`json_string_value()` internally, so it exists as long as
1693 there are still references to the corresponding JSON string.
1694
1695 ``s%`` (string) [const char \*, size_t \*]
1696 Convert a JSON string to a pointer to a null terminated UTF-8
1697 string and its length.
1698
1699 .. versionadded:: 2.6
1700
1701 ``n`` (null)
1702 Expect a JSON null value. Nothing is extracted.
1703
1704 ``b`` (boolean) [int]
1705 Convert a JSON boolean value to a C ``int``, so that ``true``
1706 is converted to 1 and ``false`` to 0.
1707
1708 ``i`` (integer) [int]
1709 Convert a JSON integer to C ``int``.
1710
1711 ``I`` (integer) [json_int_t]
1712 Convert a JSON integer to C :type:`json_int_t`.
1713
1714 ``f`` (real) [double]
1715 Convert a JSON real to C ``double``.
1716
1717 ``F`` (integer or real) [double]
1718 Convert a JSON number (integer or real) to C ``double``.
1719
1720 ``o`` (any value) [json_t \*]
1721 Store a JSON value with no conversion to a :type:`json_t` pointer.
1722
1723 ``O`` (any value) [json_t \*]
1724 Like ``o``, but the JSON value's reference count is incremented.
1725 Storage pointers should be initialized NULL before using unpack.
1726 The caller is responsible for releasing all references incremented
1727 by unpack, even when an error occurs.
1728
1729 ``[fmt]`` (array)
1730 Convert each item in the JSON array according to the inner format
1731 string. ``fmt`` may contain objects and arrays, i.e. recursive
1732 value extraction is supported.
1733
1734 ``{fmt}`` (object)
1735 Convert each item in the JSON object according to the inner format
1736 string ``fmt``. The first, third, etc. format specifier represent
1737 a key, and must be ``s``. The corresponding argument to unpack
1738 functions is read as the object key. The second, fourth, etc.
1739 format specifier represent a value and is written to the address
1740 given as the corresponding argument. **Note** that every other
1741 argument is read from and every other is written to.
1742
1743 ``fmt`` may contain objects and arrays as values, i.e. recursive
1744 value extraction is supported.
1745
1746 .. versionadded:: 2.3
1747 Any ``s`` representing a key may be suffixed with a ``?`` to
1748 make the key optional. If the key is not found, nothing is
1749 extracted. See below for an example.
1750
1751 ``!``
1752 This special format specifier is used to enable the check that
1753 all object and array items are accessed, on a per-value basis. It
1754 must appear inside an array or object as the last format specifier
1755 before the closing bracket or brace. To enable the check globally,
1756 use the ``JSON_STRICT`` unpacking flag.
1757
1758 ``*``
1759 This special format specifier is the opposite of ``!``. If the
1760 ``JSON_STRICT`` flag is used, ``*`` can be used to disable the
1761 strict check on a per-value basis. It must appear inside an array
1762 or object as the last format specifier before the closing bracket
1763 or brace.
1764
1765 Whitespace, ``:`` and ``,`` are ignored.
1766
1767 .. function:: int json_unpack(json_t *root, const char *fmt, ...)
1768
1769 Validate and unpack the JSON value *root* according to the format
1770 string *fmt*. Returns 0 on success and -1 on failure.
1771
1772 .. function:: int json_unpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, ...)
1773 int json_vunpack_ex(json_t *root, json_error_t *error, size_t flags, const char *fmt, va_list ap)
1774
1775 Validate and unpack the JSON value *root* according to the format
1776 string *fmt*. If an error occurs and *error* is not *NULL*, write
1777 error information to *error*. *flags* can be used to control the
1778 behaviour of the unpacker, see below for the flags. Returns 0 on
1779 success and -1 on failure.
1780
1781 .. note::
1782
1783 The first argument of all unpack functions is ``json_t *root``
1784 instead of ``const json_t *root``, because the use of ``O`` format
1785 specifier causes the reference count of ``root``, or some value
1786 reachable from ``root``, to be increased. Furthermore, the ``o``
1787 format specifier may be used to extract a value as-is, which allows
1788 modifying the structure or contents of a value reachable from
1789 ``root``.
1790
1791 If the ``O`` and ``o`` format specifiers are not used, it's
1792 perfectly safe to cast a ``const json_t *`` variable to plain
1793 ``json_t *`` when used with these functions.
1794
1795 The following unpacking flags are available:
1796
1797 ``JSON_STRICT``
1798 Enable the extra validation step checking that all object and
1799 array items are unpacked. This is equivalent to appending the
1800 format specifier ``!`` to the end of every array and object in the
1801 format string.
1802
1803 ``JSON_VALIDATE_ONLY``
1804 Don't extract any data, just validate the JSON value against the
1805 given format string. Note that object keys must still be specified
1806 after the format string.
1807
1808 Examples::
1809
1810 /* root is the JSON integer 42 */
1811 int myint;
1812 json_unpack(root, "i", &myint);
1813 assert(myint == 42);
1814
1815 /* root is the JSON object {"foo": "bar", "quux": true} */
1816 const char *str;
1817 int boolean;
1818 json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean);
1819 assert(strcmp(str, "bar") == 0 && boolean == 1);
1820
1821 /* root is the JSON array [[1, 2], {"baz": null} */
1822 json_error_t error;
1823 json_unpack_ex(root, &error, JSON_VALIDATE_ONLY, "[[i,i], {s:n}]", "baz");
1824 /* returns 0 for validation success, nothing is extracted */
1825
1826 /* root is the JSON array [1, 2, 3, 4, 5] */
1827 int myint1, myint2;
1828 json_unpack(root, "[ii!]", &myint1, &myint2);
1829 /* returns -1 for failed validation */
1830
1831 /* root is an empty JSON object */
1832 int myint = 0, myint2 = 0, myint3 = 0;
1833 json_unpack(root, "{s?i, s?[ii]}",
1834 "foo", &myint1,
1835 "bar", &myint2, &myint3);
1836 /* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */
1837
1838
1839 Equality
1840 ========
1841
1842 Testing for equality of two JSON values cannot, in general, be
1843 achieved using the ``==`` operator. Equality in the terms of the
1844 ``==`` operator states that the two :type:`json_t` pointers point to
1845 exactly the same JSON value. However, two JSON values can be equal not
1846 only if they are exactly the same value, but also if they have equal
1847 "contents":
1848
1849 * Two integer or real values are equal if their contained numeric
1850 values are equal. An integer value is never equal to a real value,
1851 though.
1852
1853 * Two strings are equal if their contained UTF-8 strings are equal,
1854 byte by byte. Unicode comparison algorithms are not implemented.
1855
1856 * Two arrays are equal if they have the same number of elements and
1857 each element in the first array is equal to the corresponding
1858 element in the second array.
1859
1860 * Two objects are equal if they have exactly the same keys and the
1861 value for each key in the first object is equal to the value of the
1862 corresponding key in the second object.
1863
1864 * Two true, false or null values have no "contents", so they are equal
1865 if their types are equal. (Because these values are singletons,
1866 their equality can actually be tested with ``==``.)
1867
1868 .. function:: int json_equal(json_t *value1, json_t *value2)
1869
1870 Returns 1 if *value1* and *value2* are equal, as defined above.
1871 Returns 0 if they are unequal or one or both of the pointers are
1872 *NULL*.
1873
1874
1875 Copying
1876 =======
1877
1878 Because of reference counting, passing JSON values around doesn't
1879 require copying them. But sometimes a fresh copy of a JSON value is
1880 needed. For example, if you need to modify an array, but still want to
1881 use the original afterwards, you should take a copy of it first.
1882
1883 Jansson supports two kinds of copying: shallow and deep. There is a
1884 difference between these methods only for arrays and objects. Shallow
1885 copying only copies the first level value (array or object) and uses
1886 the same child values in the copied value. Deep copying makes a fresh
1887 copy of the child values, too. Moreover, all the child values are deep
1888 copied in a recursive fashion.
1889
1890 Copying objects preserves the insertion order of keys.
1891
1892 .. function:: json_t *json_copy(json_t *value)
1893
1894 .. refcounting:: new
1895
1896 Returns a shallow copy of *value*, or *NULL* on error.
1897
1898 .. function:: json_t *json_deep_copy(const json_t *value)
1899
1900 .. refcounting:: new
1901
1902 Returns a deep copy of *value*, or *NULL* on error.
1903
1904
1905 .. _apiref-custom-memory-allocation:
1906
1907 Custom Memory Allocation
1908 ========================
1909
1910 By default, Jansson uses :func:`malloc()` and :func:`free()` for
1911 memory allocation. These functions can be overridden if custom
1912 behavior is needed.
1913
1914 .. type:: json_malloc_t
1915
1916 A typedef for a function pointer with :func:`malloc()`'s
1917 signature::
1918
1919 typedef void *(*json_malloc_t)(size_t);
1920
1921 .. type:: json_free_t
1922
1923 A typedef for a function pointer with :func:`free()`'s
1924 signature::
1925
1926 typedef void (*json_free_t)(void *);
1927
1928 .. function:: void json_set_alloc_funcs(json_malloc_t malloc_fn, json_free_t free_fn)
1929
1930 Use *malloc_fn* instead of :func:`malloc()` and *free_fn* instead
1931 of :func:`free()`. This function has to be called before any other
1932 Jansson's API functions to ensure that all memory operations use
1933 the same functions.
1934
1935 .. function:: void json_get_alloc_funcs(json_malloc_t *malloc_fn, json_free_t *free_fn)
1936
1937 Fetch the current malloc_fn and free_fn used. Either parameter
1938 may be NULL.
1939
1940 .. versionadded:: 2.8
1941
1942 **Examples:**
1943
1944 Circumvent problems with different CRT heaps on Windows by using
1945 application's :func:`malloc()` and :func:`free()`::
1946
1947 json_set_alloc_funcs(malloc, free);
1948
1949 Use the `Boehm's conservative garbage collector`_ for memory
1950 operations::
1951
1952 json_set_alloc_funcs(GC_malloc, GC_free);
1953
1954 .. _Boehm's conservative garbage collector: http://www.hboehm.info/gc/
1955
1956 Allow storing sensitive data (e.g. passwords or encryption keys) in
1957 JSON structures by zeroing all memory when freed::
1958
1959 static void *secure_malloc(size_t size)
1960 {
1961 /* Store the memory area size in the beginning of the block */
1962 void *ptr = malloc(size + 8);
1963 *((size_t *)ptr) = size;
1964 return ptr + 8;
1965 }
1966
1967 static void secure_free(void *ptr)
1968 {
1969 size_t size;
1970
1971 ptr -= 8;
1972 size = *((size_t *)ptr);
1973
1974 guaranteed_memset(ptr, 0, size + 8);
1975 free(ptr);
1976 }
1977
1978 int main()
1979 {
1980 json_set_alloc_funcs(secure_malloc, secure_free);
1981 /* ... */
1982 }
1983
1984 For more information about the issues of storing sensitive data in
1985 memory, see
1986 http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html.
1987 The page also explains the :func:`guaranteed_memset()` function used
1988 in the example and gives a sample implementation for it.
1989
1990 .. _fixed_length_keys:
1991
1992 Fixed-Length keys
1993 =================
1994
1995 The Jansson API allows work with fixed-length keys. This can be useful in the following cases:
1996
1997 * The key is contained inside a buffer and is not null-terminated. In this case creating a new temporary buffer is not needed.
1998 * The key contains U+0000 inside it.
1999
2000 List of API for fixed-length keys:
2001
2002 * :c:func:`json_object_getn`
2003 * :c:func:`json_object_setn`
2004 * :c:func:`json_object_setn_nocheck`
2005 * :c:func:`json_object_setn_new`
2006 * :c:func:`json_object_setn_new_nocheck`
2007 * :c:func:`json_object_deln`
2008 * :c:func:`json_object_iter_key_len`
2009 * :c:func:`json_object_keylen_foreach`
2010 * :c:func:`json_object_keylen_foreach_safe`
2011
2012 **Examples:**
2013
2014 Try to write a new function to get :c:struct:`json_t` by path separated by ``.``
2015
2016 This requires:
2017
2018 * string iterator (no need to modify the input for better performance)
2019 * API for working with fixed-size keys
2020
2021 The iterator::
2022
2023 struct string {
2024 const char *string;
2025 size_t length;
2026 };
2027
2028 size_t string_try_next(struct string *str, const char *delimiter) {
2029 str->string += strspn(str->string, delimiter);
2030 str->length = strcspn(str->string, delimiter);
2031 return str->length;
2032 }
2033
2034 #define string_foreach(_string, _delimiter) \
2035 for (; string_try_next(&(_string), _delimiter); (_string).string += (_string).length)
2036
2037
2038 The function::
2039
2040 json_t *json_object_get_by_path(json_t *object, const char *path) {
2041 struct string str;
2042 json_t *out = object;
2043
2044 str.string = path;
2045
2046 string_foreach(str, ".") {
2047 out = json_object_getn(out, str.string, str.length);
2048 if (out == NULL)
2049 return NULL;
2050 }
2051
2052 return out;
2053 }
2054
2055 And usage::
2056
2057 int main(void) {
2058 json_t *obj = json_pack("{s:{s:{s:b}}}", "a", "b", "c", 1);
2059
2060 json_t *c = json_object_get_by_path(obj, "a.b.c");
2061 assert(json_is_true(c));
2062
2063 json_decref(obj);
2064 }