summaryrefslogtreecommitdiff
path: root/Documentation/technical/api-allocation-growing.txt
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2007-11-25 07:48:04 (GMT)
committerJunio C Hamano <gitster@pobox.com>2007-12-15 06:29:38 (GMT)
commit530e741c726a612d78de21957d531dd2215483b4 (patch)
tree52cc876e8da8eb90edfabb1f85159d065a78bc91 /Documentation/technical/api-allocation-growing.txt
parentfa4701601a62664a9246a211c5d26f238820737e (diff)
downloadgit-530e741c726a612d78de21957d531dd2215483b4.zip
git-530e741c726a612d78de21957d531dd2215483b4.tar.gz
git-530e741c726a612d78de21957d531dd2215483b4.tar.bz2
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 <gitster@pobox.com>
Diffstat (limited to 'Documentation/technical/api-allocation-growing.txt')
-rw-r--r--Documentation/technical/api-allocation-growing.txt34
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.