libcdsa

Project Logo

[!WARNING] This library is currently a work in progress. It is experimental and may be unstable — use it at your own risk.

Table of Contents

Overview

A Feature-Rich, High-Level, and Easy-to-Use Data Structures and Algorithms Library for the C programming language.

This project provides common data structures and algorithms with clean, expressive, and reusable abstractions — bringing a modern programming experience to C. It includes implementations of widely used data structures such as array lists, linked lists, hash maps, and hash sets, along with classic algorithms like merge sort and quick sort. The API is heavily inspired by the Java Collections Framework, offering a familiar interface for developers with a Java background.

Features

The library currently provides the following data structures:

There are also thin abstraction layers for list, map, and set types (compile-time dispatch):

Also, there is some other utilities which may be useful:

Limitations

Like any other project, there are some limitations (most by design):

Technologies

This project is being built using the following technologies:

Getting Started

There are several ways of adding the library to your project:

Prerequisites

Installing

Add the library to your CMakeLists.txt and link it to your project:

FetchContent_Declare(
        libcdsa
        GIT_REPOSITORY https://github.com/ayevexy/libcdsa.git
        GIT_TAG master # replace with the current version, e.g.: v1.0.0
)
FetchContent_MakeAvailable(libcdsa)

target_link_libraries(your_project PRIVATE libcdsa)

Instead, if installed system-wide:

find_package(libcdsa REQUIRED)

target_link_libraries(your_project PRIVATE libcdsa::libcdsa)

The library is also distributed as a header/source pair files in Releases. Just grab them:

your-project/
  libcdsa.h
  libcdsa.c
  main.c

Usage

Simply include the headers you need (or the libcdsa.h master header) and start coding. Don’t forget to prefix includes with libcdsa/ if installed system-wide.

The following examples demonstrate some of the library’s features:

#include "collections/list/list.h"
#include <stdio.h>

int main() {
    ArrayList* list = list_new(DEFAULT_ARRAY_LIST_OPTIONS());

    list_add_last(list, "Hello");
    list_add_last(list, "World!");
    
    const char* hello = list_get(list, 0);
    const char* world = list_get(list, 1);
    
    printf("%s %s\n", hello, world); // Hello World!

    list_destroy(&list);    
    return 0;
}
#include "collections/map/map.h"
#include <stdio.h>

int main() {
    HashMap* map = map_new(DEFAULT_HASH_MAP_OPTIONS());

    map_put(map, "Hello", &(int){5});
    map_put(map, "World!", &(int){6});

    int* hello_length = map_get(map, "Hello");
    int* world_length = map_get(map, "World!");

    printf("Full length: %d\n", *hello_length + *world_length); // 11

    map_destroy(&map);
    return 0;
}
#include "collections/set/set.h"
#include <stdio.h>

int main() {
    HashSet* set = set_new(DEFAULT_HASH_SET_OPTIONS());
    
    set_add(set, &(int){10});
    set_add(set, &(int){20});

    bool present = set_contains(set, &(int){30});
    printf("%s\n", present ? "true" : "false"); // false

    set_destroy(&set);
    return 0;
}
#include "collections/list/list.h"
#include <stdio.h>

int main() {
    ArrayList* list = list_new(DEFAULT_ARRAY_LIST_OPTIONS());

    list_add_last(list, "Hello");
    list_add_last(list, "World!");

    Iterator* iter = list_iterator(list);

    while (iterator_has_next(iter)) {
        const char* string = iterator_next(iter);
        printf("%s ", string); // Hello World!
    }

    iterator_destroy(&iter);

    list_destroy(&list);
    return 0;
}
#include "collections/list/list.h"
#include "collections/for_each.h" // should be included last
#include <stdio.h>

int main() {
    ArrayList* list = list_new(DEFAULT_ARRAY_LIST_OPTIONS());

    list_add_last(list, "Hello");
    list_add_last(list, "World!");

    for_each (const char* string, list) {
        printf("%s ", string); // Hello World!
    }

    list_destroy(&list);
    return 0;
}
#include "collections/list/list.h"
#include "util/sequence.h"
#include <stdio.h>

bool is_even(const void* number) {
    return *(int*) number % 2 == 0;
}

void add_one(void* number) {
    *(int*) number += 1;
}

void* replace_by_two_times(void* number) {
    return new(int, *(int*) number * 2);
}

