Re: [PATCH v3 1/2] add strbuf_set operations

[Junio C Hamano <gitster@pobox.com>]

Jeremiah Mahler <jmmahler@gmail.com> writes:

> A common use case with strubfs is to set the buffer to a new value.
> This must be done in two steps: a reset followed by an add.
>
>   strbuf_reset(buf);
>   strbuf_add(buf, new_buf, len);
>
> In cases where the buffer is being built up in steps, these operations
> make sense and correctly convey what is being performed.
>
>   strbuf_reset(buf);
>   strbuf_add(buf, data1, len1);
>   strbuf_add(buf, data2, len2);
>   strbuf_add(buf, data3, len3);
>
> However, in other cases, it can be confusing and is not very concise.
>
>   strbuf_reset(buf);
>   strbuf_add(buf, default, len1);
>
>   if (cond1) {
>     strbuf_reset(buf);
>     strbuf_add(buf, data2, len2);
>   }
>
>   if (cond2) {
>     strbuf_reset(buf);
>     strbuf_add(buf, data3, len3);
>   }
>
> Add strbuf_set operations so that it can be re-written in a clear and
> concise way.
>
>   strbuf_set(buf, default len1);
>
>   if (cond1) {
>     strbuf_set(buf, data2, len2);
>   }
>
>   if (cond2) {
>     strbuf_set(buf, data3, len3);
>   }

Or even more concisely without making unnecessary internal calls to
strbuf_reset():

	strbuf_reset(buf);
        if (cond2)
        	strbuf_add(buf, data3, len3);
	else if (cond1)
        	strbuf_add(buf, data2, len2);
	else
        	strbuf_add(buf, default, len2);

;-)

I am on the fence.

I have this suspicion that the addition of strbuf_set() would *only*
help when the original written with reset-and-then-add sequence was
suboptimal to begin with, and it helps *only* how the code reads,
without correcting the fact that it is still doing unnecessary
"first set to a value to be discarded and then reset to set the
right value", sweeping the issue under the rug.

Repeated reset-and-then-add on the same strbuf used to be something
that may indicate that the code is doing unnecessary work.  Now,
repeated uses of strbuf_set on the same strbuf replaced that pattern
to be watched for to spot wasteful code paths.

I dunno...

> Signed-off-by: Jeremiah Mahler <jmmahler@gmail.com>
> ---
>  Documentation/technical/api-strbuf.txt | 18 ++++++++++++++++++
>  strbuf.c                               | 21 +++++++++++++++++++++
>  strbuf.h                               | 13 +++++++++++++
>  3 files changed, 52 insertions(+)
>
> diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
> index f9c06a7..ae9c9cc 100644
> --- a/Documentation/technical/api-strbuf.txt
> +++ b/Documentation/technical/api-strbuf.txt
> @@ -149,6 +149,24 @@ Functions
>  	than zero if the first buffer is found, respectively, to be less than,
>  	to match, or be greater than the second buffer.
>  
> +* Setting the buffer
> +
> +`strbuf_set`::
> +
> +	Replace content with data of a given length.
> +
> +`strbuf_setstr`::
> +
> +	Replace content with data from a NUL-terminated string.
> +
> +`strbuf_setf`::
> +
> +	Replace content with a formatted string.
> +
> +`strbuf_setbuf`::
> +
> +	Replace content with data from another buffer.
> +
>  * Adding data to the buffer
>  
>  NOTE: All of the functions in this section will grow the buffer as necessary.
> diff --git a/strbuf.c b/strbuf.c
> index ac62982..9d64b00 100644
> --- a/strbuf.c
> +++ b/strbuf.c
> @@ -189,6 +189,27 @@ void strbuf_splice(struct strbuf *sb, size_t pos, size_t len,
>  	strbuf_setlen(sb, sb->len + dlen - len);
>  }
>  
> +void strbuf_set(struct strbuf *sb, const void *data, size_t len)
> +{
> +	strbuf_reset(sb);
> +	strbuf_add(sb, data, len);
> +}
> +
> +void strbuf_setf(struct strbuf *sb, const char *fmt, ...)
> +{
> +	va_list ap;
> +	strbuf_reset(sb);
> +	va_start(ap, fmt);
> +	strbuf_vaddf(sb, fmt, ap);
> +	va_end(ap);
> +}
> +
> +void strbuf_setbuf(struct strbuf *sb, const struct strbuf *sb2)
> +{
> +	strbuf_reset(sb);
> +	strbuf_add(sb, sb2->buf, sb2->len);
> +}
> +
>  void strbuf_insert(struct strbuf *sb, size_t pos, const void *data, size_t len)
>  {
>  	strbuf_splice(sb, pos, 0, data, len);
> diff --git a/strbuf.h b/strbuf.h
> index e9ad03e..5041c35 100644
> --- a/strbuf.h
> +++ b/strbuf.h
> @@ -101,6 +101,19 @@ static inline struct strbuf **strbuf_split(const struct strbuf *sb,
>   */
>  extern void strbuf_list_free(struct strbuf **);
>  
> +/*----- set buffer to data -----*/
> +extern void strbuf_set(struct strbuf *sb, const void *data, size_t len);
> +
> +static inline void strbuf_setstr(struct strbuf *sb, const char *s)
> +{
> +	strbuf_set(sb, s, strlen(s));
> +}
> +
> +__attribute__((format (printf,2,3)))
> +extern void strbuf_setf(struct strbuf *sb, const char *fmt, ...);
> +
> +extern void strbuf_setbuf(struct strbuf *sb, const struct strbuf *sb2);
> +
>  /*----- add data in your buffer -----*/
>  static inline void strbuf_addch(struct strbuf *sb, int c)
>  {