Utf8 json

18.4.0 released Sep 25, 2023

Utf8 json

Purpose: Convert UTF8 string to JSON text.

utf8-json <utf8> \
    to [ define ] <json> \
    [ length <length> ] \
    [ status [ define ] <status> ] \
    [ error-text [ define ] <error text> ]

utf8-json will convert <utf8> text to <json> text which can be created with optional "define". <json> is allocated memory.

<utf8> is a string that may contain UTF8 characters (as 2, 3 or 4 bytes representing a unicode character). Encoding creates a string that can be used as a value in JSON documents. utf8-json is performed according to RFC7159 (JSON standard) and RFC3629 (UTF8 standard).

Note that hexadecimal characters used in JSON for Unicode (such as \u21d7) are always lowercase. Solidus character ("/") is not escaped, although json-utf8 will correctly process it if the input has it escaped.

<json> is always allocated in utf8-json with storage sufficient to hold it.

The optional length of <utf8> can be specified with <length> in "length" clause. If <length> is not specified, it is calculated as string length of <utf8>. Note that a single UTF-8 character can be anywhere between 1 to 4 bytes. For example "љ" is 2 bytes in length.

The status of encoding can be obtained in optional <status> variable (a number), which can be created with optional "define". <status> is the string length of the result in <json> or -1 if error occurred, in which case the error text can be obtained in <error text> in optional "error-text" clause, which can be created with optional "define".

Examples

Convert UTF8 string to JSON value and verify the expected result:

// UTF8 string 
char utf8_str[] = "\"Doc\"\n\t\b\f\r\t⇗⇘\t▷◮𝄞ᏫⲠш\n/\"()\t";

// Convert UTF8 string to text
utf8-json utf8_str status define encstatus to define json_text

// This is the text expected
(( define expected_result
@\"Doc\"\n\t\b\f\r\t\u21d7\u21d8\t\u25b7\u25ee\ud834\udd1e\u13eb\u2ca0\u0448\n/\"()\t
))

// Make sure conversion was okay, decs is the length of the result (encj string)
if (!strcmp (json_text, expected_result) && encstatus!=-1) {
    @decode-json worked okay
}