`<charconv>` 函式

發行項
08/04/2024

<charconv> 標頭包含下列非成員函式：

非成員函式	說明
to_chars	將整數或浮點值轉換為的 `char`序列。
from_chars	將的序列 `char` 轉換為整數或浮點值。

這些轉換函式會針對效能進行調整，也支援最短的來回行為。最短的來回行為表示當數字轉換成字元時，只會寫出足夠的精確度，以在將這些字元轉換成浮點時，啟用復原原始數位。

將字元轉換成數位時，數值不需要以 Null 結束。同樣地，將數字轉換成字元時，結果不會以 Null 結束。
轉換函式不會配置記憶體。您擁有所有情況下的緩衝區。
轉換函式不會擲回。傳回結果，您可以從中判斷轉換是否成功。
轉換函式不會區分運行時間四捨五入模式。
轉換函式不會感知地區設定。對於使用逗號的地區設定，它們一律會將小數點列印並剖析為 '.'，且永遠不會列印為 '' 。

`to_chars`

將整數或浮點值轉換為的 char序列。

value填入範圍 [， last，其中first [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
要進行轉換的值。如果 value 為負數，表示法會以開頭 -。

base
針對整數轉換，轉換成 value 字元時要使用的基底。必須介於 2 到 36 之間，包含。不會有前置零。範圍 10..35（含）中的數位會以小寫字元 a 表示。z

fmt
對於浮點轉換，位掩碼會指定要使用的轉換格式，例如科學、固定或十六進位。如需詳細資訊，請參閱 chars_format 。

有效位數
對於浮點數轉換，轉換值的有效位數。

傳回值

包含轉換結果的to_chars_result 。

備註

採用chars_format參數的函式會判斷轉換規範，就像使用printf()的方式如下：如果是，'e'則為 chars_format::fixedfmt'f' ，如果為， 'a' 則為，如果 chars_format::scientificfmtfmt 為，則為，0x如果為，則為，如果為 chars_format::hex，則'g'為。fmt chars_format::general 指定最短的固定表示法仍然可能會導致冗長的輸出，因為當值非常大或非常小時，它可能是最短的可能表示法。

下表描述根據和 precision 參數的不同組合fmt，轉換行為。「最短來回行為」一詞是指撰寫所需的最少位數，讓使用對應 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
將字元緩衝區的結尾元素指向要轉換的一個點。

value
如果轉換成功，則包含轉換的結果。

base
針對整數轉換，轉換期間要使用的基底。必須介於 2 到 36 之間，包含。

fmt
針對浮點轉換，要轉換的字元序列格式。如需詳細資訊，請參閱 chars_format 。

備註

函式會from_chars()分析字串 [， last] 作為數位模式，其中 [firstfirst， last] 必須是有效的範圍。

剖析字元時，不會忽略空格符。例如，不同於 strtod()，緩衝區必須以有效的數值表示法開頭。

傳回from_chars_result結構。

如果沒有字元符合數位模式， value 則為未修改， from_chars_result.ptr 指向 first，且 from_chars_result.ec 為 errc::invalid_argument。

如果只有某些字元符合數位模式， from_chars_result.ptr 則指向第一個字元不符合模式，或具有參數的值 last ，如果所有字元都相符。

如果剖析的值不在可由類型valuevalue表示的範圍中，則為未修改且 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`