1 files changed, 84 insertions, 51 deletions
diff --git a/contrib/libcbor/src/cbor/serialization.h b/contrib/libcbor/src/cbor/serialization.h
index 3f7707afca61..228ae75d6011 100644
--- a/contrib/libcbor/src/cbor/serialization.h
+++ b/contrib/libcbor/src/cbor/serialization.h
@@ -23,110 +23,143 @@ extern "C" {
 
 /** Serialize the given item
  *
- * @param item[borrow] A data item
+ * @param item A data item
  * @param buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
  * @return Length of the result. 0 on failure.
  */
-CBOR_EXPORT size_t cbor_serialize(const cbor_item_t *item,
-                                  cbor_mutable_data buffer, size_t buffer_size);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize(const cbor_item_t *item,
+                                                  cbor_mutable_data buffer,
+                                                  size_t buffer_size);
+
+/** Compute the length (in bytes) of the item when serialized using
+ * `cbor_serialize`.
+ *
+ * Time complexity is proportional to the number of nested items.
+ *
+ * @param item A data item
+ * @return Length (>= 1) of the item when serialized. 0 if the length overflows
+ * `size_t`.
+ */
+_CBOR_NODISCARD CBOR_EXPORT size_t
+cbor_serialized_size(const cbor_item_t *item);
 
 /** Serialize the given item, allocating buffers as needed
  *
+ * Since libcbor v0.10, the return value is always the same as `buffer_size` (if
+ * provided, see https://github.com/PJK/libcbor/pull/251/). New clients should
+ * ignore the return value.
+ *
  * \rst
- * .. warning:: It is your responsibility to free the buffer using an
+ * .. warning:: It is the caller's responsibility to free the buffer using an
  *  appropriate ``free`` implementation.
  * \endrst
  *
- * @param item[borrow] A data item
- * @param buffer[out] Buffer containing the result
- * @param buffer_size[out] Size of the \p buffer
- * @return Length of the result. 0 on failure, in which case \p buffer is
- * ``NULL``.
+ * @param item A data item
+ * @param[out] buffer Buffer containing the result
+ * @param[out] buffer_size Size of the \p buffer, or 0 on memory allocation
+ * failure.
+ * @return Length of the result in bytes
+ * @return 0 on memory allocation failure, in which case \p buffer is `NULL`.
  */
 CBOR_EXPORT size_t cbor_serialize_alloc(const cbor_item_t *item,
-                                        cbor_mutable_data *buffer,
+                                        unsigned char **buffer,
                                         size_t *buffer_size);
 
 /** Serialize an uint
  *
- * @param item[borrow] A uint
- * @param buffer Buffer to serialize to
+ * @param item A uint
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result
  */
-CBOR_EXPORT size_t cbor_serialize_uint(const cbor_item_t *, cbor_mutable_data,
-                                       size_t);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_uint(const cbor_item_t *item,
+                                                       cbor_mutable_data buffer,
+                                                       size_t buffer_size);
 
 /** Serialize a negint
  *
- * @param item[borrow] A neging
- * @param buffer Buffer to serialize to
+ * @param item A negint
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result
  */
-CBOR_EXPORT size_t cbor_serialize_negint(const cbor_item_t *, cbor_mutable_data,
-                                         size_t);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_negint(
+    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
 
 /** Serialize a bytestring
  *
- * @param item[borrow] A bytestring
- * @param buffer Buffer to serialize to
+ * @param item A bytestring
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
+ * still be modified
  */
-CBOR_EXPORT size_t cbor_serialize_bytestring(const cbor_item_t *,
-                                             cbor_mutable_data, size_t);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_bytestring(
+    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
 
 /** Serialize a string
  *
- * @param item[borrow] A string
- * @param buffer Buffer to serialize to
+ * @param item A string
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
+ * still be modified
  */
-CBOR_EXPORT size_t cbor_serialize_string(const cbor_item_t *, cbor_mutable_data,
-                                         size_t);
-
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_string(
+    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
 /** Serialize an array
  *
- * @param item[borrow] An array
- * @param buffer Buffer to serialize to
+ * @param item An array
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
+ * still be modified
  */
-CBOR_EXPORT size_t cbor_serialize_array(const cbor_item_t *, cbor_mutable_data,
-                                        size_t);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_array(
+    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
 
 /** Serialize a map
  *
- * @param item[borrow] A map
- * @param buffer Buffer to serialize to
+ * @param item A map
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
+ * still be modified
  */
-CBOR_EXPORT size_t cbor_serialize_map(const cbor_item_t *, cbor_mutable_data,
-                                      size_t);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_map(const cbor_item_t *item,
+                                                      cbor_mutable_data buffer,
+                                                      size_t buffer_size);
 
 /** Serialize a tag
  *
- * @param item[borrow] A tag
- * @param buffer Buffer to serialize to
+ * @param item A tag
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result. The \p buffer may
+ * still be modified
  */
-CBOR_EXPORT size_t cbor_serialize_tag(const cbor_item_t *, cbor_mutable_data,
-                                      size_t);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_tag(const cbor_item_t *item,
+                                                      cbor_mutable_data buffer,
+                                                      size_t buffer_size);
 
 /** Serialize a
  *
- * @param item[borrow] A float or ctrl
- * @param buffer Buffer to serialize to
+ * @param item A float or ctrl
+ * @param[out] buffer Buffer to serialize to
  * @param buffer_size Size of the \p buffer
- * @return Length of the result. 0 on failure.
+ * @return Length of the result
+ * @return 0 if the \p buffer_size doesn't fit the result
  */
-CBOR_EXPORT size_t cbor_serialize_float_ctrl(const cbor_item_t *,
-                                             cbor_mutable_data, size_t);
+_CBOR_NODISCARD CBOR_EXPORT size_t cbor_serialize_float_ctrl(
+    const cbor_item_t *item, cbor_mutable_data buffer, size_t buffer_size);
 
 #ifdef __cplusplus
 }