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