pceplib/pcep_utils_ordered_list.h

   1 // SPDX-License-Identifier: LGPL-2.1-or-later
   2 /*
   3  * This file is part of the PCEPlib, a PCEP protocol library.
   4  *
   5  * Copyright (C) 2020 Volta Networks https://voltanet.io/
   6  *
   7  * Author : Brady Johnson <brady@voltanet.io>
   8  *
   9  */
  10
  11
  12 #ifndef INCLUDE_PCEPUTILSORDEREDLIST_H_
  13 #define INCLUDE_PCEPUTILSORDEREDLIST_H_
  14
  15 #include <stdbool.h>
  16
  17 typedef struct ordered_list_node_ {
  18         struct ordered_list_node_ *next_node;
  19         void *data;
  20
  21 } ordered_list_node;
  22
  23 /* The implementation of this function will receive a pointer to the
  24  * new data to be inserted and a pointer to the list_entry, and should
  25  * return:
  26  *   < 0  if new_entry  < list_entry
  27  *   == 0 if new_entry == list_entry (new_entry will be inserted after
  28  * list_entry) > 0  if new_entry  > list_entry
  29  */
  30 typedef int (*ordered_compare_function)(void *list_entry, void *new_entry);
  31
  32 /* Compare function that compares pointers */
  33 int pointer_compare_function(void *list_entry, void *new_entry);
  34
  35 typedef struct ordered_list_handle_ {
  36         ordered_list_node *head;
  37         unsigned int num_entries;
  38         ordered_compare_function compare_function;
  39
  40 } ordered_list_handle;
  41
  42 ordered_list_handle *ordered_list_initialize(ordered_compare_function func_ptr);
  43 void ordered_list_destroy(ordered_list_handle *handle);
  44
  45 /* Add a new ordered_list_node to the list, using the ordered_compare_function
  46  * to determine where in the list to add it. The newly created ordered_list_node
  47  * will be returned.
  48  */
  49 ordered_list_node *ordered_list_add_node(ordered_list_handle *handle,
  50                                          void *data);
  51
  52 /* Find an entry in the ordered_list using the ordered_compare_function to
  53  * compare the data passed in.
  54  * Return the node if found, NULL otherwise.
  55  */
  56 ordered_list_node *ordered_list_find(ordered_list_handle *handle, void *data);
  57
  58 /* The same as the previous function, but with a specific orderedComparefunction
  59  */
  60 ordered_list_node *ordered_list_find2(ordered_list_handle *handle, void *data,
  61                                       ordered_compare_function compare_func);
  62
  63 /* Remove the first entry in the list and return the data it points to.
  64  * Will return NULL if the handle is NULL or if the list is empty.
  65  */
  66 void *ordered_list_remove_first_node(ordered_list_handle *handle);
  67
  68 /* Remove the first entry in the list that has the same data, using the
  69  * ordered_compare_function, and return the data it points to.
  70  * Will return NULL if the handle is NULL or if the list is empty or
  71  * if no entry is found that equals data.
  72  */
  73 void *ordered_list_remove_first_node_equals(ordered_list_handle *handle,
  74                                             void *data);
  75
  76 /* The same as the previous function, but with a specific orderedComparefunction
  77  */
  78 void *ordered_list_remove_first_node_equals2(ordered_list_handle *handle,
  79                                              void *data,
  80                                              ordered_compare_function func_ptr);
  81
  82 /* Remove the node "node_to_remove" and adjust the "prev_node" pointers
  83  * accordingly, returning the data pointed to by "node_to_remove". Will return
  84  * NULL if the handle is NULL or if the list is empty.
  85  */
  86 void *ordered_list_remove_node(ordered_list_handle *handle,
  87                                ordered_list_node *prev_node,
  88                                ordered_list_node *node_to_remove);
  89
  90 /* Remove the node "node_to_remove" by searching for it in the entire list,
  91  * returning the data pointed to by "node_to_remove".
  92  * Will return NULL if the handle is NULL or if the list is empty.
  93  */
  94 void *ordered_list_remove_node2(ordered_list_handle *handle,
  95                                 ordered_list_node *node_to_remove);
  96
  97 #endif /* INCLUDE_PCEPUTILSORDEREDLIST_H_ */