std::wprint / std::wprintln

Introduction

This proposal extends the interface of the standard printing utilities by introducing wide-string versions of std::print and std::println.

The addition allows seamless integration with systems that use wide-characters and supports codebases where wide-character-strings are the preferred representation.

Revision History

• R0: Initial proposal.

Motivation and Scope

C++23 introduced std::print and std::println function templates, which provide efficient formatted text output. These functions are currently limited to narrow string formats.

Wide-strings are widely used throughout many codebases, particularly on Windows and in specialised environments that employ non-UTF-8 encodings. The lack of direct wide-string support in the formatted printing utilities provides confusion and leads to inconsistencies across APIs.

This proposal aims to narrow the gap by providing overloads for the std::print and std::println that accept std::wformat_args, ensuring that developers can use the formatted output facilities with wide-strings.

Impact on the Standard

New Functionality

This proposal introduces additional function template overloads, no existing functionality is removed or changed, the impact is additive only.

Wording

Change the __cpp_lib_print entry's value in section "Header synopsis [version.syn]" to represent the current standard revision:

#define __cpp_lib_print placeholder  // also in <print> and <ostream> 

Add the following definitions to [print.fun]

wstring out = vformat(os.getloc(), fmt, args);

template<class... Args>
          void print(wformat_string<Args...> fmt, Args&&... args);
          

print(stdout, fmt, std::forward<Args>(args)...);

template<class... Args>
          void print(FILE* stream, wformat_string<Args...> fmt, Args&&... args);
          

vprint_unicode(stream, fmt.str, make_wformat_args(std::forward<Args>(args)...));

vprint_nonunicode(stream, fmt.str, make_wformat_args(std::forward<Args>(args)...));

template<class... Args>
          void println(wformat_string<Args...> fmt, Args&&... args);
          

println(stdout, fmt, std::forward<Args>(args)...);

template<class... Args>
          void println(FILE* stream, wformat_string<Args...> fmt, Args&&... args);
          

print(stream, L"{}\n", format(fmt, std::forward<Args>(args)...));

void vprint_unicode(wstring_view fmt, format_args args);
          

vprint_unicode(stdout, fmt, args);

Technical Specification

namespace std
{
     template <typename... Args>
     void print(wformat_string<Args...> fmt, Args&&... args);

     template <typename... Args>
     void print(FILE* stream, wformat_string<Args...> fmt, Args&&... args);

     template <typename... Args>
     void println(wformat_string<Args...> fmt, Args&&... args);

     template <typename... Args>
     void println(FILE* stream, wformat_string<Args...> fmt, Args&&... args);

     void vprint_unicode(wostream& os, wstring_view fmt, wformat_args args);
     void vprint_nonunicode(wostream& os, wstring_view fmt, wformat_args args);

}

These overloads provide wide-string support for std::print and std::println functions.

Implementation Experience

No production implementations are yet available.

Work is in progress to add these overloads to MSVC, ECPPS and Clang.

Design Decisions

An alternative design to additional overloads would introduce distinct functions named wprint and wprintln, aligning with the C naming style (printf / wprintf) and the cout/wcout precedent.

There could also exist overloads for other strings (std::basic_format_string <charN_t>), but this proposal does not cover those. Maybe in a future revision or a separate paper.

This paper rejects that approach for the following reasons:

1. std::print and std::format are designed to be consistent; overloads better match this design than distinct function names.
2. Introducing new overload sets would further unnecessarily increase the complexity and ambiguity.

Support for additional character types (char8_t, char16_t, char32_t) is conceivable but outside the scope of this paper.

References

• N5008: Programming Languages - C++
• P2093: Formatted output

Appendix A. Examples

WinAPI

int main(void)
{
     std::wstring locale{};
     locale.resize(LOCALE_NAME_MAX_LENGTH);
     locale.resize(GetUserDefaultLocaleName(locale.data(), locale.size()) - 1);     

     std::println(L"The System Locale is {}", locale);
}

Expected output:

The System Locale is en-GB

Unicode characters in paths

void PrintPath(std::filesystem::path path)
{
     std::println(L"Path = {}", path);
}
     

Displaying emojis

void PrintPath(std::filesystem::path path)
{
    std::println(L"Path = {}", path.wstring());
}

int main(void)
{
    using std::operator""s;
    SetConsoleOutputCP(CP_UTF8);
    std::wstring locale{};
    locale.resize(LOCALE_NAME_MAX_LENGTH);
    locale.resize(GetUserDefaultLocaleName(locale.data(), static_cast<DWORD>(locale.size())) - 1);

    std::println(L"The System Locale is {}", locale);
    std::println(L"Pair: 🍋\x200D🟩");
    static_assert(sizeof(L"🍋\x200D🟩") == 12);
    PrintPath(std::filesystem::current_path());
}
     

Expected output:

The System Locale is en-GB
Pair: 🍋‍🟩
Path = F:\source\P3673\P3673