Map
===
Tucker Evans
v0.2, 2020-07-06

A basic map implemented in an AVL tree.

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: 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
the future.

Types
----
The following types are defined in the header file:
[[map]]
+map+
~~~~~
This structure holds all internal information regarding a map.
All functions (except constructors) expect a pointer to this struct as their
first parameter.

[[cmp_func]]
+cmp_func+
~~~~~~~~~~~
This is a pointer to a function that to compare keys from pointers. This
typedef is provided to cast comparison functions as a map expects the
comparison function to take void* as its parameters.

Functions
---------
[[map_new]]
+map_new(cmp_func cmp)+
~~~~~~~~~~~~~~~~~~~~~~~
Constructs an empty map.
+cmp+ should be a function that takes two pointers (+lhs+, +rhs+)to your value
type and returns (int) a negative value if +lhs+ is less than  +rhs+, zero if
+lhs+ is equal to +rhs+, and positive value if +lhs+ is greater than +rhs+.

Examples
^^^^^^^^
[source,c]
----
#include "map.h"
#include <string.h>

map *dict = map_new((cmp_func) strcmp);
----

[[map_size]]
+map_size(map *self)+
~~~~~~~~~~~~~~~~~~~~~
Returns the number of key, value pairs stored in map +self+.

Examples
^^^^^^^^
[source,c]
----
#include "map.h"
#include <string.h>

map *dict = map_new((cmp_func) strcmp);

assert(map_size(dict) == 0);
map_set(dict, "ONE", NULL);
assert(map_size(dict) == 1);
----
