# How {fmt} Supports Wide Character Formatting (wchar_t) > Discover how fmtlib's header unlocks seamless wide character formatting with wchar_t, mirroring the library's powerful narrow-character API for efficient text manipulation. - Repository: [Hello World Foundation/fmt](https://github.com/fmtlib/fmt) - Tags: deep-dive - Published: 2026-09-08 --- **{fmt} provides comprehensive wide character formatting support through the `` header, exposing a complete API of type aliases and functions specialized for `wchar_t` that parallel the library's narrow-character interface.** The {fmt} library (fmtlib/fmt) treats wide character formatting as a first-class feature rather than an extension. By templating its core formatting machinery on character types, the library delivers type-safe `wchar_t` support through explicit wide-character APIs defined in [`include/fmt/xchar.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/xchar.h). This architecture ensures that Unicode and localization-heavy applications can leverage the same compile-time format string checking and high-performance runtime capabilities available to standard `char` strings. ## Wide Character Type Aliases in xchar.h The foundation of {fmt}'s wide character support rests on a family of type aliases that map standard narrow types to their `wchar_t` equivalents. In [`include/fmt/xchar.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/xchar.h), the library defines these specialized types using `basic_*` template instantiations: - **wstring_view**: `basic_string_view` for wide string views without allocation - **wformat_parse_context**: `parse_context` for parsing wide format strings at compile time - **wformat_context**: `buffered_context` for managing wide formatting operations - **wformat_args**: `basic_format_args` for type-erased wide argument storage - **wmemory_buffer**: `basic_memory_buffer` for efficient wide character buffering - **wformat_string**: A template alias providing compile-time format string validation for wide characters These definitions allow the library to reuse generic algorithms while maintaining strict type separation between narrow and wide character processing. ## Core Wide Character Formatting Functions The primary interface for wide character formatting mirrors the narrow API, returning `std::wstring` and accepting wide string literals. ### Basic Formatting with format() The `format()` function overload in [`include/fmt/xchar.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/xchar.h) accepts `wformat_string` and variadic template arguments: ```cpp #include std::wstring msg = fmt::format(FMT_STRING(L"Hello, {}!"), L"world"); // Returns: L"Hello, world!" std::wstring positional = fmt::format(L"{1} + {0} = {2}", 2, 3, 5); // Returns: L"3 + 2 = 5" ``` ### Output Streams and File Operations Wide character output functions including `print()`, `println()`, and `vprint()` are implemented as overloads taking `wformat_string` and `wformat_args`. These write directly to wide streams such as `std::wcout`: ```cpp fmt::print(L"Formatted number: {:L}\n", 12345); // Equivalent to std::wcout << L"Formatted number: 12,345\n"; ``` ### Locale-Aware Wide Formatting {fmt} supports internationalization through overloads accepting `locale_ref`. These are enabled via template constraints `FMT_ENABLE_IF(detail::is_exotic_char::value)` in [`include/fmt/xchar.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/xchar.h), allowing thousands separators and localized numeric representations: ```cpp std::locale loc("en_US.UTF-8"); std::wstring num = fmt::format(loc, L"{:L}", 1234567); // Returns: L"1,234,567" ``` ## Printf-Style Wide Character Support For legacy compatibility with `printf` syntax, [`include/fmt/printf.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/printf.h) provides `wprintf_context` and `vsprintf`-style overloads specialized for `wchar_t`. These implementations maintain {fmt}'s type safety guarantees while supporting traditional format strings in wide character contexts. ## Implementation Architecture ### Template Specialization Strategy According to the fmtlib/fmt source code, every core component templates on a `Char` type parameter. The narrow-character path (`char`) serves as the default instantiation in [`include/fmt/format.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/format.h), while the wide-character path activates when `Char` is `wchar_t`. The `basic_format_string` templates generate compile-time format-string validation for both character sets, with `detail::vformat_to` (implemented in `src/format.cc`) reused across both code paths via appropriate template specializations. ### Safety Mechanisms The library prevents accidental character type mixing through explicit static assertions. In [`include/fmt/xchar.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/xchar.h), the generic `vformat_to` overload contains `static_assert(!std::is_same::value, "");` to ensure wide-character functions remain accessible only through the explicit `wformat_*` API surface, avoiding silent conversions that could corrupt multi-byte character data. ### System-Level Utilities The [`include/fmt/os.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/os.h) header provides `wcstring_view` (defined as `basic_cstring_view`) for operating system interfaces that require wide character C-strings, completing the ecosystem for system programming with `wchar_t`. ## Practical Usage Examples ```cpp #include #include int main() { // Named arguments with wide strings std::wstring greeting = fmt::format( L"{greeting}, {name}!", fmt::arg(L"greeting", L"Hello"), fmt::arg(L"name", L"世界") ); // Memory buffer usage fmt::wmemory_buffer buf; fmt::format_to(std::back_inserter(buf), L"Value: {}", 42); // Output to wide stream fmt::print(L"Buffer contents: {}\n", std::wstring_view(buf.data(), buf.size())); } ``` ## Summary - {fmt} implements wide character formatting through the dedicated `` header, providing a parallel API to the narrow-character interface - Complete type aliases (`wstring_view`, `wformat_context`, `wformat_args`, etc.) map narrow types to their `wchar_t` equivalents using template specialization - Primary functions including `format()`, `print()`, and locale-aware overloads operate on `std::wstring` and `wformat_string` with identical syntax to narrow strings - The underlying implementation in `src/format.cc` reuses `detail::vformat_to` across both character types, ensuring consistent performance characteristics - Compile-time format string validation applies equally to wide strings through the `basic_format_string` mechanism ## Frequently Asked Questions ### Do I need to include both fmt/format.h and fmt/xchar.h for wide characters? No. For wide character formatting, you only need to include ``. This header provides all necessary wide-character definitions and automatically includes the required core formatting machinery from [`include/fmt/format.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/format.h) through internal dependencies. Including both headers explicitly is harmless but redundant for `wchar_t` operations. ### Does wide character formatting support all the same format specifiers as narrow strings? Yes. The format specification syntax is identical between `char` and `wchar_t` strings. Both support positional arguments (`{0}`, `{1}`), named arguments, locale-specific formatting (`:L`), and all alignment (`<`, `>`, `^`), padding, and precision options. The `wformat_string` type enforces the same compile-time validation as `format_string` for narrow characters. ### Can I mix narrow format strings with wide character arguments? No. {fmt} enforces strict type safety through template constraints that prevent mixing character types. A format string and all its arguments must use consistent character types—either all `char` (narrow) or all `wchar_t` (wide). The library uses `detail::is_exotic_char` type traits to specialize behavior but does not allow implicit conversion between character sets during formatting operations. ### Is there a performance penalty for using wchar_t instead of char? According to the implementation in [`include/fmt/xchar.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/xchar.h) and `src/format.cc`, both code paths utilize the same underlying `detail::vformat_to` algorithmic implementation. The primary difference lies in buffer character size (typically 2 or 4 bytes for `wchar_t` versus 1 byte for `char`) and associated memory allocation patterns. The parsing, argument handling, and output logic are instantiated from identical templates, ensuring equivalent computational complexity for both character types.