int main() {
    ArrayList* list = list_new(DEFAULT_ARRAY_LIST_OPTIONS());

    list_add_last(list, &(int){1});
    list_add_last(list, &(int){2});
    list_add_last(list, &(int){3});
    list_add_last(list, &(int){4});
    list_add_last(list, &(int){5});

    Sequence* sequence = sequence_from(list_to_collection(list));

    sequence_filter(sequence, is_even); // 2, 4
    sequence_peek(sequence, add_one); // 3, 5
    sequence_map(sequence, replace_by_two_times); // 6, 10

    Array(void*) array = sequence_to_array(sequence);

    for (int i = 0; i < array_length(array); i++) {
        printf("%d ", *(int*) array[i]); // 6, 10
    }

    list_destroy(&list);
    array_destroy(&array);
    return 0;
}
#include "collections/set/set.h"
#include "collections/for_each.h"
#include <stdio.h>

static inline uint64 int_hash_generic(const void* number) {
    return *(int*) number * 0x9e3779b97f4a7c15ULL;
}

static bool int_equals_generic(const void* a, const void* b) {
    return *(int*) a == *(int*) b;
}

static int int_compare_generic(const void* a, const void* b) {
    return (*(int*) a > *(int*) b) - (*(int*) a < *(int*) b);
}

#define INT_HASH_SET_OPTIONS \
    DEFAULT_HASH_SET_OPTIONS(.hash = int_hash_generic, .equals = int_equals_generic)

#define INT_TREE_SET_OPTIONS \
    DEFAULT_TREE_SET_OPTIONS(.compare = int_compare_generic)

int main() {
    HashSet* set_a = set_new(INT_HASH_SET_OPTIONS);
    set_add(set_a, &(int){1});
    set_add(set_a, &(int){2});
    set_add(set_a, &(int){3});

    TreeSet* set_b = set_new(INT_TREE_SET_OPTIONS);
    set_add(set_b, &(int){3});
    set_add(set_b, &(int){4});
    set_add(set_b, &(int){5});

    TreeSet* union_set = sets_union(set_a, set_b, set_new(INT_TREE_SET_OPTIONS)); // 1, 2, 3, 4, 5
    HashSet* intersection_set = sets_intersection(set_a, set_b, set_new(INT_HASH_SET_OPTIONS)); // 3
    TreeSet* difference_set = sets_difference(set_a, set_b, set_new(INT_TREE_SET_OPTIONS)); // 1, 2

    for_each (int* e, union_set) printf("%d ", *e); // 1, 2, 3, 4, 5
    printf("\n");
    for_each (int* e, intersection_set) printf("%d ", *e); // 3
    printf("\n");
    for_each (int* e, difference_set) printf("%d ", *e); // 1, 2

    set_destroy(&set_a);
    set_destroy(&set_b);
    return 0;
}
#include "collections/list/list.h"
#include <stdio.h>

int main() {
    ArrayList* list = list_new(DEFAULT_ARRAY_LIST_OPTIONS());

    list_add_last(list, "Hello");
    list_add_last(list, "World!");

    Collection collection = list_to_collection(list);

    LinkedList* other_list = list_new(DEFAULT_LINKED_LIST_OPTIONS());
    list_add_all_last(other_list, collection);

    const char* hello = list_get(other_list, 0);
    const char* world = list_get(other_list, 1);

    printf("%s %s\n", hello, world); // Hello World!

    list_destroy(&list);
    list_destroy(&other_list);
    
    return 0;
}
#include "core/errors.h"
#include <stdio.h>

// custom application error
static const Error INVALID_OPERATION_ERROR = ERROR("INVALID_OPERATION_ERROR");

int divide(int a, int b) {
    if (b == 0) {
        set_error(ARITHMETIC_ERROR, "Cannot divide by zero: %d / %d", a, b);
        return -1;
    }
    return a / b;
}

int main(void) {
    int value; Error error = attempt(value = divide(10, 0));

    if (error) {
        error_print(); // ARITHMETIC_ERROR: Cannot divide by zero: 10 / 0
    }                  //       at divide()

    printf("value: %d\n", value); // value: -1

    Result(int) result = try(divide(5, 0));

    if (result.error == ARITHMETIC_ERROR) {
        error_print(); // ARITHMETIC_ERROR: Cannot divide by zero: 5 / 0
    }                  //       at divide()
    
    printf("result value: %d\n", result.value); // result value: -1
    
    set_error(INVALID_OPERATION_ERROR); // INVALID_OPERATION_ERROR: no additional details available
                                        //      at main()
    printf("unreachable");
    return 0;
}
#include "core/array.h"
#include <stdio.h>

