From b8776806de69062ec8b7e69c56d67694fbad9f4a Mon Sep 17 00:00:00 2001 From: Lucas De Marchi Date: Tue, 12 Nov 2024 09:25:52 -0600 Subject: [PATCH] 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 Reviewed-by: Emil Velikov Link: https://github.com/kmod-project/kmod/pull/239 --- shared/strbuf.h | 24 ++++++++++++++++++++++++ testsuite/test-strbuf.c | 5 +++++ 2 files changed, 29 insertions(+) diff --git a/shared/strbuf.h b/shared/strbuf.h index 8824afd..64a5ba0 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 cc093ec..e4bfd05 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);