dynamic_array/README.md

📚 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)

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

mkdir build && cd build
cmake ..
cmake --build .
ctest --output-on-failure
cmake --install .
cd .. && rm -rf build

💡 Usage

Including the Library

#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

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

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 C testing framework.

make test

Or directly with ctest:

cd build && ctest --output-on-failure

📦 Installation

Default Installation

make install

This installs to ~/.local/bin/dynamic_array/:

• Library: lib/libdynamic_array.a
• Header: include/dynamic_array.h

Custom Installation Directory

make install INSTALL_PREFIX=/custom/path

Or set it as an environment variable:

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
• Unity Test Framework
• C Dynamic Memory Management

---

Created for learning C programming concepts 📚