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