Frozen Library for C++: Complete Guide to Compile-Time Containers

The frozen library is a header-only C++17+ library that provides containers (map, set, string) fully initialized at compile time. It lets you create immutable data structures that require no dynamic memory allocation at runtime. This is an ideal solution for embedded systems, game engines, high-load servers, and any code where performance and predictable execution time are critical.

The core idea behind frozen is that you define a container as constexpr or constinit, and all sorting, hashing, and data structure construction happens during compilation. At runtime, you get a ready-made, optimized container that operates with minimal overhead. For example, frozen::map uses binary search on a sorted array, while frozen::unordered_map uses perfect hashing, guaranteeing O(1) access with zero collisions.

For C++ developers, this means: no dynamic memory (no new/delete), no exceptions (noexcept), full thread safety (read-only data), and the ability to place containers in microcontroller flash memory. The library is actively used in Facebook (now Meta) projects, compilers, and operating system kernels.

Installation

The frozen library is header-only, so installation boils down to copying the header files into your project. The easiest way is to use Conan or CMake FetchContent. Below are exact commands for various package managers.

Install via Conan (recommended)

conan install frozen/1.1.1@ -r conancenter
# Then add to CMakeLists.txt:
# find_package(frozen REQUIRED)
# target_link_libraries(your_target frozen::frozen)

Install via vcpkg

vcpkg install frozen
# After installation, use:
# find_package(frozen CONFIG REQUIRED)
# target_link_libraries(your_target frozen::frozen)

Install via CMake FetchContent (no package manager)

include(FetchContent)
FetchContent_Declare(
  frozen
  GIT_REPOSITORY https://github.com/serge-sans-paille/frozen.git
  GIT_TAG v1.1.1
)
FetchContent_MakeAvailable(frozen)
target_link_libraries(your_target frozen::frozen)

Manual installation (header-only)

git clone https://github.com/serge-sans-paille/frozen.git
# Copy the frozen/include/frozen folder into your project
# Add the include path to your compiler:
# g++ -I/path/to/frozen/include your_file.cpp -std=c++17

Quick Start: Minimal Working Example

Create a file example.cpp with the following content:

#include <iostream>
#include <frozen/unordered_map.h>
#include <frozen/string.h>

int main() {
    // Create a compile-time map with perfect hashing
    constexpr frozen::unordered_map<frozen::string, int, 3> fruit_calories = {
        {"apple", 95},
        {"banana", 105},
        {"orange", 62}
    };

    // Runtime lookup — O(1), zero collisions
    std::cout << "Calories in a banana: " << fruit_calories.at("banana") << "\n";

    // Check if a key exists
    if (auto it = fruit_calories.find("grape"); it != fruit_calories.end()) {
        std::cout << "Grape found: " << it->second << "\n";
    } else {
        std::cout << "Grape not found\n";
    }

    // Iterate over all elements
    for (auto& [fruit, calories] : fruit_calories) {
        std::cout << fruit.data() <<