103 lines
3.7 KiB
ReStructuredText
103 lines
3.7 KiB
ReStructuredText
***************
|
|
RFC Conformance
|
|
***************
|
|
|
|
JSON is specified in :rfc:`4627`, *"The application/json Media Type
|
|
for JavaScript Object Notation (JSON)"*. This chapter discusses
|
|
Jansson's conformance to this specification.
|
|
|
|
Character Encoding
|
|
==================
|
|
|
|
Jansson only supports UTF-8 encoded JSON texts. It does not support or
|
|
auto-detect any of the other encodings mentioned in the RFC, namely
|
|
UTF-16LE, UTF-16BE, UTF-32LE or UTF-32BE. Pure ASCII is supported, as
|
|
it's a subset of UTF-8.
|
|
|
|
Strings
|
|
=======
|
|
|
|
JSON strings are mapped to C-style null-terminated character arrays,
|
|
and UTF-8 encoding is used internally. Strings may not contain
|
|
embedded null characters, not even escaped ones.
|
|
|
|
For example, trying to decode the following JSON text leads to a parse
|
|
error::
|
|
|
|
["this string contains the null character: \u0000"]
|
|
|
|
All other Unicode codepoints U+0001 through U+10FFFF are allowed.
|
|
|
|
Numbers
|
|
=======
|
|
|
|
Real vs. Integer
|
|
----------------
|
|
|
|
JSON makes no distinction between real and integer numbers; Jansson
|
|
does. Real numbers are mapped to the ``double`` type and integers to
|
|
the ``long`` type.
|
|
|
|
A JSON number is considered to be a real number if its lexical
|
|
representation includes one of ``e``, ``E``, or ``.``; regardless if
|
|
its actual numeric value is a true integer (e.g., all of ``1E6``,
|
|
``3.0``, ``400E-2``, and ``3.14E3`` are mathematical integers, but
|
|
will be treated as real values).
|
|
|
|
All other JSON numbers are considered integers.
|
|
|
|
When encoding to JSON, real values are always represented
|
|
with a fractional part; e.g., the ``double`` value 3.0 will be
|
|
represented in JSON as ``3.0``, not ``3``.
|
|
|
|
Overflow, Underflow & Precision
|
|
-------------------------------
|
|
|
|
Real numbers whose absolute values are too small to be represented in
|
|
a C double will be silently estimated with 0.0. Thus, depending on
|
|
platform, JSON numbers very close to zero such as 1E-999 may result in
|
|
0.0.
|
|
|
|
Real numbers whose absolute values are too large to be represented in
|
|
a C ``double`` type will result in an overflow error (a JSON decoding
|
|
error). Thus, depending on platform, JSON numbers like 1E+999 or
|
|
-1E+999 may result in a parsing error.
|
|
|
|
Likewise, integer numbers whose absolute values are too large to be
|
|
represented in the ``long`` type will result in an overflow error (a
|
|
JSON decoding error). Thus, depending on platform, JSON numbers like
|
|
1000000000000000 may result in parsing error.
|
|
|
|
Parsing JSON real numbers may result in a loss of precision. As long
|
|
as overflow does not occur (i.e. a total loss of precision), the
|
|
rounded approximate value is silently used. Thus the JSON number
|
|
1.000000000000000005 may, depending on platform, result in the
|
|
``double`` value 1.0.
|
|
|
|
Signed zeros
|
|
------------
|
|
|
|
JSON makes no statement about what a number means; however Javascript
|
|
(ECMAscript) does state that +0.0 and -0.0 must be treated as being
|
|
distinct values, i.e. -0.0 |not-equal| 0.0. Jansson relies on the
|
|
underlying floating point library in the C environment in which it is
|
|
compiled. Therefore it is platform-dependent whether 0.0 and -0.0 will
|
|
be distinct values. Most platforms that use the IEEE 754
|
|
floating-point standard will support signed zeros.
|
|
|
|
Note that this only applies to floating-point; neither JSON, C, or
|
|
IEEE support the concept of signed integer zeros.
|
|
|
|
.. |not-equal| unicode:: U+2260
|
|
|
|
Types
|
|
-----
|
|
|
|
No support is provided in Jansson for any C numeric types other than
|
|
``long`` and ``double``. This excludes things such as unsigned types,
|
|
``long long``, ``long double``, etc. Obviously, shorter types like
|
|
``short``, ``int`` and ``float`` are implicitly handled via the
|
|
ordinary C type coercion rules (subject to overflow semantics). Also,
|
|
no support or hooks are provided for any supplemental "bignum" type
|
|
add-on packages.
|