mindex.h (3398B)
1 #ifndef __FINWO_MINDEX_H__ 2 #define __FINWO_MINDEX_H__ 3 4 /// mindex 5 /// ====== 6 /// 7 /// In-memory indexed store and fetch library 8 /// 9 /// This library makes use of [dep](https://github.com/finwo/dep) to manage it's 10 /// dependencies and exports. 11 /// 12 /// Installation 13 /// ------------ 14 /// 15 /// ```sh 16 /// dep add finwo/mindex 17 /// dep install 18 /// ``` 19 /// 20 /// After that, simply add `include lib/.dep/config.mk` in your makefile and include 21 /// the header file by adding `#include "finwo/mindex.h`. 22 /// 23 /// Features 24 /// -------- 25 /// 26 /// - Consistent interface, always working with pointers 27 /// - ANSI C (C99) 28 /// - Purge to be called when an item is removed 29 30 #include <stdlib.h> 31 32 /// API 33 /// --- 34 35 36 /// 37 /// ### Structures 38 /// 39 40 /// <details> 41 /// <summary>struct mindex_t</summary> 42 /// 43 /// The main handle of the mindex instance 44 ///<C 45 struct mindex_t { 46 int (*compare)(const void *a, const void *b, void *udata); 47 void (*purge)(void *item, void *udata); 48 void *udata; 49 size_t length; 50 size_t max; 51 void **items; 52 }; 53 ///> 54 /// </details> 55 56 /// 57 /// ### Methods 58 /// 59 60 /// <details> 61 /// <summary>mindex_init(cmp, purge, udata)</summary> 62 /// 63 /// Initialize a new in-memory index 64 ///<C 65 struct mindex_t * mindex_init(int (*compare)(const void *a, const void *b, void *udata), void (*purge)(void *item, void *udata), void *udata); 66 ///> 67 /// </details> 68 69 /// <details> 70 /// <summary>mindex_find(mindex, pattern, items, length)</summary> 71 /// 72 /// Intended for internal use or advanced usage (like fetching both index & 73 /// the pointer of the result) 74 ///<C 75 struct mindex_find_response * mindex_find(const struct mindex_t *mindex, const void *pattern, void **items, int length); 76 ///> 77 /// </details> 78 79 /// <details> 80 /// <summary>mindex_set(mindex, item)</summary> 81 /// 82 /// Insert or replace an existing item 83 ///<C 84 void mindex_set(struct mindex_t *mindex, void *item); 85 ///> 86 /// </details> 87 88 89 /// <details> 90 /// <summary>mindex_get(mindex, pattern)</summary> 91 /// 92 /// Simple query, fetch an entry in the index matching the pattern 93 ///<C 94 void * mindex_get(struct mindex_t *mindex, const void *pattern); 95 ///> 96 /// </details> 97 98 /// <details> 99 /// <summary>mindex_nth(mindex, index)</summary> 100 /// 101 /// Fetch the nth entry in the index 102 ///<C 103 void * mindex_nth(struct mindex_t *mindex, int index); 104 ///> 105 /// </details> 106 107 /// <details> 108 /// <summary>mindex_rand(mindex)</summary> 109 /// 110 /// Retrieve a single random entry from the index 111 ///<C 112 void * mindex_rand(struct mindex_t *mindex); 113 ///> 114 /// </details> 115 116 /// <details> 117 /// <summary>mindex_delete(mindex, pattern)</summary> 118 /// 119 /// Delete a single entry from the index matching the pattern 120 ///<C 121 void mindex_delete(struct mindex_t *mindex, const void *pattern); 122 ///> 123 /// </details> 124 125 /// <details> 126 /// <summary>mindex_length(mindex)</summary> 127 /// 128 /// The current amount of entries in the index 129 ///<C 130 size_t mindex_length(struct mindex_t *mindex); 131 ///> 132 /// </details> 133 134 /// <details> 135 /// <summary>mindex_free(mindex)</summary> 136 /// 137 /// Purge all entries from the index and free the memory used 138 ///<C 139 void mindex_free(struct mindex_t *mindex); 140 ///> 141 /// </details> 142 143 #endif // __FINWO_MINDEX_H__ 144 145 /// Testing 146 /// ------- 147 /// 148 /// If you want to run the library's tests, simply run `make test` to compile 149 /// the testing binary, and then `./test` to run the actual tests. 150 /// 151 /// License 152 /// ------- 153 /// 154 /// mindex source code is available under the MIT license.