propose renaming gnulib memxfrm to amemxfrm (naming collision with coreutils)

[Paul Eggert]

On 2009-03-07 Bruno Haible wrote:

> Paul Eggert has written the module 'memcoll', which generalizes the 'strcoll'
> function to work on strings with embedded NULs.

> Here is the generalization of 'strxfrm' to strings with embedded NUL bytes.

Sorry, I didn't really notice this email until just now.  As it happens,
coreutils has had an memxfrm implementation since 2006, which
it never exported to gnulib.  The coreutils memxfrm is closer to how
strxfrm behaves, in that it does not allocate memory: it relies on the
caller to do memory allocation.  The signatures differ as follows:

  // coreutils returns number of bytes that were translated,
  // (or would be translated if there were enough room).
  // It also sets errno on error.
  size_t memxfrm (char *restrict dst, size_t dstsize,
                  char *restrict src, size_t srcsize);

  // gnulib returns pointer to destination, which is possibly-different if
  // the destination wasn't large enough.  It updates *DSTSIZEPTR to
  // the newly allocated size, if it allocated storage.  It returns
  // NULL (setting errno) on error.
  char *memxfrm (char *src, size_t srcsize, char *dst, size_t *dstsizeptr);

For coreutils, the coreutils interface is more memory-efficient,
because malloc is invoked at most once when comparing two lines.  If
the small buffer on the stack isn't large enough to hold the
translated output for both strings, the two calls to memxfrm will tell
sort.c exactly how big the buffer should be, and it can invoke malloc
just once and then invoke memxfrm again (twice) to successfully do the
translation.

The gnulib interface is more convenient for applications that don't
care about this sort of memory optimization, and I expect that for
some (large) cases it is faster because it sometimes avoids translating
the same chunk twice.  So it's useful as well.

However, the name "memxfrm" isn't well-chosen for the gnulib interface.
As a general rule, the mem* functions do not allocate memory, and
it's confusing that memxfrm is an exception.

So I propose that the gnulib memxfrm be renamed to something else, to
reflect the fact that it allocates memory.  I suggest the name
"amemxfrm", as a leading "a" is the usual convention for variants that
allocate memory (e.g., "asprintf").

I guess the coreutils memxfrm could also be migrated into gnulib,
afterwards.