CHOC: "Classy Header Only Classes" ¹

A random grab-bag of header-only, dependency-free C++ classes.

When you start trying to write a C++ project of any size, you'll soon start finding gaping holes in what the C++ standard library provides. To fill them, you'll end up either writing lots of helper functions yourself, or trawling the web for awful 3rd-party libraries which come with all kinds of baggage like messy build requirements, scads of stupid compiler warnings, awkward licenses, etc.

I got tired of re-implementing many of the same little helper classes and functions in different projects, so CHOC is an attempt at preventing future wheel-reinvention, by providing some commonly-needed things in a format that makes it as frictionless as possible for anyone to use this code in any kind of project.

So with that goal in mind, the rules for everything in CHOC are:

• It's strictly header-only. Just #include the file you want, and you're done. Nothing needs adding to your build system to use any of this stuff.
• It's all permissively ISC licensed. It should pass silently under the noses of even the most zealous legal teams.
• Each file is as self-contained as possible. If you only need a couple of these classes, you should be able to cherry-pick at most a few CHOC headers into your project and not need to drag the whole repo along.
• Clean, consistent, concise, modern C++. Not too simple. Not too over-generic or fancy. Easy to skim-read and find what you're looking for. Self-documenting where possible, with decent comments.

Basically CHOC is aimed at people (like me) who just want to use some decent library code without also spending their afternoon fighting CMake or looking up the right compiler flags to make the dratted thing work.

---

Highlights

The library is getting quite big now. Some of its many delights include:

Miscellaneous

• A tiny platform-detection header.
• A fast, round-trip-accurate float/double to string converter.
• Helpers for reading writing data with different endianness.
• Some headers which will disable and reenable warnings for times when you have to include messy 3rd-party code in your otherwise faultless codebase.
• The world's simplest unit test framework. I mainly wrote this so that CHOC can self-host its own unit-tests without any external dependencies, but have found it surprisingly useful for something that's about 100 lines of code.
• Cross-platform dynamic library loading.
• Various maths and bit-twiddling bits and bobs.

Text and Files

• Utterly basic string stuff like trimming, splitting, joining, comparisons, etc. For god's sake, I shouldn't need to write my own library just to trim a string...
• Some more esoteric string utilities like pretty-printing durations and sizes, URI encoding, etc.
• Some UTF8 validation and iteration classes.
• Some file utilities to provide single-function-call ways to do obvious things like loading a file's content, or saving a string into a file, creating self-deleting temp files, etc.
• A CodePrinter class to help creating indented code listings.
• A HTML generator for creating a tree of DOM objects and generating HTML text for it
• A text table generator, which can take an array of strings and tabulate it to align the columns nicely.
• A file wildcard matcher. I claim this is the cleanest possible implementation of this algorithm - I challenge you to prove me wrong!
• A base64 encoder/decoder.
• Some integer compression and zigzag encoding functions.
• An implementation of the xxHash very-fast-but-pretty-secure hash algorithm.

Containers

• A span class to fill the gap until we can finally use std::span.
• Some type and value classes which can represent typed values, but also build them dynamically, serialise them to a compact binary format (or as JSON).
• A handy SmallVector class which offers a std::vector interface but has pre-allocated internal storage.
• One of those aligned memory block classes that you always end up needing for some reason.
• Everyone hates COM, but sometimes you need some COM helper classes to hide the ugliness.
• A range of atomic FIFOs, and a handy variable size object FIFO for handling queues of heterogenous objects without locking.
• A lock-free dirty list for efficiently queueing up objects that need some attention.

Scripting and JSON

• A JSON parser that uses choc::value::Value objects.
• A Javascript interpreter (which is a header-only encapsulation of the duktape library).

Audio

• Some audio buffer classes for managing blocks of multi-channel sample data. These can flexibly handle both owned buffers and non-owned views in either packed/interleaved or separate-channel formats.
• Utility classes for handling MIDI messages, MIDI sequences and MIDI files.
• An AudioFileFormat system for reading/writing audio files, with support for WAV, FLAC, Ogg-Vorbis, and read-only support for MP3. Hopefully more formats will get added in due course.
• Some basic audio utilities like simple oscillators.
• A sinc interpolator
• A MIDI/audio block sync mechanism.
• Functions for packing/unpacking integer sample data to floats.

---

Hopefully some of you will find some of these things useful! If you like it, please tell your friends! If you think you're up to contributing, that's great, but be aware that anything other than an utterly immaculate pull request will be given short shrift :)

-- Jules

Footnotes

1. ...or maybe "Clean Header-Only Classes" ...or "Cuddly Header-Only Classes"... It's just a backronym, so feel free to pick whatever C-word feels right to you. I may change the word occasionally on a whim, just to cause annoying diffs in the codebase. ↩