Implementation:Duckdb Duckdb Fmt Library

Knowledge Sources	Duckdb_Duckdb fmt
Domains	String_Formatting, Third_Party
Last Updated	2026-02-07 12:00 GMT

Overview

The fmt library (v6.1.2) is a fast, safe, and extensible C++ formatting library used by DuckDB for string formatting operations under the duckdb_fmt namespace.

Description

DuckDB vendors the {fmt} library by Victor Zverovich as a high-performance replacement for printf and C++ IOStreams. The library is compiled under the duckdb_fmt namespace (via FMT_BEGIN_NAMESPACE) to avoid symbol conflicts with system-installed versions. It provides Python-style format strings with {} placeholders, positional arguments, type-safe formatting, and custom formatter extensions. The vendored copy is split across four key headers:

• core.h -- Core API including format(), format_to(), and the format argument machinery
• format.h -- Extended formatting utilities including to_string(), format_to_n(), formatted_size(), and the full arg_formatter implementation
• format-inl.h -- Implementation details such as safe_strerror, decimal/integer formatting internals, and locale-aware helpers
• printf.h -- Legacy printf-style formatting with sprintf(), fprintf(), and printf() that support DuckDB's hugeint_t and uhugeint_t types

DuckDB's copy integrates with DuckDB-specific types by including duckdb/common/hugeint.hpp and duckdb/common/uhugeint.hpp directly in the fmt headers, and uses duckdb::InvalidInputException for error reporting in printf precision handling.

Usage

DuckDB uses the fmt library pervasively for constructing error messages, formatting query results to strings, rendering diagnostic output, and building SQL expressions programmatically. The duckdb_fmt::format() function is the primary entry point, while duckdb_fmt::sprintf() and duckdb_fmt::printf() serve code paths that use C-style format specifiers.

Code Reference

Source Location

• Repository: Duckdb_Duckdb
• Files:
  • third_party/fmt/include/fmt/core.h
  • third_party/fmt/include/fmt/format.h
  • third_party/fmt/include/fmt/format-inl.h
  • third_party/fmt/include/fmt/printf.h

Signature

namespace duckdb_fmt {

// --- core.h: Primary formatting API ---

// Format a string with positional arguments using {}-style placeholders
template <typename S, typename... Args, typename Char = char_t<S>>
inline std::basic_string<Char> format(const S& format_str, Args&&... args);

// Format into an output iterator
template <typename Container, typename S, typename... Args>
inline std::back_insert_iterator<Container> format_to(
    std::back_insert_iterator<Container> out,
    const S& format_str,
    Args&&... args);

// Low-level format with pre-built args
template <typename S, typename Char = char_t<S>>
inline std::basic_string<Char> vformat(
    const S& format_str,
    basic_format_args<buffer_context<Char>> args);

// --- format.h: Extended utilities ---

// Convert a value to string using its default format
template <typename T>
inline std::string to_string(const T& value);

// Format into a buffer with size limit; returns {out, size}
template <typename OutputIt, typename S, typename... Args>
inline format_to_n_result<OutputIt> format_to_n(
    OutputIt out, std::size_t n,
    const S& format_str, const Args&... args);

// Compute formatted size without writing
template <typename... Args>
inline std::size_t formatted_size(string_view format_str, const Args&... args);

// --- printf.h: C-style printf formatting ---

// sprintf-style: returns formatted string
template <typename S, typename... Args>
inline std::basic_string<char_t<S>> sprintf(const S& format, const Args&... args);

// fprintf-style: writes to FILE*, returns char count
template <typename S, typename... Args>
inline int fprintf(std::FILE* f, const S& format, const Args&... args);

// printf-style: writes to stdout, returns char count
template <typename S, typename... Args>
inline int printf(const S& format_str, const Args&... args);

// fprintf-style: writes to ostream
template <typename Char, typename S, typename... Args>
inline int fprintf(std::basic_ostream<Char>& os, const S& format_str, const Args&... args);

} // namespace duckdb_fmt

Import

#include "fmt/core.h"       // format(), format_to()
#include "fmt/format.h"     // to_string(), format_to_n(), formatted_size()
#include "fmt/format-inl.h" // implementation internals
#include "fmt/printf.h"     // sprintf(), fprintf(), printf()

I/O Contract

Inputs

Name	Type	Required	Description
format_str	const S& (string-like)	Yes	A format string containing literal text and {}-style replacement fields (or %-style for printf functions)
args	Args&&...	No	Variadic arguments to substitute into the format string placeholders
out	OutputIt	No	Output iterator where formatted output is written (for format_to / format_to_n)
n	std::size_t	No	Maximum number of characters to write (for format_to_n)
f	std::FILE*	No	File pointer for fprintf
os	std::basic_ostream<Char>&	No	Output stream for the ostream overload of fprintf

Outputs

Name	Type	Description
formatted string	std::string	Returned by format(), sprintf(), and to_string()
output iterator	OutputIt	Returned by format_to(), pointing past the last written character
format_to_n_result	{OutputIt out, std::size_t size}	Returned by format_to_n(); out is the iterator past the output, size is the total (untruncated) output size
characters written	int	Returned by printf() and fprintf()
formatted size	std::size_t	Returned by formatted_size(); the number of characters the output would occupy

Usage Examples

#include "fmt/core.h"
#include "fmt/format.h"
#include "fmt/printf.h"

// Basic format with positional placeholders
std::string msg = duckdb_fmt::format("Hello, {}! You have {} items.", "Alice", 42);
// "Hello, Alice! You have 42 items."

// Numbered arguments and format specifiers
std::string pi = duckdb_fmt::format("{0:.4f}", 3.14159265);
// "3.1416"

// Convert value to string
std::string num = duckdb_fmt::to_string(12345);
// "12345"

// printf-style formatting
std::string legacy = duckdb_fmt::sprintf("%-20s %05d", "record", 7);
// "record               00007"

// Format to an output iterator
std::vector<char> buf;
duckdb_fmt::format_to(std::back_inserter(buf), "x={}, y={}", 10, 20);

// Write directly to a file
duckdb_fmt::fprintf(stderr, "Error code: %d\n", 404);

Related Pages

• Principle:Duckdb_Duckdb_String_Formatting