1Type 7 – Floats & control tokens 2================================= 3 4This type combines two completely unrelated types of items -- floating point numbers and special values such as true, false, null, etc. We refer to these special values as 'control values' or 'ctrls' for short throughout the code. 5 6Just like integers, they have different possible width (resulting in different value ranges and precisions). 7 8.. doxygenenum:: cbor_float_width 9 10================================== ========================================= 11Corresponding :type:`cbor_type` ``CBOR_TYPE_FLOAT_CTRL`` 12Number of allocations One per lifetime 13Storage requirements ``sizeof(cbor_item_t) + 1/4/8`` 14================================== ========================================= 15 16Getting metadata 17~~~~~~~~~~~~~~~~~ 18 19.. doxygenfunction:: cbor_float_ctrl_is_ctrl 20.. doxygenfunction:: cbor_float_get_width 21.. doxygenfunction:: cbor_ctrl_is_bool 22 23Reading data 24~~~~~~~~~~~~~ 25 26.. doxygenfunction:: cbor_float_get_float2 27.. doxygenfunction:: cbor_float_get_float4 28.. doxygenfunction:: cbor_float_get_float8 29.. doxygenfunction:: cbor_float_get_float 30.. doxygenfunction:: cbor_ctrl_value 31.. doxygenfunction:: 32 33Creating new items 34~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 35 36.. doxygenfunction:: cbor_new_ctrl 37.. doxygenfunction:: cbor_new_float2 38.. doxygenfunction:: cbor_new_float4 39.. doxygenfunction:: cbor_new_float8 40.. doxygenfunction:: cbor_new_null 41.. doxygenfunction:: cbor_new_undef 42 43 44Building items 45~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47.. doxygenfunction:: cbor_build_bool 48.. doxygenfunction:: cbor_build_ctrl 49.. doxygenfunction:: cbor_build_float2 50.. doxygenfunction:: cbor_build_float4 51.. doxygenfunction:: cbor_build_float8 52 53 54Manipulating existing items 55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 57.. doxygenfunction:: cbor_set_ctrl 58.. doxygenfunction:: cbor_set_float2 59.. doxygenfunction:: cbor_set_float4 60.. doxygenfunction:: cbor_set_float8 61 62 63.. _api_type_7_hard_floats: 64 65Half floats 66~~~~~~~~~~~~ 67CBOR supports two `bytes wide ("half-precision") <https://en.wikipedia.org/wiki/Half-precision_floating-point_format>`_ 68floats which are not supported by the C language. *libcbor* represents them using :type:`float` 69values throughout the API, which has important implications when manipulating these values. 70 71In particular, if a user uses some of the manipulation APIs 72(e.g. :func:`cbor_set_float2`, :func:`cbor_new_float2`) 73to introduce a value that doesn't have an exect half-float representation, 74the encoding semantics are given by :func:`cbor_encode_half` as follows: 75 76.. doxygenfunction:: cbor_encode_half 77