Debian Codegraph @

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

raw
1 singlylinkedlist requirements
2 ================
3
4 ## Overview
5
6 SinglyLinkedList is module that provides the functionality of a singly linked list, allowing its user to add, remove and iterate the list elements.
7
8 ## Exposed API
9
10 ```c
11 typedef struct SINGLYLINKEDLIST_INSTANCE_TAG* SINGLYLINKEDLIST_HANDLE;
12 typedef struct LIST_ITEM_INSTANCE_TAG* LIST_ITEM_HANDLE;
13 typedef bool (*LIST_MATCH_FUNCTION)(LIST_ITEM_HANDLE list_item, const void* match_context);
14 typedef bool (*LIST_CONDITION_FUNCTION)(const void* item, const void* match_context, bool* continue_processing);
15 typedef void (*LIST_ACTION_ACTION)(const void* item, const void* action_context, bool* continue_processing);
16
17 extern SINGLYLINKEDLIST_HANDLE singlylinkedlist_create(void);
18 extern void singlylinkedlist_destroy(SINGLYLINKEDLIST_HANDLE list);
19 extern LIST_ITEM_HANDLE singlylinkedlist_add(SINGLYLINKEDLIST_HANDLE list, const void* item);
20 extern LIST_ITEM_HANDLE singlylinkedlist_add_head(SINGLYLINKEDLIST_HANDLE list, const void* item);
21 extern int singlylinkedlist_remove(SINGLYLINKEDLIST_HANDLE list, LIST_ITEM_HANDLE item_handle);
22 extern LIST_ITEM_HANDLE singlylinkedlist_get_head_item(SINGLYLINKEDLIST_HANDLE list);
23 extern LIST_ITEM_HANDLE singlylinkedlist_get_next_item(LIST_ITEM_HANDLE item_handle);
24 extern LIST_ITEM_HANDLE singlylinkedlist_find(SINGLYLINKEDLIST_HANDLE list, LIST_MATCH_FUNCTION match_function, const void* match_context);
25 extern int singlylinkedlist_remove_if(SINGLYLINKEDLIST_HANDLE list, LIST_CONDITION_FUNCTION condition_function, const void* match_context);
26 extern int singlylinkedlist_foreach(SINGLYLINKEDLIST_HANDLE list, LIST_ACTION_ACTION action_function, const void* action_context);
27 extern const void* singlylinkedlist_item_get_value(LIST_ITEM_HANDLE item_handle);
28 ```
29
30 ### singlylinkedlist_create
31 ```c
32 extern SINGLYLINKEDLIST_HANDLE singlylinkedlist_create(void);
33 ```
34
35 **SRS_LIST_01_001: [** singlylinkedlist_create shall create a new list and return a non-NULL handle on success. **]**
36
37 **SRS_LIST_01_002: [** If any error occurs during the list creation, singlylinkedlist_create shall return NULL. **]**
38
39 ### singlylinkedlist_destroy
40 ```c
41 extern void singlylinkedlist_destroy(SINGLYLINKEDLIST_HANDLE list);
42 ```
43 **SRS_LIST_01_003: [** singlylinkedlist_destroy shall free all resources associated with the list identified by the handle argument. **]**
44
45 **SRS_LIST_01_004: [** If the list argument is NULL, no freeing of resources shall occur. **]**
46
47 ### singlylinkedlist_add
48 ```c
49 extern int singlylinkedlist_add(SINGLYLINKEDLIST_HANDLE list, const void* item);
50 ```
51
52 **SRS_LIST_01_005: [** singlylinkedlist_add shall add one item to the tail of the list and on success it shall return a handle to the added item. **]**
53
54 **SRS_LIST_01_006: [** If any of the arguments is NULL, singlylinkedlist_add shall not add the item to the list and return NULL. **]**
55
56 **SRS_LIST_01_007: [** If allocating the new list node fails, singlylinkedlist_add shall return NULL. **]**
57
58 ### singlylinkedlist_get_head_item
59 ```c
60 extern const void* singlylinkedlist_get_head_item(SINGLYLINKEDLIST_HANDLE list);
61 ```
62 **SRS_LIST_01_008: [** singlylinkedlist_get_head_item shall return the head of the list. **]**
63
64 **SRS_LIST_01_009: [** If the list argument is NULL, singlylinkedlist_get_head_item shall return NULL. **]**
65
66 **SRS_LIST_01_010: [** If the list is empty, list_get_head_item_shall_return NULL. **]**
67
68 ### singlylinkedlist_get_next_item
69 ```c
70 extern LIST_ITEM_HANDLE singlylinkedlist_get_next_item(LIST_ITEM_HANDLE item_handle);
71 ```
72
73 **SRS_LIST_01_018: [** singlylinkedlist_get_next_item shall return the next item in the list following the item item_handle. **]**
74
75 **SRS_LIST_01_019: [** If item_handle is NULL then singlylinkedlist_get_next_item shall return NULL. **]**
76
77 **SRS_LIST_01_022: [** If no more items exist in the list after the item_handle item, singlylinkedlist_get_next_item shall return NULL. **]**
78
79 ### singlylinkedlist_find
80 ```c
81 extern const void* singlylinkedlist_find(SINGLYLINKEDLIST_HANDLE list, const void* match_context, LIST_MATCH_FUNCTION match_function);
82 ```
83
84 **SRS_LIST_01_011: [** singlylinkedlist_find shall iterate through all items in a list and return the first one that satisfies a certain match function. **]**
85
86 **SRS_LIST_01_012: [** If the list or the match_function argument is NULL, singlylinkedlist_find shall return NULL. **]**
87
88 **SRS_LIST_01_014: [** list find shall determine whether an item satisfies the match criteria by invoking the match function for each item in the list until a matching item is found. **]**
89
90 **SRS_LIST_01_013: [** The match_function shall get as arguments the list item being attempted to be matched and the match_context as is. **]**
91
92 **SRS_LIST_01_016: [** If the match function returns false, singlylinkedlist_find shall consider that item as not matching. **]**
93
94 **SRS_LIST_01_017: [** If the match function returns true, singlylinkedlist_find shall consider that item as matching. **]**
95
96 **SRS_LIST_01_015: [** If the list is empty, singlylinkedlist_find shall return NULL. **]**
97
98 ### singlylinkedlist_remove_if
99 ```c
100 extern int singlylinkedlist_remove_if(SINGLYLINKEDLIST_HANDLE list, LIST_CONDITION_FUNCTION condition_function, void* match_context);
101 ```
102
103 **SRS_LIST_09_001: [** If the list or the condition_function argument is NULL, singlylinkedlist_remove_if shall return non-zero value. **]**
104
105 **SRS_LIST_09_002: [** singlylinkedlist_remove_if shall iterate through all items in a list and remove all that satisfies a certain condition function. **]**
106
107 **SRS_LIST_09_003: [** singlylinkedlist_remove_if shall determine whether an item satisfies the condition criteria by invoking the condition function for that item. **]**
108
109 **SRS_LIST_09_004: [** If the condition function returns true, singlylinkedlist_find shall consider that item as to be removed. **]**
110
111 **SRS_LIST_09_005: [** If the condition function returns false, singlylinkedlist_find shall consider that item as not to be removed. **]**
112
113 **SRS_LIST_09_006: [** If the condition function returns continue_processing as false, singlylinkedlist_remove_if shall stop iterating through the list and return. **]**
114
115 **SRS_LIST_09_007: [** If no errors occur, singlylinkedlist_remove_if shall return zero. **]**
116
117 ### singlylinkedlist_foreach
118 ```c
119 extern int singlylinkedlist_foreach(SINGLYLINKEDLIST_HANDLE list, LIST_ACTION_ACTION action_function, void* action_context);
120 ```
121
122 **SRS_LIST_09_008: [** If the list or the action_function argument is NULL, singlylinkedlist_foreach shall return non-zero value. **]**
123
124 **SRS_LIST_09_009: [** singlylinkedlist_foreach shall iterate through all items in a list and invoke action_function for each one of them. **]**
125
126 **SRS_LIST_09_010: [** If the condition function returns continue_processing as false, singlylinkedlist_foreach shall stop iterating through the list and return. **]**
127
128 **SRS_LIST_09_011: [** If no errors occur, singlylinkedlist_foreach shall return zero. **]**
129
130 ### singlylinkedlist_remove
131 ```c
132 extern int singlylinkedlist_remove(SINGLYLINKEDLIST_HANDLE list, LIST_ITEM_HANDLE item_handle);
133 ```
134
135 **SRS_LIST_01_023: [** singlylinkedlist_remove shall remove a list item from the list and on success it shall return 0. **]**
136
137 **SRS_LIST_01_024: [** If any of the arguments list or item_handle is NULL, singlylinkedlist_remove shall fail and return a non-zero value. **]**
138
139 **SRS_LIST_01_025: [** If the item item_handle is not found in the list, then singlylinkedlist_remove shall fail and return a non-zero value. **]**
140
141 ### singlylinkedlist_item_get_value
142 ```c
143 extern const void* singlylinkedlist_item_get_value(LIST_ITEM_HANDLE item_handle);
144 ```
145
146 **SRS_LIST_01_020: [** singlylinkedlist_item_get_value shall return the value associated with the list item identified by the item_handle argument. **]**
147
148 **SRS_LIST_01_021: [** If item_handle is NULL, singlylinkedlist_item_get_value shall return NULL. **]**
149
150 ### singlylinkedlist_add_head
151 ```
152 extern LIST_ITEM_HANDLE singlylinkedlist_add_head(SINGLYLINKEDLIST_HANDLE list, const void* item);
153 ```
154
155 `singlylinkedlist_add` inserts `item` at the head of `list`.
156
157 **SRS_LIST_02_001: [** If `list` is `NULL` then `singlylinkedlist_add_head` shall fail and return `NULL`. **]**
158
159 **SRS_LIST_02_002: [** `singlylinkedlist_add_head` shall insert `item` at head, succeed and return a non-`NULL` value. **]**
160
161 **SRS_LIST_02_003: [** If there are any failures then `singlylinkedlist_add_head` shall fail and return `NULL`. **]**