CppUtils

C++ Utilities Library

Explore the Official Documentation

Getting Started  •  API Reference  •  Discord Community

Project Health

---

Project Activity

Library Features

📦 Containers

• BidirectionalMap - Two-way key-value mapping
• BTree - Balanced tree for large sorted datasets with efficient range queries and low memory access
• DependencyGraph - Dependency graph for managing dependencies between objects
• FlatHashMap - Constexpr associative hash map with O(1) lookup and cache-friendly contiguous storage
• MeshNetwork - Graph of shared objects without hierarchy
• MultiKeyMap - Associative container with multi-axis O(1) lookup and contiguous storage
• NetworkPtr - Intrusive smart pointer representing graph-aware nodes with automatic cycle breaking
• SafeShared - Thread-safe smart pointer with monitor-object encapsulation and compile-time (constexpr) evaluation support
• Size - Semantic wrapper around std::size_t for representing 2D (Size2: width/height) and 3D (Size3: width/height/depth) sizes
• Stack - Type-specific stack without predefined type list (unlike TypedStack)
• Tree - Hierarchical node structure with parent-child links
• TypedStack - Multi-type stack with exact object size layout, suitable for argument passing and VM stacks
• Vec2 / Vec3 - 2D/3D math vectors with operators and common functions

🔐 Crypto

• HMAC - Keyed-Hash Message Authentication Code (HMAC-SHA256)
• SHA256 - SHA-256 cryptographic hashing implementation

🎯 Execution

• Event - An event for thread synchronization
• EventDispatcher - Event system to subscribe functions and trigger actions by event name
• EventQueue - Thread-safe event queue running on a dedicated thread for asynchronous event processing (preserves event order)
• Pipeline - Monadic execution pipeline with short-circuiting on std::expected failures
• Retry - Retries operations with configurable attempts and delay
• ScopeGuard - RAII utility to execute a function when leaving a scope, ensuring resource cleanup
• TryExecute - Executes operations and captures exceptions as std::expected

📁 Filesystem

• Directory - Directory traversal (forFiles, forDirectories) and RAII temporary directories
• File - Binary and text file I/O, including optimized block-by-block reading
• FileRange - Lazy line-by-line file streaming view
• FileStaging - File isolation and lifecycle management
• IndexedStorage - Thread-safe indexed storage engine for storing and retrieving serializable types in chunked binary files
• MeshPager - Paging mechanism for loading and saving MeshNetwork nodes on-demand using IndexedStorage
• Watcher - File modification watcher

⛓️ Flow

• Flow - Declarative data transformation and file orchestration with staging, watching, and parallel chunking
• FlowRunner - Orchestrator discovering, indexing, and executing XML flows in parallel
• Pipeline - Lazy C++20 range pipeline compiled from XML tags
• Tags - Standard pipeline tags (<Filter>, <Validate>, <Transform>, <Operation>, <Call>, <When>, <Let>, <Log>, <Rejected>, <Scope>, <Include>)

🧠 Functional

• LambdaCalculus - Compile-time utilities for lambda calculus manipulation

🔣 Languages (Parsers, Compilers, VM)

• Tools to create parsers and compilers (CSS, INI, HTML, JSON, Markdown, XML) (work in progress )
• CSV Lexer - RFC 4180 compliant CSV lexer and table parser with grammar interpretation
• CSV Mapping - Type-safe CSV to struct mapping with support for custom conversion functions and CSV generation
• CSV Parsing - Stream-based CSV line parser
• CLikeCompiler - Compiler for C-inspired language
• GrammarParser - A parser for defining and interpreting custom grammars, used for building language parsers
• JSON Lexer - Grammar-based JSON lexer with compile-time AST generation
• JSON Mapping - Type-safe bidirectional mapping between C++ structs and JSON with compile-time reflection
• JSON Parsing - High-performance typed JSON parser
• MetaCircularVirtualMachine - Homoiconic meta-circular virtual machine with extensible reflexivity
• MetaCircularParser - Extension of MetaCircularVirtualMachine for building parsers with input stream reading capabilities
• ASTParser - AST parser (work in progress )
• VirtualMachine - Generic virtual machine

📝 Logging & Benchmarking

• Logger - Asynchronous, configurable and formattable logger with support for colors and customizable log types
• FileSink - Pluggable sink for automated file logging with integrated rotation and file size management
• LogRotate - Log file rotation based on maximum file size
• ChronoLogger - RAII timer that logs elapsed time at scope exit

