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

Merge pull request #395 from akheron/doc-utf-8

Browse Source 
Document encoding requirements for callbacks
This commit is contained in:
Petri Lehtinen 2018-02-09 10:10:34 +02:00 committed by GitHub
commit 03620980cf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/apiref.rst
View File

@ -1138,6 +1138,10 @@ These functions output UTF-8:
the length of the buffer, and *data* is the corresponding the length of the buffer, and *data* is the corresponding
:func:`json_dump_callback()` argument passed through. :func:`json_dump_callback()` argument passed through.
*buffer* is guaranteed to be a valid UTF-8 string (i.e. multi-byte
code unit sequences are preserved). *buffer* never contains
embedded null bytes.
On error, the function should return -1 to stop the encoding On error, the function should return -1 to stop the encoding
process. On success, it should return 0. process. On success, it should return 0.
@ -1333,11 +1337,19 @@ If no error or position information is needed, you can pass *NULL*.
*buffer* points to a buffer of *buflen* bytes, and *data* is the *buffer* points to a buffer of *buflen* bytes, and *data* is the
corresponding :func:`json_load_callback()` argument passed through. corresponding :func:`json_load_callback()` argument passed through.
On success, the function should return the number of bytes read; a On success, the function should write at most *buflen* bytes to
returned value of 0 indicates that no data was read and that the *buffer*, and return the number of bytes written; a returned value
end of file has been reached. On error, the function should return of 0 indicates that no data was produced and that the end of file
has been reached. On error, the function should return
``(size_t)-1`` to abort the decoding process. ``(size_t)-1`` to abort the decoding process.
In UTF-8, some code points are encoded as multi-byte sequences. The
callback function doesn't need to worry about this, as Jansson
handles it at a higher level. For example, you can safely read a
fixed number of bytes from a network connection without having to
care about code unit sequences broken apart by the chunk
boundaries.
.. versionadded:: 2.4 .. versionadded:: 2.4
.. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error) .. function:: json_t *json_load_callback(json_load_callback_t callback, void *data, size_t flags, json_error_t *error)