path: root/strbuf.h
diff options
authorJunio C Hamano <>2017-10-07 07:27:53 (GMT)
committerJunio C Hamano <>2017-10-07 07:27:53 (GMT)
commitaae4788eee306cd4923b765cc4768fee2e7ca13e (patch)
tree84c377cfd270d42a99fe9c3ecf751add30984a54 /strbuf.h
parent436b35942cb5198a8d5e915690e65ee1c860baf2 (diff)
parente0222159fa53ea24785cfb1dc5de0214e89b0117 (diff)
Merge branch 'jn/strbuf-doc-re-reuse'
* jn/strbuf-doc-re-reuse: strbuf doc: reuse after strbuf_release is fine
Diffstat (limited to 'strbuf.h')
1 files changed, 9 insertions, 2 deletions
diff --git a/strbuf.h b/strbuf.h
index 7496cb8..0a74acb 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -82,8 +82,12 @@ extern char strbuf_slopbuf[];
extern void strbuf_init(struct strbuf *, size_t);
- * Release a string buffer and the memory it used. You should not use the
- * string buffer after using this function, unless you initialize it again.
+ * Release a string buffer and the memory it used. After this call, the
+ * strbuf points to an empty string that does not need to be free()ed, as
+ * if it had been set to `STRBUF_INIT` and never modified.
+ *
+ * To clear a strbuf in preparation for further use without the overhead
+ * of free()ing and malloc()ing again, use strbuf_reset() instead.
extern void strbuf_release(struct strbuf *);
@@ -91,6 +95,9 @@ extern void strbuf_release(struct strbuf *);
* Detach the string from the strbuf and returns it; you now own the
* storage the string occupies and it is your responsibility from then on
* to release it with `free(3)` when you are done with it.
+ *
+ * The strbuf that previously held the string is reset to `STRBUF_INIT` so
+ * it can be reused after calling this function.
extern char *strbuf_detach(struct strbuf *, size_t *);