Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/map_requirements.md

raw
1 map requirements
2 ================
3
4 ## Overview
5
6 Map is a module that implements a dictionary of STRING_HANDLE key to STRING_HANDLE values.
7
8 ## References
9
10 [strings_requiremens.md]
11 [json.org](http://www.json.org)
12
13 ## Exposed API
14
15 ```c
16 #define MAP_RESULT_VALUES \
17 MAP_OK, \
18 MAP_ERROR, \
19 MAP_INVALIDARG, \
20 MAP_KEYEXISTS, \
21 MAP_KEYNOTFOUND, \
22 MAP_FILTER_REJECT
23
24 MU_DEFINE_ENUM(MAP_RESULT, MAP_RESULT_VALUES);
25
26 typedef void* MAP_HANDLE;
27
28 typedef int (*MAP_FILTER_CALLBACK)(const char* mapProperty, const char* mapValue);
29
30
31 extern MAP_HANDLE Map_Create(MAP_FILTER_CALLBACK mapFilterFunc);
32 extern void Map_Destroy(MAP_HANDLE handle);
33 extern MAP_HANDLE Map_Clone(MAP_HANDLE handle);
34
35 extern MAP_RESULT Map_Add(MAP_HANDLE handle, const char* key, const char* value);
36 extern MAP_RESULT Map_AddOrUpdate(MAP_HANDLE handle, const char* key, const char* value);
37 extern MAP_RESULT Map_Delete(MAP_HANDLE handle, const char* key);
38
39 extern MAP_RESULT Map_ContainsKey(MAP_HANDLE handle, const char* key, bool* keyExists);
40 extern MAP_RESULT Map_ContainsValue(MAP_HANDLE handle, const char* value, bool* valueExists);
41 extern STRING_HANDLE Map_GetValueFromKey(MAP_HANDLE handle, const char* key);
42
43 extern MAP_RESULT Map_GetInternals(MAP_HANDLE handle, const char*const** keys, const char*const** values, size_t* count);
44 extern STRING_HANDLE Map_ToJSON(MAP_HANDLE handle);
45 ```
46
47 ### Map_Create
48 ```c
49 extern MAP_HANDLE Map_Create(MAP_FILTER_CALLBACK mapFilterFunc);
50 ```
51
52 **SRS_MAP_02_001: [** Map_Create shall create a new, empty map. **]**
53
54 **SRS_MAP_02_002: [** If during creation there are any error, then Map_Create shall return NULL. **]**
55
56 **SRS_MAP_02_003: [** Otherwise, it shall return a non-NULL handle that can be used in subsequent calls. **]**
57
58 ### Map_Destroy
59 ```c
60 extern void Map_Destroy(MAP_HANDLE handle);
61 ```
62 **SRS_MAP_02_004: [** Map_Destroy shall release all resources associated with the map. **]**
63
64 **SRS_MAP_02_005: [** If parameter handle is NULL then Map_Destroy shall take no action. **]**
65
66 ### Map_Clone
67 ```c
68 extern MAP_HANDLE Map_Clone(MAP_HANDLE handle);
69 ```
70 **SRS_MAP_02_038: [** Map_Clone returns NULL if parameter handle is NULL. **]**
71
72 **SRS_MAP_02_039: [** Map_Clone shall make a copy of the map indicated by parameter handle and return a non-NULL handle to it. **]**
73
74 **SRS_MAP_02_047: [** If during cloning, any operation fails, then Map_Clone shall return NULL. **]**
75
76 ### Map_Add
77 ```c
78 extern MAP_RESULT Map_Add(MAP_HANDLE handle, const char* key, const char* value);
79 ```
80
81 Map_Add adds to the map a pair of key, value.
82
83 **SRS_MAP_02_006: [** If parameter handle is NULL then Map_Add shall return MAP_INVALID_ARG. **]**
84
85 **SRS_MAP_02_007: [** If parameter key is NULL then Map_Add shall return MAP_INVALID_ARG. **]**
86
87 **SRS_MAP_02_008: [** If parameter value is NULL then Map_Add shall return MAP_INVALID_ARG. **]**
88
89 **SRS_MAP_02_009: [** If the key already exists, then Map_Add shall return MAP_KEYEXISTS. **]**
90
91 **SRS_MAP_02_010: [** Otherwise, Map_Add shall add the pair <key,value> to the map. **]**
92
93 **SRS_MAP_02_011: [** If adding the pair <key,value> fails then Map_Add shall return MAP_ERROR. **]**
94
95 **SRS_MAP_02_012: [** Otherwise, Map_Add shall return MAP_OK. **]**
96
97 **SRS_MAP_07_009: [** If the mapFilterCallback function is not NULL, then the return value will be checked and if it is not zero then Map_Add shall return MAP_FILTER_REJECT. **]**
98
99 ### Map_AddOrUpdate
100 ```c
101 extern MAP_RESULT Map_AddOrUpdate(MAP_HANDLE, const char* key, const char* value);
102 ```
103
104 **SRS_MAP_02_013: [** If parameter handle is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG. **]**
105
106 **SRS_MAP_02_014: [** If parameter key is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG. **]**
107
108 **SRS_MAP_02_015: [** If parameter value is NULL then Map_AddOrUpdate shall return MAP_INVALID_ARG. **]**
109
110 **SRS_MAP_02_016: [** If the key already exists, then Map_AddOrUpdate shall overwrite the value of the existing key with parameter value. **]**
111
112 **SRS_MAP_02_017: [** Otherwise, Map_AddOrUpdate shall add the pair <key,value> to the map. **]**
113
114 **SRS_MAP_02_018: [** If there are any failures then Map_AddOrUpdate shall return MAP_ERROR. **]**
115
116 **SRS_MAP_02_019: [** Otherwise, Map_AddOrUpdate shall return MAP_OK. **]**
117
118 **SRS_MAP_07_008: [** If the mapFilterCallback function is not NULL, then the return value will be check and if it is not zero then Map_AddOrUpdate shall return MAP_FILTER_REJECT. **]**
119
120 ### Map_Delete
121 ```c
122 extern MAP_RESULT Map_Delete(MAP_HANDLE handle, const char* key);
123 ```
124 Map_Delete removes a key and its associated value from the map.
125
126 **SRS_MAP_02_020: [** If parameter handle is NULL then Map_Delete shall return MAP_INVALIDARG. **]**
127
128 **SRS_MAP_02_021: [** If parameter key is NULL then Map_Delete shall return MAP_INVALIDARG. **]**
129
130 **SRS_MAP_02_022: [** If key does not exist then Map_Delete shall return MAP_KEYNOTFOUND. **]**
131
132 **SRS_MAP_02_023: [** Otherwise, Map_Delete shall remove the key and its associated value from the map and return MAP_OK. **]**
133
134 ### Map_ContainsKey
135 ```c
136 extern MAP_RESULT Map_ContainsKey(MAP_HANDLE handle, const char* key, bool* keyExists);
137 ```
138 Map_ContainsKey returns in parameter keyExists if the map contains a key with the same value as parameter key.
139
140 **SRS_MAP_02_024: [** If parameter handle, key or keyExists are NULL then Map_ContainsKey shall return MAP_INVALIDARG. **]**
141
142 **SRS_MAP_02_025: [** Otherwise if a key exists then Map_ContainsKey shall return MAP_OK and shall write in keyExists "true". **]**
143
144 **SRS_MAP_02_026: [** If a key doesn't exist, then Map_ContainsKey shall return MAP_OK and write in keyExists "false". **]**
145
146 ### Map_ContainsValue
147 ```c
148 extern MAP_RESULT Map_ContainsValue(MAP_HANDLE handle, const char* value, bool* valueExists);
149 ```
150 Map_ContainsKey returns in valueExists if at least one pair <key,value> in the map contains the value parameter.
151
152 **SRS_MAP_02_027: [** If parameter handle, value or valueExists is NULL then Map_ContainsValue shall return MAP_INVALIDARG. **]**
153
154 **SRS_MAP_02_028: [** Otherwise, if a pair <key, value> has its value equal to the parameter value, the Map_ContainsValue shall return MAP_OK and shall write in valueExists "true". **]**
155
156 **SRS_MAP_02_029: [** Otherwise, if such a <key, value> does not exist, then Map_ContainsValue shall return MAP_OK and shall write in valueExists "false". **]**
157
158 ### Map_GetValueFromKey
159 ```c
160 extern const char* Map_GetValueFromKey(MAP_HANDLE handle, const char* key);
161 ```
162
163 Map_GetValueFromKey returns the value of a stored key.
164
165 **SRS_MAP_02_040: [** If parameter handle or key is NULL then Map_GetValueFromKey returns NULL. **]**
166
167 **SRS_MAP_02_041: [** If the key is not found, then Map_GetValueFromKey returns NULL. **]**
168
169 **SRS_MAP_02_042: [** Otherwise, Map_GetValueFromKey returns the key's value. **]**
170
171 ### Map_GetInternals
172 ```c
173 extern MAP_RESULT Map_GetInternals(MAP_HANDLE handle, const char*const** keys, const char*const** values, size_t* count);
174 ```
175 **SRS_MAP_02_046: [** If parameter handle, keys, values or count is NULL then Map_GetInternals shall return MAP_INVALIDARG. **]**
176
177 **SRS_MAP_02_043: [** Map_GetInternals shall produce in *keys an pointer to an array of const char* having all the keys stored so far by the map. **]**
178
179 **SRS_MAP_02_044: [** Map_GetInternals shall produce in *values a pointer to an array of const char* having all the values stored so far by the map. **]**
180
181 **SRS_MAP_02_045: [** Map_GetInternals shall produce in *count the number of stored keys and values. **]**
182
183 ### Map_ToJSON
184 ```c
185 extern STRING_HANDLE Map_ToJSON(MAP_HANDLE handle);
186 ```
187 **SRS_MAP_02_052: [** If parameter handle is NULL then Map_ToJSON shall return NULL. **]**
188
189 **SRS_MAP_02_048: [** Map_ToJSON shall produce a STRING_HANDLE representing the content of the MAP. **]**
190
191 **SRS_MAP_02_049: [** If the MAP is empty, then Map_ToJSON shall produce the string "{}". **]**
192
193 **SRS_MAP_02_050: [** If the map has properties then Map_ToJSON shall produce the following string:{"name1":"value1", "name2":"value2" ...} **]**
194
195 **SRS_MAP_02_051: [** If any error occurs while producing the output, then Map_ToJSON shall fail and return NULL. **]**