On Fri, Aug 21, 2020 at 06:52:25PM +0000, Elijah Newren via GitGitGadget wrote:
> From: Elijah Newren <newren@xxxxxxxxx>
>
> The existence of hashmap_free() and hashmap_free_entries() confused me,
> and the docs weren't clear enough. I had to consult other source code
> examples and the implementation. Add a brief note to clarify,
> especially since hashmap_clear*() variants may be added in the future.
Thanks, I think this is worth doing and the text looks clear and correct
to me.
> /*
> - * Frees a hashmap structure and allocated memory, leaves entries undisturbed
> + * Frees a hashmap structure and allocated memory for the table, but does not
> + * free the entries nor anything they point to.
> + *
> + * Usage note:
> + *
> + * Many callers will need to iterate over all entries and free the data each
> + * entry points to; in such a case, they can free the entry itself while at it.
> + * Thus, you might see:
> + * hashmap_for_each_entry(map, hashmap_iter, e, hashmap_entry_name) {
> + * free(e->somefield);
> + * free(e);
> + * }
> + * hashmap_free(map);
> + * instead of
> + * hashmap_for_each_entry(map, hashmap_iter, e, hashmap_entry_name) {
> + * free(e->somefield);
> + * }
> + * hashmap_free_entries(map, struct my_entry_struct, hashmap_entry_name);
> + * to avoid the implicit extra loop over the entries. However, if there are
> + * no special fields in your entry that need to be freed beyond the entry
> + * itself, it is probably simpler to avoid the explicit loop and just call
> + * hashmap_free_entries().
A minor nit, but a blank line between the code snippets and the text
might make it a little more readable.
-Peff