int main() {
    Array(int) array_a = array_new(5, int); // [ 0, 0, 0, 0, 0 ]
    Array(int) array_b = array_of(int, 1, 2, 3, 4, 5); // [ 1, 2, 3, 4, 5 ]

    int n = array_get(array_a, 0); // `int n = array_a[0];` also works
    printf("%d\n", n); // 0

    array_set(array_a, 0, 10); // `array_a[0] = 10;` also works

    for (int i = 0; i < array_length(array_a); i++) {
        printf("%d ", array_a[i]); // 10, 0, 0, 0, 0
    }
    
    printf("\n");

    for (int i = 0; i < array_length(array_b); i++) {
        printf("%d ", array_b[i]); // 1, 2, 3, 4, 5
    }

    array_destroy(&array_a);
    array_destroy(&array_b);
    
    return 0;
}
#include "core/string.h"
#include <stdio.h>

int main() {
    String hello = string_ref("Hello"); // heap allocated
    String world = string_static("World!"); // static pool

    char c = string_char_at(hello, 2);
    printf("%c\n", c); // l

    String sub = string_substring("literal", 0, 3);
    printf("%s\n", string_data(sub)); // lit

    // functions accepts both literals and string types
    String hello_world = string_join(" ", hello, world, "Code!");
    printf("%s\n", string_data(hello_world)); // Hello World! Code!

    Array(String) words = string_split(hello_world, ' ');
    for (int i = 0; i < array_length(words); i++) {
        printf("%s ", string_data(words[i])); // Hello World! Code!
    }

    string_destroy(&hello, &sub, &hello_world);
    array_destroy(&words);
    
    return 0;
}
#include "core/memory.h"
#include <stdio.h>

typedef struct {
    float x, y;
} Point;

int main() {
    int* number = new(int, 10); // heap allocated
    int* local = ref(int, 20); // stack allocated
    Point* point = new(Point, .x = 10, .y = 20);

    printf("%d\n", *number); // 10
    printf("%d\n", *local); // 20
    printf("x: %f, y: %f\n", point->x, point->y); // x: 10, y: 20

    delete(number);
    delete(point);
}
#include "core/constraints.h"
#include <stdio.h>

// custom constraint
#define require_different_accounts(source, destination) \
    require((source) != (destination), ILLEGAL_ARGUMENT_ERROR, "source and destination accounts must be different")

bool transfer(int source_account_id, int destination_account_id, double amount) {
    if (require_positive(amount)) return false;
    if (require_different_accounts(source_account_id, destination_account_id)) return false;

    printf("Transferred $%.2f from account %d to account %d\n",
           amount, source_account_id, destination_account_id);

    return true;
}

int main(void) {
    transfer(1001, 2002, 50.00); // Transferred $50.00 from account 1001 to account 2002
    transfer(1001, 1001, 25.00); // ILLEGAL_ARGUMENT_ERROR: source and destination accounts must be different
    transfer(1001, 2002, -10.00); // ILLEGAL_ARGUMENT_ERROR: 'amount' must be greater than zero

    return 0;
}
#include "util/file.h"
#include <stdio.h>

int main(void) {

    // file operations
    file_create("test_file.txt");

    File* file = file_open("test_file.txt", FILE_READ | FILE_WRITE);

    file_write_string(file, "Hello, World!\n");
    file_rewind(file);

    String line = file_read_line(file);
    printf("%s", string_data(line));

    file_close(file);
    file_delete("test_file.txt");
    
    string_destroy(&line);

    // directory operations
    file_create_directory("test_dir");

    file_create("test_dir/file_1.txt");
    file_create("test_dir/file_2.txt");

    Array(String) files = file_list_directory("test_dir");

    for (size_t i = 0; i < array_length(files); i++) {
        printf("%s\n", string_data(files[i]));
    }

    array_destroy(&files);

    // path operations
    bool exists = file_exists("test_dir/file_2.txt");
    printf("file_2.txt exists: %s\n", exists ? "true" : "false");

    FileInfo info = file_info("test_dir/file_2.txt");

    printf("Size: %zu bytes\n", info.size);
    printf("Type: %s\n",
           info.is_regular ? "regular file" :
           info.is_directory ? "directory" :
           info.is_symbolic_link ? "symbolic link" :
           "other"
    );

    file_move("test_dir/file_2.txt", "test_dir/file_2_new.txt");
    file_delete("test_dir/file_2_new.txt");

    file_delete("test_dir/file_1.txt");
    file_delete("test_dir");

    return 0;
}
#include "core/system.h"
#include <inttypes.h>

