Un-deprecate alloc, add docs and changelog

CHANGELOG.md

@@ -18,6 +18,9 @@ Next
   - Previously, the failures were not handled in the interface. Now, `cbor_copy` may return `NULL` upon failure; clients should check the return value
 - [Fix `cbor_build_tag` illegal memory behavior when the allocator fails](https://github.com/PJK/libcbor/pull/249)
 - [Add a new `cbor_serialized_size` API](https://github.com/PJK/libcbor/pull/250)
+- [Reworked `cbor_serialize_alloc` to allocate the exact amount of memory necessary upfront](https://github.com/PJK/libcbor/pull/251)
+  - This should significantly speed up `cbor_serialize_alloc` for large items by avoiding multiple reallocation iterations
+  - Clients should not use the return value of `cbor_serialize_alloc`. It may be removed in the future.
 
 
 0.9.0 (2021-11-14)

README.md

@@ -76,12 +76,12 @@ int main(int argc, char * argv[])
 		.key = cbor_move(cbor_build_uint8(42)),
 		.value = cbor_move(cbor_build_string("Is the answer"))
 	});
-	/* Output: `length` bytes of data in the `buffer` */
+	/* Output: `buffer_size` bytes of data in the `buffer` */
 	unsigned char * buffer;
-	size_t buffer_size,
-		length = cbor_serialize_alloc(root, &buffer, &buffer_size);
+	size_t buffer_size;
+	cbor_serialize_alloc(root, &buffer, &buffer_size);
 
-	fwrite(buffer, 1, length, stdout);
+	fwrite(buffer, 1, buffer_size, stdout);
 	free(buffer);
 
 	fflush(stdout);

doc/source/using.rst

@@ -75,11 +75,12 @@ of what is it CBOR does, the examples (located in the ``examples`` directory) sh
             .key = cbor_move(cbor_build_uint8(42)),
             .value = cbor_move(cbor_build_string("Is the answer"))
         });
-        /* Output: `length` bytes of data in the `buffer` */
+        /* Output: `buffer_size` bytes of data in the `buffer` */
         unsigned char * buffer;
-        size_t buffer_size, length = cbor_serialize_alloc(root, &buffer, &buffer_size);
+        size_t buffer_size;
+        cbor_serialize_alloc(root, &buffer, &buffer_size);
 
-        fwrite(buffer, 1, length, stdout);
+        fwrite(buffer, 1, buffer_size, stdout);
         free(buffer);
 
         fflush(stdout);

examples/cjson2cbor.c

@@ -133,10 +133,10 @@ int main(int argc, char *argv[]) {
 
   /* Print out CBOR bytes */
   unsigned char *buffer;
-  size_t buffer_size,
-      cbor_length = cbor_serialize_alloc(cbor, &buffer, &buffer_size);
+  size_t buffer_size;
+  cbor_serialize_alloc(cbor, &buffer, &buffer_size);
 
-  fwrite(buffer, 1, cbor_length, stdout);
+  fwrite(buffer, 1, buffer_size, stdout);
 
   free(buffer);
   fflush(stdout);

src/cbor/serialization.h

@@ -45,9 +45,13 @@ _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
  *
@@ -57,8 +61,9 @@ cbor_serialized_size(const cbor_item_t *item);
  * @return Length of the result. 0 on failure, in which case \p buffer is
  * ``NULL``.
  */
-_CBOR_NODISCARD CBOR_DEPRECATED CBOR_EXPORT size_t cbor_serialize_alloc(
-    const cbor_item_t *item, cbor_mutable_data *buffer, size_t *buffer_size);
+CBOR_EXPORT size_t cbor_serialize_alloc(const cbor_item_t *item,
+                                        cbor_mutable_data *buffer,
+                                        size_t *buffer_size);
 
 /** Serialize an uint
  *