O(1) membership engine for 8-digit numbers. C99, 12.5 MB, no dependencies.

c99, bitset, embedded, membership, lookup, zero-dependencies, file-format, mit, performance, data-structure, uint32, binary-format

• Home
• Getting Started
• File Format
• API Reference
• Performance
• FAQ
• Troubleshooting

num8 tracks whether 8-digit numbers (00000000-99999999) exist in a set. It stores only membership state, nothing else, and each number occupies exactly one bit in a fixed 12.5 MB payload.

Measured on Release build (MSVC, Windows, num8_bench.exe, 2026-03-18):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

#include "num8.h"

num8_engine_t engine;
num8_create("employees.num8", &engine);

num8_add_u32(&engine, 12345678);

int exists = 0;
num8_exists_u32(&engine, 12345678, &exists);
/* exists == 1 */

num8_remove_u32(&engine, 12345678);
num8_flush(&engine);
num8_close(&engine);

NUM8 file layout is fixed:

• header: 64 bytes
• payload: 12,500,000 bytes
• total: 12,500,064 bytes

All numeric fields are little-endian.

Validation rules:

• set_count <= 100000000
• payload_crc32 == 0 means payload CRC is disabled

For numeric value n (0..99999999):

• byte_index = n >> 3
• bit_index = n & 7
• mask = (uint8_t)(1u << bit_index)

Presence:

• exists if (payload[byte_index] & mask) != 0
• missing if (payload[byte_index] & mask) == 0

Example for 12345678:

• byte_index = 1543209
• bit_index = 6
• mask = 0x40

• Domain is fixed to exactly 00000000..99999999
• Numeric API accepts only value <= 99999999
• String API accepts only exact 8-digit strings ("00000000".."99999999")

num8_status_t num8_create(const char* path, num8_engine_t* engine);
num8_status_t num8_open(const char* path, num8_open_mode_t mode, num8_engine_t* engine);
num8_status_t num8_close(num8_engine_t* engine);

num8_status_t num8_exists_u32(const num8_engine_t* engine, uint32_t value, int* out_exists);
num8_status_t num8_add_u32(num8_engine_t* engine, uint32_t value);
num8_status_t num8_remove_u32(num8_engine_t* engine, uint32_t value);

num8_status_t num8_exists_str(const num8_engine_t* engine, const char* number8, int* out_exists);
num8_status_t num8_add_str(num8_engine_t* engine, const char* number8);
num8_status_t num8_remove_str(num8_engine_t* engine, const char* number8);

num8_status_t num8_count(const num8_engine_t* engine, uint64_t* out_count);
num8_status_t num8_clear_all(num8_engine_t* engine);
num8_status_t num8_flush(num8_engine_t* engine);
num8_status_t num8_validate(const num8_engine_t* engine);

Shared build exports the same public API from num8.h:

• Windows: num8.dll + import library num8.lib
• Linux: libnum8.so
• macOS: libnum8.dylib

Build outputs (default CMake layout):

• library/runtime artifacts in build/Release/
• static library target: num8_static
• shared library target: num8_shared

Typical CMake consumer integration (installed layout):

• headers: include/num8.h
• libraries: lib/ (or bin/ for runtime)

• Engine uses one payload + one header commit point.
• num8_flush writes payload, updates header (set_count, generation, CRC), then syncs.
• Header CRC protects against partial/corrupted header writes.
• Recommended usage model: single-writer, multi-reader.
• Engine is not implicitly thread-safe; caller must synchronize.

• num8_builder - create .num8 from text file (one 8-digit number per line)
• num8_selftest - full self-test suite
• num8_minitest - quick smoke test
• num8_bench - performance benchmarks

• Employee / customer ID access control
• Large-scale membership checks (100M domain)
• Allowlist / blocklist management
• High-frequency ID deduplication

• Domain is fixed: 00000000-99999999 only
• File size is always 12.5 MB (by design)
• Not thread-safe (caller must synchronize)
• Single-writer model
• No compression, no variable records (by design)
• Stores presence/absence only (one bit per number)

#define NUM8_MAGIC               "NUM8"
#define NUM8_VERSION_MAJOR       1u
#define NUM8_VERSION_MINOR       0u
#define NUM8_HEADER_SIZE         64u
#define NUM8_DOMAIN_SIZE         100000000ull
#define NUM8_PAYLOAD_SIZE        12500000u
#define NUM8_MAX_VALUE           99999999u

MIT