From: Junio C Hamano <gitster@pobox.com>
Date: Sat, 7 Oct 2017 07:27:53 +0000 (+0900)
Subject: Merge branch 'jn/strbuf-doc-re-reuse'
X-Git-Tag: v2.15.0-rc1~24
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/aae4788eee306cd4923b765cc4768fee2e7ca13e?hp=-c

Merge branch 'jn/strbuf-doc-re-reuse'

* jn/strbuf-doc-re-reuse:
strbuf doc: reuse after strbuf_release is fine
---

aae4788eee306cd4923b765cc4768fee2e7ca13e
diff --combined strbuf.h
index 7496cb8ec5,80112a8c26..0a74acb236
--- a/strbuf.h
+++ b/strbuf.h
@@@ -68,7 -68,7 +68,7 @@@ struct strbuf 
  };
  
  extern char strbuf_slopbuf[];
 -#define STRBUF_INIT  { 0, 0, strbuf_slopbuf }
 +#define STRBUF_INIT  { .alloc = 0, .len = 0, .buf = strbuf_slopbuf }
  
  /**
   * Life Cycle Functions
@@@ -82,8 -82,12 +82,12 @@@
  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 +95,9 @@@
   * 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 *);
  
@@@ -147,10 -154,7 +154,10 @@@ static inline void strbuf_setlen(struc
  	if (len > (sb->alloc ? sb->alloc - 1 : 0))
  		die("BUG: strbuf_setlen() beyond buffer");
  	sb->len = len;
 -	sb->buf[len] = '\0';
 +	if (sb->buf != strbuf_slopbuf)
 +		sb->buf[len] = '\0';
 +	else
 +		assert(!strbuf_slopbuf[0]);
  }
  
  /**