Merge pull request 'h5-update-documentation' (#10) from h5-update-documentation into main

Reviewed-on: #10

Docs/Allocator.md

@@ -0,0 +1,133 @@
+# Allocator
+
+This part of the library implements a custom heap allocator which efficiently manages heap memory for both windows and linux devices.
+
+## Featurs
+
+* Memory allocation
+* Freeing of memory
+* Zeroing memory on allocation
+* Reallocating memory from existing memory
+
+## Usage
+
+### Allocating
+
+When using the library you can allocate memory using the `hallocy_allocate`, `hallocy_malloc` or `hallocy_calloc` functions. It is recommended to use `hallocy_malloc` and `hallocy_calloc` for clarity. You could also allocate memory using the `hallocy_realloc`, but this is not recommended as this is slightly slower than using the `hallocy_malloc` function.
+
+### Freeing
+
+When you are done with the allocated memory it is important you free it using the `hallocy_free` function. Freeing memory that is not used will not only prevent memory leaks, but also makes future allocations faster as the freeed memory blocks can be reused.
+
+### Error handling
+
+The `hallocy_allocate`, `hallocy_malloc`, `hallocy_calloc` and `hallocy_realloc` all return `NULL` on finding an error. These functions can return `NULL` when there is no memory available, parameters that where given where invalid or other reasons. 
+
+The `hallocy_free` function returns a `HallocyError` containing the reason for the error. When calling any Hallocy function it is important you handle these errors to prevent possible problems like trying to access an invalid memory address.
+
+## Functions
+
+### Allocate 
+
+Allocates memory on the heap and can zero the memory on allocation.
+
+```c
+void *hallocy_allocate(size_t size, bool zero_memory);
+```
+
+**Args**:
+
+- `size`: The amount of bytes to allocate.
+- `zero_memory`: Zero's memory when `true`.
+
+**Returns**: Pointer to memory if successfull, else returns `NULL`.
+
+### Malloc
+
+Allocates memory on the heap.
+
+```c
+static inline void *hallocy_malloc(size_t size) { return hallocy_allocate(size, false); }
+```
+
+**Args**:
+
+- `size`: The amount of bytes to allocate.
+
+**Returns**: Pointer to memory if successfull, else returns `NULL`.
+
+### Calloc
+
+Allocates memory and zero's it on allocation.
+
+```c
+static inline void *hallocy_calloc(size_t size, size_t count) { return  hallocy_allocate(size * count, true); }
+```
+
+**Args**:
+
+- `size`: Size of one element in bytes.
+- `count`: The amount of elements to allocate memory for.
+
+**Returns**: Pointer to memory if successfull, else returns `NULL`.
+
+### Realloc
+
+Reallocates more memory for existing allocations.
+
+```c
+void *hallocy_realloc(void *memory_pointer, size_t size);
+```
+
+**Args**:
+
+- `memory_pointer`: Pointer to already allocated heap memory.
+- `size`: The size of the new allocated memory.
+
+**Returns**: Pointer to memory if successfull, else returns `NULL`.
+
+### Free
+
+Free's heap memory.
+
+```c
+HallocyError hallocy_free(void *pointer);
+```
+
+**Args**:
+
+- `pointer`: The pointer to allocated heap memory to free.
+
+**Returns**:
+
+- **HALLOCY_ERROR_NONE**: Successfully freeed memory.
+- **HALLOCY_ERROR_INVALID_PARAM**: Invalid parameters given.
+- **HALLOCY_ERROR_OUT_OF_MEMORY**: System is out of memory.
+- **HALLOCY_ERROR_INVALID_POINTER**: Invalid memory address given.
+- **HALLOCY_ERROR_UNKNOWN**: Unknown error.
+
+## Example usage
+
+```c
+#include <Hallocy/Core/Allocator.h>
+#include <Hallocy/Utils/Error.h>
+
+int main() {
+    char *allocated_memory = hallocy_malloc(128 * sizeof(char));
+    if (allocated_memory == NULL) {
+        return -1;
+    }
+
+    allocated_memory = hallocy_realloc(allocated_memory, 256);
+    if (allocated_memory == NULL) {
+        return -1;
+    }
+
+    HallocyError error = hallocy_free(allocated memory);
+    if (error != HALLOCY_ERROR_NONE) {
+        return -1; // Check type of error here instead of returning -1 imidiatly.
+    }
+
+    return 0;
+}
+```

Docs/Index.md

@@ -0,0 +1,12 @@
+# Library documentation
+
+Welcome to the documentation of the **Hallocy C library**!
+
+This documentation is split into several parts:
+
+- [Allocator](Allocator.md)
+- [Memory management](MemoryManagement.md)
+
+Use this as a guide for using the library within your existing project.
+
+> For installation and initial setup, please refer to the [README.md](../README.md).

Docs/MemoryManagement.md

@@ -0,0 +1,116 @@
+# Allocator
+
+This part of the library implements custom memory management functions for both windows and linux devices.
+
+## Featurs
+
+* Setting memory
+* Copying memory
+* Moving memory
+* Comparing memory
+
+## Usage
+
+### Error handling
+
+When using `hallocy_set_memory`, `hallocy_copy_memory` or `hallocy_move_memory` they will return a HallocyError. This error should be handled correctly to avoid any futher problems.
+
+## Functions
+
+### Set memory
+
+Sets specified block of memory to specified value.
+
+```c
+HallocyError hallocy_set_memory(void *destination, int value, const size_t size);
+```
+
+**Args**:
+
+- `destination`: The memory to set the value of.
+- `value`: The value to set the memory in destination to.
+- `size`: The size of the memory in bytes to set the value of.
+
+**Returns**:
+
+- **HALLOCY_ERROR_NONE**: Successfully set memory.
+- **HALLOCY_ERROR_INVALID_POINTER**: Invalid pointer was given.
+
+### Copy memory
+
+Copies memory from one pointer to another pointer.
+
+```c
+HallocyError hallocy_copy_memory(void *destination, void *source, const size_t size);
+```
+
+**Args**:
+
+- `destination`: The memory to copy the values to.
+- `source`: The memory to copy the values from.
+- `size`: The size of the memory in bytes to copy the value to.
+
+**Returns**:
+
+- **HALLOCY_ERROR_NONE**: Successfully copied memory.
+- **HALLOCY_ERROR_INVALID_POINTER**: Invalid pointers where given.
+
+### Move memory
+
+Copies memory from one pointer to another pointer. Unlike the `hallocy_copy_memory` function this function will handle overlapping memory right.
+
+```c
+HallocyError hallocy_move_memory(void *destination, void *source, const size_t size);
+```
+
+**Args**:
+
+- `destination`: The memory to copy the values to.
+- `source`: The memory to copy the values from.
+- `size`: The size of the memory in bytes to copy the value to.
+
+**Returns**:
+
+- **HALLOCY_ERROR_NONE**: Successfully moved memory.
+- **HALLOCY_ERROR_INVALID_POINTER**: Invalid pointers where given.
+
+### Compare memory
+
+```c
+bool hallocy_compare_memory(void *left_side, void *right_side, const size_t size);
+```
+
+**Args**:
+
+- `left_side`: The memory to compare with the right side.
+- `right_side`: The memory to compare with the left side.
+- `size`: The size of the memory in bytes to compare the value to.
+
+**Returns**: True if both pointers contain same content, else returns false.
+
+## Example usage
+
+```c
+#include <Hallocy/Core/Allocator.h>
+#include <Hallocy/Core/Memory.h>
+#include <Hallocy/Utils/Error.h>
+
+int main() {
+    char *allocated_memory = hallocy_malloc(128 * sizeof(char));
+    if (allocated_memory == NULL) {
+        return -1;
+    }
+
+    HallocyError error = hallocy_memory_set(allocated_memory, 'T', 127);
+    if (error != HALLOCY_ERROR_NONE) {
+        return -1; // Check type of error here instead of returning -1 imidiatly.
+    }
+
+    error = hallocy_free(allocated memory);
+    if (error != HALLOCY_ERROR_NONE) {
+        return -1; // Check type of error here instead of returning -1 imidiatly.
+    }
+
+    return 0;
+}
+```

README.md

@@ -1,3 +1,65 @@
 # Hallocy
 
-An advanced allocator library for C.
+An advanced allocator library for C.
+
+## Introduction
+
+Hallocy is an advanced C allocator library. This library implements the standard malloc, calloc, realloc, free, memset, memcopy, memmove and memcmp functions. The aim of this library is to be a better version of the standard C allocator by improving performance. Hallocy supports both Windows and Linux also keeping multithreading in mind.
+
+## Features
+
+The hallocy library offers the following features:
+
+- Allocating and freeing memory
+- Zeroing memory on allocation
+- Reallocating memory 
+- Copying and moving memory
+- Setting memory
+- Comparing memory
+
+## Installation
+
+### Prerequisites
+
+Ensure you have the following installed on your system:
+
+* CMake (minimum version 3.10)
+* A compatible C compiler (e.g., GCC or MSVC)
+
+### Build Steps
+
+1. Clone the repository:
+    ```bash
+    git clone https://repo.strawhats.nl/Mineplay/Hallocy.git
+    ```
+
+2. Navigate to the directory:
+    ```bash
+    cd Hallocy
+    ```
+
+3. Create build directory and navigate to it:
+    ```bash
+    mkdir Build && cd Build
+    ```
+
+4. Run CMake to configure project:
+    ```bash
+    cmake ..
+    ```
+
+5. Build the project:
+    ```bash
+    cmake --build . --config Release
+    ```
+    To build in debug use:
+    ```bash
+    cmake --build . 
+    ```
+    This will both generate the library and test files.
+
+## Using the library
+
+The library file can be found in the `./Build/Release` folder as Hallocy.lib for windows and in `./Build` folder as libHallocy.a for linux. To use the library file you will need to copy the Hallocy folder containing the header files and follow the setup process for a library in the build system you are using. 
+
+For more info about how to use the library see the documentation folder named `Docs`.