doc/apiref.rst

   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 ``JSON_`` and other identifiers with
  21 ``json_``. Type names are suffixed with ``_t`` and ``typedef``\ 'd so
  22 that the ``struct`` keyword need not be used.
  23
  24
  25 Value Representation
  26 ====================
  27
  28 The JSON specification (:rfc:`4627`) defines the following data types:
  29 *object*, *array*, *string*, *number*, *boolean*, and *null*. JSON
  30 types are used dynamically; arrays and objects can hold any other data
  31 type, including themselves. For this reason, Jansson's type system is
  32 also dynamic in nature. There's one C type to represent all JSON
  33 values, and this structure knows the type of the JSON value it holds.
  34
  35 .. type:: json_t
  36
  37   This data structure is used throughout the library to represent all
  38   JSON values. It always contains the type of the JSON value it holds
  39   and the value's reference count. The rest depends on the type of the
  40   value.
  41
  42 Objects of :type:`json_t` are always used through a pointer. There
  43 are APIs for querying the type, manipulating the reference count, and
  44 for constructing and manipulating values of different types.
  45
  46 Unless noted otherwise, all API functions return an error value if an
  47 error occurs. Depending on the function's signature, the error value
  48 is either *NULL* or -1. Invalid arguments or invalid input are
  49 apparent sources for errors. Memory allocation and I/O operations may
  50 also cause errors.
  51
  52
  53 Type
  54 ----
  55
  56 The type of a JSON value is queried and tested using the following
  57 functions:
  58
  59 .. type:: enum json_type
  60
  61    The type of a JSON value. The following members are defined:
  62
  63    +--------------------+
  64    | ``JSON_OBJECT``    |
  65    +--------------------+
  66    | ``JSON_ARRAY``     |
  67    +--------------------+
  68    | ``JSON_STRING``    |
  69    +--------------------+
  70    | ``JSON_INTEGER``   |
  71    +--------------------+
  72    | ``JSON_REAL``      |
  73    +--------------------+
  74    | ``JSON_TRUE``      |
  75    +--------------------+
  76    | ``JSON_FALSE``     |
  77    +--------------------+
  78    | ``JSON_NULL``      |
  79    +--------------------+
  80
  81    These correspond to JSON object, array, string, number, boolean and
  82    null. A number is represented by either a value of the type
  83    ``JSON_INTEGER`` or of the type ``JSON_REAL``. A true boolean value
  84    is represented by a value of the type ``JSON_TRUE`` and false by a
  85    value of the type ``JSON_FALSE``.
  86
  87 .. function:: int json_typeof(const json_t *json)
  88
  89    Return the type of the JSON value (a :type:`json_type` cast to
  90    :type:`int`). *json* MUST NOT be *NULL*. This function is actually
  91    implemented as a macro for speed.
  92
  93 .. function:: json_is_object(const json_t *json)
  94                json_is_array(const json_t *json)
  95                json_is_string(const json_t *json)
  96                json_is_integer(const json_t *json)
  97                json_is_real(const json_t *json)
  98                json_is_true(const json_t *json)
  99                json_is_false(const json_t *json)
 100                json_is_null(const json_t *json)
 101
 102    These functions (actually macros) return true (non-zero) for values
 103    of the given type, and false (zero) for values of other types and
 104    for *NULL*.
 105
 106 .. function:: json_is_number(const json_t *json)
 107
 108    Returns true for values of types ``JSON_INTEGER`` and
 109    ``JSON_REAL``, and false for other types and for *NULL*.
 110
 111 .. function:: json_is_boolean(const json_t *json)
 112
 113    Returns true for types ``JSON_TRUE`` and ``JSON_FALSE``, and false
 114    for values of other types and for *NULL*.
 115
 116
 117 .. _apiref-reference-count:
 118
 119 Reference Count
 120 ---------------
 121
 122 The reference count is used to track whether a value is still in use
 123 or not. When a value is created, it's reference count is set to 1. If
 124 a reference to a value is kept (e.g. a value is stored somewhere for
 125 later use), its reference count is incremented, and when the value is
 126 no longer needed, the reference count is decremented. When the
 127 reference count drops to zero, there are no references left, and the
 128 value can be destroyed.
 129
 130 The following functions are used to manipulate the reference count.
 131
 132 .. function:: json_t *json_incref(json_t *json)
 133
 134    Increment the reference count of *json* if it's not non-*NULL*.
 135    Returns *json*.
 136
 137 .. function:: void json_decref(json_t *json)
 138
 139    Decrement the reference count of *json*. As soon as a call to
 140    :func:`json_decref()` drops the reference count to zero, the value
 141    is destroyed and it can no longer be used.
 142
 143 Functions creating new JSON values set the reference count to 1. These
 144 functions are said to return a **new reference**. Other functions
 145 returning (existing) JSON values do not normally increase the
 146 reference count. These functions are said to return a **borrowed
 147 reference**. So, if the user will hold a reference to a value returned
 148 as a borrowed reference, he must call :func:`json_incref`. As soon as
 149 the value is no longer needed, :func:`json_decref` should be called
 150 to release the reference.
 151
 152 Normally, all functions accepting a JSON value as an argument will
 153 manage the reference, i.e. increase and decrease the reference count
 154 as needed. However, some functions **steal** the reference, i.e. they
 155 have the same result as if the user called :func:`json_decref()` on
 156 the argument right after calling the function. These functions are
 157 suffixed with ``_new`` or have ``_new_`` somewhere in their name.
 158
 159 For example, the following code creates a new JSON array and appends
 160 an integer to it::
 161
 162   json_t *array, *integer;
 163
 164   array = json_array();
 165   integer = json_integer(42);
 166
 167   json_array_append(array, integer);
 168   json_decref(integer);
 169
 170 Note how the caller has to release the reference to the integer value
 171 by calling :func:`json_decref()`. By using a reference stealing
 172 function :func:`json_array_append_new()` instead of
 173 :func:`json_array_append()`, the code becomes much simpler::
 174
 175   json_t *array = json_array();
 176   json_array_append_new(array, json_integer(42));
 177
 178 In this case, the user doesn't have to explicitly release the
 179 reference to the integer value, as :func:`json_array_append_new()`
 180 steals the reference when appending the value to the array.
 181
 182 In the following sections it is clearly documented whether a function
 183 will return a new or borrowed reference or steal a reference to its
 184 argument.
 185
 186
 187 Circular References
 188 -------------------
 189
 190 A circular reference is created when an object or an array is,
 191 directly or indirectly, inserted inside itself. The direct case is
 192 simple::
 193
 194   json_t *obj = json_object();
 195   json_object_set(obj, "foo", obj);
 196
 197 Jansson will refuse to do this, and :func:`json_object_set()` (and
 198 all the other such functions for objects and arrays) will return with
 199 an error status. The indirect case is the dangerous one::
 200
 201   json_t *arr1 = json_array(), *arr2 = json_array();
 202   json_array_append(arr1, arr2);
 203   json_array_append(arr2, arr1);
 204
 205 In this example, the array ``arr2`` is contained in the array
 206 ``arr1``, and vice versa. Jansson cannot check for this kind of
 207 indirect circular references without a performance hit, so it's up to
 208 the user to avoid them.
 209
 210 If a circular reference is created, the memory consumed by the values
 211 cannot be freed by :func:`json_decref()`. The reference counts never
 212 drops to zero because the values are keeping the references to each
 213 other. Moreover, trying to encode the values with any of the encoding
 214 functions will fail. The encoder detects circular references and
 215 returns an error status.
 216
 217
 218 True, False and Null
 219 ====================
 220
 221 These values are implemented as singletons, so each of these functions
 222 returns the same value each time.
 223
 224 .. function:: json_t *json_true(void)
 225
 226    .. refcounting:: new
 227
 228    Returns the JSON true value.
 229
 230 .. function:: json_t *json_false(void)
 231
 232    .. refcounting:: new
 233
 234    Returns the JSON false value.
 235
 236 .. function:: json_t *json_null(void)
 237
 238    .. refcounting:: new
 239
 240    Returns the JSON null value.
 241
 242
 243 String
 244 ======
 245
 246 Jansson uses UTF-8 as the character encoding. All JSON strings must be
 247 valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null
 248 terminated C strings are used, so JSON strings may not contain
 249 embedded null characters. All other Unicode codepoints U+0001 through
 250 U+10FFFF are allowed.
 251
 252 .. function:: json_t *json_string(const char *value)
 253
 254    .. refcounting:: new
 255
 256    Returns a new JSON string, or *NULL* on error. *value* must be a
 257    valid UTF-8 encoded Unicode string.
 258
 259 .. function:: json_t *json_string_nocheck(const char *value)
 260
 261    .. refcounting:: new
 262
 263    Like :func:`json_string`, but doesn't check that *value* is valid
 264    UTF-8. Use this function only if you are certain that this really
 265    is the case (e.g. you have already checked it by other means).
 266
 267 .. function:: const char *json_string_value(const json_t *string)
 268
 269    Returns the associated value of *string* as a null terminated UTF-8
 270    encoded string, or *NULL* if *string* is not a JSON string.
 271
 272 .. function:: int json_string_set(const json_t *string, const char *value)
 273
 274    Sets the associated value of *string* to *value*. *value* must be a
 275    valid UTF-8 encoded Unicode string. Returns 0 on success and -1 on
 276    error.
 277
 278 .. function:: int json_string_set_nocheck(const json_t *string, const char *value)
 279
 280    Like :func:`json_string_set`, but doesn't check that *value* is
 281    valid UTF-8. Use this function only if you are certain that this
 282    really is the case (e.g. you have already checked it by other
 283    means).
 284
 285
 286 Number
 287 ======
 288
 289 The JSON specification only contains one numeric type, "number". The C
 290 programming language has distinct types for integer and floating-point
 291 numbers, so for practical reasons Jansson also has distinct types for
 292 the two. They are called "integer" and "real", respectively. For more
 293 information, see :ref:`rfc-conformance`.
 294
 295 .. type:: json_int_t
 296
 297    This is the C type that is used to store JSON integer values. It
 298    represents the widest integer type available on your system. In
 299    practice it's just a typedef of ``long long`` if your compiler
 300    supports it, otherwise ``long``.
 301
 302    Usually, you can safely use plain ``int`` in place of
 303    ``json_int_t``, and the implicit C integer conversion handles the
 304    rest. Only when you know that you need the full 64-bit range, you
 305    should use ``json_int_t`` explicitly.
 306
 307 ``JSON_INTEGER_IS_LONG_LONG``
 308
 309    This is a preprocessor variable that holds the value 1 if
 310    :type:`json_int_t` is ``long long``, and 0 if it's ``long``. It
 311    can be used as follows::
 312
 313        #if JSON_INTEGER_IS_LONG_LONG
 314        /* Code specific for long long */
 315        #else
 316        /* Code specific for long */
 317        #endif
 318
 319 ``JSON_INTEGER_FORMAT``
 320
 321    This is a macro that expands to a :func:`printf()` conversion
 322    specifier that corresponds to :type:`json_int_t`, without the
 323    leading ``%`` sign, i.e. either ``"lld"`` or ``"ld"``. This macro
 324    is required because the actual type of :type:`json_int_t` can be
 325    either ``long`` or ``long long``, and :func:`printf()` reuiqres
 326    different length modifiers for the two.
 327
 328    Example::
 329
 330        json_int_t x = 123123123;
 331        printf("x is %" JSON_INTEGER_FORMAT "\n", x);
 332
 333
 334 .. function:: json_t *json_integer(json_int_t value)
 335
 336    .. refcounting:: new
 337
 338    Returns a new JSON integer, or *NULL* on error.
 339
 340 .. function:: json_int_t json_integer_value(const json_t *integer)
 341
 342    Returns the associated value of *integer*, or 0 if *json* is not a
 343    JSON integer.
 344
 345 .. function:: int json_integer_set(const json_t *integer, json_int_t value)
 346
 347    Sets the associated value of *integer* to *value*. Returns 0 on
 348    success and -1 if *integer* is not a JSON integer.
 349
 350 .. function:: json_t *json_real(double value)
 351
 352    .. refcounting:: new
 353
 354    Returns a new JSON real, or *NULL* on error.
 355
 356 .. function:: double json_real_value(const json_t *real)
 357
 358    Returns the associated value of *real*, or 0.0 if *real* is not a
 359    JSON real.
 360
 361 .. function:: int json_real_set(const json_t *real, double value)
 362
 363    Sets the associated value of *real* to *value*. Returns 0 on
 364    success and -1 if *real* is not a JSON real.
 365
 366 In addition to the functions above, there's a common query function
 367 for integers and reals:
 368
 369 .. function:: double json_number_value(const json_t *json)
 370
 371    Returns the associated value of the JSON integer or JSON real
 372    *json*, cast to double regardless of the actual type. If *json* is
 373    neither JSON real nor JSON integer, 0.0 is returned.
 374
 375
 376 Array
 377 =====
 378
 379 A JSON array is an ordered collection of other JSON values.
 380
 381 .. function:: json_t *json_array(void)
 382
 383    .. refcounting:: new
 384
 385    Returns a new JSON array, or *NULL* on error. Initially, the array
 386    is empty.
 387
 388 .. function:: size_t json_array_size(const json_t *array)
 389
 390    Returns the number of elements in *array*, or 0 if *array* is NULL
 391    or not a JSON array.
 392
 393 .. function:: json_t *json_array_get(const json_t *array, size_t index)
 394
 395    .. refcounting:: borrow
 396
 397    Returns the element in *array* at position *index*. The valid range
 398    for *index* is from 0 to the return value of
 399    :func:`json_array_size()` minus 1. If *array* is not a JSON array,
 400    if *array* is *NULL*, or if *index* is out of range, *NULL* is
 401    returned.
 402
 403 .. function:: int json_array_set(json_t *array, size_t index, json_t *value)
 404
 405    Replaces the element in *array* at position *index* with *value*.
 406    The valid range for *index* is from 0 to the return value of
 407    :func:`json_array_size()` minus 1. Returns 0 on success and -1 on
 408    error.
 409
 410 .. function:: int json_array_set_new(json_t *array, size_t index, json_t *value)
 411
 412    Like :func:`json_array_set()` but steals the reference to *value*.
 413    This is useful when *value* is newly created and not used after
 414    the call.
 415
 416 .. function:: int json_array_append(json_t *array, json_t *value)
 417
 418    Appends *value* to the end of *array*, growing the size of *array*
 419    by 1. Returns 0 on success and -1 on error.
 420
 421 .. function:: int json_array_append_new(json_t *array, json_t *value)
 422
 423    Like :func:`json_array_append()` but steals the reference to
 424    *value*. This is useful when *value* is newly created and not used
 425    after the call.
 426
 427 .. function:: int json_array_insert(json_t *array, size_t index, json_t *value)
 428
 429    Inserts *value* to *array* at position *index*, shifting the
 430    elements at *index* and after it one position towards the end of
 431    the array. Returns 0 on success and -1 on error.
 432
 433 .. function:: int json_array_insert_new(json_t *array, size_t index, json_t *value)
 434
 435    Like :func:`json_array_insert()` but steals the reference to
 436    *value*. This is useful when *value* is newly created and not used
 437    after the call.
 438
 439 .. function:: int json_array_remove(json_t *array, size_t index)
 440
 441    Removes the element in *array* at position *index*, shifting the
 442    elements after *index* one position towards the start of the array.
 443    Returns 0 on success and -1 on error.
 444
 445 .. function:: int json_array_clear(json_t *array)
 446
 447    Removes all elements from *array*. Returns 0 on sucess and -1 on
 448    error.
 449
 450 .. function:: int json_array_extend(json_t *array, json_t *other_array)
 451
 452    Appends all elements in *other_array* to the end of *array*.
 453    Returns 0 on success and -1 on error.
 454
 455
 456 Object
 457 ======
 458
 459 A JSON object is a dictionary of key-value pairs, where the key is a
 460 Unicode string and the value is any JSON value.
 461
 462 .. function:: json_t *json_object(void)
 463
 464    .. refcounting:: new
 465
 466    Returns a new JSON object, or *NULL* on error. Initially, the
 467    object is empty.
 468
 469 .. function:: size_t json_object_size(const json_t *object)
 470
 471    Returns the number of elements in *object*, or 0 if *object* is not
 472    a JSON object.
 473
 474 .. function:: json_t *json_object_get(const json_t *object, const char *key)
 475
 476    .. refcounting:: borrow
 477
 478    Get a value corresponding to *key* from *object*. Returns *NULL* if
 479    *key* is not found and on error.
 480
 481 .. function:: int json_object_set(json_t *object, const char *key, json_t *value)
 482
 483    Set the value of *key* to *value* in *object*. *key* must be a
 484    valid null terminated UTF-8 encoded Unicode string. If there
 485    already is a value for *key*, it is replaced by the new value.
 486    Returns 0 on success and -1 on error.
 487
 488 .. function:: int json_object_set_nocheck(json_t *object, const char *key, json_t *value)
 489
 490    Like :func:`json_object_set`, but doesn't check that *key* is
 491    valid UTF-8. Use this function only if you are certain that this
 492    really is the case (e.g. you have already checked it by other
 493    means).
 494
 495 .. function:: int json_object_set_new(json_t *object, const char *key, json_t *value)
 496
 497    Like :func:`json_object_set()` but steals the reference to
 498    *value*. This is useful when *value* is newly created and not used
 499    after the call.
 500
 501 .. function:: int json_object_set_new_nocheck(json_t *object, const char *key, json_t *value)
 502
 503    Like :func:`json_object_set_new`, but doesn't check that *key* is
 504    valid UTF-8. Use this function only if you are certain that this
 505    really is the case (e.g. you have already checked it by other
 506    means).
 507
 508 .. function:: int json_object_del(json_t *object, const char *key)
 509
 510    Delete *key* from *object* if it exists. Returns 0 on success, or
 511    -1 if *key* was not found.
 512
 513
 514 .. function:: int json_object_clear(json_t *object)
 515
 516    Remove all elements from *object*. Returns 0 on success and -1 if
 517    *object* is not a JSON object.
 518
 519 .. function:: int json_object_update(json_t *object, json_t *other)
 520
 521    Update *object* with the key-value pairs from *other*, overwriting
 522    existing keys. Returns 0 on success or -1 on error.
 523
 524
 525 The following functions implement an iteration protocol for objects:
 526
 527 .. function:: void *json_object_iter(json_t *object)
 528
 529    Returns an opaque iterator which can be used to iterate over all
 530    key-value pairs in *object*, or *NULL* if *object* is empty.
 531
 532 .. function:: void *json_object_iter_at(json_t *object, const char *key)
 533
 534    Like :func:`json_object_iter()`, but returns an iterator to the
 535    key-value pair in *object* whose key is equal to *key*, or NULL if
 536    *key* is not found in *object*. Iterating forward to the end of
 537    *object* only yields all key-value pairs of the object if *key*
 538    happens to be the first key in the underlying hash table.
 539
 540 .. function:: void *json_object_iter_next(json_t *object, void *iter)
 541
 542    Returns an iterator pointing to the next key-value pair in *object*
 543    after *iter*, or *NULL* if the whole object has been iterated
 544    through.
 545
 546 .. function:: const char *json_object_iter_key(void *iter)
 547
 548    Extract the associated key from *iter*.
 549
 550 .. function:: json_t *json_object_iter_value(void *iter)
 551
 552    .. refcounting:: borrow
 553
 554    Extract the associated value from *iter*.
 555
 556 .. function:: int json_object_iter_set(json_t *object, void *iter, json_t *value)
 557
 558    Set the value of the key-value pair in *object*, that is pointed to
 559    by *iter*, to *value*.
 560
 561 .. function:: int json_object_iter_set_new(json_t *object, void *iter, json_t *value)
 562
 563    Like :func:`json_object_iter_set()`, but steals the reference to
 564    *value*. This is useful when *value* is newly created and not used
 565    after the call.
 566
 567 The iteration protocol can be used for example as follows::
 568
 569    /* obj is a JSON object */
 570    const char *key;
 571    json_t *value;
 572    void *iter = json_object_iter(obj);
 573    while(iter)
 574    {
 575        key = json_object_iter_key(iter);
 576        value = json_object_iter_value(iter);
 577        /* use key and value ... */
 578        iter = json_object_iter_next(obj, iter);
 579    }
 580
 581
 582 Encoding
 583 ========
 584
 585 This sections describes the functions that can be used to encode
 586 values to JSON. Only objects and arrays can be encoded, since they are
 587 the only valid "root" values of a JSON text.
 588
 589 By default, the output has no newlines, and spaces are used between
 590 array and object elements for a readable output. This behavior can be
 591 altered by using the ``JSON_INDENT`` and ``JSON_COMPACT`` flags
 592 described below. A newline is never appended to the end of the encoded
 593 JSON data.
 594
 595 Each function takes a *flags* parameter that controls some aspects of
 596 how the data is encoded. Its default value is 0. The following macros
 597 can be ORed together to obtain *flags*.
 598
 599 ``JSON_INDENT(n)``
 600    Pretty-print the result, using newlines between array and object
 601    items, and indenting with *n* spaces. The valid range for *n* is
 602    between 0 and 32, other values result in an undefined output. If
 603    ``JSON_INDENT`` is not used or *n* is 0, no newlines are inserted
 604    between array and object items.
 605
 606 ``JSON_COMPACT``
 607    This flag enables a compact representation, i.e. sets the separator
 608    between array and object items to ``","`` and between object keys
 609    and values to ``":"``. Without this flag, the corresponding
 610    separators are ``", "`` and ``": "`` for more readable output.
 611
 612 ``JSON_ENSURE_ASCII``
 613    If this flag is used, the output is guaranteed to consist only of
 614    ASCII characters. This is achived by escaping all Unicode
 615    characters outside the ASCII range.
 616
 617 ``JSON_SORT_KEYS``
 618    If this flag is used, all the objects in output are sorted by key.
 619    This is useful e.g. if two JSON texts are diffed or visually
 620    compared.
 621
 622 ``JSON_PRESERVE_ORDER``
 623    If this flag is used, object keys in the output are sorted into the
 624    same order in which they were first inserted to the object. For
 625    example, decoding a JSON text and then encoding with this flag
 626    preserves the order of object keys.
 627
 628 The following functions perform the actual JSON encoding. The result
 629 is in UTF-8.
 630
 631 .. function:: char *json_dumps(const json_t *root, size_t flags)
 632
 633    Returns the JSON representation of *root* as a string, or *NULL* on
 634    error. *flags* is described above. The return value must be freed
 635    by the caller using :func:`free()`.
 636
 637 .. function:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
 638
 639    Write the JSON representation of *root* to the stream *output*.
 640    *flags* is described above. Returns 0 on success and -1 on error.
 641    If an error occurs, something may have already been written to
 642    *output*. In this case, the output is undefined and most likely not
 643    valid JSON.
 644
 645 .. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
 646
 647    Write the JSON representation of *root* to the file *path*. If
 648    *path* already exists, it is overwritten. *flags* is described
 649    above. Returns 0 on success and -1 on error.
 650
 651
 652 Decoding
 653 ========
 654
 655 This sections describes the functions that can be used to decode JSON
 656 text to the Jansson representation of JSON data. The JSON
 657 specification requires that a JSON text is either a serialized array
 658 or object, and this requirement is also enforced with the following
 659 functions. In other words, the top level value in the JSON text being
 660 decoded must be either array or object.
 661
 662 See :ref:`rfc-conformance` for a discussion on Jansson's conformance
 663 to the JSON specification. It explains many design decisions that
 664 affect especially the behavior of the decoder.
 665
 666 .. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
 667
 668    .. refcounting:: new
 669
 670    Decodes the JSON string *input* and returns the array or object it
 671    contains, or *NULL* on error, in which case *error* is filled with
 672    information about the error. See above for discussion on the
 673    *error* parameter. *flags* is currently unused, and should be set
 674    to 0.
 675
 676 .. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
 677
 678    .. refcounting:: new
 679
 680    Decodes the JSON text in stream *input* and returns the array or
 681    object it contains, or *NULL* on error, in which case *error* is
 682    filled with information about the error. See above for discussion
 683    on the *error* parameter. *flags* is currently unused, and should
 684    be set to 0.
 685
 686 .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
 687
 688    .. refcounting:: new
 689
 690    Decodes the JSON text in file *path* and returns the array or
 691    object it contains, or *NULL* on error, in which case *error* is
 692    filled with information about the error. See above for discussion
 693    on the *error* parameter. *flags* is currently unused, and should
 694    be set to 0.
 695
 696 .. type:: json_error_t
 697
 698    This data structure is used to return information on decoding
 699    errors from the decoding functions.
 700
 701    .. member:: const char *text
 702
 703       The error message (in UTF-8), or an empty string if a message is
 704       not available.
 705
 706    .. member:: int line
 707
 708       The line number on which the error occurred, or -1 if this
 709       information is not available.
 710
 711    .. member:: int column
 712
 713       The character column on which the error occurred, or -1 if this
 714       information is not available.
 715
 716    .. member:: const char *source
 717
 718       Source of the error. This is (a part of) the file name when
 719       using :func:`json_load_file()`, or a special identifier in angle
 720       brackets otherwise (e.g. ``<string>``).
 721
 722    The normal use of :type:`json_error_t` is to allocate it on the
 723    stack, and pass a pointer to a decoding function. Example::
 724
 725       int main() {
 726           json_t *json;
 727           json_error_t error;
 728
 729           json = json_load_file("/path/to/file.json", 0, &error);
 730           if(!json) {
 731               /* the error variable contains error information */
 732           }
 733           ...
 734       }
 735
 736    Also note that if the decoding succeeded (``json != NULL`` in the
 737    above example), the contents of ``error`` are unspecified.
 738
 739    All decoding functions also accept *NULL* as the
 740    :type:`json_error_t` pointer, in which case no error information
 741    is returned to the caller.
 742
 743
 744 Equality
 745 ========
 746
 747 Testing for equality of two JSON values cannot, in general, be
 748 achieved using the ``==`` operator. Equality in the terms of the
 749 ``==`` operator states that the two :type:`json_t` pointers point to
 750 exactly the same JSON value. However, two JSON values can be equal not
 751 only if they are exactly the same value, but also if they have equal
 752 "contents":
 753
 754 * Two integer or real values are equal if their contained numeric
 755   values are equal. An integer value is never equal to a real value,
 756   though.
 757
 758 * Two strings are equal if their contained UTF-8 strings are equal,
 759   byte by byte. Unicode comparison algorithms are not implemented.
 760
 761 * Two arrays are equal if they have the same number of elements and
 762   each element in the first array is equal to the corresponding
 763   element in the second array.
 764
 765 * Two objects are equal if they have exactly the same keys and the
 766   value for each key in the first object is equal to the value of the
 767   corresponding key in the second object.
 768
 769 * Two true, false or null values have no "contents", so they are equal
 770   if their types are equal. (Because these values are singletons,
 771   their equality can actually be tested with ``==``.)
 772
 773 The following function can be used to test whether two JSON values are
 774 equal.
 775
 776 .. function:: int json_equal(json_t *value1, json_t *value2)
 777
 778    Returns 1 if *value1* and *value2* are equal, as defined above.
 779    Returns 0 if they are inequal or one or both of the pointers are
 780    *NULL*.
 781
 782
 783 Copying
 784 =======
 785
 786 Because of reference counting, passing JSON values around doesn't
 787 require copying them. But sometimes a fresh copy of a JSON value is
 788 needed. For example, if you need to modify an array, but still want to
 789 use the original afterwards, you should take a copy of it first.
 790
 791 Jansson supports two kinds of copying: shallow and deep. There is a
 792 difference between these methods only for arrays and objects. Shallow
 793 copying only copies the first level value (array or object) and uses
 794 the same child values in the copied value. Deep copying makes a fresh
 795 copy of the child values, too. Moreover, all the child values are deep
 796 copied in a recursive fashion.
 797
 798 .. function:: json_t *json_copy(json_t *value)
 799
 800    .. refcounting:: new
 801
 802    Returns a shallow copy of *value*, or *NULL* on error.
 803
 804 .. function:: json_t *json_deep_copy(json_t *value)
 805
 806    .. refcounting:: new
 807
 808    Returns a deep copy of *value*, or *NULL* on error.