UTL C++ Utility Libraries

The utl::json module provides an intuitive, lightweight JSON manipulation API for C++17. It is designed to be a high-performance alternative to nlohmann_json with a single-header integration (less than 1k lines of code) and no external dependencies.

Key characteristics:

• Standard Container Mapping: All JSON types map directly to standard library containers (std::map for objects, std::vector for arrays, etc.), making it easy to integrate with existing C++ code.
• Transparent Lookups: Objects support transparent comparators, allowing you to use std::string_view or const char* for key lookups without unnecessary allocations.
• Recursive Reflection: Supports recursive structure reflection, including nested types and containers.
• Type-Trait Based: Uses type-traits for conversions, allowing assignment and construction from various types.
• Error Handling: Provides validation with descriptive error messages via exceptions.

/* Note: This module is header-only and requires C++17 */

UTL provides a wide range of specialized utility modules. Each module resides in its own utl:: namespace to ensure non-intrusive usage. Key modules include:

• utl::assertion: Enhanced diagnostic macros.
• utl::bit: Bit-twiddling and enum bitflags.
• utl::enum_reflect: Enum reflection capabilities.
• utl::integral: Saturated math, safe integer casts, and rounding.
• utl::json: JSON parsing, serialization, and reflection.
• utl::log: Logging utilities.
• utl::math: Additional mathematical functions.
• utl::mvl: Generalized matrix and vector containers.
• utl::parallel: Thread pools, async tasks, and parallel algorithms.
• utl::predef: Architecture, compiler, and platform detection.
• utl::profiler: Call graph and thread profiling.
• utl::progressbar: CLI progress bars.
• utl::random: PRNGs and random number generation.
• utl::shell: Shell commands and temporary file management.
• utl::sleep: Precise sleep implementations.
• utl::stre: Efficient string utilities.
• utl::strong_type: Strong typedefs and RAII wrappers.
• utl::struct_reflect: Struct reflection.
• utl::table: Exporting tables to ASCII, Markdown, LaTeX, Mathematica, and CSV.
• utl::time: Timers, stopwatches, and datetime handling.

The utl::random module provides <random>-compatible implementations of several modern Pseudorandom Number Generators (PRNGs). By default, rand functions in this header use Xoshiro256++, which offers an excellent balance of speed and statistical quality.

When choosing a generator, consider the following trade-offs:

• Speed: RomuMono16, RomuTrio32, and RomuDuoJr64 are extremely fast but have lower statistical quality.
• Security: ChaCha8, ChaCha12, and ChaCha20 are cryptographically secure (CSPRNG) but come with a performance cost.
• General Purpose: Xoshiro128PP (32-bit) and Xoshiro256PP (64-bit) are recommended for most non-cryptographic use cases.
• Memory: Generators like SplitMix32 and SplitMix64 have very small state footprints.

/* 
Available PRNGs summary:
- RomuMono16: Fastest 16-bit
- RomuTrio32: Fastest 32-bit (Chaotic)
- SplitMix32: Smallest state 32-bit
- Xoshiro128PP: Best all-purpose 32-bit
- RomuDuoJr64: Fastest 64-bit (Chaotic)
- SplitMix64: Smallest state 64-bit
- Xoshiro256PP: Best all-purpose 64-bit
- ChaCha8/12/20: Cryptographically secure
*/

The utl::assertion module provides a replacement for the standard C++ assert() macro. It offers improved diagnostics by decomposing expressions (printing both the condition and its evaluated value), supporting optional context messages, and allowing for custom failure handlers.

By default, assertions are active in Debug mode (where NDEBUG is not defined) and compiled away in Release mode.

Key Features:

• Expression Decomposition: Automatically prints the values of simple expressions (e.g., a + b).
• Context Messages: Pass a string as a second argument to provide specific error context.
• Custom Handlers: Replace the default behavior (printing to std::cerr and calling std::abort()) with custom logging or stack trace logic.
• Colorized Output: Uses ANSI colors for better readability in terminals.

const int rows = 10;
const int cols = 12;

ASSERT(rows == cols, "Linear system requires a square matrix.");

utl::parallel::ThreadPool is designed as a simple, standard C++17 threading API (~600 LOC) that supports recursion, a feature missing from many common standalone thread pools.

Key Performance Insights

• Small, Non-Recursive Tasks: utl::parallel::ThreadPool significantly outperforms std::async() because it avoids the overhead of frequent thread creation. It performs comparably to other popular thread pools like BS::thread_pool and progschj/ThreadPool.
• Large, Non-Recursive Tasks: When task duration is large enough (typically >1ms) to overshadow scheduling overhead, std::async() performance approaches that of thread pools.
• Recursive Tasks: This is a primary differentiator. While std::async() can handle recursion, it suffers significant slowdowns. Most popular standalone thread pools (like BS::thread_pool and progschj/ThreadPool) will deadlock when encountering recursive tasks. utl::parallel::ThreadPool handles both shallow and deep recursion efficiently without deadlocking.

Benchmarking Context

Benchmarks were conducted on an AMD Ryzen 5 5600H (6-core, hyper-threading disabled) using g++ 11.4.0 at -O2.