Namespaces
Variants

std:: format_to_n, std:: format_to_n_result

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
format_to_n
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20) (C++20) (C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
(C++20)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20) (C++20) (C++20)
(C++20) (C++20) (C++20)
(C++23)
(C++23)
Formatting arguments
(C++20)
(C++20)
(C++20) (C++20) (C++20)
(C++20) (deprecated in C++26)
(C++20) (C++20)
Format error
(C++20)
헤더에 정의됨 <format>
template < class OutputIt, class ... Args >

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,

std:: format_string < Args... > fmt, Args && ... args ) ;
(1) (C++20부터)
template < class OutputIt, class ... Args >

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,

std:: wformat_string < Args... > fmt, Args && ... args ) ;
(2) (C++20부터)
template < class OutputIt, class ... Args >

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,
const std:: locale & loc,

std:: format_string < Args... > fmt, Args && ... args ) ;
(3) (C++20부터)
template < class OutputIt, class ... Args >

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,
const std:: locale & loc,

std:: wformat_string < Args... > fmt, Args && ... args ) ;
(4) (C++20부터)
헬퍼 타입
template < class OutputIt >

struct format_to_n_result {
OutputIt out ;
std:: iter_difference_t < OutputIt > size ;

} ;
(5) (C++20부터)

형식 문자열 fmt 에 따라 args 를 포맷하고, 결과를 출력 반복자 out 에 기록합니다. 최대 n 개의 문자만 기록됩니다. 만약 존재한다면, loc 은 로케일별 포맷팅에 사용됩니다.

CharT 가 char 인 경우 (1,3) 번 오버로드, wchar_t 인 경우 (2,4) 번 오버로드에 해당합니다.

이러한 오버로드는 OutputIt 가 다음 개념을 만족하는 경우에만 오버로드 해결에 참여합니다: std:: output_iterator < const CharT & > .

OutputIt 가 std:: output_iterator < const CharT & > 개념을 모델링하지 않거나(의미적 요구사항을 충족하지 않거나), Args 내의 어떤 Ti 에 대해서도 std:: formatter < std:: remove_cvref_t < Ti > , CharT > 가 BasicFormatter 요구사항을 충족하지 않는 경우 동작은 정의되지 않습니다.

5) std::format_to_n_result 는 out , size 그리고 암시적으로 선언된 특별 멤버 함수들 외에는 기본 클래스나 다른 멤버를 가지고 있지 않습니다.

목차

매개변수

out - 출력 버퍼에 대한 iterator
n - 버퍼에 기록될 최대 문자 수
fmt -
포맷 문자열을 나타내는 객체. 포맷 문자열은 다음으로 구성됩니다:
  • { 과 } 를 제외한 일반 문자들은 출력에 변경 없이 복사됩니다,
  • 이스케이프 시퀀스 { { 와 } } 는 출력에서 각각 { 와 } 로 대체됩니다, 그리고
  • 치환 필드들.

각 치환 필드는 다음 형식을 가집니다:

{ arg-id (optional) } (1)
{ arg-id (optional) : format-spec } (2)
1) 포맷 명세가 없는 치환 필드
2) 포맷 명세가 있는 치환 필드
arg-id - 포맷팅에 사용될 인수의 인덱스를 지정합니다; 생략된 경우 인수들은 순서대로 사용됩니다.

포맷 문자열 내의 arg-id 들은 모두 명시되거나 모두 생략되어야 합니다. 수동 인덱싱과 자동 인덱싱을 혼합하는 것은 오류입니다.

format-spec - 해당 인수에 대한 std::formatter 특수화에 의해 정의된 포맷 명세. } 로 시작할 수 없습니다.

(C++23부터)
(C++26부터)
  • 다른 포맷 가능 타입들의 경우, 포맷 명세는 사용자 정의 formatter 특수화에 의해 결정됩니다.
args... - 포맷팅될 인수들
loc - std::locale 로케일별 포맷팅에 사용되는 로케일

반환값

format_to_n_result 객체는 out 멤버가 출력 범위의 끝을 지난 반복자이고, size 멤버는 전체(잘리지 않은) 출력 크기인 결과입니다.

예외

포매터나 반복자 연산에서 발생하는 모든 예외를 전파합니다.

참고 사항

GCC-13.3 이전의 libstdc++ 구현체에는 올바른 버그 를 보고하는 데 format_to_n_result :: out 값에 문제가 있었습니다.

예제

Godbolt의 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++ 표준에 소급 적용되었습니다.

DR 적용 대상 게시된 동작 올바른 동작
P2216R3 C++20 잘못된 형식 문자열에 대해 std::format_error 를 발생시킴 잘못된 형식 문자열은 컴파일 타임 오류를 발생시킴
P2418R2 C++20 const-usable도 복사 가능하지도 않은 객체
(예: 생성기형 객체)는 포맷팅 불가능 		이러한 객체의 포맷팅 허용
P2508R1 C++20 이 기능에 대한 사용자 가시적 이름이 없음 basic_format_string 이름이 노출됨

참고 항목

(C++20)
인수들의 형식화된 표현을 새 문자열에 저장합니다
(function template)
(C++20)
출력 반복자를 통해 인수들의 형식화된 표현을 출력합니다
(function template)
(C++20)
인수들의 형식화된 표현을 저장하는 데 필요한 문자 수를 결정합니다
(function template)