Add reset key function for maps

Allows changing the pointer to key when they are equivalent (by cmp
function), to avoid memory leaks that could happen if we assumed either
pointer was to be freed or overwritten.

1 files changed, 22 insertions, 1 deletions

diff --git a/collections/map/map.adoc b/collections/map/map.adoc
index 2b3e2cb..2822b79 100644
--- a/collections/map/map.adoc
+++ b/collections/map/map.adoc
@@ -1,7 +1,7 @@
 Map
 ===
 Tucker Evans
-v0.3, 2020-07-06
+v0.4, 2020-07-06
 
 A basic map implemented in an AVL tree.
 
@@ -92,6 +92,27 @@ map_insert(dict, "ONE", NULL);
 assert(map_size(dict) == 1);
 ----
 
+[[map_reset_key]]
++void* map_reset_key(map *self, vaid *key)+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This replaces an equivalent key with the one passed in, the key that is
+overwritten is return so the user can free it.
+
+Examples
+^^^^^^^^
+[source,c]
+----
+#include "map.h"
+#include <string.h>
+
+map *dict = map_new((cmp_func) strcmp);
+
+map_insert(dict, strdup("ONE"), "VALUE");
+assert(map_insert(dict, "ONE", "NEW_VALUE") < 0);
+free(map_reset_key(dict "ONE"));
+assert(map_insert(dict, "ONE", "NEW_VALUE") == 0);
+----
+
 [[map_clear]]
 +void map_clear(map *self)+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~