🧮 Math

• BigInt - Arbitrary-precision integer arithmetic
• Easing - Collection of easing functions for smooth animation
• Random - Pseudorandom number generation
• Utility - Floating-point comparison with epsilon tolerance

🔠 String

• Encoding - UTF-8 and UTF-32 conversion and character display width utilities
• Hash - Hashing utilities for strings

🌐 Networking

• Client - TCP client with synchronous and asynchronous modes
• Server - TCP server with multi-client support

🧩 Patterns

• Singleton - Generic Meyers Singleton implementation (thread-safe and lazy)
• Multiton - Generic Multiton implementation based on the Meyers Singleton

📶 Ranges

• Drain - Consuming range adaptor draining elements from a range
• Expected - Range adaptors for std::expected streams
• Inspect - Range element inspection for side-effects and logging
• Parallel - Multithreaded range pipelining

💻 Terminal

• Area - Dedicated drawing context for a single child widget
• Canvas - Terminal-based 2D drawing surface
• Cursor - Terminal cursor manipulation
• Layout - Container widget for dynamic children positioning
• Primitive - Basic drawing primitives for terminal (lines, rectangles, circles, ellipses)
• ProgressBar - Dynamically updating terminal progress bar
• RawTerminal - Raw input handling (no buffering or echo)
• Scrollable - Scrollable viewport for viewing large content areas
• Size - Terminal size utilities
• Spinner - Animated widget displaying a sequence of frames
• TextColor - Terminal text color utilities
• TextModifier - Utilities to style and color terminal text
• Title - Terminal title utilities
• Viewport - Rectangular region with clipping and intersection logic
• Widget - UI interface for rendering and update lifecycle
• WidgetManager - Central hub for widget events and update scheduling

🚦 Multithreading & Synchronization

• Scheduler - Simple scheduler to run delayed functions on separate thread
• ScheduledEventDispatcher - Dispatches events asynchronously with timed (delay/when) execution
• AsyncEventDispatcher - Event dispatcher that uses a ThreadPool for immediate asynchronous event execution
• ThreadLoop - Thread loop with exception handling
• ThreadPool - Fixed-size thread pool for parallel task execution
• TryAsync - Launches a function asynchronously, forwards exception to caller
• UniqueLocker - RAII wrapper holding a value with exclusive access
• SharedLocker - RAII wrapper holding a value with shared/exclusive access
• SharedPtr - Thread-safe reference-counting smart pointer (SharedPtr, WeakPtr, makeShared, ownerEqual) with compile-time (constexpr) and runtime atomic support
• Accessor - RAII accessor for reading/writing an UniqueLocker or exclusive access to a SharedLocker
• ReadOnlyAccessor - RAII accessor for shared (non-exclusive) reading of a SharedLocker, allowing parallel access
• MultipleAccessor - RAII accessor for multiple lockers, safely acquiring them to avoid deadlocks and data races

🏷️ Type

• Concept - Extensions to <type_traits> and <concepts> providing additional compile-time checks and utilities
• Enum - Generic enum-to-string conversion
• Mapping - Generic compile-time mapping between values
• ReadWriteAdapter - write and read CPOs (Customization Point Objects) mapping stream and buffer operations (std::ostream, std::istream, std::vectorstd::byte, std::span, etc)
• Serializer - serialize and deserialize CPOs (Customization Point Objects) and custom Binary/Text Serializers
• Tuple - Visitor for std::tuple
• VariadicTemplate - Metaprogramming on variadic parameters
• Variant - Generic print and comparison operators for std::variant

🧪 Unit Testing

• LifetimeChecker - Object that prints construction, destruction, copy and move operations, while counting copies and moves for test verification
• UnitTest - Minimal test framework with assertions and filters

🧩 Miscellaneous

• Many other functions

---

Installation

Add CppUtils to your xmake.lua:

add_repositories("xmake-repo https://github.com/MorganCaron/xmake-repo.git")
add_requires("CppUtils 0.1.*") -- or add_requires("CppUtils") for latest

target("YourProject", function()
	add_packages("CppUtils", {public = true})
end)

For step-by-step instructions, compiler prerequisites, and modular C++26 code examples, see the Getting Started Guide.

---

Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md for development guidelines, test execution, and build instructions.

---