doc/conformance.rst

   1 ***************
   2 RFC Conformance
   3 ***************
   4
   5 JSON is specified in :rfc:`4627`, *"The application/json Media Type
   6 for JavaScript Object Notation (JSON)"*. This chapter discusses
   7 Jansson's conformance to this specification.
   8
   9 Character Encoding
  10 ==================
  11
  12 Jansson only supports UTF-8 encoded JSON texts. It does not support or
  13 auto-detect any of the other encodings mentioned in the RFC, namely
  14 UTF-16LE, UTF-16BE, UTF-32LE or UTF-32BE. Pure ASCII is supported, as
  15 it's a subset of UTF-8.
  16
  17 Strings
  18 =======
  19
  20 JSON strings are mapped to C-style null-terminated character arrays,
  21 and UTF-8 encoding is used internally. Strings may not contain
  22 embedded null characters, not even escaped ones.
  23
  24 For example, trying to decode the following JSON text leads to a parse
  25 error::
  26
  27     ["this string contains the null character: \u0000"]
  28
  29 All other Unicode codepoints U+0001 through U+10FFFF are allowed.
  30
  31 Numbers
  32 =======
  33
  34 Real vs. Integer
  35 ----------------
  36
  37 JSON makes no distinction between real and integer numbers; Jansson
  38 does. Real numbers are mapped to the ``double`` type and integers to
  39 the ``json_int_t`` type, which is a typedef of ``long long`` or
  40 ``long``, depending on whether ``long long`` is supported by your
  41 compiler or not.
  42
  43 A JSON number is considered to be a real number if its lexical
  44 representation includes one of ``e``, ``E``, or ``.``; regardless if
  45 its actual numeric value is a true integer (e.g., all of ``1E6``,
  46 ``3.0``, ``400E-2``, and ``3.14E3`` are mathematical integers, but
  47 will be treated as real values).
  48
  49 All other JSON numbers are considered integers.
  50
  51 When encoding to JSON, real values are always represented
  52 with a fractional part; e.g., the ``double`` value 3.0 will be
  53 represented in JSON as ``3.0``, not ``3``.
  54
  55 Overflow, Underflow & Precision
  56 -------------------------------
  57
  58 Real numbers whose absolute values are too small to be represented in
  59 a C ``double`` will be silently estimated with 0.0. Thus, depending on
  60 platform, JSON numbers very close to zero such as 1E-999 may result in
  61 0.0.
  62
  63 Real numbers whose absolute values are too large to be represented in
  64 a C ``double`` will result in an overflow error (a JSON decoding
  65 error). Thus, depending on platform, JSON numbers like 1E+999 or
  66 -1E+999 may result in a parsing error.
  67
  68 Likewise, integer numbers whose absolute values are too large to be
  69 represented in the ``json_int_t`` type (see above) will result in an
  70 overflow error (a JSON decoding error). Thus, depending on platform,
  71 JSON numbers like 1000000000000000 may result in parsing error.
  72
  73 Parsing JSON real numbers may result in a loss of precision. As long
  74 as overflow does not occur (i.e. a total loss of precision), the
  75 rounded approximate value is silently used. Thus the JSON number
  76 1.000000000000000005 may, depending on platform, result in the
  77 ``double`` value 1.0.
  78
  79 Signed zeros
  80 ------------
  81
  82 JSON makes no statement about what a number means; however Javascript
  83 (ECMAscript) does state that +0.0 and -0.0 must be treated as being
  84 distinct values, i.e. -0.0 |not-equal| 0.0. Jansson relies on the
  85 underlying floating point library in the C environment in which it is
  86 compiled. Therefore it is platform-dependent whether 0.0 and -0.0 will
  87 be distinct values. Most platforms that use the IEEE 754
  88 floating-point standard will support signed zeros.
  89
  90 Note that this only applies to floating-point; neither JSON, C, or
  91 IEEE support the concept of signed integer zeros.
  92
  93 .. |not-equal| unicode:: U+2260
  94
  95 Types
  96 -----
  97
  98 No support is provided in Jansson for any C numeric types other than
  99 ``json_int_t`` and ``double``. This excludes things such as unsigned
 100 types, ``long double``, etc. Obviously, shorter types like ``short``,
 101 ``int``, ``long`` (if ``json_int_t`` is ``long long``) and ``float``
 102 are implicitly handled via the ordinary C type coercion rules (subject
 103 to overflow semantics). Also, no support or hooks are provided for any
 104 supplemental "bignum" type add-on packages.