FGCOM/jansson
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document JSON_ALLOW_NUL and clarify NUL byte handling

Browse Source
This commit is contained in:
Petri Lehtinen 2013-09-30 10:52:49 +03:00
parent 1bfc33362e
commit f8d8d524cf
2 changed files with 24 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/apiref.rst
View File

@ -294,8 +294,9 @@ String
Jansson uses UTF-8 as the character encoding. All JSON strings must be 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 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 terminated C strings are used, so JSON strings may not contain
embedded null characters. All other Unicode codepoints U+0001 through embedded null characters. All other Unicode codepoints U+0000 through
U+10FFFF are allowed. U+10FFFF are allowed, but you must use length-aware functions if you
wish to embed NUL bytes in strings.
.. function:: json_t *json_string(const char *value) .. function:: json_t *json_string(const char *value)
@ -568,6 +569,9 @@ Object
A JSON object is a dictionary of key-value pairs, where the key is a A JSON object is a dictionary of key-value pairs, where the key is a
Unicode string and the value is any JSON value. Unicode string and the value is any JSON value.
Even though NUL bytes are allowed in string values, they are not
allowed in object keys.
.. function:: json_t *json_object(void) .. function:: json_t *json_object(void)
.. refcounting:: new .. refcounting:: new
@ -987,6 +991,19 @@ macros can be ORed together to obtain *flags*.
.. versionadded:: 2.5 .. versionadded:: 2.5
``JSON_ALLOW_NUL``
Allow ``\u0000`` escape inside string values. This is a safety
measure; If you know your input can contain NUL bytes, use this
flag. If you don't use this flag, you don't have to worry about NUL
bytes inside strings unless you explicitly create themselves by
using e.g. :func:`json_stringn()` or ``s#`` format specifier for
:func:`json_pack()`.
Object keys cannot have embedded NUL bytes even if this flag is
used.
.. versionadded:: 2.6
Each function also takes an optional :type:`json_error_t` parameter Each function also takes an optional :type:`json_error_t` parameter
that is filled with error information if decoding fails. It's also that is filled with error information if decoding fails. It's also
updated on success; the number of bytes of input read is written to updated on success; the number of bytes of input read is written to

7
doc/conformance.rst
View File

@ -19,8 +19,11 @@ Strings
======= =======
JSON strings are mapped to C-style null-terminated character arrays, JSON strings are mapped to C-style null-terminated character arrays,
and UTF-8 encoding is used internally. All Unicode codepoints U+0000 and UTF-8 encoding is used internally.
through U+10FFFF are allowed.
All Unicode codepoints U+0000 through U+10FFFF are allowed in string
values. However, U+0000 is not allowed in object keys because of API
restrictions.
Unicode normalization or any other transformation is never performed Unicode normalization or any other transformation is never performed
on any strings (string values or object keys). When checking for on any strings (string values or object keys). When checking for