Clarify documentation for `Allocator.resize`

[babaisflag]

Current documentation:

Attempt to expand or shrink memory in place.

memory.len must equal the length requested from the most recent successful call to alloc, resize, or remap. alignment must equal the same value that was passed as the alignment parameter to the original alloc call.

A result of true indicates the resize was successful and the allocation now has the same address but a size of new_len. false indicates the resize could not be completed without moving the allocation to a different address.

new_len must be greater than zero.

ret_addr is optionally provided as the first return address of the allocation call stack. If the value is 0 it means no return address has been provided.

I think the current wording strongly suggests that calling resize will modify the len field of the slice ("result of true indicates the resize was successful and the allocation now has the same address but a size of new_len) - and it doesn't help that remap also has a very similar wording but does return a new slice with the new length. I understand from a previous issue that it is by design that len field cannot be fixed and the user is expected to modify the slice themselves, but in my opinion it would be good to clarify that in the docs.

Additionally (this also applies to remap), "new_len must be greater than zero" seems to imply that the function should not accept new_len equal to 0 as an argument and throw an error or what not, when in reality it calls free, so it might be better to have that added in the docs for users to know. For instance, the manpage for glibc realloc states:

if size is equal to zero, and ptr is not NULL, then the call is equivalent to free(ptr).

so some thing like that would be good.

[dweiller]

Additionally (this also applies to remap), "new_len must be greater than zero" seems to imply that the function should not accept new_len equal to 0 as an argument and throw an error or what not, when in reality it calls free, so it might be better to have that added in the docs for users to know. For instance, the manpage for glibc realloc states:

if size is equal to zero, and ptr is not NULL, then the call is equivalent to free(ptr).

so some thing like that would be good.

This is not the case - it seems to me that you're mixing up the allocator vtable functions and the API methods in std.mem.Allocator, which have different contracts. The vtable functions (which say new_len must be greater than zero) do not call free internally; it is the API methods that do, and these say that new_len may be zero.

[babaisflag]

Oh I see, then for new_len == 0 case I think it's fine (maybe good to indicate that it does free at len 0 for the API functions, but that's another discussion).