From 20c79049e9b0a6a1aa47b1b9dacfbb31b6e7c992 Mon Sep 17 00:00:00 2001
From: Tucker Evans <tucker@tuckerevans.com>
Date: Mon, 6 Jul 2020 17:26:10 -0400
Subject: Add clear & free functions for maps

---
 collections/map/map.adoc | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

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

diff --git a/collections/map/map.adoc b/collections/map/map.adoc
index 837a08a..4668e0e 100644
--- a/collections/map/map.adoc
+++ b/collections/map/map.adoc
@@ -66,6 +66,52 @@ Examples
 map *dict = map_new((cmp_func) strcmp);
 
 assert(map_size(dict) == 0);
-map_set(dict, "ONE", NULL);
+map_insert(dict, "ONE", NULL);
 assert(map_size(dict) == 1);
 ----
+
+[[map_clear]]
++void map_clear(map *self)+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Free all elements within dict +self+, and sets dict to empty (size 0).
+
+NOTE: Does not free all internal memory of +self+ or +self+ itself, if this is
+desired <<map_free,+map_free()+>> should be called immediatly after this.
+
+Examples
+^^^^^^^^
+[source,c]
+----
+#include "map.h"
+#include <string.h>
+
+char *str1 = "ONE";
+char *str2 = "TWO";
+
+map *dict = map_new();
+map_insert(dict, str_dup(str1), NULL);
+map_insert(dict, str_dup(str2), NULL);
+
+map_clear(dict);
+assert(map_size(dict) == 0);
+map_free(dict);
+----
+
+[[map_free]]
++void map_free(map *self)+
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Frees all internal memory and +self+.
+
+NOTE: All item pointers are still valid after a call to
+<<map_free,+map_free()+>>, <<map_clear,+map_clear()+>> should be called before
+if they are no longer needed to avoid memory leaks.
+
+Examples
+^^^^^^^^
+[source,c]
+----
+#include "map.h"
+
+map *dict = map_new();
+map_free(dict);
+----
-- 
cgit v1.1

