commit 8b604526434d905cb247a4315c34266682bf3729
parent 7ac1189db9da26c7557a3a8a013ac3f3b8d89bc1
Author: Yersa Nordman <finwo@pm.me>
Date: Mon, 11 Mar 2024 20:24:04 +0100
Moved readme to be sourced from the main header file ; exporting mindex_find fn
Diffstat:
| M | Makefile | | | 5 | ++++- |
| M | README.md | | | 124 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------------- |
| M | src/mindex.h | | | 144 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---- |
3 files changed, 230 insertions(+), 43 deletions(-)
diff --git a/Makefile b/Makefile
@@ -17,7 +17,7 @@ BIN=\
benchmark \
test
-default: $(BIN)
+default: README.md $(BIN)
$(BIN): $(OBJ) $(BIN:=.o)
$(CC) $(CFLAGS) $(OBJ) $@.o -o $@
@@ -27,3 +27,6 @@ clean:
rm -f $(OBJ)
rm -f $(BIN:=.o)
rm -f test
+
+README.md: ${SRC} src/mindex.h
+ stddoc < src/mindex.h > README.md
diff --git a/README.md b/README.md
@@ -23,73 +23,127 @@ Features
- Consistent interface, always working with pointers
- ANSI C (C99)
- Purge to be called when an item is removed
+API
+---
-Example
--------
+### Structures
+
+<details>
+ <summary>struct mindex_t</summary>
+
+ The main handle of the mindex instance
-```c
-int main() {
- // TODO
-}
+```C
+struct mindex_t {
+ int (*compare)(const void *a, const void *b, void *udata);
+ void (*purge)(void *item, void *udata);
+ void *udata;
+ size_t length;
+ size_t max;
+ void **items;
+};
```
-API
----
+</details>
+
+### Methods
+
+<details>
+ <summary>mindex_init(cmp, purge, udata)</summary>
+
+ Initialize a new in-memory index
-### Basic
+```C
+struct mindex_t * mindex_init(int (*compare)(const void *a, const void *b, void *udata), void (*purge)(void *item, void *udata), void *udata);
+```
+
+</details>
+<details>
+ <summary>mindex_find(mindex, pattern, items, length)</summary>
+
+ Intended for internal use or advanced usage (like fetching both index &
+ the pointer of the result)
-```c
-struct mindex_t * mindex_init(int (*compare)(const void *a, const void *b, void *udata), void (*purge)(const void *item, void *udata), void *udata);
+```C
+struct mindex_find_response * mindex_find(const struct mindex_t *mindex, const void *pattern, void **items, int length);
```
-Initialize the indexing library.
+</details>
+<details>
+ <summary>mindex_set(mindex, item)</summary>
-```c
-void mindex_set(struct mindex_t *mindex, void *item);
+ Insert or replace an existing item
+
+```C
+void mindex_set(struct mindex_t *mindex, void *item);
```
-Insert or replace an existing item
+</details>
+<details>
+ <summary>mindex_get(mindex, pattern)</summary>
+
+ Simple query, fetch an entry in the index matching the pattern
-```c
-void * mindex_get(struct mindex_t *mindex, void *pattern);
+```C
+void * mindex_get(struct mindex_t *mindex, void *pattern);
```
-Get an existing item
+</details>
+<details>
+ <summary>mindex_nth(mindex, index)</summary>
-```c
-void mindex_delete(struct mindex_t *mindex, void *pattern);
+ Fetch the nth entry in the index
+
+```C
+void * mindex_nth(struct mindex_t *mindex, int index);
```
-Delete an item from the index
+</details>
+<details>
+ <summary>mindex_rand(mindex)</summary>
-**:warning: CAUTION :warning:**: Deletes by finding in the index with the
-compare fn, not by the pointer of the given item/pattern.
+ Retrieve a single random entry from the index
-```c
-size_t mindex_length(struct mindex_t *mindex);
+```C
+void * mindex_rand(struct mindex_t *mindex);
```
-Returns the amount of items in the index
+</details>
+<details>
+ <summary>mindex_delete(mindex, pattern)</summary>
+
+ Delete a single entry from the index matching the pattern
-```c
-void mindex_free(struct mindex_t *mindex);
+```C
+void mindex_delete(struct mindex_t *mindex, void *pattern);
```
-Release the memory used by the index
+</details>
+<details>
+ <summary>mindex_length(mindex)</summary>
-### Extended
+ The current amount of entries in the index
-```c
-void * mindex_rand(struct mindex_t *mindex);
+```C
+size_t mindex_length(struct mindex_t *mindex);
```
-Retreive a random item from the index
+</details>
+<details>
+ <summary>mindex_free(mindex)</summary>
+
+ Purge all entries from the index and free the memory used
+
+```C
+void mindex_free(struct mindex_t *mindex);
+```
+</details>
Testing
-------
-If you want to run the library's tests, simply run `make test` to compile the
-testing binary, and then `./test` to run the actual tests.
+If you want to run the library's tests, simply run `make test` to compile
+the testing binary, and then `./test` to run the actual tests.
License
-------
diff --git a/src/mindex.h b/src/mindex.h
@@ -1,8 +1,47 @@
#ifndef __FINWO_MINDEX_H__
#define __FINWO_MINDEX_H__
+/// mindex
+/// ======
+///
+/// In-memory indexed store and fetch library
+///
+/// This library makes use of [dep](https://github.com/finwo/dep) to manage it's
+/// dependencies and exports.
+///
+/// Installation
+/// ------------
+///
+/// ```sh
+/// dep add finwo/mindex
+/// dep install
+/// ```
+///
+/// After that, simply add `include lib/.dep/config.mk` in your makefile and include
+/// the header file by adding `#include "finwo/mindex.h`.
+///
+/// Features
+/// --------
+///
+/// - Consistent interface, always working with pointers
+/// - ANSI C (C99)
+/// - Purge to be called when an item is removed
+
#include <stdlib.h>
+/// API
+/// ---
+
+
+///
+/// ### Structures
+///
+
+/// <details>
+/// <summary>struct mindex_t</summary>
+///
+/// The main handle of the mindex instance
+///<C
struct mindex_t {
int (*compare)(const void *a, const void *b, void *udata);
void (*purge)(void *item, void *udata);
@@ -11,14 +50,105 @@ struct mindex_t {
size_t max;
void **items;
};
+///>
+/// </details>
+///
+/// ### Methods
+///
+
+/// <details>
+/// <summary>mindex_init(cmp, purge, udata)</summary>
+///
+/// Initialize a new in-memory index
+///<C
struct mindex_t * mindex_init(int (*compare)(const void *a, const void *b, void *udata), void (*purge)(void *item, void *udata), void *udata);
-void mindex_set(struct mindex_t *mindex, void *item);
-void * mindex_get(struct mindex_t *mindex, void *pattern);
-void * mindex_nth(struct mindex_t *mindex, int index);
-void * mindex_rand(struct mindex_t *mindex);
-void mindex_delete(struct mindex_t *mindex, void *pattern);
-size_t mindex_length(struct mindex_t *mindex);
-void mindex_free(struct mindex_t *mindex);
+///>
+/// </details>
+
+/// <details>
+/// <summary>mindex_find(mindex, pattern, items, length)</summary>
+///
+/// Intended for internal use or advanced usage (like fetching both index &
+/// the pointer of the result)
+///<C
+struct mindex_find_response * mindex_find(const struct mindex_t *mindex, const void *pattern, void **items, int length);
+///>
+/// </details>
+
+/// <details>
+/// <summary>mindex_set(mindex, item)</summary>
+///
+/// Insert or replace an existing item
+///<C
+void mindex_set(struct mindex_t *mindex, void *item);
+///>
+/// </details>
+
+
+/// <details>
+/// <summary>mindex_get(mindex, pattern)</summary>
+///
+/// Simple query, fetch an entry in the index matching the pattern
+///<C
+void * mindex_get(struct mindex_t *mindex, void *pattern);
+///>
+/// </details>
+
+/// <details>
+/// <summary>mindex_nth(mindex, index)</summary>
+///
+/// Fetch the nth entry in the index
+///<C
+void * mindex_nth(struct mindex_t *mindex, int index);
+///>
+/// </details>
+
+/// <details>
+/// <summary>mindex_rand(mindex)</summary>
+///
+/// Retrieve a single random entry from the index
+///<C
+void * mindex_rand(struct mindex_t *mindex);
+///>
+/// </details>
+
+/// <details>
+/// <summary>mindex_delete(mindex, pattern)</summary>
+///
+/// Delete a single entry from the index matching the pattern
+///<C
+void mindex_delete(struct mindex_t *mindex, void *pattern);
+///>
+/// </details>
+
+/// <details>
+/// <summary>mindex_length(mindex)</summary>
+///
+/// The current amount of entries in the index
+///<C
+size_t mindex_length(struct mindex_t *mindex);
+///>
+/// </details>
+
+/// <details>
+/// <summary>mindex_free(mindex)</summary>
+///
+/// Purge all entries from the index and free the memory used
+///<C
+void mindex_free(struct mindex_t *mindex);
+///>
+/// </details>
#endif // __FINWO_MINDEX_H__
+
+/// Testing
+/// -------
+///
+/// If you want to run the library's tests, simply run `make test` to compile
+/// the testing binary, and then `./test` to run the actual tests.
+///
+/// License
+/// -------
+///
+/// mindex source code is available under the MIT license.
