Demangler interface proposal

[Matt Austern]

We need to return multiple return values: a status code, and a buffer
pointer.  We can use an extra level of indirection on one, both, or
neither.  If neither, we need to return a pair or the moral
equivalent.

ALTERNATIVE A

namespace abi {
    extern "C" 
    char* __cxa_demangle(const char* mangled_name, char* buf, size_t n,
                         int* status);
}

mangled_name is a null-terminated string with the mangled name.  buf
is a pointer to a user-provided buffer of at least n characters.  If
buf is a null pointer then n is ignored, and demangle allocates its
own buffer with malloc.  The user is responsible for freeing it.

If the return value is non-null, it points to a null-terminated string
with the demangled name.  If the return value is null, an error has
occurred.  *status == 0 means the demangling failed because the buffer
wasn't long enough (or because malloc failed.)  *status == -1 means
the demangling failed because mangled_name is invalid.

Users may pass a null pointer as the last argument to __cxa_demangle.
All that means is that, if the demangling fails, they won't be able
to find out why.

ALTERNATIVE B

namespace abi {
    struct dm {
      char* name;
      enum { buffer_too_small, invalid_name } status;
    };
    dm demangle(const char* mangled_name, char* buf, size_t n);
}

mangled_name is a null-terminated string with the mangled name.  buf
is a pointer to a user-provided buffer of at least n characters.  If
buf is a null pointer then n is ignored, and demangle allocates its
own buffer with malloc.  The user is responsible for freeing it.

If result.name is non-null, it points to a null-terminated string with
the demangled name.  If result.name is null, demangling has failed and
result.status gives the type of failure.

DISCUSSION

I prefer alternative A, even though the error indication is clumsier,
because it's callable from C.  Having a C-callable demangling
interface could come in handy, e.g. for linkers.  If we decide that's
unimportant, we should go with alternative B.  



                        --Matt