Update documentation
This commit is contained in:
Leonardo committed
1 parent
14845d9b23
commit
952292462a
57 files changed
+3027
-204
No files matched your search
@@ -0,0 +1,86 @@
|
||||
# deque.h
|
||||
|
||||
A Deque, also known as a double-ended queue, is a linear data structure that is able to add and remove elements from both ends. It can also be thought of a double-ended stack since you can push and pop elements from two ends. The Deque can also be used as a Queue. The only elements accessible from a Deque ar the two elements at its ends (front element and back element).
|
||||
|
||||
## Deque Implementation
|
||||
|
||||
This implementation uses a circular buffer (ring buffer or cyclic buffer) in order to operate on O(1) for push and pop on either ends. The only case where it takes longer than O(1) is when the buffer is reallocated. If it was implemented as a regular array, adding or removing elements from the front would take O(N) due to the need to shift all elements in the Deque.
|
||||
|
||||
Two indices are kept track of. The `front` index and the `rear` index. These represent the both ends of the Deque. If an index reaches one end of the real buffer, they wrap around to the other end and an element is added there. This abstracts the real buffer as a circular buffer with the cost os constantly checking for boundaries and using the modulo operator.
|
||||
|
||||
## Deque Generation Macros
|
||||
|
||||
* `CMC_GENERATE_DEQUE(PFX, SNAME, V)` - Generate full definition.
|
||||
* `CMC_GENERATE_DEQUE_HEADER(PFX, SNAME, V)` - Generate only the header portion
|
||||
* `CMC_GENERATE_DEQUE_SOURCE(PFX, SNAME, V)` - Generate only the source portion
|
||||
|
||||
| Parameter | Description |
|
||||
| --------- | ----------------------------- |
|
||||
| `PFX` | Functions namespace or prefix |
|
||||
| `SNAME` | Structure name |
|
||||
| `V` | Value type |
|
||||
|
||||
## Deque Structures
|
||||
|
||||
| Declared structs | Description |
|
||||
| ------------------------- | ----------------------------------- |
|
||||
| `struct SNAME` | A double-ended queue data structure |
|
||||
| `struct SNAME##_fval` | A function table for the `V` type |
|
||||
| `struct SNAME##_iter` | A double-ended queue iterator |
|
||||
|
||||
## struct SNAME
|
||||
|
||||
| `struct SNAME` | Description |
|
||||
| --------------------------------- | ------------------------------------------------------------ |
|
||||
| `V *buffer` | Dynamic circular array of elements. |
|
||||
| `size_t capacity` | Current circular array capacity. |
|
||||
| `size_t count` | Current amount of elements. |
|
||||
| `size_t front` | Index representing the front of the Deque. |
|
||||
| `size_t rear` | Index representing the back of the Deque. |
|
||||
| `int flag` | Flag indicating errors or success. |
|
||||
| `struct SNAME##_fval *f_val` | Functions table for the Value type. |
|
||||
| `struct cmc_alloc_node *alloc` | Custom allocation functions. |
|
||||
| `struct cmc_callbacks *callbacks` | Callback functions. |
|
||||
| `it_start` <sup>\[1\]</sup> | Returns an iterator to the start of the Deque. |
|
||||
| `it_end` <sup>\[2\]</sup> | Returns an iterator to the end of the Deque. |
|
||||
|
||||
1. Full definition: `struct SNAME##_iter (*it_start)(struct SNAME *);`.
|
||||
2. Full definition: `struct SNAME##_iter (*it_end)(struct SNAME *);`.
|
||||
|
||||
## struct SNAME##_fval
|
||||
|
||||
The Functions Table for `V`. Check out the Functions Table documentation [here](../../cor/functions_table/index.html).
|
||||
|
||||
## struct SNAME##_iter
|
||||
|
||||
| `struct SNAME##_iter` | Description |
|
||||
| ---------------------- | --------------------------------------------------- |
|
||||
| `struct SNAME *target` | Deque being iterated over. |
|
||||
| `size_t cursor` | Cursor's current position (index). |
|
||||
| `size_t index` | Relative index to all elements in the iteration. |
|
||||
| `bool start` | If the iterator reached the start of the iteration. |
|
||||
| `bool end` | If the iterator reached the end of iteration. |
|
||||
|
||||
## Callbacks
|
||||
|
||||
This list associates which functions calls which callbacks.
|
||||
|
||||
* `create`
|
||||
* `PFX##_push_front()`
|
||||
* `PFX##_push_back()`
|
||||
* `read`
|
||||
* `PFX##_front()`
|
||||
* `PFX##_back()`
|
||||
* `PFX##_contains()`
|
||||
* `update`
|
||||
* `delete`
|
||||
* `PFX##_pop_front()`
|
||||
* `PFX##_pop_back()`
|
||||
* `resize`
|
||||
* `PFX##_resize()`
|
||||
|
||||
## Functions Table
|
||||
|
||||
| CMP | CPY | STR | FREE | HASH | PRI |
|
||||
| :-: | :-: | :-: | :--: | :--: | :-: |
|
||||
|  |  |  |  |  |  |
|
||||
@@ -0,0 +1,27 @@
|
||||
# CMC
|
||||
|
||||
The main C Macro Collections.
|
||||
|
||||
The C Macro Collections library was created out of necessity. To create powerful data structures of any type without the constant use of macros and `void *` pointers, but at the same time being [type-safe](https://en.wikipedia.org/wiki/Type_safety). These collections are generated by macros containing a template. These templates allow for some much needed customizations including the data type you wish to handle.
|
||||
|
||||
In the `cmc` folder is the default implementation of all collections. There is also a `dev` folder that pretty much has the same macros that expand to the same code, except that they have an extensive use of logging that might be useful for debugging or getting to know what is happening in your program. There is also the `sac` collections that are statically allocated (have a fixed sized buffer).
|
||||
|
||||
## Quick Example
|
||||
|
||||
Let's say you need a HashMap mapping keys of type `char *` to `int`. All you need to do is:
|
||||
|
||||
```c
|
||||
#include "cmc/hashmap"
|
||||
|
||||
// CMC_GENERATE_HASHMAP(PFX, SNAME, K, V)
|
||||
CMC_GENERATE_HASHMAP(map, hashmap, char *, int)
|
||||
|
||||
int main(void)
|
||||
{
|
||||
// Here you have full functionalities of a HashMap
|
||||
// No more macros needed!
|
||||
// Every function can be found in the 'map_' prefix and are all type-safe
|
||||
}
|
||||
```
|
||||
|
||||
You can customize the functions prefix (`PFX`) and the `struct` name (`SNAME`). The macro `CMC_GENERATE_HASHMAP` will expand to all the code that you will need to operate on a HashMap with `char *` keys and `int` values. The only thing left to do is to define a hash function and a comparator functions for the keys of this map. In case of `char *` you can find these functions in `utl/futils.h` or make your own. To know which collections require which functions check out [Functions Table](../cor/functions_table/index.html) or the documentation for each collection.
|
||||
Reference in new issue
Block a user