`<charconv>`Функции

Статья
10/12/2023

Заголовок <charconv> включает следующие функции, не являющиеся членами:

Функции, не являющиеся членами	Description
to_chars	Преобразуйте целочисленное или плавающее значение в последовательность `char`.
from_chars	Преобразуйте последовательность `char` в целочисленное или плавающее значение.

Эти функции преобразования настраиваются для повышения производительности, а также поддерживают поведение кратчайшего кругового пути. Поведение кратчайшего кругового пути означает, что при преобразовании числа в символы записывается только достаточная точность, чтобы включить восстановление исходного числа при преобразовании этих знаков обратно в плавающую точку.

При преобразовании символов в число числовое значение не требуется завершать значение NULL. Аналогичным образом, при преобразовании числа в символы результат не завершается значением NULL.
Функции преобразования не выделяют память. Буфер принадлежит во всех случаях.
Функции преобразования не вызываются. Результат возвращается, из которого можно определить, успешно ли выполнено преобразование.
Функции преобразования не учитывается в режиме округления среды выполнения.
Функции преобразования не знают языкового стандарта. Они всегда печатают и анализируют десятичные знаки как '.', и никогда не как ", для языковых стандартов, использующих запятые.

`to_chars`

Преобразуйте целочисленное или плавающее значение в последовательность char.

