A lightweight, reference-counted dynamic type and variant library for C.
Online documentation and API reference: dtl-type.readthedocs.io
In C, building heterogeneous and deeply nested data structures (such as parsed JSON, dynamic configurations, or arbitrary object graphs) requires complex manual memory management and ad-hoc union types.
dtl-type provides a clean runtime type system and dynamic container library built around:
- Polymorphic Dynamic Values (
dtl_dv_t): A unified base handle for all dynamic types. - Scalar Variants (
dtl_sv_t): Flexible containers holding numbers (signed/unsigned 32/64-bit integers, floats, doubles), booleans, strings, raw byte arrays, or custom pointers with automatic destructor callbacks. Includes safe runtime type inspection and cross-type conversion routines. - Dynamic Arrays (
dtl_av_t): Ordered, growable collections that can contain any combination of dynamic values (scalars, nested arrays, or hashes). - Hash Maps (
dtl_hv_t): String-keyed lookup tables storing arbitrary dynamic values. - Automatic Lifetime Management: Pure reference counting across all objects. When a root container is released, all nested children are automatically cleaned up without memory leaks.
- Recursive Reference Counting: Simplifies memory management when building complex, shared object trees.
- Safe Type Conversions: Built-in conversion between integers, floating-point numbers, booleans, and strings with success flags.
- Custom Pointer Management: Scalars can manage external pointers and automatically trigger a user-defined destructor callback when freed.
- Lightweight & Portable: Written in standard C99 with zero external dependencies beyond
adtandcutil.
This repo is a submodule of the cogu/c-apx (top-level) project.
The unit test project(s) assume that the repos are cloned side-by-side to a common directory as seen below.
- adt
- cutil
- dtl-type (this repo)
cd ~
mkdir repo && cd repo
git clone https://github.com/cogu/adt.git
git clone https://github.com/cogu/cutil.git
git clone https://github.com/cogu/dtl-type.git
cd dtl-typeThe cogu/dtl_json project provides JSON serialization and deserialization routines based on the dtl-type system.
First clone this repo and its dependencies into a common directory (such as ~/repo) as seen above. Alternatively the repos can be submodules of a top-level repo (as seen in cogu/c-apx).
For Windows, use a "Native tools command prompt" from your Visual Studio installation. It comes with a cmake binary that by default chooses the appropriate compiler version.
# Run unit tests
cmake --preset clang-test
cmake --build --preset clang-test
ctest --preset clang-test
# Address and Undefined Behavior Sanitizers (ASan + UBSan)
cmake --preset clang-asan
cmake --build --preset clang-asan
ctest --preset clang-asan
# Static Analysis
cmake --preset clang-tidy
cmake --build --preset clang-tidyFor Windows, use a "Native tools command prompt" from your Visual Studio installation. It comes with a cmake binary that by default chooses the appropriate compiler version.
Configure:
cmake -S . -B build-test -GNinja -DUNIT_TEST=ONBuild:
cmake --build build-testRun test cases:
ctest --test-dir build-test --output-on-failure