Some functions that return arrays allow you to provide your own buffer. These are indicated in the type system as UserProvidedBuffer!Type, and you get to decide what you want to happen if the buffer is too small via the OnOutOfSpace parameter.

These are usually optional, since an empty user provided buffer with the default policy of reallocate will also work fine for whatever needs to be returned, thanks to the garbage collector taking care of it for you.

The API inside UserProvidedBuffer is all private to the arsd library implementation; your job is just to provide the buffer to it with provideBuffer or a constructor call and decide on your on-out-of-space policy.

To properly size a buffer, I suggest looking at what covers about 80% of cases. Trying to cover everything often leads to wasted buffer space, and if you use a reallocate policy it can cover the rest. You might be surprised how far just two elements can go!



Added August 4, 2023 (dub v11.0)