Introduction

Collection is a modern generic data structures and algorithms library for C, inspired by C++ STL. It provides essential data structures like dynamic arrays, heap, linked lists, hash tables, and efficient algorithms with a clean, type-safe API.

Features

Generic Design - Type-agnostic implementation using void pointers
Memory Safe - Automatic memory management with custom destructor support
Modern C - Clean API following C11 standards and best practices
STL-Inspired - Familiar interface for developers coming from C++

Requirements

Build Dependencies

C Compiler: GCC or Clang with C11 support
Make: GNU Make 3.81 or later
Standard C Library: glibc or compatible

Quick Start

1. Clone the Repository

git clone <repository-url>
cd collection

2. Build the Library

Build the static library:

make lib

This creates a static library at lib/libcollection.a.

3. Run Tests

Build the library, then compile and run the full test suite:

make test

Or build the library and run all tests in one step:

make all

Module-scoped tests use the test-% pattern (replace NAME with the module name), for example:

make test-vector

4. Use the Library

Include the library in your project:

gcc -I./include your_program.c -L./lib -lcollection -o your_program

Build Configuration

The build system is configured via config/config.mk:

C Standard: c11
Build Method: static or dynamic
Library Name: collection

To build as a dynamic library, edit config/config.mk:

BUILD_METHOD := dynamic

Then rebuild:

make clean
make lib

Docker Development Environment

For a consistent development environment across different platforms, you can use Docker:

make docker

This command will:

Check if the Docker image exists, and build it if needed (Ubuntu-based with GCC and C development tools)
Remove any existing container with the same name
Start an interactive container with your project directory mounted at /workspace

The Docker image includes:

Ubuntu Linux
GCC (GNU Compiler Collection)
Make and build-essential tools

Once inside the container, you can build and test the library:

make lib
make test

Available Make Targets

Running make with no target defaults to help and prints the same usage as make help.

Target	Description
`make help`	Show available commands
`make all`	Build the library and run all tests
`make lib`	Build the library
`make test`	Build and run all tests
`make test-NAME`	Build and run tests for a specific module
`make clean`	Clean the build artifacts
`make flags`	Show the compile and link flags
`make clang`	Run clang to generate compile commands
`make format`	Format the code
`make docker`	Run Docker container with development environment

Contributing

Contributions are welcome! Whether it’s:

Bug reports
Feature requests
Documentation improvements
Code contributions

Please feel free to:

Open an issue to discuss proposed changes
Fork the repository
Submit a pull request

Building Documentation

The documentation is built using Astro and Starlight.

cd doc
npm install
npm run dev
npm run build

License

This project is licensed under the GNU General Public License v3.0 or later.

Support

Documentation: Full API Reference
Issues: Report bugs or request features via GitHub Issues
Discussions: Ask questions in GitHub Discussions

Acknowledgments

Inspired by C++ Standard Template Library (STL)
Test framework: utest
Documentation: Astro Starlight