clearRetainingCapacity documentation string unclear

[urban gazelle]

I am trying to use ArrayList more in my w.i.p game. I found the documentation of clearRetainingCapacity confusing, so looked up the source (both in Zig 0.14.1 and current 0.15 dev head):

        /// Invalidates all element pointers.
        pub fn clearRetainingCapacity(self: *Self) void {
            self.items.len = 0;
        }

        /// Invalidates all element pointers.
        pub fn clearAndFree(self: *Self) void {
            self.allocator.free(self.allocatedSlice());
            self.items.len = 0;
            self.capacity = 0;
        }

First of, the documentation is identical for these two, and they are clearly doing differnt things.

For my use case, I am not using pointers for the elements, but (small) structs and wanted to re-use an ArrayList over and over in the main loop of my game, only freeing the array after exiting the main loop, so I guess clearRetainingCapacity is the one I want?

[past briar]

Yes, clearAndFree will also free as the name suggests. It might be better to look at using an arena for fixed-lifetime code like that though.

[urban gazelle]

Also, even the doc for clearAndFree does not 'free' the elements per se, only the 'underlying array' if I read things correctly? I think the documentation could be clearly improved on this...

I guess 'deinit' is the one that clears up everything (elements and underlying array)?

I guess one of my confusions is what 'invalidates' really means?

[past briar]

deinit doesn't prepare the arraylist for adding new elements unlike clearAndFree and leaves all the arraylist's fields the same

[void wasp]

if you have taken &list.items[i], that pointer is no longer guaranteed to point to something meaningful after calling either of these functions

[urban gazelle]

Ah, that's where Invalidates comes from, thanks!

I think that is quite important, however, more important is the general use case of these two?
clearRetainingCapacity // Clear the arraylist without freeing memory. Capacity kept. Note: any pointers to elements are made invalid!
clearAndFree // Clear the arraylist freeing underlying memory. Note: any pointers to elements are made invalid!

[past briar]

Its not too hard to tell from the function names/bodies, which is why I'm ok with the documentation only having the warning (at least I think that's the intent)

[urban gazelle]

It does seem to be much less documentation than many other fn's in ArrayList? E.g. this:

        /// Append a value to the list `n` times.
        /// Allocates more memory as necessary.
        /// Invalidates element pointers if additional memory is needed.
        /// The function is inline so that a comptime-known `value` parameter will
        /// have a more optimal memset codegen in case it has a repeated byte pattern.
        pub inline fn appendNTimes(self: *Self, value: T, n: usize) Allocator.Error!void {
            const old_len = self.items.len;
            try self.resize(try addOrOom(old_len, n));
            @memset(self.items[old_len..self.items.len], value);
        }

Here's the source: https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig

[past briar]

Hmm yeah reading it an explanation of what the function does seems to be...missing