Needful
One header. Zero dependencies. Rust-grade safety for C.
Needful is a single-file, header-only library that brings Option(T), Result(T), non-null Need(T), type-safe casts, and executable comment annotations to C codebases—with zero runtime cost and no tools beyond the compiler you already have.
The key trick: every Needful construct compiles as a transparent no-op in C. Flip one switch (#define NEEDFUL_CPP_ENHANCED 1) and build as C++11, and those same constructs light up with compile-time type enforcement that catches real bugs. Your C code stays C. The C++ compiler just checks it harder.
Getting Started
Step 1. Drop needful.h into your project and #include it. All macros expand to trivial C — your build won’t even notice.
Step 2. When ready, add the needful-enhanced/ enhancement files alongside needful.h and #define NEEDFUL_CPP_ENHANCED 1. Build as C++11 or later. Every macro grows teeth: type mismatches become compile errors.
Step 3. Run both modes in CI: C build for production, C++ build to catch bugs. No code changes needed between them.
What You Get
| Construct | What It Does |
|---|---|
Need(T) | Non-null/non-zero type; blocks boolean coercion |
Option(T) | Rust-like optional with same size as T |
Result(T) | Multiplexed error + return value; auto-propagation via trap |
cast() family | Visible, hookable, semantically-named casts |
Contra(T) / Sink(T) / Init(T) | Contravariant output parameter markers |
known(T, expr) | Zero-cost compile-time type assertion inside macros |
| Comment macros | possibly(), dont(), heeded() — executable documentation |
nocast | Bridge void* and enum zero between C and C++ |
Design Goals
- No magic. The C definitions are written out in full so you can see how trivial they are. Adding Needful to a C project is a low-impact proposition.
- Gradual adoption. Use just
nocasttoday. AddOptionnext month. EnableNEEDFUL_CPP_ENHANCEDwhen you’re ready. Nothing breaks. - Codebase documentation. The comment macros (
possibly,definitely,impossible,unnecessary,dont) replace prose comments with compile-checked expressions that keep themselves up-to-date.
Frequently Asked Questions
Common gotchas and design rationale are collected in the FAQ.