Converting CBOR to text

Group of functions used to convert CBOR to text form. More...

Functions
CborError	cbor_value_to_pretty_advance (FILE *out, CborValue *value)
	Converts the current CBOR type pointed by value to its textual representation and writes it to the out stream. More...
CborError	cbor_value_to_pretty (FILE *out, const CborValue *value)
	Converts the current CBOR type pointed by value to its textual representation and writes it to the out stream. More...

Detailed Description

Group of functions used to convert CBOR to text form.

This group contains two functions that are can be used to convert one CborValue object to a text representation. This module attempts to follow the recommendations from RFC 7049 section 6 "Diagnostic Notation", though it has a few differences. They are noted below.

TinyCBOR does not provide a way to convert from the text representation back to encoded form. To produce a text form meant to be parsed, CborToJson is recommended instead.

Either of the functions in this section will attempt to convert exactly one CborValue object to text. Those functions may return any error documented for the functions for CborParsing. In addition, if the C standard library stream functions return with error, the text conversion will return with error CborErrorIO.

These functions also perform UTF-8 validation in CBOR text strings. If they encounter a sequence of bytes that not permitted in UTF-8, they will return CborErrorInvalidUtf8TextString. That includes encoding of surrogate points in UTF-8.

Warning

The output type produced by these functions is not guaranteed to remain stable. A future update of TinyCBOR may produce different output for the same input and parsers may be unable to handle them.

See also

Parsing CBOR streams, Converting CBOR to JSON, cbor_parser_init()

Text format

As described in RFC 7049 section 6 "Diagnostic Notation", the format is largely borrowed from JSON, but modified to suit CBOR's different data types. TinyCBOR makes further modifications to distinguish different, but similar values.

CBOR values are currently encoded as follows:

Integrals (unsigned and negative)

Base-10 (decimal) text representation of the value

Byte strings:

"h'" followed by the Base16 (hex) representation of the binary data, followed by an ending quote (')

Text strings:

C-style escaped string in quotes, with C11/C++11 escaping of Unicode codepoints above U+007F.

Tags:

Tag value, with the tagged value in parentheses. No special encoding of the tagged value is performed.

Simple types:

"simple(nn)" where nn is the simple value

Null:

null

Undefined:

undefined

Booleans:

true or false

Floating point:

If NaN or infinite, the actual words NaN or infinite. Otherwise, the decimal representation with as many digits as necessary to ensure no loss of information, with float values suffixed by "f" and half-float values suffixed by "f16" (doubles have no suffix). A dot is always present.

Arrays:

Comma-separated list of elements, enclosed in square brackets ("[" and "]"). If the array length is indeterminate, an underscore ("_") appears immediately after the opening bracket.

Maps:

Comma-separated list of key-value pairs, with the key and value separated by a colon (":"), enclosed in curly braces ("{" and "}"). If the map length is indeterminate, an underscore ("_") appears immediately after the opening brace.

Function Documentation

cbor_value_to_pretty()

CborError cbor_value_to_pretty	(	FILE *	out,
		const CborValue *	value
	)

Converts the current CBOR type pointed by value to its textual representation and writes it to the out stream.

If an error occurs, this function returns an error code similar to CborParsing.

See also

cbor_value_to_pretty_advance(), cbor_value_to_json_advance()

cbor_value_to_pretty_advance()

CborError cbor_value_to_pretty_advance	(	FILE *	out,
		CborValue *	value
	)

Converts the current CBOR type pointed by value to its textual representation and writes it to the out stream.

If an error occurs, this function returns an error code similar to CborParsing.

If no error ocurred, this function advances value to the next element. Often, concatenating the text representation of multiple elements can be done by appending a comma to the output stream.

See also

cbor_value_to_pretty(), cbor_value_to_json_advance()

Referenced by cbor_value_to_pretty().