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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
Map
===
Tucker Evans
v0.3, 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_insert]]
+int map_insert(map *self, void *key, void *value)+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Inserts item +value+ for +key+ into +self+
This returns an int indicating a successful insertion; currently the only
two potential errors are caused by a NULL map or an equivalent key with a
different pointer, this is in order to prevent a memory leak.
<<reset_key,+map_reset_key()+>> can be used to fix this issue.
Examples
^^^^^^^^
[source,c]
----
#include "map.h"
#include <string.h>
map *dict = map_new((cmp_func) strcmp);
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);
----
|
