linked_list.h 3.21 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
/****************************************************************************
 * Linked list header file	                                                *
 ****************************************************************************/

/**
 * @file linked_list.h
 * @author Celine Mercier
 * @date February 22th 2017
 * @brief Header file for linked list functions.
 */


#ifndef LINKED_LIST_H_
#define LINKED_LIST_H_


#include <stdlib.h>
#include <stdio.h>
#include <stdint.h>


/**
 * @brief Structure for a node in a double linked chain.
 */
typedef struct Linked_list_node {
	void*                      value;    				     		/**< A pointer (the value kept).
																	 */
	struct Linked_list_node* next;    							/**< A pointer on the next node.
																	 */
	struct Linked_list_node* previous;    				    	/**< A pointer on the previous node.
																	 */
} Linked_list_node_t, *Linked_list_node_p;


/**
 * @brief Adds a new node at the end of a linked list.
 *
 * Works even if it is the first node.
 *
 * @param head A pointer on the first node of the linked list, or NULL if the list is empty.
 * @param value The value to associate with the node.
 *
 * @returns A pointer on the new head node of the linked list.
 * @retval NULL if an error occurred.
 *
 * @since February 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Linked_list_node_p ll_add(Linked_list_node_p head, void* value);


/**
 * @brief Sets a value at a given index of the list.
 *
 * @param head A pointer on the first node of the linked list, or NULL if the list is empty.
 * @param idx The index of the node at which the value should be changed.
 * @param value The new value to associate with the node.
 *
 * @returns A value indicating the success of the operation.
 * @retval 0 if the operation was successfully completed.
 * @retval -1 if an error occurred.
 *
 * @since February 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
int ll_set(Linked_list_node_p head, int idx, void* value);


/**
 * @brief Gets a node from its index.
 *
 * @warning The pointer returned is a pointer on the node and not on the value.
 *
 * @param head A pointer on the first node of the linked list, or NULL if the list is empty.
 * @param idx The index of the node to retrieve.
 *
 * @returns A pointer on the retrieved node.
 * @retval NULL if an error occurred.
 *
 * @since February 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Linked_list_node_p ll_get(Linked_list_node_p head, int idx);


/**
 * @brief Deletes a node.
 *
 * @param head A pointer on the first node of the linked list.
 * @param idx The index of the node to delete.
 *
 * @returns A pointer on the new head node of the linked list.
93
 * @retval NULL if the list is now empty, or if the node did not exist.	  // TODO discuss
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
 *
 * @since February 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
Linked_list_node_p ll_delete(Linked_list_node_p head, int idx);


/**
 * @brief Frees all the nodes of a linked list.
 *
 * @param head A pointer on the first node of the linked list.
 *
 * @since February 2017
 * @author Celine Mercier (celine.mercier@metabarcoding.org)
 */
void ll_free(Linked_list_node_p head);


#endif /* LINKED_LIST_H_ */