6e3ca5c45c
Couple some string and number information from the RFC conformance chapter in the API reference, and refer to the RFC conformance chapter from API reference for more information. Also, state more clearly that a JSON text must have an array or object as the top-level value, and better document the string comparison performed by json_equal().
105 lines
3.7 KiB
ReStructuredText
105 lines
3.7 KiB
ReStructuredText
.. _rfc-conformance:
|
|
|
|
***************
|
|
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 ``int`` 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 ``int`` 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
|
|
``int`` and ``double``. This excludes things such as unsigned types,
|
|
``long``, ``long long``, ``long double``, etc. Obviously, shorter
|
|
types like ``short`` 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.
|