Update documentation

documentation/Overview/features_overview.md

@@ -6,5 +6,6 @@ The C Macro Collections library comes with some core features available to all c
 | ------- | ----------- |
 | [Callbacks](../cor/callbacks/index.html) | Callbacks are functions that are called when an operation is successful. These operations are divided in 5 categories (create, read, update, delete, resize). |
 | [Custom Allocation](../cor/custom_allocation/index.html) | Allows you to use your own custom dynamic memory allocation functions inside the collections. |
+| [Error Codes](../cor/error_codes/index.md) | Error codes that can be used to treat certain common errors when operating on a collection. |
 | [Functions Table](../cor/functions_table/index.html) | A standard way to access required behaviors from the custom data types. Things like hash, comparison, freeing from memory if needed, etc. |
 | [Iterators](../cor/iterators/index.html) | Iterators are a simplified access to the values of a collection. |

documentation/SUMMARY.md

@@ -12,6 +12,7 @@
 - [cor](./cor/index.md)
     - [Callbacks](./cor/callbacks/index.md)
     - [Custom allocation](./cor/custom_allocation/index.md)
+    - [Error Codes](./cor/error_codes/index.md)
     - [Functions Table](./cor/functions_table/index.md)
     - [Iterators](./cor/iterators/index.md)
 - [cmc](./cmc/index.md)

documentation/cor/error_codes/index.md

@@ -0,0 +1,76 @@
+# Error Codes
+
+Error codes are ways to signal errors or success. It is accessed through the `flag` component of a `struct` or through a function that is present in every collection:
+
+```c
+int PFX##_flag(struct SNAME *_collection_);
+```
+
+Some functions have a return type of `bool` indicating if it exited successfully or not. These error codes can be used for further error handling.
+
+## cmc_flags
+
+It is a global `struct` with default values for error codes.
+
+```c
+static struct
+{
+    int OK;
+    int ALLOC;
+    int EMPTY;
+    int NOT_FOUND;
+    int INVALID;
+    int RANGE;
+    int DUPLICATE;
+    int ERROR;
+} cmc_flags = { 0, 1, 2, 3, 4, 5, 6, 7 };
+```
+
+* `OK` - No errors. The operation exited successfully.
+* `ALLOC` - Allocation failed.
+* `EMPTY` - The collection is empty when it shouldn't.
+* `NOT_FOUND` - Key or value not found.
+* `INVALID` - Invalid argument or operation given the collection's state
+* `RANGE` - Index out of range.
+* `DUPLICATE` - Duplicate key or value.
+* `ERROR` - Generic error. Usually caused by algorithm errors.
+
+## cmc_flags_to_str
+
+Maps the integer representation of error codes to their character representation.
+
+```c
+const char *cmc_flags_to_str[8] = { "OK",        "ALLOC",   "EMPTY",
+                                    "NOT_FOUND", "INVALID", "RANGE",
+                                    "DUPLICATE", "ERROR" };
+```
+
+## Example
+
+```c
+#include "cmc/treeset.h"
+#include "utl/futils.h" // cmc_i32_cmp
+
+// Generate a sorted set of integers
+CMC_GENERATE_TREESET(tset, sortedset, int)
+
+int main(void)
+{
+    struct sortedset *set =
+        tset_new(&(struct sortedset_fval){ .cmp = cmc_i32_cmp });
+
+    if (!tset_insert(set, 10))
+        printf("Error! %s\n", cmc_flags_to_str[tset_flag(set)]);
+
+    if (!tset_insert(set, 10))
+        printf("Error! %s\n", cmc_flags_to_str[tset_flag(set)]);
+
+    if (!tset_remove(set, 10))
+        printf("Error! %s\n", cmc_flags_to_str[tset_flag(set)]);
+
+    if (!tset_remove(set, 10))
+        printf("Error! %s\n", cmc_flags_to_str[tset_flag(set)]);
+
+    tset_free(set);
+}
+```