std::from_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>

Определено в заголовочном файле <charconv>
std::from_chars_result from_chars( const char* first, const char* last, /* целочисленный тип */& value, int base = 10 );	(1)	(начиная с C++17) (constexpr начиная с C++23)
	(2)
std::from_chars_result from_chars( const char* first, const char* last, float& value, std::chars_format fmt = std::chars_format::general ); std::from_chars_result from_chars( const char* first, const char* last, double& value, std::chars_format fmt = std::chars_format::general ); std::from_chars_result from_chars( const char* first, const char* last, long double& value, std::chars_format fmt = std::chars_format::general );			(начиная с C++17) (до C++23)
std::from_chars_result from_chars( const char* first, const char* last, /* тип с плавающей запятой */& value, std::chars_format fmt = std::chars_format::general );			(начиная с C++23)

Анализирует последовательность символов [first, last) на предмет шаблона, описанного ниже. Если ни один символ не соответствует шаблону или если значение, полученное в результате анализа соответствующих шаблону символов, не может быть представлено в виде value, value не изменяется, иначе символы, соответствующие шаблону, интерпретируются как текстовое представление арифметического значения, которое сохраняется в value.

1) Целочисленные анализаторы: ожидает шаблон, идентичный тому, который используется std::strtol в локали по умолчанию ("C") и с заданной ненулевой базой числа, за исключением того, что

• префиксы "0x" или "0X" не распознаются, если base равно 16
• распознаётся только знак минус (не знак плюс) и только для целочисленных типов со знаком параметра value
• ведущие пробелы не игнорируются.

Библиотека предоставляет перегрузки для всех cv-неквалифицированных (начиная с C++23) целочисленных типов со знаком и без и char в качестве ссылочного типа параметра value.

2) Анализаторы чисел с плавающей запятой: ожидает шаблон, идентичный тому, который используется std::strtod в локали по умолчанию ("C"), за исключением того, что

• знак плюс не распознаётся за пределами экспоненты (в начале разрешён только знак минус)
• если в fmt установлен std::chars_format::scientific, но не установлен std::chars_format::fixed, показатель степени является обязательным (иначе он необязателен)
• если в fmt установлен std::chars_format::fixed, но не установлен std::chars_format::scientific, необязательная экспонента не разрешена
• если в fmt установлен std::chars_format::hex, то префикс "0x" или "0X" не разрешён (строка "0x123" разбирается как значение "0" с неразобранным остатком "x123")
• ведущие пробелы не игнорируются.

В любом случае результирующее значение является одним из не более двух значений с плавающей запятой, наиболее близких к значению строки, соответствующей шаблону, после округления в соответствии с std::round_to_nearest.

Библиотека предоставляет перегрузки для всех cv-неквалифицированных типов с плавающей запятой в качестве ссылочного типа параметра value.

(начиная с C++23)

Параметры

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

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

В случае успеха возвращает значение типа std::from_chars_result, такое, что ptr указывает на первый символ, не соответствующий шаблону, или имеет значение, равное last, если все символы соответствуют шаблону, и ec инициализируется значением.

Если совпадений с шаблоном нет, возвращает значение типа std::from_chars_result, такое, что ptr равно first, а ec равно std::errc::invalid_argument. value не изменяется.

Если шаблон найден, но разобранное значение не находится в диапазоне, представленном типом value, возвращается значение типа std::from_chars_result, такое что ec равно std::errc::result_out_of_range, а ptr указывает на первый символ, не соответствующий шаблону. value не изменяется.

Исключения

Ничего не генерирует.

Примечание

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

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

Шаблон, состоящий из знака без следующих за ним цифр, рассматривается как шаблон, который ничему не соответствует.

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

Пример

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

#include <cassert>
#include <charconv>
#include <iomanip>
#include <iostream>
#include <optional>
#include <string_view>
#include <system_error>

int main()
{
    for (std::string_view const str : {"1234", "15 foo", "bar", " 42", "5000000000"})
    {
        std::cout << "Строка: " << std::quoted(str) << ". ";
        int result{};
        auto [ptr, ec] = std::from_chars(str.data(), str.data() + str.size(), result);

        if (ec == std::errc())
            std::cout << "Результат: " << result << ", ptr-> " << std::quoted(ptr) << '\n';
        else if (ec == std::errc::invalid_argument)
            std::cout << "Это не число.\n";
        else if (ec == std::errc::result_out_of_range)
            std::cout << "Это число больше, чем int.\n";
    }

    // Демонстрация constexpr from_char в C++23 / демонстрация operator bool() в C++26:
    auto to_int = [](std::string_view s) -> std::optional<int>
    {
        int value{};
#if __cpp_lib_to_chars >= 202306L
        if (std::from_chars(s.data(), s.data() + s.size(), value))
#else
        if (std::from_chars(s.data(), s.data() + s.size(), value).ec == std::errc{})
#endif
            return value;
        else
            return std::nullopt;
    };

    assert(to_int("42") == 42);
    assert(to_int("foo") == std::nullopt);
#if __cpp_lib_constexpr_charconv and __cpp_lib_optional >= 202106
    static_assert(to_int("42") == 42);
    static_assert(to_int("foo") == std::nullopt);
#endif
}

Вывод:

Строка: "1234". Результат: 1234, ptr -> ""
Строка: "15 foo". Результат: 15, ptr -> " foo"
Строка: "bar". Это не число.
Строка: " 42". Это не число.
Строка: "5000000000". Это число больше, чем int.

Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

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

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

from_chars_result (C++17)	тип возвращаемого значения std::from_chars (класс)
to_chars (C++17)	преобразует целое число или значение с плавающей запятой в последовательность символов (функция)
stoistolstoll (C++11)(C++11)(C++11)	преобразует строку в целое число со знаком (функция)
stofstodstold (C++11)(C++11)(C++11)	преобразует строку в значение с плавающей запятой (функция)
strtolstrtoll (C++11)	преобразует байтовую строку в целочисленное значение (функция)
strtofstrtodstrtold	преобразует байтовую строку в число с плавающей запятой (функция)
scanffscanfsscanf	производит форматированный ввод из stdin, файлового потока или буфера (функция)
operator>>	извлекает форматированные данные из потока ввода std::basic_istream (public функция-элемент std::basic_istream)