Converting CBOR to text

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

Enumerations
enum	CborPrettyFlags
	The CborPrettyFlags enum contains flags that control the conversion of CBOR to text format. More...

Functions
CborError	cbor_value_to_pretty_stream (CborStreamFunction streamFunction, void *token, CborValue *value, int flags)
	Converts the current CBOR type pointed by value to its textual representation and writes it to the stream by calling the streamFunction. More...

Detailed Description

Group of functions used to convert CBOR to text form.

This group contains two functions that can be used to convert a 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 is 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 it.

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. By default, float values are suffixed by "f" and half-float values suffixed by "f16" (doubles have no suffix). If the CborPrettyNumericEncodingIndicators flag is active, the values instead are encoded following the Section 6 recommended encoding indicators: float values are suffixed with "_2" and half-float with "_1". A decimal point is always present.

Arrays:

Comma-separated list of elements, enclosed in square brackets ("[" and "]").

Maps:

Comma-separated list of key-value pairs, with the key and value separated by a colon (":"), enclosed in curly braces ("{" and "}").

The CborPrettyFlags enumerator contains flags to control some aspects of the encoding:

String fragmentation

When the CborPrettyShowStringFragments option is active, text and byte strings that are transmitted in fragments are shown instead inside parentheses ("(" and ")") with no preceding number and each fragment is displayed individually. If a tag precedes the string, then the output will contain a double set of parentheses. If the option is not active, the fragments are merged together and the display will not show any difference from a string transmitted with determinate length.

Encoding indicators

Numbers and lengths in CBOR can be encoded in multiple representations. If the CborPrettyIndicateOverlongNumbers option is active, numbers and lengths that are transmitted in a longer encoding than necessary will be indicated, by appending an underscore ("_") to either the number or the opening bracket or brace, followed by a number indicating the CBOR additional information: 0 for 1 byte, 1 for 2 bytes, 2 for 4 bytes and 3 for 8 bytes. If the CborPrettyIndicateIndeterminateLength option is active, maps, arrays and strings encoded with indeterminate length will be marked by an underscore after the opening bracket or brace or the string (if not showing fragments), without a number after it.

Enumeration Type Documentation

CborPrettyFlags

enum CborPrettyFlags

The CborPrettyFlags enum contains flags that control the conversion of CBOR to text format.

• CborPrettyNumericEncodingIndicators Use numeric encoding indicators instead of textual for float and half-float.
• CborPrettyTextualEncodingIndicators Use textual encoding indicators for float ("f") and half-float ("f16").
• CborPrettyIndicateIndeterminateLength (default) Indicate when a map or array has indeterminate length.
• CborPrettyIndicateOverlongNumbers Indicate when a number or length was encoded with more bytes than needed.
• CborPrettyShowStringFragments If the byte or text string is transmitted in chunks, show each individually.
• CborPrettyMergeStringFragment Merge all chunked byte or text strings and display them in a single entry.
• CborPrettyDefaultFlags Default conversion flags.

Function Documentation

cbor_value_to_pretty_stream()

CborError cbor_value_to_pretty_stream	(	CborStreamFunction	streamFunction,
		void *	token,
		CborValue *	value,
		int	flags
	)

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

If an error occurs, this function returns an error code similar to Parsing CBOR streams.

The textual representation can be controlled by the flags parameter (see CborPrettyFlags for more information).

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 in between calls to this function.

The streamFunction function will be called with the token value as the first parameter and a printf-style format string as the second, with a variable number of further parameters.

See also

cbor_value_to_pretty(), cbor_value_to_json_advance()

Referenced by cbor_value_to_pretty_advance(), and cbor_value_to_pretty_advance_flags().