conformance.html revision 4139
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1f48f8236de7de97be1c6b9d06bef50b379c8801jenkins "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <title>RFC Conformance — Jansson 2.7 documentation</title>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <link rel="stylesheet" href="_static/default.css" type="text/css" />
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk var DOCUMENTATION_OPTIONS = {
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk URL_ROOT: './',
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk VERSION: '2.7',
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk COLLAPSE_INDEX: false,
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk FILE_SUFFIX: '.html',
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk HAS_SOURCE: true
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <script type="text/javascript" src="_static/jquery.js"></script>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <script type="text/javascript" src="_static/underscore.js"></script>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <script type="text/javascript" src="_static/doctools.js"></script>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <link rel="top" title="Jansson 2.7 documentation" href="index.html" />
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <link rel="next" title="Portability" href="portability.html" />
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <link rel="prev" title="Tutorial" href="tutorial.html" />
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<span id="id1"></span><h1>RFC Conformance<a class="headerlink" href="#rfc-conformance" title="Permalink to this headline">¶</a></h1>
a277eacba0534b81b8bd19173f7060a3971d03dajeff.schenk<p>JSON is specified in <span class="target" id="index-0"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc4627.html"><strong>RFC 4627</strong></a>, <em>“The application/json Media Type
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkfor JavaScript Object Notation (JSON)”</em>.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<h2>Character Encoding<a class="headerlink" href="#character-encoding" title="Permalink to this headline">¶</a></h2>
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig<p>Jansson only supports UTF-8 encoded JSON texts. It does not support or
a622f6b14edb724c3cdbc8b5836a109d4ac80086Peter Majorauto-detect any of the other encodings mentioned in the RFC, namely
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkUTF-16LE, UTF-16BE, UTF-32LE or UTF-32BE. Pure ASCII is supported, as
a149d11dfee7bcc667e71ec330b7566dd0437c1fjeff.schenkit’s a subset of UTF-8.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<h2>Strings<a class="headerlink" href="#strings" title="Permalink to this headline">¶</a></h2>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>JSON strings are mapped to C-style null-terminated character arrays,
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkand UTF-8 encoding is used internally.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>All Unicode codepoints U+0000 through U+10FFFF are allowed in string
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkvalues. However, U+0000 is not allowed in object keys because of API
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkrestrictions.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>Unicode normalization or any other transformation is never performed
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkon any strings (string values or object keys). When checking for
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkequivalence of strings or object keys, the comparison is performed
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkbyte by byte between the original UTF-8 representations of the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<h2>Numbers<a class="headerlink" href="#numbers" title="Permalink to this headline">¶</a></h2>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<span id="id2"></span><h3>Real vs. Integer<a class="headerlink" href="#real-vs-integer" title="Permalink to this headline">¶</a></h3>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>JSON makes no distinction between real and integer numbers; Jansson
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkdoes. Real numbers are mapped to the <tt class="docutils literal"><span class="pre">double</span></tt> type and integers to
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkthe <tt class="docutils literal"><span class="pre">json_int_t</span></tt> type, which is a typedef of <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> or
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<tt class="docutils literal"><span class="pre">long</span></tt>, depending on whether <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt> is supported by your
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkcompiler or not.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>A JSON number is considered to be a real number if its lexical
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkrepresentation includes one of <tt class="docutils literal"><span class="pre">e</span></tt>, <tt class="docutils literal"><span class="pre">E</span></tt>, or <tt class="docutils literal"><span class="pre">.</span></tt>; regardless if
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkits actual numeric value is a true integer (e.g., all of <tt class="docutils literal"><span class="pre">1E6</span></tt>,
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<tt class="docutils literal"><span class="pre">3.0</span></tt>, <tt class="docutils literal"><span class="pre">400E-2</span></tt>, and <tt class="docutils literal"><span class="pre">3.14E3</span></tt> are mathematical integers, but
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkwill be treated as real values). With the <tt class="docutils literal"><span class="pre">JSON_DECODE_INT_AS_REAL</span></tt>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkdecoder flag set all numbers are interpreted as real.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>All other JSON numbers are considered integers.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>When encoding to JSON, real values are always represented
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkwith a fractional part; e.g., the <tt class="docutils literal"><span class="pre">double</span></tt> value 3.0 will be
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkrepresented in JSON as <tt class="docutils literal"><span class="pre">3.0</span></tt>, not <tt class="docutils literal"><span class="pre">3</span></tt>.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<div class="section" id="overflow-underflow-precision">
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<h3>Overflow, Underflow & Precision<a class="headerlink" href="#overflow-underflow-precision" title="Permalink to this headline">¶</a></h3>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>Real numbers whose absolute values are too small to be represented in
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenka C <tt class="docutils literal"><span class="pre">double</span></tt> will be silently estimated with 0.0. Thus, depending on
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkplatform, JSON numbers very close to zero such as 1E-999 may result in
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>Real numbers whose absolute values are too large to be represented in
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenka C <tt class="docutils literal"><span class="pre">double</span></tt> will result in an overflow error (a JSON decoding
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkerror). Thus, depending on platform, JSON numbers like 1E+999 or
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk-1E+999 may result in a parsing error.</p>
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenk<p>Likewise, integer numbers whose absolute values are too large to be
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkrepresented in the <tt class="docutils literal"><span class="pre">json_int_t</span></tt> type (see above) will result in an
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkoverflow error (a JSON decoding error). Thus, depending on platform,
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkJSON numbers like 1000000000000000 may result in parsing error.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>Parsing JSON real numbers may result in a loss of precision. As long
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkas overflow does not occur (i.e. a total loss of precision), the
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkrounded approximate value is silently used. Thus the JSON number
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk1.000000000000000005 may, depending on platform, result in the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<tt class="docutils literal"><span class="pre">double</span></tt> value 1.0.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<h3>Signed zeros<a class="headerlink" href="#signed-zeros" title="Permalink to this headline">¶</a></h3>
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major<p>JSON makes no statement about what a number means; however Javascript
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major(ECMAscript) does state that +0.0 and -0.0 must be treated as being
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkdistinct values, i.e. -0.0 ≠ 0.0. Jansson relies on the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkunderlying floating point library in the C environment in which it is
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkcompiled. Therefore it is platform-dependent whether 0.0 and -0.0 will
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkbe distinct values. Most platforms that use the IEEE 754
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkfloating-point standard will support signed zeros.</p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<p>Note that this only applies to floating-point; neither JSON, C, or
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkIEEE support the concept of signed integer zeros.</p>
133bed8ec2ccc857a62d6301f67c3ef3d36aa333Peter Major<h3>Types<a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
66f6c6680ec1673ff6f1094a9e2b74967dd6bfb7jeff.schenk<p>No support is provided in Jansson for any C numeric types other than
16651a2450d2672ea2eb2751bd775918497432d7Phill Cunnington<tt class="docutils literal"><span class="pre">json_int_t</span></tt> and <tt class="docutils literal"><span class="pre">double</span></tt>. This excludes things such as unsigned
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Majortypes, <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt>, etc. Obviously, shorter types like <tt class="docutils literal"><span class="pre">short</span></tt>,
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major<tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt> (if <tt class="docutils literal"><span class="pre">json_int_t</span></tt> is <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>) and <tt class="docutils literal"><span class="pre">float</span></tt>
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Majorare implicitly handled via the ordinary C type coercion rules (subject
64d3fa08513695d9a3c20bdd22593aa9d0d900b4Alin Bricito overflow semantics). Also, no support or hooks are provided for any
a277eacba0534b81b8bd19173f7060a3971d03dajeff.schenksupplemental “bignum” type add-on packages.</p>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <h3><a href="index.html">Table Of Contents</a></h3>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#">RFC Conformance</a><ul>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#character-encoding">Character Encoding</a></li>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#strings">Strings</a></li>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#numbers">Numbers</a><ul>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#real-vs-integer">Real vs. Integer</a></li>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#overflow-underflow-precision">Overflow, Underflow & Precision</a></li>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#signed-zeros">Signed zeros</a></li>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk<li><a class="reference internal" href="#types">Types</a></li>
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major <form class="search" action="search.html" method="get">
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major <input type="hidden" name="check_keywords" value="yes" />
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major <input type="hidden" name="area" value="default" />
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk Enter search terms or a module, class or function name.
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk<script type="text/javascript">$('#searchbox').show(0);</script>
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk <li><a href="index.html">Jansson 2.7 documentation</a> »</li>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk © Copyright 2009-2014, Petri Lehtinen.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.