| 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. **]** |