1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
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_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);
----
|
