about summary refs log tree commit diff
path: root/third_party/git/Documentation/technical/api-allocation-growing.txt
diff options
context:
space:
mode:
authorVincent Ambo <Vincent Ambo>2020-01-11T23·36+0000
committerVincent Ambo <Vincent Ambo>2020-01-11T23·40+0000
commit7ef0d62730840ded097b524104cc0a0904591a63 (patch)
treea670f96103667aeca4789a95d94ca0dff550c4ce /third_party/git/Documentation/technical/api-allocation-growing.txt
parent6a2a3007077818e24a3d56fc492ada9206a10cf0 (diff)
parent1b593e1ea4d2af0f6444d9a7788d5d99abd6fde5 (diff)
merge(third_party/git): Merge squashed git subtree at v2.23.0 r/373
Merge commit '1b593e1ea4d2af0f6444d9a7788d5d99abd6fde5' as 'third_party/git'
Diffstat (limited to 'third_party/git/Documentation/technical/api-allocation-growing.txt')
-rw-r--r--third_party/git/Documentation/technical/api-allocation-growing.txt39
1 files changed, 39 insertions, 0 deletions
diff --git a/third_party/git/Documentation/technical/api-allocation-growing.txt b/third_party/git/Documentation/technical/api-allocation-growing.txt
new file mode 100644
index 000000000000..5a59b548448f
--- /dev/null
+++ b/third_party/git/Documentation/technical/api-allocation-growing.txt
@@ -0,0 +1,39 @@
+allocation growing API
+======================
+
+Dynamically growing an array using realloc() is error prone and boring.
+
+Define your array with:
+
+* a pointer (`item`) that points at the array, initialized to `NULL`
+  (although please name the variable based on its contents, not on its
+  type);
+
+* an integer variable (`alloc`) that keeps track of how big the current
+  allocation is, initialized to `0`;
+
+* another integer variable (`nr`) to keep track of how many elements the
+  array currently has, initialized to `0`.
+
+Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
+alloc)`.  This ensures that the array can hold at least `n` elements by
+calling `realloc(3)` and adjusting `alloc` variable.
+
+------------
+sometype *item;
+size_t nr;
+size_t alloc
+
+for (i = 0; i < nr; i++)
+	if (we like item[i] already)
+		return;
+
+/* we did not like any existing one, so add one */
+ALLOC_GROW(item, nr + 1, alloc);
+item[nr++] = value you like;
+------------
+
+You are responsible for updating the `nr` variable.
+
+If you need to specify the number of elements to allocate explicitly
+then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`.