From 809d2f47640f98417732d72e1fb5882062949989 Mon Sep 17 00:00:00 2001 From: Vitor Hideyoshi Date: Fri, 27 Mar 2026 15:53:17 -0300 Subject: [PATCH] add README.md: provide documentation for dynamic array library --- Makefile | 7 +- README.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/Makefile b/Makefile index 5fe94be..9a4e078 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,16 @@ .PHONY: configure build clean test install +# Lib +LIB_NAME := dynamic_array + # Build directory BUILD_DIR := build # Default target .DEFAULT_GOAL := help +INSTALL_PREFIX ?= ~/.local/bin/$(LIB_NAME) + # Help target help: @@ -35,5 +40,5 @@ test: build # Install: Install the library install: build - cd $(BUILD_DIR) && cmake --install . + cd $(BUILD_DIR) && cmake --install . --prefix $(INSTALL_PREFIX) diff --git a/README.md b/README.md new file mode 100644 index 0000000..a4b145f --- /dev/null +++ b/README.md @@ -0,0 +1,199 @@ +# 📚 Dynamic Array Library + +A simple, educational C implementation of a dynamic array (vector-like) data structure. + +> ⚠️ **Study Case Only** — This project is for **learning purposes** and should **NOT** be used in production environments. + +## Overview + +This library provides a basic dynamic array implementation in C, similar to C++'s `std::vector` or Python's lists. It demonstrates fundamental concepts in systems programming: + +- **Memory management** — allocation, reallocation, deallocation +- **Generic programming** — using `void*` pointers +- **Type-safe macros** — for type casting and operations +- **Unit testing** — with the Unity C testing framework +## ✨ Features + +- **Dynamic resizing** — Automatically grows as elements are added +- **Type-safe operations** — Macros for working with typed elements +- **Simple API** — Easy-to-use functions for common operations +## 📁 Project Structure + +``` +test-meson/ +├── src/ +│ ├── dynamic_array.c # Implementation +│ ├── dynamic_array.h # Public API header +│ ├── test_dynamic_array.c # Unit tests +│ └── CMakeLists.txt # Build configuration +├── submodules/ +│ └── external/ +│ └── unity/ # Unity test framework +├── CMakeLists.txt # Root CMake configuration +├── Makefile # Build automation +└── README.md # This file +``` +## 🔧 Prerequisites + +- **CMake** ≥ 3.12 +- **C compiler** (GCC, Clang, MSVC) +- **Make** (optional, but recommended) +## 🔨 Building + +### Using the Makefile (Recommended) + +```bash +make configure # Configure the project +make build # Build the project +make test # Run tests +make install # Install the library +make clean # Clean build artifacts +``` + +### Using CMake Directly + +```bash +mkdir build && cd build +cmake .. +cmake --build . +ctest --output-on-failure +cmake --install . +cd .. && rm -rf build +``` +## 💡 Usage + +### Including the Library + +```c +#include "dynamic_array.h" + +// Create an array of integers +ArrayCreateOptions opts = { + .initial_size = 10, + .element_size = sizeof(int) +}; +Array *my_array = array_create(&opts); + +// Add elements +int value = 42; +array_set_value(my_array, 0, &value); + +// Retrieve elements +int *retrieved = (int*)array_get_value(my_array, 0); + +// Using type-safe macros +int result = array_set_value_as(int, my_array, 1, 100); + +// Get size and capacity +size_t size = array_get_size(my_array); +size_t capacity = array_get_capacity(my_array); + +// Cleanup +array_deconstructor(&my_array); +``` +## 📖 API Reference + +### Structures + +#### `Array` + +```c +typedef struct { + void *value; // Pointer to element data + size_t element_size; // Size of each element + size_t size; // Current number of elements + size_t capacity; // Allocated capacity +} Array; +``` + +#### `ArrayCreateOptions` + +```c +typedef struct { + int initial_size; // Initial capacity + size_t element_size; // Size of each element type +} ArrayCreateOptions; +``` + +### Functions + +| Function | Description | +|----------|-------------| +| `Array *array_create(const ArrayCreateOptions *options)` | Creates a new dynamic array | +| `void array_deconstructor(Array **pp_array)` | Frees allocated memory and sets pointer to NULL | +| `void array_resize(Array *p_array, size_t new_size)` | Resizes the array's capacity | +| `void *array_get_value(const Array *p_array, size_t index)` | Retrieves a pointer to the element at index | +| `void array_set_value(Array *p_array, size_t index, const void *value)` | Sets the element at index | +| `size_t array_get_size(const Array *p_array)` | Returns the current number of elements | +| `size_t array_get_capacity(const Array *p_array)` | Returns the allocated capacity | + +### Macros + +| Macro | Description | +|-------|-------------| +| `array_get_value_as(type, arr, idx)` | Type-safe retrieval of elements | +| `array_set_value_as(type, arr, idx, value)` | Type-safe setting of elements (with type checking) | +## ✅ Testing + +Tests are written using the [Unity](http://www.throwtheswitch.org/unity) C testing framework. + +```bash +make test +``` + +Or directly with ctest: + +```bash +cd build && ctest --output-on-failure +``` +## 📦 Installation + +### Default Installation + +```bash +make install +``` + +This installs to `~/.local/bin/dynamic_array/`: +- **Library:** `lib/libdynamic_array.a` +- **Header:** `include/dynamic_array.h` + +### Custom Installation Directory + +```bash +make install INSTALL_PREFIX=/custom/path +``` + +Or set it as an environment variable: + +```bash +export INSTALL_PREFIX=$HOME/.local +make install +``` +## ⚠️ Known Issues & Limitations + +- ⚠️ No bounds checking in release builds +- ⚠️ Simple reallocation strategy (not optimized for performance) +- ⚠️ Not thread-safe +- ⚠️ Limited error handling +- ⚠️ Educational purpose only — use established libraries for production +## 🚀 Future Improvements + +- [ ] Add more comprehensive error handling +- [ ] Implement shrinking functionality +- [ ] Add iterator support +- [ ] Optimize memory allocation strategy +- [ ] Add more test coverage +## 📄 License + +This project is for educational purposes. + +## 📚 References + +- [CMake Documentation](https://cmake.org/documentation/) +- [Unity Test Framework](http://www.throwtheswitch.org/unity) +- [C Dynamic Memory Management](https://en.cppreference.com/w/c/memory) + +--- + +**Created for learning C programming concepts** 📚