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 8824afdcc347d121a4b3e2d37be4c290b77cb081..64a5ba00f823e4b2944a6a1b0b5d6b471d14c8bf 100644 (file)
--- 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 cc093ec3778d4eda7e47f5a9a9a8b9a9c33dc226..e4bfd05892e2923c817ab81f49d0370886083526 100644 (file)
--- 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);