From: Lucas De Marchi <lucas.de.marchi@gmail.com>
Date: Tue, 12 Nov 2024 15:25:52 +0000 (-0600)
Subject: strbuf: Document strbuf_popchar(s)
X-Git-Tag: v34~92
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b8776806de69062ec8b7e69c56d67694fbad9f4a;p=thirdparty%2Fkmod.git

strbuf: Document strbuf_popchar(s)

Document the behavior for these functions and also clarify why the
testsuite can check the buffer for equality after calling strbuf_str().

Signed-off-by: Lucas De Marchi <lucas.de.marchi@gmail.com>
Reviewed-by: Emil Velikov <emil.l.velikov@gmail.com>
Link: https://github.com/kmod-project/kmod/pull/239
---

diff --git a/shared/strbuf.h b/shared/strbuf.h
index 8824afdc..64a5ba00 100644
--- a/shared/strbuf.h
+++ b/shared/strbuf.h
@@ -27,5 +27,29 @@ const char *strbuf_str(struct strbuf *buf);
 
 bool strbuf_pushchar(struct strbuf *buf, char ch);
 size_t strbuf_pushchars(struct strbuf *buf, const char *str);
+
+/*
+ * Remove the last char from buf.
+ *
+ * No reallocation is done, so it's guaranteed @buf will have at least 1 char available to
+ * be filled after this call, as long as @buf wasn't empty.
+ */
 void strbuf_popchar(struct strbuf *buf);
+
+/*
+ * Remove the last @n chars from buf.
+ *
+ * No reallocation is done, so it's guaranteed @buf will have at least @n chars available
+ * to be filled after this call, as long as @buf had @n chars allocated before.
+ *
+ * Example:
+ *
+ * 	struct strbuf buf;
+ * 	strbuf_init(&buf);
+ * 	strbuf_pushchars(&buf, "foobar");
+ * 	strbuf_popchars(&buf, 5);
+ *
+ * After these calls @buf is [ 'f', x, x, x, ... ], where "x" means undefined. However it's
+ * guaranteed to have (at least) 5 chars available without needing to reallocate.
+ */
 void strbuf_popchars(struct strbuf *buf, size_t n);
diff --git a/testsuite/test-strbuf.c b/testsuite/test-strbuf.c
index cc093ec3..e4bfd058 100644
--- a/testsuite/test-strbuf.c
+++ b/testsuite/test-strbuf.c
@@ -62,6 +62,11 @@ static int test_strbuf_pushchars(const struct test *t)
 		lastwordlen = strlen(c);
 	}
 
+	/*
+	 * Replace the last space char, which also guarantees there's at least 1 char
+	 * available for the '\0' added by strbuf_str() so result1 == buf.bytes should be
+	 * true
+	 */
 	strbuf_popchar(&buf);
 	result1 = strbuf_str(&buf);
 	assert_return(result1 == buf.bytes, EXIT_FAILURE);