diff --git a/README.md b/README.md index 7db0c24..17f6cd0 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,14 @@ Cisastor is a collection of C libraries and utilities. - [Testing Guide](docs/testing/how-to.md) - Learn how to write and run tests using the built-in testing framework. +### Libraries + +- [Arena Allocator](docs/libs/arena_allocator.md) +- [Data Containers](docs/libs/data_containers.md) (ArrayList, Iterator, StringView) +- [Progress Bar](docs/libs/progressbar.md) +- [Testing Framework](docs/libs/testing.md) +- [Utils](docs/libs/utils.md) + ## Project Structure - `libs/`: Core libraries. diff --git a/docs/libs/arena_allocator.md b/docs/libs/arena_allocator.md new file mode 100644 index 0000000..6460ebd --- /dev/null +++ b/docs/libs/arena_allocator.md @@ -0,0 +1,21 @@ +# Arena Allocator + +A simple region-based memory allocator that manages memory in chunks. + +## API + +### Functions + +#### `void *arena_alloc(size_t size)` +Allocates `size` bytes from the current arena chunk. If the current chunk is full or uninitialized, a new chunk is allocated. Memory is automatically freed when the program exits via `atexit`. + +#### `char *string_create_empty(size_t characters)` +Allocates a null-terminated string of the given character length in the arena. + +### Macros + +#### `aalloc(size)` +Alias for `arena_alloc(size)`. + +#### `reaalloc(a, b)` +Alias for `aalloc(b)`. Note: Currently does not reallocate existing memory, just allocates a new block. diff --git a/docs/libs/data_containers.md b/docs/libs/data_containers.md new file mode 100644 index 0000000..0ddac66 --- /dev/null +++ b/docs/libs/data_containers.md @@ -0,0 +1,100 @@ +# Data Containers + +Collection of generic data structures and utilities. + +## Array List + +A dynamic array implementation similar to Go slices or C++ `std::vector`. + +### Type Safe API Generation +Use the `array_list_init(type)` macro to generate type-safe wrapper functions. + +```c +typedef struct foo { int id; } foo; +array_list_init(foo); + +// Generated functions: +struct array_list_foo *al = array_list_create_foo(); +foo f = {1}; +array_list_append_foo(al, f); +foo *ptr = array_list_get_foo_at(al, 0); +``` + +### Core API + +#### `size_t array_list_get_length(struct array_list *al)` +Returns the current number of elements. + +#### `size_t array_list_get_capacity(struct array_list *al)` +Returns the current allocated capacity. + +#### `byte *array_list_get_element_at(struct array_list *al, int index)` +Returns a pointer to the element at the given index, or `NULL` if out of bounds. + +#### `byte *array_list_append(struct array_list *al, const void *data)` +Appends data to the list, reallocating if necessary. Returns a pointer to the newly added element. + +--- + +## Iterator + +A generic iterator pattern for traversing containers. + +### Core API + +#### `struct iterator *iterator_begin(struct array_list *list)` +Creates an iterator for an `array_list`. + +#### `void *iterator_end(struct iterator *it)` +Returns a sentinel pointer representing the end of the container. + +#### `byte *iterator_element(struct iterator *it)` +Returns the current element. + +#### `void iterator_increment(struct iterator *it)` +Advances the iterator. + +### Mutating Iterators + +#### `struct iterator_mutating *iterator_map(struct iterator *it, iterator_map_predicate predicate, void *result_buffer)` +Creates a mapping iterator. + +#### `struct iterator_mutating *iterator_filter(struct iterator *it, iterator_filter_predicate predicate)` +Creates a filtering iterator. + +--- + +## String View + +A non-owning view into a string, useful for parsing. + +### Core API + +#### `struct string_view *string_view_create(char *stream)` +Creates a view for the given string. + +#### `char string_view_peek_char(struct string_view *sv)` +Returns the current character without advancing the pointer. + +#### `char string_view_next_char(struct string_view *sv)` +Returns the current character and advances the pointer. + +#### `int string_view_current_pos(struct string_view *sv)` +Returns the index of the last character read (-1 initially). + +#### `char string_view_char_at(struct string_view *sv, int pos)` +Returns the character at the absolute position in the original stream. + +#### `int string_view_compare_word(struct string_view *sv, const char *const word)` +Checks if the next characters match `word`. Advances pointer on match. Returns 0 on success. + +### Consumption API + +#### `void string_view_consume_whitespace(struct string_view *sv)` +Skips spaces and tabs. + +#### `const char *const string_view_consume_word(struct string_view *sv)` +Consumes and returns an alphanumeric (plus underscore) word. + +#### `void string_consume_till_end_of_line(struct string_view *sv)` +Advances the pointer to the next newline or end of string. diff --git a/docs/libs/progressbar.md b/docs/libs/progressbar.md new file mode 100644 index 0000000..d0e4fc5 --- /dev/null +++ b/docs/libs/progressbar.md @@ -0,0 +1,16 @@ +# Progress Bar + +A drop-in replacement for `std::ostream` like functionality to display progress in the terminal. + +## API + +### Types + +#### `ProgressBarOptions` +- `int bytes_length`: Total size to reach 100%. +- `char *label`: Label displayed next to the bar. + +### Functions + +#### `FILE *progressbar_open(FILE *fp, ProgressBarOptions *options)` +Returns a `FILE` pointer that, when written to, updates the progress bar on `stderr` while passing data through to the original `fp`. diff --git a/docs/libs/testing.md b/docs/libs/testing.md new file mode 100644 index 0000000..e97c58d --- /dev/null +++ b/docs/libs/testing.md @@ -0,0 +1,29 @@ +# Testing Framework + +A simple unit testing framework for Cisastor. + +## API + +### Defining Tests + +#### `TEST(name)` / `IT(name)` +Defines a test function. Tests are automatically registered. + +### Assertions + +#### `cassert(cond, message)` +Asserts that `cond` is true, otherwise fails the test with `message`. + +#### `cassertf(cond, fmt, ...)` +Formatted version of `cassert`. + +#### `fail(message)` / `failf(fmt, ...)` +Manually fails a test. + +### Utilities + +#### `uint8_t strcmp_at_any(const char *const src, const char *const match)` +Checks if `match` is a substring of `src`. + +#### `uint8_t run_command(const char *const args)` +Executes a shell command and prints output. Returns 0 on success. diff --git a/docs/libs/utils.md b/docs/libs/utils.md new file mode 100644 index 0000000..32c3eee --- /dev/null +++ b/docs/libs/utils.md @@ -0,0 +1,16 @@ +# Utils + +Generic helper macros and types. + +## API + +### Macros + +#### `cast(type, value)` +A macro for explicit casting: `((type)value)`. + +#### `null` +Alias for `NULL`. + +#### `byte` +Alias for `char`.