rvlib

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 15 Open GitHub ↗

a weird data structures library with type descriptors.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# rvlib

a minimal, **generic** c library providing reusable data structures and utilities. created because dynamic data structures in c shouldn't require complex `void*` gymnastics or boilerplate-heavy setups, **rvlib** handles generic types cleanly using **type descriptors**.

## table of contents
- [in action](#in-action)
- [quick start](#quick-start)
- [features](#features)
- [type descriptor api](#type-descriptor-api)
- [data structures & api reference](#data-structures--api-reference)
  - [singly linked list](#singly-linked-list-slisth)
  - [doubly linked list](#doubly-linked-list-dlisth)
  - [circular linked list](#circular-linked-list-clisth)
  - [stack](#stack-stackh)
  - [queue](#queue-queueh)
  - [double-ended queue (deque)](#double-ended-queue-deque-dequeh)
  - [dictionary](#dictionary-dicth)
- [error handling](#error-handling-lib_status)
- [advanced usage: custom types](#advanced-usage-custom-types)
- [building & testing](#building--testing)

***

## in action

```c
#include <stdio.h>
#include <rvlib/rvlib.h>

int main(void) {
    slist *list = slist_construct();

int val1 = 10, val2 = 20, val3 = 30;
    slist_insert(list, 0, &val1, &TD_INT); // insert 10 at head
    slist_insert(list, 1, &val2, &TD_INT); // insert 20 at index 1
    slist_insert(list, 1, &val3, &TD_INT); // insert 30 at index 1 (middle)

printf("list elements:\n");
    slist_print(list); // prints: 10, 30, 20

slist_destruct(list);
    return 0;
}
```

## quick start

1. copy the `include/rvlib` headers and `src` directory into your project.
2. include the library header: `#include <rvlib/rvlib.h>`.
3. create a test file (e.g. `main.c` above) and compile it along with `src/td/td.c` and the required structure source files:

```bash
$ gcc -Iinclude -Isrc/structs main.c src/td/td.c src/structs/slist/slist.c src/structs/slist/slist_node/slist_node.c -o my_app
$ ./my_app
list elements:
10
30
20
```

---

## features

- **generic void* storage**: containers store a copy of the data, falling back to a raw `memcpy` of `type->size` if no custom copy callback is provided.
- **type descriptors (td)**: out of the box support for primitive types (`int`, `str`, `bool`, etc.) and a simple interface to describe your own structs.
- **memory safety**: destructors recursively free internal node memory and trigger custom item destructors if registered.
- **no external dependencies**: standard c library components only (`stdio.h`, `stdlib.h`, `string.h`, `stdint.h`).

---

## type descriptor api

the library utilizes a type descriptor struct `td` to manage type-specific operations.

```c
struct td {
    uint32_t magic;
    size_t size;
    void (*print)(void *data); 
    size_t (*hash)(void *key);
    int (*compare)(void *a, void *b); 
    void (*destruct)(void *data); // custom element destructor
    void *(*copy)(void *data);    // custom deep-copy logic
};
```

### built-in type descriptors
`rvlib` provides several predefined type descriptors under `rvlib/td.h`:

| descriptor | wrapped type | default printer | default hasher |
|------------|--------------|-----------------|----------------|
| `TD_INT` | `int` | `%d\n` | cast to `size_t` |
| `TD_UINT` | `unsigned int`| `%u\n` | cast to `size_t` |
| `TD_STR` | `char *` | `%s\n` | `djb2` hash |
| `TD_BOOL` | `int` (bool) | `true`/`false` | cast to `size_t` |
| `TD_CHAR` | `char` | `%c\n` | cast to `size_t` |
| `TD_SIZE_T`| `size_t` | `%zu\n` | value itself |
| `TD_LONG` | `long` | `%ld\n` | cast to `size_t` |
| `TD_ULONG` | `unsigned long`| `%lu\n` | cast to `size_t` |
| `TD_SHORT` | `short` | `%hd\n` | cast to `size_t` |
| `TD_USHORT`| `unsigned short`| `%hu\n`| cast to `size_t` |

---

## data structures & api reference

### singly linked list (`slist.h`)
a standard singly linked list implementation.

| function | description |
|----------|-------------|
| `slist_construct()` | allocates and returns a new empty `slist*`. |
| `slist_destruct(list)` | recursively frees all nodes and the list itself. |
| `slist_insert(list, index, data, type)` | inserts a deep-copied element at `index`. |
| `slist_remove(list, index)` | removes and destroys the node at `index`. |
| `slist_print(list)` | iterates and prints each element using its type printer. |
| `slist_fetch_node(list, index)` | returns the internal `slist_node*` at `index` (or `NULL`). |

---

### doubly linked list (`dlist.h`)
a doubly linked list implementation supporting bidirectional iteration.

| function | description |
|----------|-------------|
| `dlist_construct()` | allocates and returns a new empty `dlist*`. |
| `dlist_destruct(list)` | recursively frees all nodes and the list itself. |
| `dlist_insert(list, index, data, type)` | inserts a deep-copied element at `index`. |
| `dlist_remove(list, index)` | removes and destroys the node at `index`. |
| `dlist_print(list)` | prints the list elements from head to tail. |
| `dlist_fetch_node(list, index)` | returns a `void*` referencing the node at `index`. |

---

### circular linked list (`clist.h`)
a circular doubly linked list where the head and tail link together.

| function | description |
|----------|-------------|
| `clist_construct()` | allocates and returns a new empty `clist*`. |
| `clist_destruct(list)` | recursively frees all nodes and the list itself. |
| `clist_insert(list, index, data, type)` | inserts a deep-copied element at `index`. |
| `clist_remove(list, index)` | removes and destroys the node at `index`. |
| `clist_print(list)` | prints the list starting from head and completing a cycle. |
| `clist_fetch_node(list, index)` | returns a `void*` referencing the node at `index`. |

---

### stack (`stack.h`)
a lifo (last-in, first-out) stack structure.

| function | description |
|----------|-------------|
| `stack_construct()` | allocates and returns a new empty `stack*`. |
| `stack_destruct(stk)` | recursively pops and destroys all items. |
| `push(stk, data, type)` | pushes a deep-copied element onto the stack. |
| `pop(stk)` | removes the top element. |
| `is_empty(stk)` | returns `1` if empty, `0` otherwise. |
| `peek(stk)` | returns a raw `void*` pointer to the top element's data. |

---

### queue (`queue.h`)
a fifo (first-in, first-out) queue structure.

| function | description |
|----------|-------------|
| `queue_construct()` | allocates and returns a new empty `queue*`. |
| `queue_destruct(q)` | recursively dequeues and destroys all items. |
| `enqueue(q, data, type)` | appends a deep-copied element to the rear of the queue. |
| `dequeue(q)` | removes the front element. |
| `is_qempty(q)` | returns `1` if empty, `0` otherwise. |
| `get_front(q)` | returns a raw `void*` pointer to the front element's data. |
| `get_rear(q)` | returns a raw `void*` pointer to the rear element's data. |

---

### double-ended queue (deque) (`deque/deque.h`)
a double-ended queue supporting insertion and removal at both ends.

| function | description |
|----------|-------------|
| `deque_construct()` | allocates and returns a new empty `deque*`. |
| `deque_destruct(dq)` | recursively frees all nodes and the deque itself. |
| `push_front(dq, data, type)` | inserts a deep-copied element at the front. |
| `push_back(dq, data, type)` | inserts a deep-copied element at the back. |
| `pop_front(dq)` | removes the front element. |
| `pop_back(dq)` | removes the back element. |
| `is_dqempty(dq)` | returns `1` if empty, `0` otherwise. |
| `get_dqlength(dq)` | returns the number of items in the deque. |
| `peek_front(dq)` | returns a raw `void*` pointer to the front element's data. |
| `peek_back(dq)` | returns a raw `void*` pointer to the back element's data. |

---

### dictionary (`dict.h`)
a bucket-chained hash map for key-value pairs (with `char *` keys).

| function | description |
|----------|-------------|
| `dict_construct(buckets)` | allocates dictionary with a specific bucket capacity. |
| `dict_destruct(dict)` | frees all entries and buckets. |
| `dict_search(dict, key)` | finds and returns the raw `void*` value for `key` (or `NULL`). |
| `dict_insert(dict, key, value, type)` | inserts a new deep-copied key-value pair. |
| `dict_entry_replace(dict, key, new_key, new_value, new_type)` | replaces the entry matching `key`. |
| `dict_entry_remove(dict, key)` | removes the entry matching `key`. |
| `hash(dict, key)` | returns the hashed index for the given key. |

---

## error handling (`lib_status`)

operations that can fail return a `lib_status` enum:

| status code | description |
|-------------|-------------|
| `LIB_OK` | operation completed successfully. |
| `LIB_PTR_INVALID` | a provided structure pointer was `NULL` or invalid. |
| `LIB_ERR_NOMEM` / `LIB_ERR_MALLOC` | allocation failure. |
| `LIB_INDEX_ERR` | index out of bounds. |
| `LIB_LENGTH_ERR` | operation invalid due to length/empty constraints. |
| `LIB_TD_FUNC_MISSING` | required callback missing in type descriptor. |

---

## advanced usage: custom types

to store custom structures, define a `td` descriptor. the descriptor specifies the memory size and optional custom logic for deep-copying, printing, and freeing resources.

```c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <rvlib/rvlib.h>

// 1. define custom structure
struct person {
    int id;
    char *name; // must be dynamically allocated or deep copied
};

// 2. define custom callbacks
void print_person(void *data) {
    struct person *p = data;
    printf("person{id: %d, name: %s}\n", p->id, p->name);
}

void *copy_person(void *data) {
    struct person *src = data;
    struct person *dst = malloc(sizeof(struct person));
    if (!dst) return NULL;
    dst->id = src->id;
    dst->name = strdup(src->name); // deep copy name string
    return dst;
}

void destruct_person(void *data) {
    struct person *p = data;
    free(p->name); // free the inner allocated string
    free(p);       // free the struct itself
}

int main(void) {
    // 3. register type descriptor
    td TD_PERSON = {
        .size = sizeof(struct person),
        .print = print_person,
        .copy = copy_person,
        .destruct = destruct_person
    };

slist *list = slist_construct();

struct person p1 = { .id = 101, .name = "alice" };
    slist_insert(list, 0, &p1, &TD_PERSON);

slist_print(list); // prints: person{id: 101, name: alice}
    slist_destruct(list); // safely triggers destruct_person
    return 0;
}
```

---

## building & testing

to compile and build the test suites, run the provided `makefile`.

### makefile commands
- **build all tests**: `make all`
- **clean build artifacts**: `make clean`

tests will compile into the `run_tests/` directory:
- `run_tests/sltest` — singly linked list tests
- `run_tests/dltest` — doubly linked list tests
- `run_tests/cltest` — circular linked list tests
- `run_tests/stktest` — stack tests
- `run_tests/qtest` — queue tests
- `run_tests/dqtest` — deque tests
- `run_tests/dict_test` — dictionary tests

rvlib

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README