std::to_chars

std::to_chars_result
    to_chars( char* first, char* last,
              /* integer-type */ value, int base = 10 );

std::to_chars_result
    to_chars( char*, char*, bool, int = 10 ) = delete;

std::to_chars_result
    to_chars( char* first, char* last, float value );
std::to_chars_result
    to_chars( char* first, char* last, double value );
std::to_chars_result
    to_chars( char* first, char* last, long double value );

std::to_chars_result
    to_chars( char* first, char* last, /* floating-point-type */ value );

std::to_chars_result
    to_chars( char* first, char* last, float value,
              std::chars_format fmt );
std::to_chars_result
    to_chars( char* first, char* last, double value,
              std::chars_format fmt );
std::to_chars_result
    to_chars( char* first, char* last, long double value,
              std::chars_format fmt );

std::to_chars_result
    to_chars( char* first, char* last, /* floating-point-type */ value,
              std::chars_format fmt );

std::to_chars_result
    to_chars( char* first, char* last, float value,
              std::chars_format fmt, int precision );
std::to_chars_result
    to_chars( char* first, char* last, double value,
              std::chars_format fmt, int precision );
std::to_chars_result
    to_chars( char* first, char* last, long double value,
              std::chars_format fmt, int precision );

std::to_chars_result
    to_chars( char* first, char* last, /* floating-point-type */ value,
              std::chars_format fmt, int precision );

Преобразует value в строку символов, последовательно заполняя диапазон [first, last), где [first, last) должен быть валидным диапазоном.

Параметры

Возвращаемое значение

При успешном выполнении возвращает значение типа std::to_chars_result, такое что ec равно инициализированному нулевым значением std::errc и ptr — указатель на символ, следующий за последним записанным символом. Обратите внимание, что строка не завершается нулём.

При ошибке возвращает значение типа std::to_chars_result, содержащее std::errc::value_too_large в ec, копию значения last в ptr, и оставляет содержимое диапазона [first, last) в неопределённом состоянии.

Исключения

Ничего не выбрасывает.

Примечания

В отличие от других функций форматирования в C++ и C библиотеках, std::to_chars не зависит от локали, не выделяет память и не выбрасывает исключения. Предоставлен лишь небольшой поднабор политик форматирования, используемых другими библиотеками (например, std::sprintf). Это предназначено для обеспечения максимально быстрой реализации, полезной в общих контекстах с высокой пропускной способностью, таких как обмен текстовыми данными (JSON или XML).

Гарантия того, что std::from_chars может точно восстановить каждое значение с плавающей запятой, отформатированное с помощью std::to_chars , предоставляется только если обе функции из одной реализации.

Необходимо явно преобразовать значение типа bool в другой целочисленный тип, если нужно отформатировать его как "0"/"1".

Пример

#include <array>
#include <charconv>
#include <iostream>
#include <string_view>
#include <system_error>
 
void show_to_chars(auto... format_args)
{
    std::array<char, 10> str;
 
#if __cpp_lib_to_chars >= 202306L
    // use C++26 operator bool() for error checking
    if (auto res = std::to_chars(str.data(), str.data() + str.size(), format_args...))
        std::cout << std::string_view(str.data(), res.ptr) << '\n';
    else
        std::cout << std::make_error_code(res.ec).message() << '\n';
#else
    if (auto [ptr, ec]
            = std::to_chars(str.data(), str.data() + str.size(), format_args...);
        ec == std::errc())
        std::cout << std::string_view(str.data(), ptr) << '\n';
    else
        std::cout << std::make_error_code(ec).message() << '\n';
#endif
}
 
int main()
{
    show_to_chars(42);
    show_to_chars(+3.14159F);
    show_to_chars(-3.14159, std::chars_format::fixed);
    show_to_chars(-3.14159, std::chars_format::scientific, 3);
    show_to_chars(3.1415926535, std::chars_format::fixed, 10);
}

42
3.14159
-3.14159
-3.142e+00
Value too large for defined data type

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были применены ретроактивно к ранее опубликованным стандартам C++.

См. также