Re: [PATCH 1/4] strbuf: fix doc for `strbuf_attach()`

From: "Martin Ågren" <martin.agren@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Git Mailing List" <git@vger.kernel.org>,
	"Đoàn Trần Công Danh" <congdanhqx@gmail.com>
Subject: Re: [PATCH 1/4] strbuf: fix doc for `strbuf_attach()`
Date: Tue, 21 Apr 2020 20:44:23 +0200	[thread overview]
Message-ID: <CAN0heSrqDYrZnR8aGRksf4qLZE0YPgPYUbK4AFnnOX470M34Ow@mail.gmail.com> (raw)
In-Reply-To: <xmqqd082rrns.fsf@gitster.c.googlers.com>

On Mon, 20 Apr 2020 at 19:30, Junio C Hamano <gitster@pobox.com> wrote:
>
> Martin Ågren <martin.agren@gmail.com> writes:
>
> > The function handles reallocation and truncation, yet the docs say that
> > the "amount [of allocated memory] must be larger than the string length,
> > because the string you pass is supposed to be a NUL-terminated string".
>
> IOW, _attach() does not mind if the original lacks '\0' at the end.

Right, nor if it lacks the space for it.

> > diff --git a/strbuf.h b/strbuf.h
> > index ce8e49c0b2..2a462f70cc 100644
> > --- a/strbuf.h
> > +++ b/strbuf.h
> > @@ -112,10 +112,12 @@ char *strbuf_detach(struct strbuf *sb, size_t *sz);
> >  /**
> >   * Attach a string to a buffer. You should specify the string to attach,
> >   * the current length of the string and the amount of allocated memory.
> > + * The amount must be at least as large as the string length. If the two
> > + * lengths are equal, reallocation will be handled as appropriate and in
> > + * any case, the string will be NUL-truncated as implied by `len`.
>
> NUL-truncated?  Ah, if mem and len are the same, the string is reallocated
> to fit an extra byte to NUL-terminate, to make sure strlen(sb->buf)==len
> holds.  Makes sense.

Exactly. NUL-terminated would be better. I think I'll split that last
sentence and replace it with something like the following:

  If the two lengths are equal, reallocation will be handled as
  needed. And regardless, the string will be NUL-terminated at `len`.

(One might still have strlen(sb->buf) < len though. This just guarantees
"<=")

Martin