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