Create docs page for bson_alloc_array(0)

Author: Julia-Garland

src/common/src/common-bson-dsl-private.h

@@ -659,24 +659,24 @@ BSON_IF_GNU_LIKE(_Pragma("GCC diagnostic ignored \"-Wshadow\""))
       }                                      \
    } while (0);
 
-#define _bsonParseMarkVisited(Index)                                                                \
-   if (1) {                                                                                         \
-      const size_t nth_int = Index / 64u;                                                           \
-      const size_t nth_bit = Index % 64u;                                                           \
-      while (nth_int >= _bpNumVisitBitInts) {                                                       \
-         /* Say that five times, fast: */                                                           \
-         size_t new_num_visit_bit_ints = _bpNumVisitBitInts * 2u;                                   \
+#define _bsonParseMarkVisited(Index)                                                                 \
+   if (1) {                                                                                          \
+      const size_t nth_int = Index / 64u;                                                            \
+      const size_t nth_bit = Index % 64u;                                                            \
+      while (nth_int >= _bpNumVisitBitInts) {                                                        \
+         /* Say that five times, fast: */                                                            \
+         size_t new_num_visit_bit_ints = _bpNumVisitBitInts * 2u;                                    \
          uint64_t *new_visit_bit_ints = bson_array_alloc0(sizeof(uint64_t), new_num_visit_bit_ints); \
-         memcpy(new_visit_bit_ints, _bpVisitBits, sizeof(uint64_t) * _bpNumVisitBitInts);           \
-         if (_bpVisitBits != _bpVisitBits_static) {                                                 \
-            bson_free(_bpVisitBits);                                                                \
-         }                                                                                          \
-         _bpVisitBits = new_visit_bit_ints;                                                         \
-         _bpNumVisitBitInts = new_num_visit_bit_ints;                                               \
-      }                                                                                             \
-                                                                                                    \
-      _bpVisitBits[nth_int] |= (UINT64_C(1) << nth_bit);                                            \
-   } else                                                                                           \
+         memcpy(new_visit_bit_ints, _bpVisitBits, sizeof(uint64_t) * _bpNumVisitBitInts);            \
+         if (_bpVisitBits != _bpVisitBits_static) {                                                  \
+            bson_free(_bpVisitBits);                                                                 \
+         }                                                                                           \
+         _bpVisitBits = new_visit_bit_ints;                                                          \
+         _bpNumVisitBitInts = new_num_visit_bit_ints;                                                \
+      }                                                                                              \
+                                                                                                     \
+      _bpVisitBits[nth_int] |= (UINT64_C(1) << nth_bit);                                             \
+   } else                                                                                            \
       ((void)0)
 
 #define _bsonParseDidVisitNth(Index) _bsonParseDidVisitNth_1(Index / 64u, Index % 64u)

src/libbson/doc/bson_alloc_array.rst

@@ -0,0 +1,36 @@
+:man_page: bson_alloc_array
+
+bson_alloc_array()
+=============
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void *
+  bson_alloc_array (size_t type_size, size_t num_elems);
+
+Parameters
+----------
+
+* ``type_size``: A size_t containing the size in bytes of a single object in the array. 
+* ``num_elems``: A size_t containing the number of objects to be stored in the array.
+
+Description
+-----------
+
+This is a portable ``malloc()`` wrapper to allocate an array of objects.
+
+In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger.
+
+If there was a failure to allocate ``type_size * num_elems`` bytes, the process will be aborted.
+
+.. warning::
+
+  This function will abort on failure to allocate memory.
+
+Returns
+-------
+
+A pointer to a memory region which *HAS NOT* been zeroed.

src/libbson/doc/bson_alloc_array0.rst

@@ -0,0 +1,36 @@
+:man_page: bson_alloc_array0
+
+bson_alloc_array0()
+=============
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void *
+  bson_alloc_array0 (size_t type_size, size_t num_elems);
+
+Parameters
+----------
+
+* ``type_size``: A size_t containing the size in bytes of a single object in the array. 
+* ``num_elems``: A size_t containing the number of objects to be stored in the array.
+
+Description
+-----------
+
+This is a portable ``malloc()`` wrapper to allocate an array of objects that also sets the memory to zero.
+
+In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger.
+
+If there was a failure to allocate ``type_size * num_elems`` bytes, the process will be aborted.
+
+.. warning::
+
+  This function will abort on failure to allocate memory.
+
+Returns
+-------
+
+A pointer to a memory region which *HAS* been zeroed.

src/libbson/doc/bson_memory.rst

@@ -26,6 +26,8 @@ To aid in language binding integration, Libbson allows for setting a custom memo
     bson_malloc0
     bson_aligned_alloc
     bson_aligned_alloc0
+    bson_array_alloc
+    bson_array_alloc0
     bson_mem_restore_vtable
     bson_mem_set_vtable
     bson_realloc