IceCream-Cpp
A single-header C++ library for expressive and concise print debugging, replacing cout/printf with powerful formatting and lazy evaluation.
What is IceCream-Cpp?
Icecream-cpp is a single-header C++ library that simplifies print debugging by replacing verbose `cout` or `printf` statements with concise macros. It automatically prints variable names and values, supports formatting, and can inspect data in range pipelines, making debugging faster and less error-prone. The library is designed for use during development and can be disabled for production builds.
C++ developers (C++11 and later) who frequently use print debugging and want a more expressive, less intrusive way to inspect variables, function flow, and range-based data transformations.
Developers choose Icecream-cpp because it drastically reduces boilerplate in debug code, provides rich formatting options, and integrates seamlessly with modern C++ features like ranges and third-party libraries. Its header-only nature and configurability make it easy to adopt and tailor to specific debugging needs.
Overview
🍦 Never use cout/printf to debug again
Use Cases
Best For
- Quickly inspecting variable values during C++ development without writing verbose output statements
- Debugging complex range or view pipelines in C++20 or Range-v3 by inserting print points lazily
- Formatting debug output in hex, decimal, or custom layouts for integers, floats, and containers
- Adding context-aware debug prints that automatically include file, line, and function information
- Temporarily enabling detailed logging in specific scopes with configurable output destinations
- Integrating print debugging with third-party libraries like Boost, {fmt}, or Range-v3 without extra setup
Not Ideal For
- Projects requiring structured, production-grade logging with features like log levels or file output
- Teams with strict no-macro policies or existing identifier conflicts (e.g., 'IC' used elsewhere)
- Environments limited to pre-C++11 standards or compilers with poor C++11 support
- Debugging timing-sensitive code where lazy evaluation in range pipelines could skew performance analysis
Pros & Cons
Pros
IC() macros automatically print variable names and values, replacing verbose cout statements with minimal code, as shown in examples like IC(a, b, sum(a, b)).
IC_V() integrates lazily into C++20 or Range-v3 pipelines to print intermediate data without breaking the flow, supporting views like vws::split.
Format strings (e.g., IC_F('#x', i)) allow control over output for integers, floats, ranges, and tuples, including hex, decimal, and slicing.
Global and scoped IC_CONFIG objects enable customization of output destination, prefixes, string handling, and more, with thread-safe operations.
Cons
The IC macro can clash with other identifiers, requiring workarounds like defining ICECREAM_LONG_NAME, as admitted in the pitfalls section.
Handling wide and Unicode strings involves multiple transcoding layers (wide_string_transcoder, unicode_transcoder), which can be confusing and require custom implementations for edge cases.
For standards before C++20, separate nullary macros like IC0() are needed, adding boilerplate and complexity for cross-version compatibility.
Frequently Asked Questions
Related Projects
googletestGoogleTest - Google Testing and Mocking Framework
Google MockGoogleTest - Google Testing and Mocking Framework
Catch2A modern, C++-native, test framework for unit-tests, TDD and BDD - using C++14, C++17 and later (C++11 support is in v2.x branch, and C++03 on the Catch1.x branch)
benchmarkA microbenchmark support library
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.