void* hello_thread(void*) {
    system_write_line("I'm a thread!");
    return nullptr;
}

int main() {

    // input/output operations
    system_write_line("What's up?");

    String response = system_read_line();
    system_write_line(response);

    string_destroy(&response);


    // process management
    const intptr process_id = system_process_create("echo", "I'm a child process!");

    system_process_wait(process_id);


    // multithreading
    const intptr thread_id = system_thread_create(hello_thread);

    system_thread_join(thread_id);


    // environment variables
    system_set_environment_variable("LIBCDSA_TEST_ENV", "0");

    const char* env = system_get_environment_variable("LIBCDSA_TEST_ENV");
    system_write_line("LIBCDSA_TEST_ENV: %s", env);

    system_remove_environment_variable("LIBCDSA_TEST_ENV");


    // platform information
    system_write_line(system_platform_name());
    system_write_line(system_platform_version());
    system_write_line(system_platform_architecture());


    // time measurement
    uint64 milliseconds = system_current_time(); // milliseconds elapsed since the Unix epoch.
    uint64 nanoseconds = system_elapsed_time(); // nanoseconds suitable for measuring elapsed time.

    system_write_line("%" PRIu64 "", milliseconds);
    system_write_line("%" PRIu64 "", nanoseconds);

    return 0;
}
#include "util/allocators.h"

#include <stdio.h>
#include <string.h>

int main(void) {
    // an arena allocates memory from a fixed-size region
    MemoryArena* arena = memory_arena_new(1024);

    char* message = memory_arena_alloc(arena, 32);
    int* numbers = memory_arena_alloc(arena, 4 * sizeof(int));

    strcpy(message, "Hello from the arena!");

    for (int i = 0; i < 4; i++) {
        numbers[i] = i + 1;
    }

    printf("Arena: %s\n", message); // Arena: Hello from the arena!

    printf("Arena numbers: %d %d %d %d\n", numbers[0], numbers[1], numbers[2], numbers[3]);
    // Arena numbers: 1 2 3 4

    // reset reuses the arena without destroying it
    memory_arena_reset(arena);

    // a pool provides a fixed number of equally-sized blocks
    MemoryPool* pool = memory_pool_new(4, 32); // 4 blocks of 32 bytes

    char* block_1 = memory_pool_alloc(pool);
    char* block_2 = memory_pool_alloc(pool);

    strcpy(block_1, "First pool block");
    strcpy(block_2, "Second pool block");

    printf("Pool: %s\n", block_1); // Pool: First pool block
    printf("Pool: %s\n", block_2); // Pool: Second pool block

    // individual blocks can be returned to the pool
    memory_pool_dealloc(pool, block_1);
    memory_pool_dealloc(pool, block_2);

    memory_arena_destroy(&arena);
    memory_pool_destroy(&pool);

    return 0;
}
#include "util/logging.h"

#undef LOG_MODULE
#define LOG_MODULE "main"

int main(void) {
    logger_initialize((LoggerOutput) { .console = true });

    logger_trace("Entering function...");
    logger_debug("Variable value: %d", 42);
    logger_info("Nothing happened...");
    logger_warn("Something unexpected happened...");
    logger_error("An operation failed...");
    logger_fatal("Unrecoverable error occurred...");

    // Output:
    // [2026-10-22 19:26:59] [TRACE] [main] [main.c:9 main()] : Entering function...
    // [2026-10-22 19:26:59] [DEBUG] [main] [main.c:10 main()] : Variable value: 42
    // [2026-10-22 19:26:59] [INFO] [main] [main.c:11 main()] : Nothing happened...
    // [2026-10-22 19:26:59] [WARN] [main] [main.c:12 main()] : Something unexpected happened...
    // [2026-10-22 19:26:59] [ERROR] [main] [main.c:13 main()] : An operation failed...
    // [2026-10-22 19:26:59] [FATAL] [main] [main.c:14 main()] : Unrecoverable error occurred...

    logger_finalize();
    return 0;
}
#include "util/temporal.h"
#include <stdio.h>

