[0/4] strbuf: fix doc for `strbuf_attach()` and avoid it

Message

Martin Ågren April 19, 2020, 12:32 p.m. UTC

This is v2 of my attempt to look into how `strbuf_attach()` works, how
it's documented and how it's actually used.

This is based on top of Danh's series [1]. Both their patch 2/3 and my
4/4 reason about "NUL" at a particular spot. In short, they conflict
about whether to use function "A" or "B" at one spot and a merge should
(in my opinion) use function "C". That seemed odd enough to me that I
decided to build on top instead.

`strbuf_attach()` has always handled `mem == len`. This was intentional.
When the function was eventually documented, this usage was incorrectly
documented as being wrong.

That documentation didn't stop lots of callers from using it
"incorrectly", though. I first fix the documentation. I then try to
avoid such usage anyway, partly because it can be confusing, partly
because if we know we have enough memory, there's no need to reallocate
a larger buffer.

Martin

[1] https://lore.kernel.org/git/[e-mail]/

Martin Ågren (4):
  strbuf: fix doc for `strbuf_attach()`
  strbuf: introduce `strbuf_attachstr_len()`
  strbuf: introduce `strbuf_attachstr()`
  strbuf_attach: prefer `strbuf_attachstr_len()`

 strbuf.h             | 40 ++++++++++++++++++++++++++++++++++++----
 apply.c              |  2 +-
 archive.c            |  2 +-
 blame.c              |  2 +-
 builtin/am.c         |  2 +-
 convert.c            |  4 ++--
 fast-import.c        |  2 +-
 imap-send.c          |  2 +-
 mailinfo.c           |  2 +-
 merge-recursive.c    |  2 +-
 path.c               |  3 +--
 pretty.c             |  4 ++--
 refs/files-backend.c |  3 +--
 trailer.c            |  2 +-
 14 files changed, 51 insertions(+), 21 deletions(-)