parser: Let the TIMESERIES command accept optional data-source names.

[sysdb.git] / src / include / utils / llist.h

diff --git a/src/include/utils/llist.h b/src/include/utils/llist.h
index 354e97665649fa915fdd67e7a08d330d73db5e71..8d2b96e9ae95cf38a693d1a701397160e5936b1a 100644 (file)
--- a/src/include/utils/llist.h
+++ b/src/include/utils/llist.h
@@ -30,6 +30,8 @@
 
 #include "core/object.h"
 
+#include <stdbool.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -53,6 +55,14 @@ sdb_llist_create(void);
 void
 sdb_llist_destroy(sdb_llist_t *list);
 
+/*
+ * sdb_llist_clear:
+ * Remove all elements from the list, releasing the included objects
+ * (decrement the ref-count).
+ */
+void
+sdb_llist_clear(sdb_llist_t *list);
+
 /*
  * sdb_llist_clone:
  * Clone an existing list. The objects stored in the list will not be copied
@@ -93,7 +103,7 @@ sdb_llist_append(sdb_llist_t *list, sdb_object_t *obj);
  *  - a negative value on failure
  */
 int
-sdb_llist_insert(sdb_llist_t *list, sdb_object_t *obj, size_t index);
+sdb_llist_insert(sdb_llist_t *list, sdb_object_t *obj, size_t idx);
 
 /*
  * sdb_llist_insert_sorted:
@@ -113,27 +123,77 @@ sdb_llist_insert(sdb_llist_t *list, sdb_object_t *obj, size_t index);
  *  - a negative value on failure
  */
 int
-sdb_llist_insert_sorted(sdb_llist_t *list, sdb_object_t *obj,
-               int (*compare)(const sdb_object_t *, const sdb_object_t *));
+sdb_llist_insert_sorted(sdb_llist_t *list,
+               sdb_object_t *obj, sdb_object_cmp_cb);
+
+/*
+ * sdb_llist_get:
+ * Returns the i-th element of the list or NULL in case of an error. The
+ * reference count of the element is incremented before returning it to share
+ * ownership between the list and the caller.
+ */
+sdb_object_t *
+sdb_llist_get(sdb_llist_t *list, size_t i);
+
+/*
+ * sdb_llist_search:
+ * Search for a object in the given 'list'. The function will return the first
+ * entry for which the 'lookup' callback returns 0. The 'user_data' is passed
+ * on to the lookup function on each invocation.
+ *
+ * Returns:
+ *  - a pointer to the first matching object
+ *  - NULL else
+ */
+sdb_object_t *
+sdb_llist_search(sdb_llist_t *list,
+               sdb_object_lookup_cb lookup, const void *user_data);
 
-/* sdb_llist_search:
- * Search for a 'key' in the given 'list'. The function will return the first
- * entry that matches the specified 'key'. For that purpose, the 'compare'
- * function is used. It should return 0 iff the two arguments compare equal.
+/*
+ * sdb_llist_search_by_name:
+ * Search for an object named 'key' in the given 'list'. The function will
+ * return the first entry whose name matches the specified 'key' ignoring the
+ * case of the characters.
  *
  * Returns:
- *  - a pointer the sdb_object_t containing the matching entry
+ *  - a pointer to the first matching object
  *  - NULL else
  */
 sdb_object_t *
-sdb_llist_search(sdb_llist_t *list, const sdb_object_t *key,
-               int (*compare)(const sdb_object_t *, const sdb_object_t *));
+sdb_llist_search_by_name(sdb_llist_t *list, const char *key);
+
+/*
+ * sdb_llist_remove:
+ * Removes and returns the first matching element of the list. The ref-count
+ * of the item will not be changed, that is, if the element will not be used
+ * any further, it should be de-referenced by the caller.
+ *
+ * Returns:
+ *  - a pointer to the first matching object
+ *  - NULL else
+ */
+sdb_object_t *
+sdb_llist_remove(sdb_llist_t *list,
+               sdb_object_lookup_cb lookup, const void *user_data);
+
+/*
+ * sdb_llist_remove_by_name:
+ * Removes and returns the first element whose name matches the specified key.
+ * The ref-count of the item will not be changed, that is, if the element will
+ * not be used any further, it should be de-referenced by the caller.
+ *
+ * Returns:
+ *  - a pointer to the first matching object
+ *  - NULL else
+ */
+sdb_object_t *
+sdb_llist_remove_by_name(sdb_llist_t *list, const char *key);
 
 /*
  * sdb_llist_shift:
  * Removes and returns the first element of the list. The ref-count of the
  * item will not be changed, that is, if the element will not be used any
- * further, it should be re-referenced by the caller.
+ * further, it should be de-referenced by the caller.
  *
  * Returns:
  *  - the former first element of the list
@@ -142,7 +202,8 @@ sdb_llist_search(sdb_llist_t *list, const sdb_object_t *key,
 sdb_object_t *
 sdb_llist_shift(sdb_llist_t *list);
 
-/* sdb_llist_get_iter, sdb_llist_iter_has_next, sdb_llist_iter_get_next:
+/*
+ * sdb_llist_get_iter, sdb_llist_iter_has_next, sdb_llist_iter_get_next:
  * Iterate through the list, element by element.
  *
  * sdb_llist_iter_get_next returns NULL if there is no next element.
@@ -152,11 +213,32 @@ sdb_llist_get_iter(sdb_llist_t *list);
 void
 sdb_llist_iter_destroy(sdb_llist_iter_t *iter);
 
-_Bool
+bool
 sdb_llist_iter_has_next(sdb_llist_iter_t *iter);
 sdb_object_t *
 sdb_llist_iter_get_next(sdb_llist_iter_t *iter);
 
+/*
+ * sdb_llist_iter_remove_current:
+ * Remove the current object from the list, that is, the object which was
+ * returned by the last call to sdb_llist_iter_get_next().
+ *
+ * This operation is not safe if another iterator is in use at the same time.
+ *
+ * Returns:
+ *  - 0 on success
+ *  - a negative value else
+ */
+int
+sdb_llist_iter_remove_current(sdb_llist_iter_t *iter);
+
+/*
+ * sdb_llist_len:
+ * Return the length (number of elements) of the list.
+ */
+size_t
+sdb_llist_len(sdb_llist_t *list);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif