From: Petri Lehtinen <petri@digip.org>
Date: Fri, 26 Mar 2010 20:00:41 +0000 (+0200)
Subject: doc: Add chapter on RFC conformance
X-Git-Tag: v1.2.1~4
X-Git-Url: http://www.project-moonshot.org/gitweb/?p=jansson.git;a=commitdiff_plain;h=c7c2edae8a6a2ba25c31d50c9f44bbbf080889da

doc: Add chapter on RFC conformance

Thanks to Deron Meranda for providing the initial text.
---

diff --git a/doc/conformance.rst b/doc/conformance.rst
new file mode 100644
index 0000000..785a94d
--- /dev/null
+++ b/doc/conformance.rst
@@ -0,0 +1,102 @@
+***************
+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.
diff --git a/doc/index.rst b/doc/index.rst
index d6018b9..c7321df 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -34,6 +34,7 @@ Contents
 
    gettingstarted
    tutorial
+   conformance
    apiref
    changes