Namespaces
Variants

std:: to_chars

From cppreference.net
C++
Text processing library
Определено в заголовочном файле <charconv>
std :: to_chars_result

to_chars ( char * first, char * last,

/* integer-type */ value, int base = 10 ) ;
(1) (начиная с C++17)
(constexpr начиная с C++23)
std :: to_chars_result
to_chars ( char * , char * , bool , int = 10 ) = delete ;
(2) (начиная с C++17)
std :: to_chars_result
to_chars ( char * first, char * last, /* floating-point-type */ value ) ;
(3) (начиная с C++17)
std :: to_chars_result

to_chars ( char * first, char * last, /* floating-point-type */ value,

std:: chars_format fmt ) ;
(4) (начиная с C++17)
std :: to_chars_result

to_chars ( char * first, char * last, /* floating-point-type */ value,

std:: chars_format fmt, int precision ) ;
(5) (начиная с C++17)

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

1) Форматтеры целых чисел: value преобразуется в строку цифр в указанной base (без избыточных ведущих нулей). Цифры в диапазоне 10..35 (включительно) представляются в виде символов нижнего регистра a..z . Если значение меньше нуля, представление начинается со знака минус. Библиотека предоставляет перегрузки для всех cv-неквалифицированных знаковых и беззнаковых целочисленных типов, а также для типа char в качестве типа параметра value .
2) Перегрузка для bool удалена. std::to_chars отклоняет аргумент типа bool , потому что результатом были бы "0" / "1" , а не "false" / "true" , если бы это было разрешено.
3) value преобразуется в строку в стиле std::printf в локали по умолчанию ("C"). Спецификатор преобразования — f или e (с выбором в пользу f в случае равенства), выбираемый согласно требованию кратчайшего представления: строковое представление состоит из минимального количества символов, при котором перед точкой (если присутствует) есть хотя бы одна цифра, и разбор представления с помощью соответствующей функции std::from_chars точно восстанавливает значение. Если существует несколько таких представлений, выбирается представление с наименьшей разницей относительно value , а оставшиеся ничьи разрешаются округлением согласно std::round_to_nearest . Библиотека предоставляет перегрузки для всех cv-неквалифицированных стандартных (до C++23) типов с плавающей точкой в качестве типа параметра value .
4) То же, что и (3) , но преобразование, указанное для as-if printf, равно f если fmt равен std::chars_format::fixed , e если fmt равен std::chars_format::scientific , a (но без ведущего "0x" в результате) если fmt равен std::chars_format::hex , и g если fmt равен chars_format::general . Библиотека предоставляет перегрузки для всех cv-неквалифицированных стандартных (до C++23) типов с плавающей запятой в качестве типа параметра value .
5) То же, что и (4) , за исключением того, что точность задаётся параметром precision , а не требованием кратчайшего представления. Библиотека предоставляет перегрузки для всех cv-неквалифицированных стандартных (до C++23) типов с плавающей запятой в качестве типа параметра value .

Содержание

Параметры

first, last - диапазон символов для записи
value - значение для преобразования в строковое представление
base - целочисленное основание для использования: значение от 2 до 36 (включительно).
fmt - формат чисел с плавающей точкой для использования, битовая маска типа std::chars_format
precision - точность чисел с плавающей точкой для использования

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

При успехе возвращает значение типа 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" с использованием std::to_chars , значение необходимо привести к другому целочисленному типу.

Макрос тестирования возможностей Значение Стандарт Функция
__cpp_lib_to_chars 201611L (C++17) Элементарные преобразования строк ( std::to_chars , std::from_chars )
202306L (C++26) Тестирование успеха или неудачи функций <charconv>
__cpp_lib_constexpr_charconv 202207L (C++23) Добавление модификаторов constexpr к перегрузкам std::to_chars и std::from_chars ( 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++.

DR Applied to Behavior as published Correct behavior
LWG 2955 C++17 this function was in <utility> and used std::error_code moved to <charconv> and uses std::errc
LWG 3266 C++17 bool argument was accepted and promoted to int rejected by a deleted overload
LWG 3373 C++17 std::to_chars_result might have additional members additional members are disallowed

Смотрите также

(C++17)
тип возвращаемого значения std::to_chars
(класс)
(C++17)
преобразует последовательность символов в целочисленное или значение с плавающей запятой
(функция)
(C++11)
преобразует целочисленное значение или значение с плавающей запятой в string
(функция)
(C++11)
выводит форматированный вывод в stdout , файловый поток или буфер
(функция)
вставляет форматированные данные
(публичная функция-член std::basic_ostream<CharT,Traits> )