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, /* floating-point-type */ value );

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, /* 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 <charconv>
#include <iomanip>
#include <iostream>
#include <string_view>
#include <system_error>

void show_to_chars(auto... format_args)
{
    const size_t buf_size = 10;
    char buf[buf_size]{};
    std::to_chars_result result = std::to_chars(buf, buf + buf_size, format_args...);

    if (result.ec != std::errc())
        std::cout << std::make_error_code(result.ec).message() << '\n';
    else
    {
        std::string_view str(buf, result.ptr - buf);
        std::cout << std::quoted(str) << '\n';
    }
}

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++.

См. также