"Fossies" - the Fresh Open Source Software Archive

Member "jansson-2.14/doc/conformance.rst" (9 Sep 2021, 4525 Bytes) of package /linux/www/jansson-2.14.tar.bz2:

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