Преобразуется в символьную строку, заполнив value диапазон [first, lastгде [first, last) должен быть допустимым диапазоном. Возвращает структуру to_chars_result. Если преобразование выполнено успешно, как указано to_char_result.ec, элемент ptr является одним из конечных указателей на записанные символы. to_char_result.ec В противном случае имеет значение, to_char_result.ptr имеет значениеlasterrc::value_too_large, а содержимое диапазона [first, last) не указано.

Единственный способ, который может завершиться сбоем, заключается в том, что to_chars при наличии недостаточно большого буфера для хранения результата.

// integer to chars

to_chars_result to_chars(char* first, char* last, char value, int base = 10);
to_chars_result to_chars(char* first, char* last, signed char value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned char value, int base = 10);
to_chars_result to_chars(char* first, char* last, short value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned short value, int base = 10);
to_chars_result to_chars(char* first, char* last, int value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned int value, int base = 10);
to_chars_result to_chars(char* first, char* last, long value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned long value, int base = 10);
to_chars_result to_chars(char* first, char* last, long long value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned long long value, int base = 10);
to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;

// floating-point to chars

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

Параметры

first
Указывает на начало заполняемого буфера.

last
Указывает один символ за конец буфера для заполнения.

значение
Преобразуемое значение . Если value отрицательный, представление начинается с -.

base
Для целочисленных преобразований база, используемая при преобразовании value в символы. Должно быть от 2 до 36 включительно. Не будет начальных нулей. Цифры в диапазоне 10..35 (включительно) представлены как строчные символы a.. z

fmt
Для преобразования с плавающей запятой битовая маска, указывающая формат преобразования, используемый, например научный, фиксированный или шестнадцатеричный. Дополнительные сведения см . в chars_format .

precision
Для преобразования с плавающей запятой число цифр точности для преобразованного значения.

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

To_chars_result, содержащий результат преобразования.

Замечания

Функции, принимающие параметр chars_format, определяют описатель преобразования, как если бы они использовались printf() следующим образом: описатель преобразования имеет значение , если fmt 'a' chars_format::scientificfmt имеет chars_format::fixedзначение 'f' , 'e' (без ведущего 0x в результате), если fmt имеет значение , и fmt 'g' если имеет значение .chars_format::generalchars_format::hex Указание короткой фиксированной нотации может по-прежнему привести к длительным выходным данным, так как это может быть самым коротким представлением, если значение очень большое или очень небольшое.

В следующей таблице описывается поведение преобразования с учетом различных сочетаний fmt и precision параметров. Термин "поведение кратчайшего кругового пути" относится к написанию наименьшего количества цифр, необходимых таким образом, чтобы синтаксический анализ этого представления с помощью соответствующей from_chars функции восстанавливал значение точно.

`fmt` и `precision` сочетание	Выходные данные
Нет	Независимо от фиксированной или научной нотации короче, предпочитая исправить как тай-брейк. Это поведение нельзя имитировать с помощью какой-либо перегрузки, которая принимает `fmt` параметр.
`fmt`	Поведение с коротким циклом для указанного формата, например самого короткого научного формата.
`fmt` и `precision`.	Использует заданную точность, следующую `printf()` по стилю, без поведения кратчайшего кругового пути.

Пример

#include <charconv>
#include <stdio.h>
#include <system_error>

template <typename T> void TestToChars(const T t)
{
    static_assert(std::is_floating_point_v<T>);
    constexpr bool IsFloat = std::is_same_v<T, float>;

    char buf[100]; // 100 is large enough for double and long double values because the longest possible outputs are "-1.23456735e-36" and "-1.2345678901234567e-100".
    constexpr size_t size = IsFloat ? 15 : 24;
    const std::to_chars_result res = std::to_chars(buf, buf + size, t);  // points to buffer area it can use. Must be char, not wchar_t, etc.

    if (res.ec == std::errc{}) // no error
    {
        // %.*s provides the exact number of characters to output because the output range, [buf, res.ptr), isn't null-terminated
        printf("success: %.*s\n", static_cast<int>(res.ptr - buf), buf);
    }
    else // probably std::errc::value_too_large
    {
        printf("Error: %d\n", static_cast<int>(res.ec));
    }
}

int main()
{
    TestToChars(123.34);
    return 0;
}

`from_chars`

Преобразуйте последовательность char в целочисленное или плавающее значение.

// char to an integer value

from_chars_result from_chars(const char* first, const char* last, char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, signed char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, short& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned short& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, int& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned int& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, long long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned long long& value, int base = 10);

// char to a floating-point value

from_chars_result from_chars(const char* first, const char* last, float& value, chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, double& value, chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, long double& value, chars_format fmt = chars_format::general);

Параметры

first
Указывает на начало буфера символов для преобразования.

last
Указывает один за конечным элементом буфера символов для преобразования.

значение
Если преобразование выполнено успешно, содержит результат преобразования.

base
Для целочисленных преобразований база, используемая во время преобразования. Должно быть от 2 до 36 включительно.

fmt
Для преобразования с плавающей запятой формат преобразуемой последовательности символов. Дополнительные сведения см . в chars_format .

Замечания

from_chars() Функции анализируют строку [first, last) для шаблона числа, где [first, last) является допустимым диапазоном.

При синтаксическом анализе пробелы не игнорируются. В отличие strtod()от буфера, например, должен начинаться с допустимого числового представления.

Возвращает структуру from_chars_result.

Если символы не соответствуют шаблону чисел, не изменены, value from_chars_result.ptr указывает на firstи from_chars_result.ec имеет значение errc::invalid_argument.

Если только некоторые символы соответствуют числовой схеме, from_chars_result.ptr указывает на первый символ, не соответствующий шаблону, или значение last параметра, если все символы совпадают.

Если проанализированное значение не находится в диапазоне, представляющегося типом value, value не изменено и from_chars_result.ec имеет значение errc::result_out_of_range.

В противном случае задано значение синтаксического анализа, value после округления и from_chars_result.ec равно errc{}.

Пример

#include <charconv>
#include <stdio.h>
#include <string_view>
#include <system_error>

double TestFromChars(const std::string_view sv)
{
    const char* const first = sv.data();
    const char* const last = first + sv.size();
    double dbl;

    const std::from_chars_result res = std::from_chars(first, last, dbl);

    if (res.ec == std::errc{}) // no error
    {
        printf("success: %g\n", dbl);
    }
    else
    {
        printf("Error: %d\n", static_cast<int>(res.ec));
    }

    return dbl;
}

int main()
{
    double dbl = TestFromChars("123.34");
    return 0;
}

Требования

Заголовок:<charconv>

Пространство имен: std

/std:c++17 или более поздней версии требуется.

См. также

<charconv>
Кратчайшее десятичное число, указывающее формат printf() круговых путей

Поделиться через

`<charconv>`Функции

`to_chars`

Параметры

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

Замечания

Пример

`from_chars`

Параметры

Замечания

Пример

Требования

См. также

Обратная связь

Дополнительные ресурсы

Поделиться через

<charconv>Функции

to_chars

Параметры

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

Замечания

Пример

from_chars

Параметры

Замечания

Пример

Требования

См. также

Обратная связь

Дополнительные ресурсы

`<charconv>`Функции

`to_chars`

`from_chars`