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