mindex.h (3402B)
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 /// 33 /// API 34 /// --- 35 36 37 /// 38 /// ### Structures 39 /// 40 41 /// <details> 42 /// <summary>struct mindex_t</summary> 43 /// 44 /// The main handle of the mindex instance 45 ///<C 46 struct mindex_t { 47 int (*compare)(const void *a, const void *b, void *udata); 48 void (*purge)(void *item, void *udata); 49 void *udata; 50 size_t length; 51 size_t max; 52 void **items; 53 }; 54 ///> 55 /// </details> 56 57 /// 58 /// ### Methods 59 /// 60 61 /// <details> 62 /// <summary>mindex_init(cmp, purge, udata)</summary> 63 /// 64 /// Initialize a new in-memory index 65 ///<C 66 struct mindex_t * mindex_init(int (*compare)(const void *a, const void *b, void *udata), void (*purge)(void *item, void *udata), void *udata); 67 ///> 68 /// </details> 69 70 /// <details> 71 /// <summary>mindex_find(mindex, pattern, items, length)</summary> 72 /// 73 /// Intended for internal use or advanced usage (like fetching both index & 74 /// the pointer of the result) 75 ///<C 76 struct mindex_find_response * mindex_find(const struct mindex_t *mindex, const void *pattern, void **items, int length); 77 ///> 78 /// </details> 79 80 /// <details> 81 /// <summary>mindex_set(mindex, item)</summary> 82 /// 83 /// Insert or replace an existing item 84 ///<C 85 void mindex_set(struct mindex_t *mindex, void *item); 86 ///> 87 /// </details> 88 89 90 /// <details> 91 /// <summary>mindex_get(mindex, pattern)</summary> 92 /// 93 /// Simple query, fetch an entry in the index matching the pattern 94 ///<C 95 void * mindex_get(struct mindex_t *mindex, const void *pattern); 96 ///> 97 /// </details> 98 99 /// <details> 100 /// <summary>mindex_nth(mindex, index)</summary> 101 /// 102 /// Fetch the nth entry in the index 103 ///<C 104 void * mindex_nth(struct mindex_t *mindex, int index); 105 ///> 106 /// </details> 107 108 /// <details> 109 /// <summary>mindex_rand(mindex)</summary> 110 /// 111 /// Retrieve a single random entry from the index 112 ///<C 113 void * mindex_rand(struct mindex_t *mindex); 114 ///> 115 /// </details> 116 117 /// <details> 118 /// <summary>mindex_delete(mindex, pattern)</summary> 119 /// 120 /// Delete a single entry from the index matching the pattern 121 ///<C 122 void mindex_delete(struct mindex_t *mindex, const void *pattern); 123 ///> 124 /// </details> 125 126 /// <details> 127 /// <summary>mindex_length(mindex)</summary> 128 /// 129 /// The current amount of entries in the index 130 ///<C 131 size_t mindex_length(struct mindex_t *mindex); 132 ///> 133 /// </details> 134 135 /// <details> 136 /// <summary>mindex_free(mindex)</summary> 137 /// 138 /// Purge all entries from the index and free the memory used 139 ///<C 140 void mindex_free(struct mindex_t *mindex); 141 ///> 142 /// </details> 143 144 #endif // __FINWO_MINDEX_H__ 145 146 /// Testing 147 /// ------- 148 /// 149 /// If you want to run the library's tests, simply run `make test` to compile 150 /// the testing binary, and then `./test` to run the actual tests. 151 /// 152 /// License 153 /// ------- 154 /// 155 /// mindex source code is available under the MIT license.