<charconv>, funkcje

Nagłówek <charconv> zawiera następujące funkcje inne niż składowe:

Funkcje inne niż składowe	Opis
to_chars	Przekonwertuj wartość całkowitą lub zmiennoprzecinkową na sekwencję char.
from_chars	Przekonwertuj char sekwencję na liczbę całkowitą lub wartość zmiennoprzecinkową.

Te funkcje konwersji są dostrojone pod kątem wydajności, a także obsługują zachowanie najkrótszej rundy. Zachowanie najkrótszej rundy oznacza, że gdy liczba jest konwertowana na znaki, jest zapisywana wystarczająca precyzja, aby umożliwić odzyskanie oryginalnej liczby podczas konwertowania tych znaków z powrotem na zmiennoprzecinkowe.

• Podczas konwertowania znaków na liczbę wartość liczbowa nie musi być zakończona wartością null. Podobnie podczas konwertowania liczby na znaki wynik nie kończy się wartością null.
• Funkcje konwersji nie przydzielają pamięci. Jesteś właścicielem buforu we wszystkich przypadkach.
• Funkcje konwersji nie są zwracane. Zwracany jest wynik, z którego można określić, czy konwersja zakończyła się pomyślnie.
• Funkcje konwersji nie są poufne w trybie zaokrąglania w czasie wykonywania.
• Funkcje konwersji nie są świadome ustawień regionalnych. Zawsze drukują i analizują punkty dziesiętne jako '.', i nigdy nie są "", dla ustawień regionalnych, które używają przecinków.

to_chars

Przekonwertuj wartość całkowitą lub zmiennoprzecinkową na sekwencję char.

Konwertuje value na ciąg znaków, wypełniając zakres [first, last), gdzie [first, last) musi być prawidłowym zakresem. Zwraca strukturę to_chars_result. Jeśli konwersja zakończy się pomyślnie, jak wskazano w to_char_result.ecelemencie , element członkowski ptr jest wskaźnikiem jeden-przeszłości-end znaków zapisanych. to_char_result.ec W przeciwnym razie ma wartość errc::value_too_large, ma wartość last, to_char_result.ptr a zawartość zakresu [first, last) są nieokreślone.

Jedynym sposobem, w jaki to_chars może zakończyć się niepowodzenie, jest podanie niewystarczająco dużego buforu do przechowywania wyniku.

// 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);

Parametry

pierwszy
Wskazuje początek buforu do wypełnienia.

ostatni
Wskazuje jeden znak obok końca buforu do wypełnienia.

wartość
Wartość do konwersji. Jeśli value jest ujemna, reprezentacja zaczyna się od -.

base
W przypadku konwersji liczb całkowitych baza do użycia podczas konwertowania value na znaki. Musi należeć do przedziału od 2 do 36 włącznie. Nie będzie zer wiodących. Cyfry w zakresie 10..35 (włącznie) są reprezentowane jako małe litery a.. z

Fmt
W przypadku konwersji zmiennoprzecinkowych maska bitowa określająca format konwersji do użycia, taki jak naukowy, stały lub szesnastkowy. Aby uzyskać szczegółowe informacje, zobacz chars_format .

precyzja
W przypadku konwersji zmiennoprzecinkowych liczba cyfr precyzji dla przekonwertowanej wartości.

Wartość zwracana

To_chars_result zawierający wynik konwersji.

Uwagi

Funkcje używające parametru chars_format określają specyfikator konwersji tak, jakby były używane printf() w następujący sposób: specyfikator konwersji jest, jeśli fmt ma chars_format::fixed'f' wartość , jeśli fmt ma 'a' chars_format::scientificwartość , 'e' (bez wiodącego 0x w wyniku), jeśli ma wartość , a 'g' jeśli fmt fmt ma chars_format::hexchars_format::generalwartość . Określenie najkrótszej stałej notacji może nadal powodować długie dane wyjściowe, ponieważ może to być najkrótsza możliwa reprezentacja, gdy wartość jest bardzo duża lub bardzo mała.

W poniższej tabeli opisano zachowanie konwersji, biorąc pod uwagę różne kombinacje parametrów fmt i precision . Termin "zachowanie najkrótszej rundy" odnosi się do pisania najmniejszej liczby cyfr niezbędnych, tak aby analizowanie tej reprezentacji przy użyciu odpowiedniej from_chars funkcji dokładnie odzyskało wartość.

fmt i precision kombinacja	Wyjście
Żadna	Niezależnie od stałej lub naukowej notacji jest krótszy, preferując stały jako tiebreaker. Tego zachowania nie można symulować przez żadne przeciążenie, które przyjmuje fmt parametr .
fmt	Najkrótsze zachowanie dwukierunkowe dla określonego formatu, takie jak najkrótszy format naukowy.
fmt i precision	Używa podanej precyzji, następującego printf() stylu, bez najkrótszego zachowania w obie strony.

Przykład

#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

Przekonwertuj char sekwencję na liczbę całkowitą lub wartość zmiennoprzecinkową.

// 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);

Parametry

pierwszy
Wskazuje początek buforu znaków do konwersji.

ostatni
Wskazuje jeden obok elementu końcowego buforu znaków do konwersji.

wartość
Jeśli konwersja zakończy się pomyślnie, zawiera wynik konwersji.

base
W przypadku konwersji liczb całkowitych podstawa do użycia podczas konwersji. Musi należeć do przedziału od 2 do 36 włącznie.

Fmt
W przypadku konwersji zmiennoprzecinkowych format sekwencji konwertowanych znaków. Aby uzyskać szczegółowe informacje, zobacz chars_format .

Uwagi

Funkcje from_chars() analizują ciąg [first, last) dla wzorca liczbowego, gdzie [first, last) jest wymagany do prawidłowego zakresu.

Podczas analizowania znaków odstępy nie są ignorowane. W przeciwieństwie do strtod()funkcji , na przykład bufor musi zaczynać się od prawidłowej reprezentacji liczbowej.

Zwraca strukturę from_chars_result.

Jeśli żaden znak nie jest zgodny ze wzorcem liczbowym, value jest niezmodyfikowany, from_chars_result.ptr wskazuje wartość firsti from_chars_result.ec ma wartość errc::invalid_argument.

Jeśli tylko niektóre znaki pasują do wzorca liczbowego, from_chars_result.ptr wskazuje pierwszy znak, który nie pasuje do wzorca, lub ma wartość parametru last , jeśli wszystkie znaki są zgodne.

Jeśli przeanalizowana wartość nie znajduje się w zakresie reprezentowanym przez typ value, value jest niezmodyfikowana i from_chars_result.ec ma wartość errc::result_out_of_range.

value W przeciwnym razie jest ustawiona wartość przeanalizowana po zaokrągleniu i from_chars_result.ec jest równa errc{}.

Przykład

#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;
}

Wymagania

Nagłówek:<charconv>

Przestrzeń nazw: std

/std:c++17 lub nowszy jest wymagany.

Zobacz też

<charconv>
Najkrótszy ciąg dziesiętny, który specyfikatory formatu printf() round-trips