std::to_chars

 

C++

Поддержка компилятором

Автономные и размещённые реализации

Язык

Стандартная библиотека

Заголовки стандартной библиотеки

Требования к именованию

Макросы тестирования функциональности (C++20)

Поддержка языка

Библиотека концептов (C++20)

Библиотека метапрограммирования (C++11)

Библиотека диагностики

Библиотека общих утилит

Библиотека строк

Библиотека контейнеров

Библиотека итераторов

Библиотека диапазонов (C++20)

Библиотека алгоритмов

Библиотека численных данных

Библиотека ввода/вывода

Библиотека локализаций

Регулярные выражения (C++11)

Атомарные операции (C++11)

Библиотека поддержки конкуренции (C++11)

Библиотека файловой системы (C++17)

Технические спецификации

Указатель символов

Внешние библиотеки

 

Библиотека утилит

Языковая поддержка Поддержка типов (базовые типы, RTTI) Макросы тестирования функциональности библиотеки (C++20)     Управление динамической памятью Программные утилиты Поддержка сопрограмм (C++20) Вариативные функции is_constant_evaluated (C++20) is_within_lifetime (C++26) initializer_list (C++11) source_location (C++20) Трёхстороннее сравнение (C++20) three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)     is_eqis_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

Общие утилиты Дата и время Функциональные объекты Библиотека форматирования (C++20) bitset hash (C++11) Операторы отношения (устарело в C++20) rel_ops::operator!=rel_ops::operator> rel_ops::operator<=rel_ops::operator>= Целочисленные функции сравнения cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)     cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Операции обмена и типа swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Общие лексические типы pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Элементарные преобразования строк to_chars (C++17) from_chars (C++17) chars_format (C++17) to_chars_result (C++17) from_chars_result (C++17)

 

<tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody>

Определено в заголовочном файле <charconv>
std::to_chars_result to_chars( char* first, char* last, /* целочисленный тип */ 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)
	(3)
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 );			(начиная с C++17) (до C++23)
std::to_chars_result to_chars( char* first, char* last, /* тип с плавающей запятой */ value );			(начиная с C++23)
		(4)
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 );				(начиная с C++17) (до C++23)
std::to_chars_result to_chars( char* first, char* last, /* тип с плавающей запятой */ value, std::chars_format fmt );				(начиная с C++23)
			(5)
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 );					(начиная с C++17) (до C++23)
std::to_chars_result to_chars( char* first, char* last, /* тип с плавающей запятой */ value, std::chars_format fmt, int precision );					(начиная с C++23)

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

1) Форматирование целых чисел: value преобразуется в строку цифр с заданной базой base (без избыточных ведущих нулей). Цифры в диапазоне 10..35 (включительно) представляются в виде строчных букв a..z. Если значение меньше нуля, представление начинается со знака минус. Библиотека предоставляет перегрузки для всех cv-неквалифицировыанных (начиная с C++23) целочисленных типов со знаком и без и для типа 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-неквалифицированных типов с плавающей запятой в качестве типа параметра value. (начиная с C++23)

4) То же, что и (3), но преобразование указывается как для 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-неквалифицированных типов с плавающей запятой в качестве типа параметра value. (начиная с C++23)

5) То же, что (4), за исключением того, что точность определяется параметром precision, а не требованием кратчайшего представления. Библиотека предоставляет перегрузки для всех cv-неквалифицированных типов с плавающей запятой в качестве типа параметра value. (начиная с C++23)

Параметры

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

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

В случае успеха возвращает значение типа std::to_chars_result, такое что ec инициализировано значением std::errc и ptr указывает на один символ за концом записанных символов. Обратите внимание, что строка не завершается NULL.

В случае ошибки возвращает значение типа 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".

Макрос тест функциональности	Значение	Стандарт	Комментарий
__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 в перегрузки (1) std::to_chars и std::from_chars для целочисленных типов.

Пример

Запустить этот код

#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
    // использование оператора C++26 bool() для проверки ошибок
    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++:

Номер	Применён	Поведение в стандарте	Корректное поведение
LWG 2955	C++17	эта функция была в <utility> и использовала std::error_code	перемещена в <charconv> и использует std::errc
LWG 3266	C++17	аргумент bool принимался и расширялся до int	отклоняется удалённой перегрузкой
LWG 3373	C++17	std::to_chars_result может иметь дополнительные элементы	дополнительные элементы запрещены

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

to_chars_result (C++17)	тип возвращаемого значения std::to_chars (класс)
from_chars (C++17)	преобразует последовательность символов в целое число или значение с плавающей запятой (функция)
to_string (C++11)	преобразует целое значение или значение с плавающей запятой в string (функция)
printffprintfsprintfsnprintf (C++11)	отпечатки отформатировать вывод stdout, поток файл или буфер Оригинал: prints formatted output to stdout, a file stream or a buffer Текст был переведён автоматически используя Переводчик Google. Вы можете проверить и исправить перевод. Для инструкций щёлкните сюда. (функция)
operator<<	вставляет форматированные данные в поток вывода std::basic_ostream (public функция-элемент std::basic_ostream)