74 lines
4.7 KiB
Plaintext
74 lines
4.7 KiB
Plaintext
.TL
|
|
single_linked_list.h
|
|
|
|
.AU
|
|
Wael Karram
|
|
|
|
.AB no
|
|
Documentation for single_linked_list.h
|
|
.AE
|
|
|
|
.DA
|
|
|
|
.LP
|
|
This header defines a linked list, with one link per node. Using the prepoccessor variable SINGLE_LINKED_LIST_H used as an include guard.
|
|
.br
|
|
Relies on single_node.h to implement the nodes.
|
|
|
|
.LP
|
|
These are the compile-time constants declared by this header:
|
|
.br
|
|
SUCCESS_CODE_SINGLE_LINKED_LIST_C, this is the code returned by a function on succcess, evaluates to 1.
|
|
.br
|
|
FAILURE_CODE_SINGLE_LINKED_LIST_C, this is the code returned by a function on failure, evaluates to 0.
|
|
.br
|
|
INDEX_NOT_FOUND_CODE_SINGLE_LINKED_LIST_C, this is the code returned by a function when a requested index is not found, evaluates to -1.
|
|
.br
|
|
INVALID_INPUT_CODE_SINGLE_LINKED_LIST_C, this is the code returned by a function when recieving invalid input, evaluates to -2.
|
|
.br
|
|
CODE_FREE_SUCCESS_MALFORMED_SINGLE_LINKED_LIST_C, this code is returned when freeing the data is successful, but the list is maformed, evaluates to -1.
|
|
.br
|
|
INDEX_HEAD_LINKED_LIST, this is the index of the head of the linked list, evaluates to 0.
|
|
|
|
|
|
.LP
|
|
These are the function defitions and input arguments for this data structre:
|
|
.br
|
|
linked_list* initialize_single_linked_list(): initializes an empty linked list, returns NULL on failure.
|
|
.br
|
|
int aLPend_node_single_linked_list(linked_list_t *list, node_t *node): aLPends the node to the given list, returns success if worked, otherwise failure code is returned.
|
|
.br
|
|
int prepend_node_single_linked_list(linked_list_t *list, node_t *node): prepends the node to the given list, returns success if worked, otherwise failure code is returned.
|
|
.br
|
|
int aLPend_node_data_single_linked_list(linked_list_t *list, void *data): much like the node aLPending function, but creates the node itself - note that the data can be NULL, will also return failure code when allocation of the node fails.
|
|
.br
|
|
int prepend_node_data_single_linked_list(linked_list_t *list, void *data): much like the node prepending function, but creates the node itself - note that the data can be NULL, will also return failure code when allocation of the node fails.
|
|
.br
|
|
int add_node_i_single_linked_list(linked_list_t *list, node_t *node, int i): much like aLPend node, but might also fail when the index is invalid (returning the aforementioned error code).
|
|
.br
|
|
int add_node_data_i_single_linked_list(linked_list_t *list, void *data, int i): much like the node insertion function, but also attempts to allocate a node and put the data in it beforehand, will fail with the failure error code if allocation fails.
|
|
.br
|
|
void* read_node_i_single_linked_list(linked_list_t *list, int i): attempts to return the stored data at the ith node, will return NULL if the list is NULL or index is invalid.
|
|
.br
|
|
node_t* get_node_i_single_linked_list(linked_list_t *list, int i, int *error): attempts to return the pointer to the i\*{th\*} nodes in the list, returns NULL on failure - sets the error code via the pointer as to allow to return pointers from the function (error must not be NULL).
|
|
.br
|
|
int get_node_index_pointer_single_linked_list(linked_list_t *list, node_t *node): attempts to find the index of a given node, returns INVALID_INPUT_CODE_LINKED_LIST_C on invalid input and returns INDEX_NOT_FOUND_CODE_SINGLE_LINKED_LIST_C when the given node doesn't exist in the given linked list.
|
|
.br
|
|
int get_node_index_data_single_linked_list(linked_list_t *list, void *data, int *(comparison_function)(const void*, const void*)): attempts to find the index of a node that stores the given data, returns INVALID_INPUT_CODE_LINKED_LIST_C on invalid input (including a NULL comparison function) and returns INDEX_NOT_FOUND_CODE_SINGLE_LINKED_LIST_C when the given node doesn't exist in the given linked list.
|
|
.br
|
|
int remove_node_i_single_linked_list(linked_list_t *list, int i): frees the i\*{th\*} node in the given list, returns FAILURE_CODE_SINGLE_LINKED_LIST_C on failure (including invalid input), and returns SUCCESS_CODE_SINGLE_LINKED_LIST_C on success. Note that it doesn't free the data.
|
|
.br
|
|
int remove_node_i_data_single_linked_list(linked_list_t *list, int i): frees the i\*{th\*} node in the given list, returns FAILURE_CODE_SINGLE_LINKED_LIST_C on failure (including invalid input), and returns SUCCESS_CODE_SINGLE_LINKED_LIST_C on success. Uses free_function to free the data, if it is NULL: will use stdlib's free().
|
|
.br
|
|
void* read_node_head_single_linked_list(linked_list_t *list, int *error): attempts to read the data at the first node, will return NULL on invalid input or first node being NULL.
|
|
.br
|
|
|
|
.UL node_t \0which
|
|
has the fields
|
|
.I "next" \0and
|
|
.I "data" ,
|
|
the former of which is another node pointer, and the latter is a void pointer.
|
|
.br
|
|
It is of note that this header type-defines the aformentioned node as
|
|
.I "node_t" .
|