Welcome to dross¶

dross is a modern C++23 library providing fundamental building blocks for applications, designed to be a general-purpose library similar to Boost with a focus on:

Zero external dependencies - Only requires the standard library
Modern C++ design - Leveraging C++23 features throughout
Errors in the return type - std::optional and std::expected rather than exceptions, apart from the bounds-checked accessors and the path calls that let std::filesystem exceptions through
ABI stability - Through careful use of the Pimpl idiom
Comprehensive type system - Dynamic types with value semantics

Getting Started

New to dross? Start here with installation instructions and a quick tutorial.

Get Started

User Guide

Learn how to use dross effectively with in-depth guides and best practices.

Read the Guide

API Reference

Complete API documentation for all dross modules and classes.

Browse API

Examples

See dross in action with practical examples and use cases.

View Examples

Core Modules¶

Type System¶

The dross type system provides dynamic typing with strong value semantics:

#include <iostream>

#include <dross/type/array.h>
#include <dross/type/dictionary.h>
#include <dross/type/value.h>

using namespace dross;

// dictionary has no initializer-list constructor
dictionary dict;
dict["key"] = string("value");

// Create various types
value v1 = 42;                 // number
value v2 = "hello world";      // string
value v3 = array{1, 2, 3};     // array
value v4 = dict;               // dictionary
value v5 = boolean{true};      // boolean

// Type checking, then casting
if (v1.is<number>()) {
    auto n = v1.as<number>();
    std::cout << "Number: " << n << std::endl;  // number has operator<<
}

Platform Utilities¶

Cross-platform utilities for common operations:

#include <iostream>
#include <string>

#include <dross/platform/environment.h>
#include <dross/platform/path.h>
#include <dross/platform/xdg.h>

using namespace dross;

// Environment variables
const std::string home = environment::value("HOME").value_or("/tmp");

// Path operations
const path config_dir = path{home}.append(".config");
std::cout << "Config: " << config_dir.string() << std::endl;

// XDG Base Directory support
xdg app{"myapp"};
if (auto data_home = app.data_home()) {
    std::cout << "Data: " << *data_home << std::endl;
}

Features¶

Dynamic Type System: Polymorphic value type using std::variant
UTF-8 Strings: Text held as UTF-8 bytes, with byte-oriented operations
Arbitrary Precision: Number type with string-based storage
Error Handling: Consistent use of std::optional and std::expected
Modern C++: Concepts, ranges, three-way comparison, and more
Platform Utilities: Cross-platform environment and filesystem operations

Installation¶

dross can be built using CMake:

# Clone the repository
git clone https://github.com/skipbit/dross.git
cd dross

# Configure and build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Run tests
cd build && ctest

See Getting Started for detailed installation instructions.

Contributing¶

We welcome contributions! Please see our Contributing to dross guide for details on:

Code style and conventions
Testing requirements
Submitting pull requests
Reporting issues

License¶

dross is released under the MIT License. See the LICENSE file for details.