format_to_n

format_to_n (출력 크기를 제한하는 서식화 함수)

std::format_to_n은 서식 문자열 fmt에 따라 인자들을 서식화하고, 그 결과를 출력 반복자 out에 최대 n개의 문자만 기록하는 함수예요. C++20에서 도입된 <format> 라이브러리의 일부로, 출력 버퍼의 크기를 제한하면서도 전체(잘리지 않은) 출력 크기를 함께 알 수 있어요. std::format이 새 문자열을 통째로 만드는 것과 달리, 이 함수는 사용자가 지정한 버퍼에 직접 쓰므로 메모리 제어가 중요한 상황에서 유용해요.

출처: cppreference

본문

개요

<format> 헤더에 정의되어 있어요.

서식 문자열 fmt에 따라 인자를 서식화하고, 결과를 출력 반복자 out에 써요. 최대 n개의 문자만 기록되며, loc이 제공되면 로케일별 서식화에 사용돼요.

CharT는 오버로드 (1,3)에서 char, 오버로드 (2,4)에서 wchar_t예요.

이 오버로드들은 OutputIt이 std::output_iterator<const CharT&> 개념을 만족할 때만 오버로드 해석에 참여해요.

OutputIt이 std::output_iterator<const CharT&> 개념을 모델링하지 않거나, Args의 어떤 Ti에 대해서도 std::formatter<std::remove_cvref_t<Ti>, CharT>가 BasicFormatter 요구 사항을 충족하지 않으면 동작이 정의되지 않아요.

매개변수

반환값

out 멤버가 출력 범위의 끝을 가리키는 반복자이고, size 멤버가 전체(잘리지 않은) 출력 크기인 format_to_n_result를 반환해요.

예외

formatter 또는 반복자 연산이 던지는 모든 예외를 전파해요.

참고

GCC-13.3 이전의 libstdc++ 구현에는 올바른 format_to_n_result::out 값을 보고하지 않는 버그가 있었어요.

예제

Godbolt's Compiler Explorer에서: clang (trunk) + libc++, GCC (trunk) + libstdc++.

#include <format>
#include <initializer_list>
#include <iomanip>
#include <iostream>
#include <string_view>

int main()
{
    char buffer[64];

    for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz, 21uz})
    {
        const std::format_to_n_result result =
            std::format_to_n(
                buffer, max_chars_to_write,
                "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", // 24 bytes w/o formatters
                71,       // {0}, occupies 2 bytes
                8,        // {1}, occupies 1 byte
                "\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO)
                "\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO)
                "\u00B1"  // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN)
                ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0'

        *result.out = '\0'; // adds terminator to buffer

        const std::string_view str(buffer, result.out);

        std::cout << "Buffer until '\\0': " << std::quoted(str) << '\n'
                  << "Max chars to write: " << max_chars_to_write << '\n'
                  << "result.out offset: " << result.out - buffer << '\n'
                  << "Untruncated output size: " << result.size << "\n\n";
    }
}

출력:

Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc."
Max chars to write: 63
result.out offset: 35
Untruncated output size: 35

Buffer until '\0': "Hubble's H₀ ≅ 71±8"
Max chars to write: 23
result.out offset: 23
Untruncated output size: 35

Buffer until '\0': "Hubble's H₀ ≅ 71�"
Max chars to write: 21
result.out offset: 21
Untruncated output size: 35

결함 보고

다음 동작 변경 결함 보고서는 이전에 발표된 C++ 표준에 소급 적용되었어요.

같이 보기

더 알아보기 (Learn more)

cppreference