Debian Codegraph @

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

raw
1 VECTOR Requirements
2 ================
3
4 ## Overview
5
6 The VECTOR object is an index based collection of uniform size elements.
7
8 ## Exposed API
9 ```c
10
11 typedef struct VECTOR_TAG* VECTOR_HANDLE;
12
13 typedef bool(*PREDICATE_FUNCTION)(const void* element, const void* value);
14
15 /* creation */
16 extern VECTOR_HANDLE VECTOR_create(size_t elementSize);
17 extern VECTOR_HANDLE VECTOR_move(VECTOR_HANDLE handle);
18 extern void VECTOR_destroy(VECTOR_HANDLE handle);
19
20 /* insertion */
21 extern int VECTOR_push_back(VECTOR_HANDLE handle, const void* elements, size_t numElements);
22
23 /* removal */
24 extern void VECTOR_erase(VECTOR_HANDLE handle, void* elements, size_t numElements);
25 extern void VECTOR_clear(VECTOR_HANDLE handle);
26
27 /* access */
28 extern void* VECTOR_element(VECTOR_HANDLE handle, size_t index);
29 extern void* VECTOR_front(VECTOR_HANDLE handle);
30 extern void* VECTOR_back(VECTOR_HANDLE handle);
31 extern void* VECTOR_find_if(VECTOR_HANDLE handle, PREDICATE_FUNCTION pred, const void* value);
32
33 /* capacity */
34 extern size_t VECTOR_size(VECTOR_HANDLE handle);
35 ```
36
37 ### PREDICATE_FUNCTION
38 ```c
39 bool(*PREDICATE_FUNCTION)(const void* element, const void* value);
40 /**
41 * PREDICATE_FUNCTION defines a function prototype that is used in conjunction with `VECTOR_find_if()`.
42 * VECTOR_find_if will iterate through each element of the object and call the given function
43 * with two parameters. Once a match is found, a pointer to the matched element will be returned.
44 * NULL will be returned if no match is found.
45 * Care must be taken if one or both of the arguments are of type VECTOR_HANDLE. For example,
46 * calling the `VECTOR_move` from inside a `PREDICATE_FUNCTION` is not supported and may cause undefined
47 * behavior.
48 *
49 * - element: points to the member of the array being evaluated.
50 * - value: points to a variable whose contents will be used to find a matching element.
51 **/
52
53 ```
54
55 ### VECTOR_create
56 ```c
57 VECTOR_HANDLE VECTOR_create(size_t elementSize)
58 ```
59
60 **SRS_VECTOR_10_001: [** VECTOR_create shall allocate a VECTOR_HANDLE that will contain an empty vector. The size of each element is given in elementSize. **]**
61
62 **SRS_VECTOR_10_002: [** VECTOR_create shall fail and return NULL if elementsize is equal to 0. **]**
63
64 **SRS_VECTOR_10_033: [** VECTOR_create shall fail and return NULL if malloc fails. **]**
65
66 ### VECTOR_move
67 ```c
68 VECTOR_HANDLE VECTOR_move(VECTOR_HANDLE handle)
69 ```
70
71 **SRS_VECTOR_10_004: [** VECTOR_move shall allocate a VECTOR_HANLDE and move the data to it from the given handle. **]**
72
73 **SRS_VECTOR_10_005: [** VECTOR_move shall fail and return NULL if the given handle is NULL. **]**
74
75 **SRS_VECTOR_10_006: [** VECTOR_move shall fail and return NULL if malloc fails. **]**
76
77 ### VECTOR_destroy
78 ```c
79 void VECTOR_destroy(VECTOR_HANDLE handle)
80 ```
81
82 **SRS_VECTOR_10_008: [** VECTOR_destroy shall free the given handle and its internal storage. **]**
83
84 **SRS_VECTOR_10_009: [** VECTOR_destroy shall return if the given handle is NULL. **]**
85
86 ### VECTOR_push_back
87 ```c
88 int VECTOR_push_back(VECTOR_HANDLE handle, const void* elements, size_t numElements)
89 ```
90
91 **SRS_VECTOR_10_011: [** VECTOR_push_back shall fail and return non-zero if `handle` is NULL. **]**
92
93 **SRS_VECTOR_10_034: [** VECTOR_push_back shall fail and return non-zero if `elements` is NULL. **]**
94
95 **SRS_VECTOR_10_035: [** VECTOR_push_back shall fail and return non-zero if `numElements` is 0. **]**
96
97 **SRS_VECTOR_10_012: [** VECTOR_push_back shall fail and return non-zero if memory allocation fails. **]**
98
99 **SRS_VECTOR_10_013: [** VECTOR_push_back shall append the given elements and return 0 indicating success. **]**
100
101 ### VECTOR_erase
102 ```c
103 void VECTOR_erase(VECTOR_HANDLE handle, void* elements, size_t numElements)
104 ```
105
106 **SRS_VECTOR_10_014: [** VECTOR_erase shall remove the `numElements` starting at `elements` and reduce its internal storage. **]**
107
108 **SRS_VECTOR_10_015: [** VECTOR_erase shall return if `handle` is NULL. **]**
109
110 **SRS_VECTOR_10_038: [** VECTOR_erase shall return if `elements` is NULL. **]**
111
112 **SRS_VECTOR_10_040: [** VECTOR_erase shall return if `elements` is out of bound. **]**
113
114 **SRS_VECTOR_10_041: [** VECTOR_erase shall return if `elements` is misaligned. **]**
115
116 **SRS_VECTOR_10_039: [** VECTOR_erase shall return if `numElements` is 0. **]**
117
118 **SRS_VECTOR_10_027: [** VECTOR_erase shall return if `numElements` is out of bound. **]**
119
120
121 ### VECTOR_clear
122 ```c
123 void VECTOR_clear(VECTOR_HANDLE handle)
124 ```
125
126 **SRS_VECTOR_10_016: [** VECTOR_clear shall remove all elements from the object and release internal storage. **]**
127
128 **SRS_VECTOR_10_017: [** VECTOR_clear shall return if the object is NULL or empty. **]**
129
130 ### VECTOR_element
131 ```c
132 void* VECTOR_element(VECTOR_HANDLE handle, size_t index)
133 ```
134
135
136 **SRS_VECTOR_10_018: [** VECTOR_element shall return a pointer to the element at the given index. **]**
137
138 **SRS_VECTOR_10_019: [** VECTOR_element shall fail and return NULL if handle is NULL. **]**
139
140 **SRS_VECTOR_10_020: [** VECTOR_element shall fail and return NULL if the given index is out of range. **]**
141
142 ### VECTOR_front
143 ```c
144 void* VECTOR_front(VECTOR_HANDLE handle)
145 ```
146
147
148 **SRS_VECTOR_10_021: [** VECTOR_front shall return the element at index 0. **]**
149
150 **SRS_VECTOR_10_022: [** VECTOR_front shall fail and return NULL if handle is NULL. **]**
151
152 **SRS_VECTOR_10_028: [** VECTOR_front shall fail and return NULL if the vector is empty. **]**
153
154 ### VECTOR_back
155 ```c
156 void* VECTOR_back(VECTOR_HANDLE handle)
157 ```
158
159
160 **SRS_VECTOR_10_023: [** VECTOR_back shall return the last element of the vector. **]**
161
162 **SRS_VECTOR_10_024: [** VECTOR_back shall fail and return NULL if handle is NULL. **]**
163
164 **SRS_VECTOR_10_029: [** VECTOR_back shall fail and return NULL if the vector is empty. **]**
165
166 ### VECTOR_find_if
167 ```c
168 void* VECTOR_find_if(VECTOR_HANDLE handle, PREDICATE_FUNCTION pred, const void* value)
169 ```
170
171
172 **SRS_VECTOR_10_030: [** VECTOR_find_if shall fail and return NULL if `handle` is NULL. **]**
173
174 **SRS_VECTOR_10_036: [** VECTOR_find_if shall fail and return NULL if `pred` is NULL. **]**
175
176 **SRS_VECTOR_10_031: [** VECTOR_find_if shall return the first element in the vector that matches `pred`. **]**
177
178 **SRS_VECTOR_10_032: [** VECTOR_find_if shall return NULL if no matching element is found. **]**
179
180 ### VECTOR_size
181 ```c
182 size_t VECTOR_size(VECTOR_HANDLE handle)
183 ```
184
185 **SRS_VECTOR_10_025: [** VECTOR_size shall return the number of elements stored with the given handle. **]**
186
187 **SRS_VECTOR_10_026: [** VECTOR_size shall return 0 if the given handle is NULL. **]**