int main(void) {
    // current date and time
    const DateTime now = date_time_now();

    // create a specific date and time
    const DateTime launch = date_time_of(2025, 12, 17, 14, 30, 0);

    // format date and time
    printf("Current: %s\n", string_data(date_time_to_string(now)));
    printf("Launch:  %s\n", string_data(date_time_to_string(launch)));

    // extract date and time components
    const Date date = now.date;
    const Time time = now.time;

    printf("DateTime: %04d-%02d-%02d %02d:%02d:%02d\n",
        now.year, now.month, now.day, now.hour, now.minute, now.second
    );
    printf("Date: %04d-%02d-%02d\n", date.year, date.month, date.day);
    printf("Time: %02d:%02d:%02d\n", time.hour, time.minute, time.second);

    // date calculations
    const DateTime tomorrow = date_time_plus(now, 1, DAY);
    const DateTime next_week = date_time_plus(now, 7, DAY);

    printf("Tomorrow:  %s\n", string_data(date_time_to_string(tomorrow)));
    printf("Next week: %s\n", string_data(date_time_to_string(next_week)));

    // date inspection
    printf("Leap year: %s\n", date_is_leap_year(date) ? "yes" : "no");
    printf("Day of year: %d\n", date_year_day(date));
    printf("Weekday: %d\n", date_week_day(date));

    // comparison
    if (date_time_is_after(now, launch)) {
        printf("The launch is in the future.\n");
    } else if (date_time_is_before(now, launch)) {
        printf("The launch has passed.\n");
    }

    return 0;
}

#include "core/assertions.h"

int divide(int a, int b) {
    assert_precondition(b != 0, "divisor must not be zero, received %d", b);

    const int result = a / b;

    assert_postcondition(result * b == a, "expected %d, received %d", a, result * b);

    return result;
}

int main(void) {
    int size = 5;
    int capacity = 10;

    assert_condition(size > 0, "expected positive size, received %d", size);
    assert_invariant(size <= capacity, "size (%d) exceeds capacity (%d)", size, capacity);

    divide(10, 2);

    if (false) {
        assert_unreachable();
    }

    return 0;
}

Documentation

Each data structure and utility is documented in its corresponding header file within the src folder. For usage examples, see the corresponding test file in the test folder.

Building

If you want to build the project locally follow these steps instead:

Clone the project:

  git clone https://github.com/ayevexy/libcdsa.git

Go to the project directory:

  cd libcdsa

Build the project with CMake:

  mkdir build
  cmake -S . -B build
  cmake --build build

It will compile the library as a static library by default. To compile it as a shared library instead, add the following flag:

  cmake -S . -B build -DBUILD_SHARED_LIBS=ON

Tests

To run tests, execute the following command:

  ctest --test-dir build

Installing System-Wide

To install the library system-wide in /usr/local, execute the following command:

  sudo cmake --install build

Instead, to install to a custom directory in the home folder:

  cmake --install build --prefix $HOME/my-libraries

Frequently Asked Questions

I made libcdsa as a hobby project to learn and practice the C programming language and data structures and algorithms. But the project grew while developing it and became a powerful library with a different and interesting design approach from most implementations.

Most implementations focus on simplicity and performance, at the cost of limited scope and heavy use of macros. libcdsa is the opposite—its focus is mainly on functionality, an abstracted API, and ease of use. For example: the Array List module has 50+ functions! The library also provides some flexibility regarding memory management by making it available but optional. You can check the documentation to learn more about what this project can offer.

Even though libcdsa is heavily inspired by Java Collections, it’s not a reimplementation. The API is based on Java because I personally like it, but there are many differences, both in the API and in the implementation. For example, Java makes heavy use of exceptions; however, in libcdsa, exceptions don’t exist—there’s an entirely new built-in error handling mechanism. If you look at the source code and the API, the differences will become clear.

Absolutely. If you’ve used Java before, the API will feel familiar. Even if you haven’t, the design is straightforward and consistent across all data structures. The only tough part would be installing it, which requires CMake and some steps—unless you grab the header/source pair files instead.

If the mentioned limitations aren’t an obstacle for your project, it might be used in production, but it’s better to wait until the first stable version is released. The project is currently in beta, and breaking changes may occur before the definitive version v1.0.0.

One thing I tried to achieve and maintain while developing this project is the clarity and readability of the code. But it can be difficult due to the size of the project, the topics it addresses, and some design decisions made. Still, I think it could be a good source for learning.

Yes! If you have any feedback, feature requests, bug reports, or questions, you can start a discussion, open an issue, or email me at ayevexy@proton.me. If you’ve used libcdsa anywhere, I’d love to know too!

License

This project is licensed under the MIT License. See the LICENSE file for details.