Dross 🧱

A modern C++23 general-purpose library designed for robust, self-contained applications

Dross is a comprehensive C++ library that provides fundamental building blocks for modern applications. Similar in spirit to Boost, but designed with C++23 features and minimal dependencies in mind.

✨ Key Features

• 🔢 Arbitrary Precision Arithmetic - String-based number system supporting unlimited precision
• 🧵 Dynamic Type System - Unified value type using modern std::variant
• 🔧 Platform Utilities - Cross-platform environment, filesystem, and XDG support
• ⚡ Zero Dependencies - Self-contained with only standard library requirements
• 🛡️ Memory Safe - RAII principles with smart pointers throughout
• 🎯 Modern C++23 - Leverages concepts, ranges, and latest language features

🚀 Quick Start

Requirements

• A compiler configured for C++23 or later. The public headers use C++23, so C++17 and C++20 are outside the supported range. C++26 consumers are best effort: no required job builds one, so neither compiling these headers as C++26 nor the ABI and ODR compatibility of linking such a consumer against a C++23 build of the library is verified.

• A supported compiler and standard library pairing. On Linux those are:

  • GCC 13–15 with the libstdc++ it is paired with (13, 14 or 15)
  • Clang 20–22 with libstdc++ 13, 14 or 15
  • Clang 20–22 with libc++ 20 or 22

  The version in each pairing is the version of the standard library headers the compiler builds against. The shared runtime a resulting binary loads comes from the system's own runtime package, which is versioned and updated separately.

  GCC with libc++ is not one of them, because upstream does not support that pairing: GCC has no -stdlib option to select libc++ with in the first place. It would be worth revisiting if GCC gained an equivalent option, or if libc++ started supporting GCC officially. On macOS the compiler is the Apple Clang shipped with macOS 15 or 26, and the standard library is not a separate axis there, because libc++ comes with the OS toolchain.

• What the required Linux jobs build. GCC 13 and 15, each against the libstdc++ paired with it, and Clang 20 and 22 against libstdc++ 13, 14 and 15 (15 being the release Ubuntu 26.04 provides) as well as against libc++ 20 and 22. Every libstdc++ release in the supported range is therefore covered in the Clang pairings; among the GCC ones only 13 and 15 are, since the libstdc++ version follows the compiler version there. GCC 14 and Clang 21 are inside the declared range but are not built by a required job. On macOS the required jobs build with the Apple Clang of macOS 15 and 26. Newer versions are best effort: the nightly toolchain watch tracks the newest versioned GCC available once the toolchain PPA is in place, and the specific Clang release next in line to enter this range.

• CMake 3.20+

Installation

Package Managers

# vcpkg (coming soon)
vcpkg install dross

# Conan (coming soon)
conan install dross/0.0.1@

# CPM (CMake Package Manager)
CPMAddPackage("gh:skipbit/dross@0.0.1")

From Source

# Clone and build
git clone https://github.com/skipbit/dross.git
cd dross

# Configure with desired options
cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=ON \
    -DCMAKE_INSTALL_PREFIX=/usr/local

# Build and install
cmake --build build
sudo cmake --install build

# Run tests (optional)
cd build && ctest -V

Library Types

# Shared library (default)
cmake -DBUILD_SHARED_LIBS=ON ...

# Static library
cmake -DBUILD_SHARED_LIBS=OFF ...

Using in Your Project

CMake Integration

# Option 1: find_package (after installation)
find_package(dross REQUIRED)
target_link_libraries(your_target PRIVATE dross::dross)

# Option 2: FetchContent (no installation needed)
include(FetchContent)
FetchContent_Declare(dross
    GIT_REPOSITORY https://github.com/skipbit/dross.git
    GIT_TAG v0.0.1
)
FetchContent_MakeAvailable(dross)
target_link_libraries(your_target PRIVATE dross::dross)

pkg-config Integration

# Compile flags
pkg-config --cflags dross

# Link flags
pkg-config --libs dross

# Check version
pkg-config --modversion dross

Manual Compilation

# Using pkg-config
g++ -std=c++23 $(pkg-config --cflags dross) main.cpp $(pkg-config --libs dross)

# Or manually
g++ -std=c++23 -I/usr/local/include main.cpp -L/usr/local/lib -ldross

Basic Usage

#include <dross/dross.h>
using namespace dross;

// Arbitrary precision arithmetic
number big_num{"99999999999999999999999999999999999999"};
number result = big_num * big_num;  // No overflow!

// Dynamic typing. dictionary has no initializer-list constructor, so
// entries are assigned after construction.
dictionary config;
config["name"] = string("Dross");
config["version"] = number("0.0.1");
config["features"] = array{string{"fast"}, string{"safe"}};
config["release_date"] = timestamp{2024, 1, 21, 15, 30, 0, timezone::utc()};

value data = config;

// Platform utilities. The XDG accessors are instance methods, and the
// application name is already part of what they return.
xdg app{"myapp"};
if (auto config_dir = app.config_home()) {
    path app_config = path{*config_dir}.append("config.toml");
}

📚 Core Modules

Type System

• boolean - Type-safe boolean operations with logical operators
• number - Arbitrary precision arithmetic with string-based storage
• string - UTF-8 text held as bytes, with byte-oriented operations
• timestamp - Date and time handling with timezone support
• timezone - Type-safe timezone representation with ISO 8601 support
• array - Dynamic arrays with value semantics
• dictionary - Key-value containers
• value - Polymorphic type holding any supported type

Platform Layer

• environment - Environment variable access
• path - Filesystem operations with error handling
• xdg - XDG Base Directory specification support

📖 Documentation

📘 API Reference & User Guide

Complete documentation including:

• 🔍 API Reference - Detailed documentation of all classes and functions
• 📚 User Guide - Tutorials and best practices
• 💡 Examples - Practical code examples and use cases
• 🏗️ Architecture - Design patterns and implementation details

🏗️ Architecture

Dross follows modern C++ best practices:

• Pimpl Idiom - ABI stability through opaque pointers
• Value Semantics - The value types are copyable and assignable; environment exposes only static members
• Error Handling - std::expected and std::optional for failures, apart from the bounds-checked accessors and the path calls that let std::filesystem exceptions through
• Type Safety - Concepts for compile-time constraints
• Zero-Cost Abstractions - Performance without compromise

🧪 Testing

Comprehensive test suite using GoogleTest:

# Run all tests
ctest

# Run specific test patterns
ctest -R number
./build/debug/test/dross_test --gtest_filter="number_test.*"

# Verbose output
ctest -V

🗺️ Roadmap

Current Modules

• ✅ Type System (boolean, number, string, timestamp, timezone, array, dictionary, value)
• ✅ Platform utilities (environment, path, xdg)

Planned Features

• Configuration - TOML, JSON, XML, YAML parsers
• Concurrency - Thread management, async operations, coroutines
• Multimedia - Image processing, color management, transformations
• Application Support - CLI parsing, logging, preferences

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CODINGSTYLE.md for coding guidelines.

📄 License

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

🙏 Acknowledgments

• Inspired by the Boost libraries
• Built with modern C++23 features
• Designed for real-world applications

---

Made with ❤️ by Yuma Endo