| 1 |
ConstMap Requirements |
| 2 |
================ |
| 3 |
|
| 4 |
|
| 5 |
## Overview |
| 6 |
|
| 7 |
Const Map is a module that implements a read-only dictionary of `const char*` key to `const char*` values. It is intially populated by a Map. |
| 8 |
|
| 9 |
## References |
| 10 |
[refcount](../inc/refcount.h) |
| 11 |
|
| 12 |
[Map](map_requirements.md) |
| 13 |
|
| 14 |
## Exposed API |
| 15 |
```C |
| 16 |
#define CONSTMAP_RESULT_VALUES \ |
| 17 |
CONSTMAP_OK, \ |
| 18 |
CONSTMAP_ERROR, \ |
| 19 |
CONSTMAP_INVALIDARG, \ |
| 20 |
CONSTMAP_KEYNOTFOUND |
| 21 |
|
| 22 |
MU_DEFINE_ENUM(CONSTMAP_RESULT, CONSTMAP_RESULT_VALUES); |
| 23 |
|
| 24 |
typedef struct CONSTMAP_HANDLE_DATA_TAG* CONSTMAP_HANDLE; |
| 25 |
|
| 26 |
extern CONSTMAP_HANDLE CONSTMAP_Create(MAP_HANDLE sourceMap); |
| 27 |
extern void ConstMap_Destroy(CONSTMAP_HANDLE handle); |
| 28 |
extern CONSTMAP_HANDLE ConstMap_Clone(CONSTMAP_HANDLE handle); |
| 29 |
extern MAP_HANDLE ConstMap_CloneWriteable(CONSTMAP_HANDLE handle); |
| 30 |
|
| 31 |
|
| 32 |
extern bool ConstMap_ContainsKey(CONSTMAP_HANDLE handle, const char* key); |
| 33 |
extern bool ConstMap_ContainsValue(CONSTMAP_HANDLE handle, const char* value); |
| 34 |
extern const char* ConstMap_GetValue(CONSTMAP_HANDLE handle, const char* key); |
| 35 |
|
| 36 |
extern CONSTMAP_RESULT ConstMap_GetInternals(CONSTMAP_HANDLE handle, const char*const** keys, const char*const** values, size_t* count); |
| 37 |
``` |
| 38 |
|
| 39 |
|
| 40 |
### ConstMap_Create |
| 41 |
```C |
| 42 |
extern CONSTMAP_HANDLE ConstMap_Create(MAP_HANDLE sourceMap); |
| 43 |
``` |
| 44 |
**SRS_CONSTMAP_17_001: [** `ConstMap_Create` shall create an immutable map, populated by the key, value pairs in the source map. **]** |
| 45 |
|
| 46 |
**SRS_CONSTMAP_17_048: [** `ConstMap_Create` shall accept any non-`NULL` `MAP_HANDLE` as input. **]** |
| 47 |
|
| 48 |
**SRS_CONSTMAP_17_002: [** If during creation there are any errors, then `ConstMap_Create` shall return `NULL`. **]** |
| 49 |
|
| 50 |
**SRS_CONSTMAP_17_003: [** Otherwise, it shall return a non-`NULL` handle that can be used in subsequent calls. **]** |
| 51 |
|
| 52 |
### ConstMap_Destroy |
| 53 |
```C |
| 54 |
extern void ConstMap_Destroy(CONSTMAP_HANDLE handle); |
| 55 |
``` |
| 56 |
**SRS_CONSTMAP_17_005: [** If parameter handle is `NULL` then `ConstMap_Destroy` shall take no action. **]** |
| 57 |
|
| 58 |
**SRS_CONSTMAP_17_049: [** `ConstMap_Destroy` shall decrement the internal reference count of the immutable map. **]** |
| 59 |
|
| 60 |
**SRS_CONSTMAP_17_004: [** If the reference count is zero, `ConstMap_Destroy` shall release all resources associated with the immutable map. **]** |
| 61 |
|
| 62 |
|
| 63 |
### ConstMap_Clone |
| 64 |
```C |
| 65 |
extern CONSTMAP_HANDLE ConstMap_Clone(CONSTMAP_HANDLE handle); |
| 66 |
``` |
| 67 |
**SRS_CONSTMAP_17_038: [** `ConstMap_Clone` returns `NULL` if parameter `handle` is `NULL`. **]** |
| 68 |
|
| 69 |
**SRS_CONSTMAP_17_039: [** `ConstMap_Clone` shall increase the internal reference count of the immutable map indicated by parameter `handle` **]** |
| 70 |
|
| 71 |
**SRS_CONSTMAP_17_050: [** `ConstMap_Clone` shall return the non-`NULL` handle. **]** |
| 72 |
|
| 73 |
### ConstMap_CloneWriteable |
| 74 |
```C |
| 75 |
extern MAP_HANDLE ConstMap_CloneWriteable(CONSTMAP_HANDLE handle); |
| 76 |
``` |
| 77 |
|
| 78 |
This function will return a new MAP_HANDLE populated by the key, value pairs contained in the CONSTMAP_HANDLE. This MAP_HANDLE needs to be destroyed when it is no longer needed. |
| 79 |
|
| 80 |
**SRS_CONSTMAP_17_051: [** `ConstMap_CloneWriteable` returns `NULL` if parameter handle is `NULL`. **]** |
| 81 |
|
| 82 |
**SRS_CONSTMAP_17_052: [** `ConstMap_CloneWriteable` shall create a new, writeable map, populated by the key, value pairs in the parameter defined by `handle`. **]** |
| 83 |
|
| 84 |
**SRS_CONSTMAP_17_053: [** If during copying, any operation fails, then `ConstMap_CloneWriteableap_Clone` shall return `NULL`. **]** |
| 85 |
|
| 86 |
**SRS_CONSTMAP_17_054: [** Otherwise, `ConstMap_CloneWriteable` shall return a non-`NULL` handle that can be used in subsequent calls. **]** |
| 87 |
|
| 88 |
|
| 89 |
### ConstMap_ContainsKey |
| 90 |
```C |
| 91 |
extern bool ConstMap_ContainsKey(CONSTMAP_HANDLE handle, const char* key); |
| 92 |
``` |
| 93 |
`ConstMap_ContainsKey` returns `true` if the map contains a key with the same value as parameter `key`. |
| 94 |
|
| 95 |
**SRS_CONSTMAP_17_024: [** If parameter `handle` or `key` are `NULL` then `ConstMap_ContainsKey` shall return `false`. **]** |
| 96 |
|
| 97 |
**SRS_CONSTMAP_17_025: [** Otherwise if a key exists then `ConstMap_ContainsKey` shall return `true`. **]** |
| 98 |
|
| 99 |
**SRS_CONSTMAP_17_026: [** If a key doesn't exist, then `ConstMap_ContainsKey` shall return `false`. **]** |
| 100 |
|
| 101 |
### ConstMap_ContainsValue |
| 102 |
```C |
| 103 |
extern bool ConstMap_ContainsValue(CONSTMAP_HANDLE handle, const char* value); |
| 104 |
``` |
| 105 |
|
| 106 |
`ConstMap_ContainsKey` returns `true` if at least one pair <key,value> in the map contains the `value` parameter. |
| 107 |
|
| 108 |
**SRS_CONSTMAP_17_027: [** If parameter `handle` or `value` is `NULL` then `ConstMap_ContainsValue` shall return `false`. **]** |
| 109 |
|
| 110 |
**SRS_CONSTMAP_17_028: [** Otherwise, if a pair <key, value> has its value equal to the parameter `value`, the `ConstMap_ContainsValue` shall return `true`. **]** |
| 111 |
|
| 112 |
**SRS_CONSTMAP_17_029: [** Otherwise, if such a <key, value> does not exist, then `ConstMap_ContainsValue` shall return `false`. **]** |
| 113 |
|
| 114 |
### ConstMap_GetValue |
| 115 |
```C |
| 116 |
extern const char* ConstMap_GetValue(CONSTMAP_HANDLE handle, const char* key); |
| 117 |
``` |
| 118 |
`ConstMap_GetValue` returns the value of a stored key. |
| 119 |
|
| 120 |
**SRS_CONSTMAP_17_040: [** If parameter `handle` or `key` is `NULL` then `ConstMap_GetValue` returns `NULL`. **]** |
| 121 |
|
| 122 |
**SRS_CONSTMAP_17_041: [** If the key is not found, then `ConstMap_GetValue` returns `NULL`. **]** |
| 123 |
|
| 124 |
**SRS_CONSTMAP_17_042: [** Otherwise, `ConstMap_GetValue` returns the key's value. **]** |
| 125 |
|
| 126 |
### ConstMap_GetInternals |
| 127 |
```C |
| 128 |
extern CONSTMAP_RESULT ConstMap_GetInternals(CONSTMAP_HANDLE handle, const char*const** keys, const char*const** values, size_t* count); |
| 129 |
``` |
| 130 |
**SRS_CONSTMAP_17_046: [** If parameter `handle`, `keys`, `values` or `count` is `NULL` then `ConstMap_GetInternals` shall return `CONSTMAP_INVALIDARG`. **]** |
| 131 |
|
| 132 |
**SRS_CONSTMAP_17_043: [** `ConstMap_GetInternals` shall produce in `*keys` a pointer to an array of `const char*` having all the keys stored so far by the map. **]** |
| 133 |
|
| 134 |
**SRS_CONSTMAP_17_044: [** `ConstMap_GetInternals` shall produce in `*values` a pointer to an array of `const char*` having all the values stored so far by the map. **]** |
| 135 |
|
| 136 |
**SRS_CONSTMAP_17_045: [** `ConstMap_GetInternals` shall produce in `*count` the number of stored keys and values. **]** |