Debian Codegraph @

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

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