diff options
Diffstat (limited to 'src/cbor/floats_ctrls.h')
| -rw-r--r-- | src/cbor/floats_ctrls.h | 114 |
1 files changed, 71 insertions, 43 deletions
diff --git a/src/cbor/floats_ctrls.h b/src/cbor/floats_ctrls.h index 92eb8bc3eaa3..335eab8328be 100644 --- a/src/cbor/floats_ctrls.h +++ b/src/cbor/floats_ctrls.h @@ -23,111 +23,131 @@ extern "C" { /** Is this a ctrl value? * - * @param item[borrow] A float or ctrl item + * @param item A float or ctrl item * @return Is this a ctrl value? */ -CBOR_EXPORT bool cbor_float_ctrl_is_ctrl(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT bool cbor_float_ctrl_is_ctrl( + const cbor_item_t *item); /** Get the float width * - * @param item[borrow] A float or ctrl item + * @param item A float or ctrl item * @return The width. */ -CBOR_EXPORT cbor_float_width cbor_float_get_width(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT cbor_float_width +cbor_float_get_width(const cbor_item_t *item); /** Get a half precision float * * The item must have the corresponding width * - * @param[borrow] A half precision float + * @param item A half precision float * @return half precision value */ -CBOR_EXPORT float cbor_float_get_float2(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT float cbor_float_get_float2( + const cbor_item_t *item); /** Get a single precision float * * The item must have the corresponding width * - * @param[borrow] A signle precision float + * @param item A single precision float * @return single precision value */ -CBOR_EXPORT float cbor_float_get_float4(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT float cbor_float_get_float4( + const cbor_item_t *item); /** Get a double precision float * * The item must have the corresponding width * - * @param[borrow] A double precision float + * @param item A double precision float * @return double precision value */ -CBOR_EXPORT double cbor_float_get_float8(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT double cbor_float_get_float8( + const cbor_item_t *item); /** Get the float value represented as double * * Can be used regardless of the width. * - * @param[borrow] Any float + * @param item Any float * @return double precision value */ -CBOR_EXPORT double cbor_float_get_float(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT double cbor_float_get_float( + const cbor_item_t *item); /** Get value from a boolean ctrl item * - * @param item[borrow] A ctrl item + * @param item A ctrl item * @return boolean value */ -CBOR_EXPORT bool cbor_get_bool(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT bool cbor_get_bool(const cbor_item_t *item); /** Constructs a new ctrl item * * The width cannot be changed once the item is created * - * @return **new** 1B ctrl or `NULL` upon memory allocation failure + * @return Reference to the new ctrl item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_new_ctrl(); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_ctrl(void); /** Constructs a new float item * * The width cannot be changed once the item is created * - * @return **new** 2B float or `NULL` upon memory allocation failure + * @return Reference to the new float item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_new_float2(); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_float2(void); /** Constructs a new float item * * The width cannot be changed once the item is created * - * @return **new** 4B float or `NULL` upon memory allocation failure + * @return Reference to the new float item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_new_float4(); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_float4(void); /** Constructs a new float item * * The width cannot be changed once the item is created * - * @return **new** 8B float or `NULL` upon memory allocation failure + * @return Reference to the new float item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_new_float8(); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_float8(void); /** Constructs new null ctrl item * - * @return **new** null ctrl item or `NULL` upon memory allocation failure + * @return Reference to the new null item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_new_null(); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_null(void); /** Constructs new undef ctrl item * - * @return **new** undef ctrl item or `NULL` upon memory allocation failure + * @return Reference to the new undef item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_new_undef(); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_new_undef(void); /** Constructs new boolean ctrl item * * @param value The value to use - * @return **new** boolen ctrl item or `NULL` upon memory allocation failure + * @return Reference to the new boolean item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_build_bool(bool value); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_bool(bool value); /** Assign a control value * @@ -136,7 +156,7 @@ CBOR_EXPORT cbor_item_t *cbor_build_bool(bool value); * invalid value using this mechanism. Please consult the standard before use. * \endrst * - * @param item[borrow] A ctrl item + * @param item A ctrl item * @param value The simple value to assign. Please consult the standard for * allowed values */ @@ -144,66 +164,74 @@ CBOR_EXPORT void cbor_set_ctrl(cbor_item_t *item, uint8_t value); /** Assign a boolean value to a boolean ctrl item * - * @param item[borrow] A ctrl item + * @param item A ctrl item * @param value The simple value to assign. */ CBOR_EXPORT void cbor_set_bool(cbor_item_t *item, bool value); /** Assigns a float value * - * @param item[borrow] A half precision float + * @param item A half precision float * @param value The value to assign */ CBOR_EXPORT void cbor_set_float2(cbor_item_t *item, float value); /** Assigns a float value * - * @param item[borrow] A single precision float + * @param item A single precision float * @param value The value to assign */ CBOR_EXPORT void cbor_set_float4(cbor_item_t *item, float value); /** Assigns a float value * - * @param item[borrow] A double precision float + * @param item A double precision float * @param value The value to assign */ CBOR_EXPORT void cbor_set_float8(cbor_item_t *item, double value); /** Reads the control value * - * @param item[borrow] A ctrl item + * @param item A ctrl item * @return the simple value */ -CBOR_EXPORT uint8_t cbor_ctrl_value(const cbor_item_t *item); +_CBOR_NODISCARD CBOR_EXPORT uint8_t cbor_ctrl_value(const cbor_item_t *item); /** Constructs a new float * * @param value the value to use - * @return **new** float + * @return Reference to the new float item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_build_float2(float value); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_float2(float value); /** Constructs a new float * * @param value the value to use - * @return **new** float or `NULL` upon memory allocation failure + * @return Reference to the new float item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_build_float4(float value); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_float4(float value); /** Constructs a new float * * @param value the value to use - * @return **new** float or `NULL` upon memory allocation failure + * @return Reference to the new float item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_build_float8(double value); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_float8(double value); /** Constructs a ctrl item * * @param value the value to use - * @return **new** ctrl item or `NULL` upon memory allocation failure + * @return Reference to the new ctrl item. The item's reference count is + * initialized to one. + * @return `NULL` if memory allocation fails */ -CBOR_EXPORT cbor_item_t *cbor_build_ctrl(uint8_t value); +_CBOR_NODISCARD CBOR_EXPORT cbor_item_t *cbor_build_ctrl(uint8_t value); #ifdef __cplusplus } |