path: root/Documentation/technical/api-allocation-growing.txt
diff options
authorJunio C Hamano <>2007-11-25 07:48:04 (GMT)
committerJunio C Hamano <>2007-12-15 06:29:38 (GMT)
commit530e741c726a612d78de21957d531dd2215483b4 (patch)
tree52cc876e8da8eb90edfabb1f85159d065a78bc91 /Documentation/technical/api-allocation-growing.txt
parentfa4701601a62664a9246a211c5d26f238820737e (diff)
Start preparing the API documents.
Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/technical/api-allocation-growing.txt')
1 files changed, 34 insertions, 0 deletions
diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt
new file mode 100644
index 0000000..43dbe09
--- /dev/null
+++ b/Documentation/technical/api-allocation-growing.txt
@@ -0,0 +1,34 @@
+allocation growing API
+Dynamically growing an array using realloc() is error prone and boring.
+Define your array with:
+* a pointer (`ary`) that points at the array, initialized to `NULL`;
+* 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 array, call `ALLOC_GROW(ary, n,
+alloc)`. This ensures that the array can hold at least `n` elements by
+calling `realloc(3)` and adjusting `alloc` variable.
+sometype *ary;
+size_t nr;
+size_t alloc
+for (i = 0; i < nr; i++)
+ if (we like ary[i] already)
+ return;
+/* we did not like any existing one, so add one */
+ALLOC_GROW(ary, nr + 1, alloc);
+ary[nr++] = value you like;
+You are responsible for updating the `nr` variable.