From 6e3ca5c45c984a27d0f5c9b9249e17ef0c412e3a Mon Sep 17 00:00:00 2001 From: Petri Lehtinen Date: Wed, 16 Jun 2010 21:34:10 +0300 Subject: [PATCH] Clarify the documentation 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(). --- doc/apiref.rst | 23 +++++++++++++++++++---- doc/conformance.rst | 2 ++ 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/doc/apiref.rst b/doc/apiref.rst index bacd756..2c6cf3b 100644 --- a/doc/apiref.rst +++ b/doc/apiref.rst @@ -244,6 +244,12 @@ returns the same value each time. String ====== +Jansson uses UTF-8 as the character encoding. All JSON strings must be +valid UTF-8 (or ASCII, as it's a subset of UTF-8). Normal null +terminated C strings are used, so JSON strings may not contain +embedded null characters. All other Unicode codepoints U+0001 through +U+10FFFF are allowed. + .. cfunction:: json_t *json_string(const char *value) .. refcounting:: new @@ -287,6 +293,12 @@ String Number ====== +The JSON specification only contains one numeric type, "number". The C +programming language has distinct types for integer and floating-point +numbers, so for practical reasons Jansson also has distinct types for +the two. They are called "integer" and "real", respectively. For more +information, see :ref:`rfc-conformance`. + .. cfunction:: json_t *json_integer(int value) .. refcounting:: new @@ -656,10 +668,12 @@ This sections describes the functions that can be used to decode JSON text to the Jansson representation of JSON data. The JSON specification requires that a JSON text is either a serialized array or object, and this requirement is also enforced with the following -functions. +functions. In other words, the top level value in the JSON text being +decoded must be either array or object. -The only supported character encoding is UTF-8 (which ASCII is a -subset of). +See :ref:`rfc-conformance` for a discussion on Jansson's conformance +to the JSON specification. It explains many design decisions that +affect especially the behavior of the decoder. .. ctype:: json_error_t @@ -744,7 +758,8 @@ only if they are exactly the same value, but also if they have equal values are equal. An integer value is never equal to a real value, though. -* Two strings are equal if their contained UTF-8 strings are equal. +* Two strings are equal if their contained UTF-8 strings are equal, + byte by byte. Unicode comparison algorithms are not implemented. * Two arrays are equal if they have the same number of elements and each element in the first array is equal to the corresponding diff --git a/doc/conformance.rst b/doc/conformance.rst index 785a94d..3bfe51d 100644 --- a/doc/conformance.rst +++ b/doc/conformance.rst @@ -1,3 +1,5 @@ +.. _rfc-conformance: + *************** RFC Conformance *************** -- 2.1.4