Dragonbox Implementation in fmtlib: Location and Source Structure

The Dragonbox floating-point formatting algorithm resides in include/fmt/format-inl.h inside the fmt::detail::dragonbox namespace, with explicit instantiations for float and double located in src/format.cc.

The fmtlib library leverages the Dragonbox algorithm to convert IEEE 754 binary floating-point numbers to decimal strings with optimal precision and minimal overhead. Locating this implementation within the codebase is essential for debugging formatting edge cases, understanding performance characteristics, or extending the library's numeric conversion capabilities.

Core Implementation in format-inl.h

The complete Dragonbox algorithm lives in include/fmt/format-inl.h. The implementation resides within the namespace dragonbox block starting at approximately line 207, nested inside fmt::detail to indicate internal API status.

This header defines the primary template to_decimal<T>(T) at line 1275, which serves as the generic driver for the conversion process. This function extracts raw IEEE 754 bits, selects the correct interval case (IEEE 754 binary32 or binary64), and returns a decimal_fp<T> structure containing the decimal significand and exponent.

Explicit Instantiations in src/format.cc

While the template implementation remains in the header, concrete instantiations for standard floating-point types appear in src/format.cc to prevent code bloat:

• dragonbox::to_decimal(float) — instantiated at lines 19–20
• dragonbox::to_decimal(double) — instantiated at lines 21–22

These explicit instantiations provide the compiled entry points that the public fmt::format API invokes when processing floating-point format specifiers, ensuring the heavy template machinery compiles once in the library rather than in every translation unit.

Internal Arithmetic and Cache Helpers

Supporting the main conversion routine, format-inl.h contains specialized low-level utilities between lines 207–400:

• umul96_upper64 — Performs 96-bit multiplication and returns the upper 64 bits, critical for high-precision significand calculations
• floor_log10_pow2 — Computes $\lfloor \log_{10}(2^e) \rfloor$ efficiently using integer arithmetic for exponent scaling
• float_info<T> — Provides IEEE 754 type traits, including bit masks for exponent and significand extraction
• cache_accessor — Manages the compressed power-of-ten cache used during the fast path of decimal conversion

These helpers implement the bounded-complexity arithmetic that distinguishes Dragonbox from earlier Grisu2 or Grisu3 algorithms.

Code Examples

Standard Formatting Through fmt::format

When you invoke fmt::format with floating-point arguments, the library automatically routes through the Dragonbox implementation:

#include <fmt/format.h>
#include <iostream>

int main() {
    double value = 12345.6789;
    // Internally dispatches to dragonbox::to_decimal
    std::string result = fmt::format("{:.6f}", value);
    std::cout << result << '\n';  // Output: 12345.678900
}

Accessing Dragonbox Internals Directly

For debugging or advanced decimal decomposition, you can access the internal representation through the detail namespace, though this interface lacks API stability guarantees:

#include <fmt/format-inl.h>

int main() {
    // Direct conversion to decimal floating-point structure
    fmt::detail::dragonbox::decimal_fp<double> decimal = 
        fmt::detail::dragonbox::to_decimal(3.141592653589793);
    
    // decimal.significand holds the exact integer mantissa
    // decimal.exponent holds the power of ten offset
}

Summary

• The Dragonbox algorithm implementation is centralized in include/fmt/format-inl.h within the fmt::detail::dragonbox namespace starting at line 207
• Template instantiations for float and double reside in src/format.cc at lines 19–22, providing the compiled symbols used by the public API
• The main conversion entry point is the to_decimal<T> template defined at line 1275 of format-inl.h, returning a decimal_fp<T> structure
• Low-level arithmetic helpers including umul96_upper64 and cache_accessor occupy lines 207–400 of the same header
• The implementation derives from the reference jk-jeon/dragonbox reference implementation

Frequently Asked Questions

Where is the main Dragonbox namespace defined in fmtlib?

The dragonbox namespace is defined inside include/fmt/format-inh.h starting around line 207, nested within fmt::detail. This placement signals that the algorithm constitutes an implementation detail subject to change between releases, though it remains accessible for specialized debugging scenarios.

How does fmtlib instantiate Dragonbox for different floating-point types?

Explicit template instantiations appear in src/format.cc at lines 19–20 for float and lines 21–22 for double. These instantiate the generic to_decimal<T> template defined in format-inl.h, compiling the heavy conversion logic into the fmtlib binary rather than recompiling it in every translation unit that includes the header.

Can I use the Dragonbox implementation directly from fmtlib?

Yes, through fmt::detail::dragonbox::to_decimal(), but this is strongly discouraged for production code. Because these symbols reside in the detail namespace, their signatures and behavior may change without deprecation notices between fmtlib versions. Rely on the public fmt::format API for stable decimal conversion, reserving direct Dragonbox access for debugging numeric edge cases only.

What files should I examine to understand the Dragonbox cache logic?

Examine include/fmt/format-inl.h between lines 207–400, specifically the cache_accessor template and related arithmetic primitives like umul96_upper64. Additionally, review test/format-impl-test.cc, which contains unit tests exercising cache boundaries and verifying correct behavior for subnormal numbers and power-of-ten edge cases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}