granicus.if.org Git - transmission/blob - libtransmission/ptrarray.h

   1 /*
   2  * This file Copyright (C) 2008-2014 Mnemosyne LLC
   3  *
   4  * It may be used under the GNU GPL versions 2 or 3
   5  * or any future license endorsed by Mnemosyne LLC.
   6  *
   7  */
   8
   9 #pragma once
  10
  11 #ifndef __TRANSMISSION__
  12 #error only libtransmission should #include this header.
  13 #endif
  14
  15 #include "transmission.h"
  16 #include "tr-assert.h"
  17
  18 /**
  19  * @addtogroup utils Utilities
  20  * @{
  21  */
  22
  23 /**
  24  * @brief simple pointer array that resizes itself dynamically.
  25  */
  26 typedef struct tr_ptrArray
  27 {
  28     void** items;
  29     int n_items;
  30     int n_alloc;
  31 }
  32 tr_ptrArray;
  33
  34 typedef tr_voidptr_compare_func PtrArrayCompareFunc;
  35
  36 typedef void (* PtrArrayForeachFunc)(void*);
  37
  38 #define TR_PTR_ARRAY_INIT_STATIC { NULL, 0, 0 }
  39
  40 extern tr_ptrArray const TR_PTR_ARRAY_INIT;
  41
  42 /** @brief Destructor to free a tr_ptrArray's internal memory */
  43 void tr_ptrArrayDestruct(tr_ptrArray*, PtrArrayForeachFunc func);
  44
  45 /** @brief Iterate through each item in a tr_ptrArray */
  46 void tr_ptrArrayForeach(tr_ptrArray* array, PtrArrayForeachFunc func);
  47
  48 /** @brief Return the nth item in a tr_ptrArray
  49     @return the nth item in a tr_ptrArray */
  50 static inline void* tr_ptrArrayNth(tr_ptrArray* array, int i)
  51 {
  52     TR_ASSERT(array != NULL);
  53     TR_ASSERT(i >= 0);
  54     TR_ASSERT(i < array->n_items);
  55
  56     return array->items[i];
  57 }
  58
  59 /** @brief Remove the last item from the array and return it
  60     @return the pointer that's been removed from the array
  61     @see tr_ptrArrayBack() */
  62 void* tr_ptrArrayPop(tr_ptrArray* array);
  63
  64 /** @brief Return the last item in a tr_ptrArray
  65     @return the last item in a tr_ptrArray, or NULL if the array is empty
  66     @see tr_ptrArrayPop() */
  67 static inline void* tr_ptrArrayBack(tr_ptrArray* array)
  68 {
  69     return array->n_items > 0 ? tr_ptrArrayNth(array, array->n_items - 1) : NULL;
  70 }
  71
  72 void tr_ptrArrayErase(tr_ptrArray* t, int begin, int end);
  73
  74 static inline void tr_ptrArrayRemove(tr_ptrArray* t, int pos)
  75 {
  76     tr_ptrArrayErase(t, pos, pos + 1);
  77 }
  78
  79 /** @brief Peek at the array pointer and its size, for easy iteration */
  80 void** tr_ptrArrayPeek(tr_ptrArray* array, int* size);
  81
  82 static inline void tr_ptrArrayClear(tr_ptrArray* a)
  83 {
  84     a->n_items = 0;
  85 }
  86
  87 /** @brief Insert a pointer into the array at the specified position
  88     @return the index of the stored pointer */
  89 int tr_ptrArrayInsert(tr_ptrArray* array, void* insertMe, int pos);
  90
  91 /** @brief Append a pointer into the array */
  92 static inline int tr_ptrArrayAppend(tr_ptrArray* array, void* appendMe)
  93 {
  94     return tr_ptrArrayInsert(array, appendMe, -1);
  95 }
  96
  97 static inline void** tr_ptrArrayBase(tr_ptrArray const* a)
  98 {
  99     return a->items;
 100 }
 101
 102 /** @brief Return the number of items in the array
 103     @return the number of items in the array */
 104 static inline int tr_ptrArraySize(tr_ptrArray const* a)
 105 {
 106     return a->n_items;
 107 }
 108
 109 /** @brief Return True if the array has no pointers
 110     @return True if the array has no pointers */
 111 static inline bool tr_ptrArrayEmpty(tr_ptrArray const* a)
 112 {
 113     return tr_ptrArraySize(a) == 0;
 114 }
 115
 116 int tr_ptrArrayLowerBound(tr_ptrArray const* array, void const* key, tr_voidptr_compare_func compare, bool* exact_match);
 117
 118 /** @brief Insert a pointer into the array at the position determined by the sort function
 119     @return the index of the stored pointer */
 120 int tr_ptrArrayInsertSorted(tr_ptrArray* array, void* value, tr_voidptr_compare_func compare);
 121
 122 /** @brief Remove this specific pointer from a sorted ptrarray */
 123 void tr_ptrArrayRemoveSortedPointer(tr_ptrArray* t, void const* ptr, tr_voidptr_compare_func compare);
 124
 125 /** @brief Find a pointer from an array sorted by the specified sort function
 126     @return the matching pointer, or NULL if no match was found */
 127 void* tr_ptrArrayFindSorted(tr_ptrArray* array, void const* key, tr_voidptr_compare_func compare);
 128
 129 /* @} */