Allow users to pass in their own byte arrays

[kevinburke]

For example, the base64 api's have a user pass in a dst array to decode into. The nacl API's in golang.org/x/crypto follow a similar pattern.

The advantage of doing it this way is that it reduces allocations, which helps performance.

The disadvantage is that it requires the caller to know more about how the API works, and ensure they bring along a byte array that's large enough.

The C/C++ API's have it both ways. The C++ API's return a byte array, the C API's require you to pass one in, but I think the latter is because you can only return integers from C functions..

[kevinburke]

(To be clear, I'm not entirely convinced this is a good idea, but if anyone has input, go ahead and give it)

[raylee]

Just a minor comment related to the performance issue. You can return more than just ints from a C function -- structs are fine, for example -- but how the compiler implements that is up to the platform ABI. It could be allocated from the stack which is a bit of a precious resource. So libraries in C often avoid that uncertainty and just return pointers. I wouldn't read anything more into it than that.

Anyway, thanks for this work. I'm looking forward to reading through the code.