From cb80c9dcad5f5def30d62995e38ee8894d8909de Mon Sep 17 00:00:00 2001
From: Tucker Evans <tucker@tuckerevans.com>
Date: Tue, 21 Jul 2020 15:57:37 -0400
Subject: Add remove to header and documentation for maps

---
 collections/map/map.adoc | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

(limited to 'collections/map/map.adoc')

diff --git a/collections/map/map.adoc b/collections/map/map.adoc
index 09dfde7..c42a99a 100644
--- a/collections/map/map.adoc
+++ b/collections/map/map.adoc
@@ -9,9 +9,6 @@ NOTE: Keys are passed as void pointers and their data is not copied (this
 should be handled by the user), they should not be freed without clearing the
 map.
 
-NOTE: NULL keys are used to distingish a empty map, therefore NULL keys should
-never be used.
-
 NOTE: There is currently no way to distinquish between a failed retrieval
 (pop, index, back, etc.) and returning a NULL value. Keep this in mind if
 you plan on storing NULL values in the vector, there are plans to fix this in
@@ -95,6 +92,32 @@ if (map_insert(dict, "ONE", NULL) < 0)
 else
 	assert(map_size(dict) == 1);
 ----
+[[map_remove]]
++void* map_remove(map *self, void *key)+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Removes (and returns) the element at position +key+. The key and value are not
+freed.
+
+Examples
+^^^^^^^^
+[source,c]
+----
+#include "map.h"
+#include <string.h>
+
+map *dict = map_new((cmp_func) strcmp);
+
+map_insert(dict, "ONE", strdup("VALUE"));
+map_insert(dict, "TWO", strdup("VALUE"));
+map_insert(dict, "THREE", strdup("VALUE"));
+map_insert(dict, "FOUR", strdup("VALUE"));
+map_insert(dict, "FIVE", strdup("VALUE"));
+map_insert(dict, "SIX", strdup("VALUE"));
+
+char* tmp = map_remove(dict, "FOUR");
+assert(strcmp(tmp, "FOUR") == 0);
+free(tmp);
+----
 
 [[map_set_val]]
 +void* map_set_val(map *self, void *key, void *val)+
-- 
cgit v1.1

