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