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

**Linux-only project**

- **CMake** ≥ 3.12
- **C compiler** (GCC recommended, Clang supported)
- **Make** (optional, but recommended)
- **build-essential** (on Ubuntu/Debian): `sudo apt-get install build-essential`
## 🔨 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** 📚