# Dragonbox Implementation in fmtlib: Location and Source Structure

> Discover the location of the Dragonbox implementation in the fmtlib repository. Find the source code and understand its structure within the fmt::detail::dragonbox namespace.

- Repository: [Hello World Foundation/fmt](https://github.com/fmtlib/fmt)
- Tags: internals
- Published: 2026-09-09

---

**The Dragonbox floating-point formatting algorithm resides in [`include/fmt/format-inl.h`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/format-inl.h)

The complete Dragonbox algorithm lives in **[`include/fmt/format-inl.h`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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:

```cpp
#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:

```cpp
#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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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](https://github.com/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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.