libdeck39 is a zero-allocation C99 library that encodes a standard deck of playing cards into a compressed 39-byte binary format. The premise is a simple observation carried to its conclusion: a card carries only two pieces of information, a suit in the range 0–3 and a rank in the range 1–13, which together need six bits rather than the byte a naive representation would spend. Four cards therefore pack into exactly three bytes, and a full 52-card deck into 39 — the number the library is named for. An optional 54-card joker mode packs into 41 bytes, with the all-zero six-bit pattern reserved as the joker sentinel.
The API is deliberately small and predictable. A stack-based deck structure supports initialisation, an unbiased Fisher–Yates shuffle, constant-time draw, peek, remaining-count, empty-check and reset operations, human-readable card formatting, and the encode/decode pair that moves between the card array and the packed byte stream. Nothing in the library allocates: every structure fits on the stack, the caller owns all buffers, and encode and decode are single sequential bitwise passes in O(N) time and O(1) space. Every symbol is namespaced behind a deck39_ prefix so the library drops into a larger codebase without collisions.
The project is built as a proper deliverable rather than a single source file. A Makefile produces both a static archive and a shared object, an assertion-based test suite covers the round-trip and edge-case behaviour, a worked example demonstrates integration, and separate documents record the encoding theory and design rationale, the algorithm and complexity analysis, and the build and integration guide. The result is a compact study in low-level representation: bit packing, sentinel design, complexity discipline and clean library packaging applied to a domain small enough that the engineering, not the problem, is the point.